| --- |
| title: Reachy_Mini_Teleop |
| emoji: 🎮 |
| colorFrom: blue |
| colorTo: indigo |
| sdk: static |
| pinned: false |
| short_description: Local gamepad puppeteering with independent antenna control. |
| tags: |
| - reachy_mini |
| - reachy_mini_python_app |
| --- |
| |
| # Reachy Mini Teleop |
|
|
| Local, expressive gamepad control for Reachy Mini Lite. Control the head, body, |
| height, and both antennas independently. A browser panel shows app/controller |
| status, switches Precision/Turbo mode, and provides Stop. |
|
|
| The controller connects to this Windows computer. The browser panel is local; |
| it does not provide remote robot access or camera/audio streaming. |
|
|
| ## Start here |
|
|
| 1. Power/connect Reachy Mini and open **Reachy Mini Control**. Connect the robot |
| and wait until it is ready. Close other apps that command its movements. |
| 2. Connect your Xbox or DualSense controller by USB or Bluetooth. Center the |
| sticks and release the triggers before starting. |
| 3. Double-click **start-local.cmd** in this folder. It checks the locked Python |
| environment, starts Teleop, and opens **http://127.0.0.1:8042**. |
| 4. Keep the terminal open. Use the gamepad to move the robot. |
| 5. Click **Stop** in the browser, or press **Ctrl+C** in the terminal. Allow about |
| three seconds for the neutral return. Motors remain enabled to support the head. |
|
|
| Closing the browser tab does **not** stop Teleop. Force-closing the terminal, |
| losing power, or a broken daemon connection cannot guarantee a neutral return. |
| The browser Stop button is a normal software stop, not an emergency hardware stop. |
|
|
| ## First-time setup |
|
|
| Requires Windows, Python **3.12**, and [uv](https://docs.astral.sh/uv/getting-started/installation/). |
| The launcher creates/updates the environment using the committed lock file. |
| Initial setup needs internet access; a prepared environment can run offline. |
| No Hugging Face login is required for this local app. |
|
|
| From PowerShell in this folder: |
|
|
| ```powershell |
| uv sync --locked --python 3.12 |
| uv run --no-sync python -m teleop.main --check |
| ``` |
|
|
| The check connects to the daemon's WebSocket and reads telemetry. It sends no |
| motion commands and does not initialize camera/audio. For normal operation: |
|
|
| ```powershell |
| .\start-local.cmd |
| ``` |
|
|
| For offline operation after setup, bypass the launcher's environment check: |
|
|
| ```powershell |
| .\.venv\Scripts\python.exe -m teleop.main --open-browser |
| ``` |
|
|
| The app also retains its `reachy_mini_apps` entry point for discovery by Reachy |
| Mini Control. The launcher is the supported Windows workflow tested here. |
|
|
| ## Controls |
|
|
| | Input | Action | |
| |---|---| |
| | Left stick | Head yaw and pitch relative to the body | |
| | Right stick horizontal | Body rotation; head follows while preserving relative yaw | |
| | Right stick vertical | Head height | |
| | L2 / LT | Left antenna outward | |
| | R2 / RT | Right antenna outward | |
| | L1 / LB | Left antenna inward | |
| | R1 / RB | Right antenna inward | |
| | D-pad up | Turbo | |
| | D-pad down | Precision | |
| | Browser mode switch | Same Precision/Turbo state | |
| | Browser Stop / terminal Ctrl+C | Smooth neutral return, then exit | |
|
|
| Both antenna channels remain enabled. The SDK receives antennas in **right, left** |
| order. SDL's controller mapping handles Xbox/DualSense layout differences. Unknown |
| controllers are rejected rather than assigned guessed button indices; configure |
| `SDL_GAMECONTROLLERCONFIG` if your controller needs a custom mapping. |
|
|
| The app streams one atomic head/body/antenna target at approximately 60 Hz, with |
| elapsed-time integration, smoothing, and per-channel speed limits. Turbo doubles |
| rates but retains pose bounds. Conservative limits are head/body relative yaw |
| +/-45 degrees, pitch +/-20 degrees, body +/-90 degrees, height -20 to +30 mm, and |
| antennas +/-60 degrees. Height-dependent yaw/pitch limits narrow near either |
| height extreme. These are conservative heuristics, **not collision detection**; |
| the daemon also applies its own limits. Startup begins at measured pose, then |
| converges gradually into app limits if necessary. Sticks hold the last position |
| when released; they do not automatically recenter the head. |
|
|
| Controller loss stops the loop and requests a three-second neutral return. A lost |
| daemon connection stops commands and logs an error; it cannot send a return move. |
|
|
| ## Pollen Telepresence or this app? |
|
|
| Pollen's current [Telepresence app](https://huggingface.co/spaces/pollen-robotics/telepresence) |
| is the easier choice for remote viewing, phone/touch control, robot camera, |
| and two-way audio. It also supports physical gamepads: its current source reads |
| whichever stick has the larger deflection and uses that to steer head yaw/pitch, |
| with body yaw taking over beyond the head's relative yaw limit. |
|
|
| This app remains useful for **local expressive puppeteering**: separate sticks |
| for head versus body/height, independent trigger/shoulder antenna control, |
| Precision/Turbo modes, and holding poses when controls are released. The reviewed |
| Pollen Telepresence code does not provide those antenna/height controls. Its motion |
| loop is 20 Hz; ours targets 60 Hz with explicit smoothing, but that alone does not |
| prove smoother hardware movement. An attended comparison is still needed. |
|
|
| We recommend Pollen Telepresence for general remote teleoperation and keeping |
| this app for the richer local performance controls. There is no need to rebuild |
| Pollen's camera/audio stack here. |
|
|
| Sources reviewed October 24, 2026: |
|
|
| - [Pollen Telepresence README](https://huggingface.co/spaces/pollen-robotics/telepresence/blob/main/README.md) |
| - [Gamepad input](https://huggingface.co/spaces/pollen-robotics/telepresence/blob/main/src/components/joystick/useGamepadDeflection.ts) |
| - [Motion controller](https://huggingface.co/spaces/pollen-robotics/telepresence/blob/main/src/components/joystick/useHeadVelocityControl.ts) |
| - [Reachy Mini Python SDK](https://huggingface.co/docs/reachy_mini/en/SDK/python-sdk) |
|
|
| ## Troubleshooting |
|
|
| - **Zenoh / port 7447:** an old Python environment is being used. This app pins |
| SDK 1.11.0 to match the installed daemon. Run the launcher from this folder; |
| there is another Teleop copy at `Desktop\teleop` that was not updated. |
| - **Port 8000 / connection refused:** open Reachy Mini Control and connect the robot. |
| The new `--check` command explains missing/unsupported daemon readiness. |
| - **GStreamer 1.28.8 / cp312 installation error:** Windows media components are |
| constrained to the Desktop-compatible 1.28.7 wheels. Use the committed lock |
| and Python 3.12; do not install GStreamer independently into this environment. |
| - **`exclude-newer = "7 days"` warning:** this project's own uv settings isolate |
| it from the parent SDK checkout's newer uv configuration format. |
| - **Waiting for controller:** ensure the pad is connected to the same computer, |
| not just the robot or another Bluetooth host. Restart after pairing if needed. |
| - **Port 8042 already in use:** stop the existing Teleop instance before starting |
| another. Do not run two robot-control apps simultaneously. |
| - **Antenna motion looks choppy:** the earlier hardware issue may still need |
| attention. Software keeps both channels available; do not force the mechanism. |
|
|
| The browser status and extension bar show commanded app state, not independently |
| verified physical movement. Watch the terminal for errors. |
|
|
| ## Development checks |
|
|
| ```powershell |
| uv run --no-sync python -m unittest discover -s tests -v |
| uv run --no-sync python -m teleop.main --check |
| ``` |
|
|
| Tests use fake robot/controller input. Physical controls, direction, feel, antenna |
| behavior, and Stop/disconnect acceptance still require an attended hardware trial. |
|
|
