Merge pull request #3346 from pareenaverma/content_review

Reachy Mini LP tech review

Author: pareenaverma

content/learning-paths/cross-platform/build-a-reachy-robot-app-on-pi/extend.md

@@ -25,14 +25,14 @@ motion, or packaging.
 
 ## Change the classifier
 
-Trying adding new gesture controls. Start in `gesture.py`, where the app maps MediaPipe labels such as `Thumb_Up` and `Thumb_Down` to app labels. Then add matching robot behavior in `moves.py` and branch on the new label in `main.py`.
+Try adding new gesture controls. Start in `gesture.py`, where the app maps MediaPipe labels such as `Thumb_Up` and `Thumb_Down` to app labels. Then add matching robot behavior in `moves.py` and branch on the new label in `main.py`.
 
 Some game-themed ideas:
 
 - Map `Closed_Fist` to `challenge`, and make Reachy repeat the current move
 - Map `Pointing_Up` to `reroll`, and make Reachy reject the current move and
   choose another one.
-- Map `Number of fingers` to choosing a specific move.
+- Map the number of fingers shown to choose a specific move.
 
 ## Add audio output
 
@@ -50,7 +50,7 @@ robot motion and sound effects easy to change independently.
 ## Replace thumbs with audio input
 
 The vision-based verdict is one edge AI input modality. You can replace
-or complement it with audio - many webcams include microphones or you can use a USB microphone.
+or complement it with audio. Many webcams include microphones, or you can use a USB microphone.
 
 - say "yes" for victory and "no" for defeat,
 - clap once for victory and twice for defeat,
@@ -62,10 +62,10 @@ A lightweight keyword-spotting model can map spoken commands to the same game st
 If you have a physical Reachy Mini, the quickest way to try the finished
 experience is to install the packaged [Reachy Gladiator app](https://huggingface.co/spaces/cossinsmatthew/reachy_gladiator) through the [Reachy Mini Control app](https://github.com/pollen-robotics/reachy-mini-desktop-app).
 
-Simply install Reachy Mini Control on a supported machine, connected to your Reachy, and search for the reachy gladiator app.
+Install Reachy Mini Control on a supported machine, connect it to your Reachy, and search for the Reachy Gladiator app.
 
 {{% notice Warning %}}
-If using a physical Reachy Mini, use caution and ensure the robot is used in an area with appropriate space. The robot has moving parts and could be a health & safety risk. You are responsible for your safety and the safety of others around you when using physical robotic devices
+If using a physical Reachy Mini, use caution and ensure the robot is used in an area with appropriate space. The robot has moving parts and could be a health & safety risk. You are responsible for your safety and the safety of others around you when using physical robotic devices.
 {{% /notice %}}
 
 ## Adapt this source project for physical Reachy
@@ -129,4 +129,4 @@ Pollen Robotics `AGENTS.md` instructions, provided by the [Reachy Mini project](
 
 ## What you learned
 
-You explored options for extending from simulation to a physical Reachy, as well ideas for changing the project to include audio, new vision gestures, or different behaviours.
+You explored options for extending from simulation to a physical Reachy, as well as ideas for changing the project to include audio, new vision gestures, or different behaviors.

content/learning-paths/cross-platform/build-a-reachy-robot-app-on-pi/reachy-app.md

@@ -6,22 +6,20 @@ weight: 2
 layout: learningpathall
 ---
 
-## Reachy Gladiator - Decide Reachy's Fate
+## Reachy Gladiator - Decide Reachy's fate
 
-In this Learning Path, Reachy is stepping out onto the sands of the Arena. Reachy has practiced their gladiator moves, but are they good enough?
-
-You will decide Reachy's fate in the classic Roman way - a 👍 for **Victory**, or a 👎 for **Defeat**.
+In this Learning Path, you build a distributed edge AI application where a Raspberry Pi runs local gesture inference and sends robot motion commands to a simulated Reachy Mini. The app follows a gladiator arena theme: Reachy performs a move, and you give a thumbs-up 👍 for **Victory** or thumbs-down 👎 for **Defeat** to trigger a victory or defeat reaction.
 
 ![Illustration of Reachy Mini in a gladiator style pose. The app uses this arena theme for its moves, verdicts, and dashboard.#center](reachy_gladiator.png "Reachy Mini Gladiator App Concept")
 
 ## What is Reachy Mini?
 
-Reachy Mini is a small open robotics platform from Pollen Robotics. It is designed for expressive head, antenna, and body motion, and it can be controlled from Python with the Reachy Mini SDK. The Reachy Mini Wireless version includes an onboard Arm-powered Raspberry Pi 4 Compute Module, and the Lite version is operated with external compute (e.g., Raspberry Pi, DGX Spark, Mac/PC).
+Reachy Mini is a small open robotics platform from Pollen Robotics. It is designed for expressive head, antenna, and body motion, and it can be controlled from Python with the Reachy Mini SDK. The Reachy Mini Wireless version includes an onboard Arm-powered Raspberry Pi 4 Compute Module, and the Lite version is operated with external compute such as a Raspberry Pi, DGX Spark, or Mac/PC.
 
 Reachy can also be simulated using MuJoCo software. Most developers do not have a physical Reachy Mini robot on their desk, and it is often useful to develop software before hardware is available. Extrapolating from Reachy to more industrial robotics, it is also important to test applications in simulation in advance for safety.
 
 {{% notice Warning %}}
-If using a physical Reachy Mini, use caution and ensure the robot is used in an area with appropriate space. The robot has moving parts and could be a health & safety risk. You are responsible for your safety and the safety of others around you when using physical robotic devices
+If using a physical Reachy Mini, use caution and ensure the robot is used in an area with appropriate space. The robot has moving parts and could be a health & safety risk. You are responsible for your safety and the safety of others around you when using physical robotic devices.
 {{% /notice %}}
 
 ## What will you build?
@@ -54,7 +52,7 @@ Keeping perception, robot control, and observability as separate pieces makes it
 
 The app is called Reachy Gladiator. Reachy (in simulation or otherwise) performs a randomly-chosen scripted gladiator move. You provide a 👍 for **Victory**, or a 👎 for **Defeat**. **Victory** makes Reachy celebrate, **Defeat** makes Reachy react sadly.
 
-This learning path starts from the complete `reachy_gladiator_lp` project instead of asking you to create every file from scratch. The simulation host only needs a launcher script, but the Raspberry Pi will clone and run the full project. You will inspect the different parts of the system so you can recreate your own apps running on Reachy or in simulation.
+This Learning Path starts from the complete [`reachy_gladiator_lp`](https://github.com/matt-cossins/reachy_gladiator_lp) project instead of asking you to create every file from scratch. The simulation host only needs a launcher script, but the Raspberry Pi will clone and run the full project. You will inspect the different parts of the system so you can recreate your own apps running on Reachy or in simulation.
 
 The Reachy Gladiator app runs a repeated loop:
 
@@ -96,7 +94,7 @@ The rest of this learning path shows the common Bash commands and calls out the
 The simulation host does not need the full project checkout. In the next
 section, you will download only the simulation launcher script on that machine.
 
-You will clone the full `reachy_gladiator_lp` project on the Raspberry Pi later on.
+You will clone the full `reachy_gladiator_lp` project on the Raspberry Pi later.
 
 The key files are:
 

content/learning-paths/cross-platform/build-a-reachy-robot-app-on-pi/run-pi-app.md

@@ -1,5 +1,5 @@
 ---
-title: Setup Pi and run Edge AI app
+title: Set up the Pi and run the Edge AI app
 weight: 4
 
 ### FIXED, DO NOT MODIFY
@@ -8,9 +8,9 @@ layout: learningpathall
 
 ## Prepare the Raspberry Pi
 
-The Raspberry Pi should be installed with Raspberry Pi OS Trixie, and be accessible over SSH.
+The Raspberry Pi should be installed with Raspberry Pi OS Trixie (Debian 13-based), and be accessible over SSH.
 
-Connect to your Raspberry Pi over SSH using [VSCode Remote - SSH](https://code.visualstudio.com/docs/remote/ssh), or via terminal e.g.,
+Connect to your Raspberry Pi over SSH. If you use VS Code, you can use the [Remote - SSH](https://code.visualstudio.com/docs/remote/ssh) extension. From a terminal:
 
 ```bash
 ssh <user>@<pi-ip-address>
@@ -33,7 +33,7 @@ sudo apt install git-lfs
 git lfs install
 ```
 
-Clone the `reachy_gladiator_lp` project into this directory:
+Clone the [`reachy_gladiator_lp`](https://github.com/matt-cossins/reachy_gladiator_lp) project into this directory:
 
 ```bash
 git clone https://github.com/matt-cossins/reachy_gladiator_lp.git
@@ -52,7 +52,7 @@ again before continuing.
 
 ## Install the Pi runtime
 
-Run the Pi setup script:
+Run the Pi setup script. This can take several minutes because it installs `pyenv`, builds Python 3.12, and installs all Python dependencies:
 
 ```bash
 ./scripts/setup_pi.sh
@@ -78,7 +78,7 @@ source .venv/bin/activate
 
 The setup script runs an import smoke test. It also runs `pip check`; a MediaPipe NumPy metadata warning is expected for this Pi setup.
 
-Test the MediaPipe gesture worker from a real Python file:
+Test the MediaPipe gesture worker by writing a small test script and running it. The `cat` command below creates the file at `/tmp/test_gesture_worker.py` using a heredoc — the text between `<<'PY'` and the closing `PY` becomes the file contents:
 
 ```bash
 cat > /tmp/test_gesture_worker.py <<'PY'

content/learning-paths/cross-platform/build-a-reachy-robot-app-on-pi/start-simulation.md

@@ -22,13 +22,19 @@ The simulation host does not need the full `reachy_gladiator_lp` project. It
 only needs the Reachy Mini SDK with MuJoCo support and the `start_sim.sh`
 launcher script.
 
+### macOS prerequisites
+
+{{% notice Note %}}
+Python 3.12 is required for the simulation environment. Python 3.13 can cause dependency resolution failures because pre-built wheels for some SDK dependencies are not yet available for that version. Check your version with `python3 --version`. On macOS, install Python 3.12 with [Homebrew](https://brew.sh): `brew install python@3.12`. On Ubuntu or WSL2, install it with `sudo apt install python3.12 python3.12-venv`.
+{{% /notice %}}
+
 On the machine that will run the simulation, create a small workspace and a
 Python virtual environment:
 
 ```bash
 mkdir -p ~/reachy_projects/reachy_sim/scripts
 cd ~/reachy_projects/reachy_sim
-python3 -m venv .venv
+python3.12 -m venv .venv
 source .venv/bin/activate
 python -m pip install --upgrade pip
 ```
@@ -43,7 +49,7 @@ The `mujoco` extra is required for `--sim`. If you install only `reachy-mini`, t
 
 If you already have a working Reachy Mini simulation environment, you can activate that environment instead.
 
-Download the simulation launcher script from the project repository:
+Download the simulation launcher script from the [reachy_gladiator_lp repository](https://github.com/matt-cossins/reachy_gladiator_lp):
 
 ```bash
 curl -L https://raw.githubusercontent.com/matt-cossins/reachy_gladiator_lp/main/scripts/start_sim.sh -o scripts/start_sim.sh
@@ -64,9 +70,19 @@ source .venv/bin/activate
 REACHY_SIM_PORT=18000 ./scripts/start_sim.sh
 ```
 
-This can take several minutes to start up. Leave this terminal running after it completes and boots the simulation view.
+This can take several minutes to start up. When the simulation is ready, the output is similar to:
+
+```output
+reachy_mini.daemon.daemon - INFO - Daemon started successfully.
+uvicorn.error - INFO - Application startup complete.
+uvicorn.error - INFO - Uvicorn running on http://0.0.0.0:18000 (Press CTRL+C to quit)
+reachy_mini.utils.discovery - INFO - mDNS service registered: reachy_mini on port 18000
+reachy_mini.media.media_server - INFO - Pipeline latency (live=True, min_latency=30000000, max_latency=1200000000)
+```
+
+Leave this terminal running after it completes and boots the simulation view.
 
-![MuJoCo Simulation#center](MuJoCo.png "MuJoCo Simulation")
+![MuJoCo physics simulation window showing the Reachy Mini robot in a standing position, confirming the simulation started successfully#center](mujoco.png "MuJoCo simulation window with Reachy Mini")
 
 
 The script starts the Reachy Mini daemon with simulation enabled, binds FastAPI to `0.0.0.0`, and disables localhost-only mode so the Raspberry Pi can connect. This Learning Path uses port `18000`.

content/learning-paths/cross-platform/build-a-reachy-robot-app-on-pi/understand-code.md

@@ -214,7 +214,7 @@ XNNPACK delegate to speed up neural-network operations on Arm CPUs.
 
 The detector runs in a worker process instead of the main app thread. This
 keeps MediaPipe inference separate from the robot-control loop, dashboard
-responses, and camera capture. Other processes therefore don't pause the MediaPipe worker while it is classifying frames.
+responses, and camera capture. The robot-control loop and dashboard server therefore remain responsive while MediaPipe is classifying a frame.
 
 The app uses the CPU delegate:
 
@@ -415,7 +415,7 @@ if __name__ == "__main__":
     app.wrapped_run(host=daemon_host, port=daemon_port, timeout=daemon_timeout)
 ```
 
-Take some time to look through the files and try to understand the different parts. Feel free to ask a coding agent or LLM to help explain any areas you are unsure about.
+Take some time to read through the files and understand the different parts before moving on to extend the project.
 
 ## What you learned
 

content/learning-paths/cross-platform/build-a-reachy-robot-app-on-pi/use-the-app.md

@@ -31,7 +31,7 @@ http://<pi-ip-address>:8042
 This works even when the Pi is headless. The browser only needs network access
 to the Pi and port `8042`.
 
-The app will countdown from 10, and then Reachy will start performing moves. Reachy will perform the same move three times, and then await your verdict. After a verdict is given, Reachy will perform the **Victory** or **Defeat** moves. Reachy will then randomly select another move the cycle will repeat.
+The app will count down from 10, and then Reachy will start performing moves. Reachy will perform the same move three times, and then await your verdict. After a verdict is given, Reachy will perform the **Victory** or **Defeat** moves. Reachy will then randomly select another move, and the cycle repeats.
 
 ![Thumbs Up Victory#center](thumbs-up.gif "Thumbs Up Victory")