techreview + codex review

content/learning-paths/cross-platform/tuning-zenoh-ros2-lp3/1-overview.md

@@ -1,14 +1,16 @@
 ---
-title: Overview
+title: Understand ROS 2 sensor traffic constraints over wireless links
 weight: 2
 
+description: Understand how ROS 2 sensor traffic can exceed wireless link capacity before evaluating Zenoh traffic-control policies.
+
 layout: learningpathall
 ---
 
 <!-- ## From a local test to Wi-Fi -->
-## Overview
+## Understand the wireless traffic constraints
 
-A robot can work correctly in a controlled test environment and still fail when you move its ROS 2 traffic over to Wi-Fi. This is sometimes described as a robot that *works on the bench*. 
+A robot can work correctly in a controlled test environment and still fail when you move its ROS 2 traffic over to Wi-Fi. This is sometimes described as a robot that *works on the bench*.
 
 The simulation from the preceding Learning Paths published three sensor streams:
 
@@ -22,10 +24,11 @@ These three streams together need about 800 Mbps, whereas a typical 2.4 GHz Wi-F
 
 This Learning Path tests four ways to control this traffic: compression, access control, downsampling, and quality of service (QoS) with congestion control. Most policies are applied at the Zenoh router. Compression must be enabled at both ends of the connection.
 
-The work is done in two series: 
-- Experiment A uses `tc`/`netem` to emulate a degraded wireless link between two containers on the same server, which isolates each mechanism under repeatable conditions. 
+The work is done in two series:
+
+- Experiment A uses `tc`/`netem` to emulate a degraded wireless link between two containers on the same server, which isolates each mechanism under repeatable conditions.
 - Experiment B repeats the measurements with a Raspberry Pi over real Wi-Fi, confirming the conclusions outside the emulator.
 
 ## What you've learned and what's next
 
-The ROS 2 applications are not the problem in this experiment. The combined sensor traffic exceeds the capacity of the wireless link. Next, you'll start the completed LP1 and LP2 environment and record an unconstrained baseline.
+The ROS 2 applications are not the problem in this experiment. The combined sensor traffic exceeds the capacity of the wireless link. Next, you'll start the environment you completed in the preceding two Learning Paths and record an unconstrained baseline.

content/learning-paths/cross-platform/tuning-zenoh-ros2-lp3/2-setup-and-measure-the-baseline.md

@@ -2,16 +2,18 @@
 title: Prepare the system and measure the baseline
 weight: 3
 
+description: Start the ROS 2 and Zenoh environment and measure baseline sensor rates, bandwidth, and link traffic.
+
 layout: learningpathall
 ---
 
-## Setup
+## Start the ROS 2 and Zenoh environment
 
 {{% notice Important %}}
-Complete [Build a ROS 2 and Zenoh simulation environment on an Arm server](/learning-paths/cross-platform/ros2-zenoh-arm/) and [Distribute a ROS 2 robotic system across Arm devices with Zenoh](/learning-paths/cross-platform/distributed-ros2-zenoh-lp2/) before you continue. This Learning Path tunes that working system; it does not repeat its installation and network configuration.
+Please complete both LP1 ([Build a ROS 2 and Zenoh simulation environment on an Arm server](/learning-paths/cross-platform/ros2-zenoh-arm/)) and LP2 ([Distribute a ROS 2 robotic system across Arm devices with Zenoh](/learning-paths/cross-platform/distributed-ros2-zenoh-lp2/)) before you continue. This Learning Path tunes that working system; it does not repeat its installation and network configuration.
 {{% /notice %}}
 
-If the containers are stopped, start them from the Arm server host. Use the LP1 working directory if you selected a different location:
+If the containers are stopped, start them from the Arm server host. Use the same working directory you set up in the first Learning Path:
 
 ```bash
 cd ~/ros_zenoh
@@ -32,7 +34,13 @@ The commands that ran in interactive terminals from the previous Learning Paths
 <details>
 <summary>Restart the robot stack</summary>
 
-Open the robot container desktop.
+Each running container provides a browser-accessible desktop (sign in with the password `ubuntu` if needed):
+
+- `Robot` container desktop: `http://<your_arm_server_ip_address>:6080/`
+- `Control` container desktop: `http://<your_arm_server_ip_address>:6081/`
+
+Open the `robot` container desktop and launch three terminals.
+
 Run the router in the first terminal:
 
 ```bash
@@ -56,7 +64,9 @@ just rox_nav2
 
 </details>
 
-Open another `robot` terminal and remove any network limit left by an earlier test:
+Next, open the [robot container desktop](http://<your_arm_server_ip_address>:6080/) in another browser tab or window.
+
+Once in the `robot` container desktop, open a terminal and remove any network limit left by an earlier test:
 
 ```bash
 source ~/workshop_env.bash
@@ -75,9 +85,10 @@ Using three separate terminals in the `control` container, run the following com
 | Control 2 | `ros2 topic hz /camera/image_raw` | Average rate and standard deviation |
 | Control 3 | `ros2 topic bw /camera/points` | Average bandwidth and message size |
 
-Run the fourth measurement in a `robot` terminal:
+Run the fourth measurement in an additional terminal within the `robot` container:
 
 ```bash
+source ~/workshop_env.bash
 just iftop_router
 ```
 
@@ -89,7 +100,7 @@ At the end of the display, `iftop` reports three TX rates:
 TX:  rates: 813Mb  819Mb  832Mb
 ```
 
-This shows the 2 s / 10 s / 40 s moving averages of traffic respectively sent by the robot. Record the **middle** value. 
+These values show the 2-second, 10-second, and 40-second moving averages of traffic sent by the robot. Record the **middle** value, which is the 10-second average.
 
 ![iftop display monitoring Zenoh router traffic. A red circle marks 819 Mb in the middle TX column, the 10-second average to record as the link traffic.#center](a0-iftop-baseline.png "The circled middle TX value is the 10-second link rate")
 

content/learning-paths/cross-platform/tuning-zenoh-ros2-lp3/3-emulate-a-wireless-link.md

@@ -2,20 +2,23 @@
 title: Tune Zenoh on an emulated wireless link
 weight: 4
 
+description: Emulate a constrained wireless link and measure how Zenoh traffic-control policies affect ROS 2 sensor delivery.
+
 layout: learningpathall
 ---
 
 ## Apply network constraints (A1)
 
 Linux traffic control (`tc`) decides how packets leave a network interface. Its network emulator (`netem`) can add delay, loss, duplication, corruption, and reordering. Together they let you reproduce a difficult network without moving the containers to Wi-Fi.
 
-In a `robot` terminal:
+In a terminal within the `robot` container desktop:
 
 ```bash
+source ~/workshop_env.bash
 just network_limit
 ```
 
-**Expected result:** the script reports the emulated link parameters.
+The expected output shows the emulated link parameters:
 
 ```output
 WiFi medium connection simulation applied to 172.1.0.3:
@@ -42,9 +45,9 @@ Stop all four measurement commands with **Ctrl+C**.
 
 ## Apply compression (A2)
 
-Zenoh uses [LZ4 compression](https://lz4.org/) to reduce the bytes sent over a unicast connection. LZ4 was chosen for speed rather than ratio, since compression must not become a latency source. Compression is negotiated when a client connects, so the router and the client must both enable it.
+Zenoh uses [LZ4 compression](https://lz4.org/) to reduce the bytes sent over a unicast connection. LZ4 was chosen for speed rather than ratio, because compression must not become a latency source. Compression is negotiated when a client connects, so the router and the client must both enable it.
 
-In a `robot` terminal, open the router configuration:
+In a terminal on the `robot` container desktop, open the router configuration:
 
 ```bash
 nano ~/container_data/ROUTER_CONFIG.json5
@@ -60,7 +63,7 @@ compression: {
 
 Do not add a second `transport` block. Edit the active value rather than a commented example.
 
-In a `control` terminal, open the client configuration:
+In a terminal on the `control` container desktop, open the client configuration:
 
 ```bash
 nano ~/container_data/SESSION_CONFIG.json5
@@ -70,7 +73,7 @@ Find the same compression setting and set it to `true`.
 
 Save each file with **Ctrl+O** and **Enter**, then exit Nano with **Ctrl+X**.
 
-The router reads its configuration only at startup. In the `robot` desktop, find the terminal running the router, press Ctrl+C, then restart it:
+The router reads its configuration only at startup. In the `robot` container desktop, find the terminal running the router, press **Ctrl+C**, then restart it:
 
 ```bash
 just router
@@ -82,7 +85,7 @@ Restart the four measurements and record:
 |---|---|---|---|---|
 | **A2** | **7.95 Hz** (link traffic ~380 Kbps → ~200 Kbps) | **0.5–2.8 Hz, drifting** | **still nothing** | **~23.5 Mbps, still at the cap** |
 
-The scan's rate is unchanged but its bytes on the link roughly halve — LZ4 achieving about 1.8× on this data. The image improves, but the reading drifts between measurements, while the point cloud's doomed fragments still compete for the link. An unstable reading here is the expected result, not a mistake.
+The scan's rate is unchanged but its bytes on the link roughly halve — LZ4 achieving about 1.8× on this data. The image improves, but the reading drifts between measurements, while incomplete point-cloud fragments still compete for the link. An unstable reading here is the expected result, not a mistake.
 
 The total TX rate (Link traffic) can remain close to the constrained link’s capacity. Compression reduces individual messages, but publishers continue supplying more data than the link can carry.
 
@@ -92,7 +95,7 @@ Stop all four measurement commands with **Ctrl+C**. Keep compression enabled and
 
 A monitoring station does not always need the point cloud. Zenoh access control can stop that topic at the router while local robot nodes continue to use it.
 
-Open the router configuration in `robot`:
+Open the router configuration in the `robot` container desktop:
 
 ```bash
 nano ~/container_data/ROUTER_CONFIG.json5
@@ -135,7 +138,7 @@ access_control: {
 
 The first key expression matches the point-cloud data. The `@adv` form matches the additional keys used to advertise topics with transient-local durability.
 
-Save the file, stop the router with **Ctrl+C**, and restart it:
+Save the file, stop the router with **Ctrl+C**, and restart it on the `robot` container desktop:
 
 ```bash
 just router
@@ -165,9 +168,9 @@ Stop all measurement commands with **Ctrl+C**. Keep compression, access control,
 
 ## Downsample the image (A4)
 
-Downsampling drops publications on the egress path to a target frequency. 
+Downsampling drops publications on the egress path to a target frequency.
 
-Keep the A3 access-control block active. Open the router configuration in `robot`:
+Keep the A3 access-control block active. Open the router configuration in `robot` container desktop:
 
 ```bash
 nano ~/container_data/ROUTER_CONFIG.json5
@@ -187,9 +190,11 @@ downsampling: [
   },
 ],
 ```
+
 The rule sets a maximum egress rate of 3 Hz for the image and its transient-local advertisement keys.
 
-Save the file, stop the router, and restart it:
+Save the file, stop the router, and restart it on the `robot` container desktop:
+
 ```bash
 just router
 ```
@@ -208,9 +213,9 @@ Stop all measurement commands with **Ctrl+C**.
 
 ## Apply priority and congestion control (A5)
 
-The remaining problem is the point cloud, which so far has only ever been blocked, never delivered. This step restores point-cloud traffic and changes the congestion policy.
+The remaining problem is the point cloud, which has only been blocked and never delivered. Restore the point-cloud traffic. Then change the congestion policy.
 
-Open `~/container_data/ROUTER_CONFIG.json5` in robot. Comment out the `access_control` and `downsampling` blocks — keep them in the file, Experiment B needs them again. Add this `qos` block at the top level:
+Open `~/container_data/ROUTER_CONFIG.json5` in the `robot` container desktop. Comment out the `access_control` and `downsampling` blocks — keep them in the file, Experiment B needs them again. Add this `qos` block at the top level:
 
 ```json5
 qos: {
@@ -250,11 +255,12 @@ qos: {
 ```
 
 Verify the state of all three blocks before restarting:
+
 ```bash
 grep -n "access_control\|downsampling\|qos\|block_first" ~/container_data/ROUTER_CONFIG.json5
 ```
 
-Restart the router and the measurements.
+Restart the router on the `robot` container desktop and the measurements.
 
 | Scenario | `/scan` | `/camera/image_raw` | `/camera/points` | Link traffic |
 |---|---|---|---|---|
@@ -264,7 +270,7 @@ For the first time under the constrained link, `ros2 topic bw /camera/points` sh
 
 When the queue is full, `block_first` waits for the first matching message to progress and can drop later matching messages. This favors complete point-cloud frames over fragments from several competing frames, so fewer frames arrive, but the received frames are usable.
 
-Stop the measurements with **Ctrl+C**. Restore the normal Docker network in `robot`:
+Stop the measurements with **Ctrl+C**. Restore the normal Docker network in the `robot` container desktop:
 
 ```bash
 just network_normal

content/learning-paths/cross-platform/tuning-zenoh-ros2-lp3/4-measure-real-wifi.md

@@ -2,6 +2,8 @@
 title: Measure with real Wi-Fi
 weight: 5
 
+description: Measure Zenoh policy effects on ROS 2 sensor traffic between an Arm server and a Raspberry Pi over Wi-Fi.
+
 layout: learningpathall
 ---
 
@@ -14,16 +16,16 @@ Experiment A: robot container ── Docker network ── control container
 Experiment B: robot container ── Arm server ── Wi-Fi ── Raspberry Pi
 ```
 
-Put the Raspberry Pi on Wi-Fi (2.4 GHz makes the effects clearer). Connect it as a Zenoh client, just as was done in the [previous Learning Path](/learning-paths/cross-platform/distributed-ros2-zenoh-lp2/3-connect-the-raspberry-pi/). 
+Configure your Raspberry Pi to connect to an existing Wi-Fi network that also contains the Arm server. Using 2.4 GHz makes the effects clearer. Follow the [Raspberry Pi connection procedure from the preceding Learning Path](/learning-paths/cross-platform/distributed-ros2-zenoh-lp2/3-connect-the-raspberry-pi/) to connect it as a Zenoh client.
 
 ## Restore the B0 router configuration
 
-Before starting, return the router configuration to a clean state. Open `~/container_data/ROUTER_CONFIG.json5` in `robot` and ensure the following:
+Before starting, return the router configuration to a clean state. Open `~/container_data/ROUTER_CONFIG.json5` in a terminal within the `robot` container desktop and ensure the following:
 
 - Set `transport/unicast/compression/enabled` to `false`
 - Keep `access_control`, `downsampling`, and `qos` commented out
 
-Restart the router after saving the file. Confirm that the emulated link is no longer active:
+Restart the router on the `robot` container desktop after saving the file. Confirm that the emulated link is no longer active:
 
 ```bash
 just network_normal
@@ -33,14 +35,14 @@ Experiment B uses the physical wireless link. Do not run `just network_limit` du
 
 ## Record scenario B0
 
-Open three SSH sessions to the Raspberry Pi. In each session, enter `pi_edge` and source ROS 2:
+Open three SSH sessions to the Raspberry Pi. In each session, open a bash shell in the `pi_edge` container and source ROS 2:
 
 ```bash
-docker exec -it pi_edge bash
+docker exec -it pi_edge /bin/bash
 source /opt/ros/jazzy/setup.bash
 ```
 
-Run one receiver command in each container shell:
+Run one receiver command in each bash shell that has been opened in the `pi_edge` container:
 
 ```bash
 ros2 topic hz /scan
@@ -54,7 +56,7 @@ ros2 topic hz /camera/image_raw
 ros2 topic bw /camera/points
 ```
 
-Run `just iftop_router` in `robot`. Wait 60–90 seconds and complete the B0 row:
+Run `just iftop_router` in a terminal within the `robot` container desktop. Wait 60–90 seconds and complete the B0 row:
 
 | Scenario | `/scan` | `/camera/image_raw` | `/camera/points` | Link traffic |
 |---|---|---|---|---|
@@ -68,7 +70,7 @@ Stop the three measurements and `iftop` with **Ctrl+C**.
 
 ## Enable compression (B1)
 
-Keep the three Pi shells open after stopping the B0 measurements. In `robot`, enable compression in `~/container_data/ROUTER_CONFIG.json5`. Keep `access_control`, `downsampling`, and `qos` commented out.
+Keep the three bash shells in the `pi_edge` container on the Raspberry Pi open after stopping the B0 measurements. In the `robot` container desktop, enable compression in `~/container_data/ROUTER_CONFIG.json5`. Keep `access_control`, `downsampling`, and `qos` commented out.
 
 Enable compression in each Pi shell:
 
@@ -82,7 +84,7 @@ Confirm that the override includes compression:
 echo $ZENOH_CONFIG_OVERRIDE
 ```
 
-Stop and restart the router so that it reads the new configuration. Restart the same three Pi measurements used for B0, run `just iftop_router` in `robot`, and collect data for 60–90 seconds.
+Stop and restart the router on the `robot` container desktop so that it reads the new configuration. Restart the same three measurements in the Raspberry Pi `pi_edge` container used for B0. Run `just iftop_router` in the `robot` container desktop. Collect data for 60–90 seconds.
 
 Record your measurements and compare them with the reference result:
 
@@ -96,15 +98,15 @@ Compression allows the camera images to fit the real Wi-Fi link, restoring the s
 
 Stop the B1 measurements and `iftop`. In the router configuration, disable compression and enable only the `downsampling` block from A4. Keep `access_control` and `qos` commented out.
 
-The current Pi shells still contain the compression override from B1. Exit each container shell, open a fresh one, and source ROS 2:
+The current Pi shells still contain the compression override from B1. Exit each of the three container shells into `pi_edge` and open fresh ones. Then source ROS 2:
 
 ```bash
 exit
-docker exec -it pi_edge bash
+docker exec -it pi_edge /bin/bash
 source /opt/ros/jazzy/setup.bash
 ```
 
-Do not enable compression in these new shells. Stop and restart the router, restart the three Pi measurements, run `just iftop_router` in `robot`, and collect data for 60–90 seconds.
+Do not enable compression in these new shells. Stop and restart the router on the `robot` container desktop. Restart the measurements in the three `pi_edge` shells. Run `just iftop_router` in the `robot` container desktop. Collect data for 60–90 seconds.
 
 Record your measurements and compare them with the reference result:
 
@@ -124,7 +126,7 @@ Enable compression in each Pi shell:
 export ZENOH_CONFIG_OVERRIDE="${ZENOH_CONFIG_OVERRIDE};transport/unicast/compression/enabled=true"
 ```
 
-Stop and restart the router, restart the three Pi measurements, run `just iftop_router` in `robot`, and collect data for 60–90 seconds.
+Stop and restart the router on the `robot` container desktop. Restart the measurements in the three `pi_edge` shells. Run `just iftop_router` in the `robot` container desktop. Collect data for 60–90 seconds.
 
 Record your measurements and compare them with the reference result:
 
@@ -138,7 +140,7 @@ The point cloud now consumes no link bandwidth, while the camera and scan remain
 
 Stop the B3 measurements and `iftop`. In the router configuration, comment out the access-control block, keep compression enabled, and enable the `qos` block from A5. Keep downsampling disabled.
 
-The Pi shells already have compression enabled, so no client-side change is needed. Stop and restart the router, restart the three Pi measurements, run `just iftop_router` in `robot`, and collect data for 60–90 seconds.
+The Pi shells already have compression enabled, so no client-side change is needed. Stop and restart the router on the `robot` container desktop. Restart the measurements in the three `pi_edge` shells. Run `just iftop_router` in the `robot` container desktop. Collect data for 60–90 seconds.
 
 Record your measurements and compare them with the reference result: