| # ReachyPi |
|
|
| <p align="center"> |
| <img src="reachypi.png" alt="ReachyPi — a Reachy Mini Lite USB going wireless via a Raspberry Pi 5" width="320"> |
| </p> |
|
|
| <p align="center"><em>Run the Reachy Mini Lite wirelessly</em></p> |
|
|
| **Reachy Mini Lite USB** without cable and the official app, via a **Raspberry Pi 5** running [reachy-mini-os](https://github.com/pollen-robotics/reachy-mini-os). |
|
|
| The Lite normally tethers to a computer over USB. ReachyPi gives you a Pi 5 SD-card image so the robot runs standalone — **motors, camera, sound, and the official app over Bluetooth** all work (tested on a Pi 5, daemon `v1.8.4`). |
|
|
| ## Getting started |
|
|
| 1. **Download** the image: [⬇ latest build](https://huggingface.co/Domotick/ReachyPi/resolve/main/image_2026-06-27-reachyminios.zip) (`.zip`, ~1.6 GB) — or [build it](#build). |
| 2. **Flash it** to an SD card, then boot it (now wireless). |
|
|
| <sub>🛠️ Flash with [Raspberry Pi Imager](https://www.raspberrypi.com/software/) — "Use custom" → the `.zip`<br> |
| ⚠️ In the customization, **don't set a user** (it renames `pollen` and breaks the robot); wifi is fine.</sub> |
|
|
| ## Build |
|
|
| The build runs in **Docker**, so any OS works (a Raspberry Pi builds it natively). |
|
|
| ### Install Docker and start it |
|
|
| | OS | Docker | |
| |---|---| |
| | Ubuntu / Debian / Raspberry Pi OS | `sudo apt install docker.io` | |
| | Arch | `sudo pacman -S docker` | |
| | Fedora | `sudo dnf install docker` | |
| | macOS | [Docker Desktop](https://docs.docker.com/desktop/) (or `brew install --cask docker`) | |
| | Windows | [Docker Desktop](https://docs.docker.com/desktop/) with the WSL2 backend | |
| | other Linux | `curl -fsSL https://get.docker.com \| sudo sh` | |
|
|
| On Linux, start it with `sudo systemctl enable --now docker`. On macOS/Windows, just launch Docker Desktop (on Windows, run the build from a WSL2 terminal). |
|
|
| ### Build the image |
|
|
| ```bash |
| sudo modprobe loop # often already loaded (Ubuntu) — needed on Arch |
| docker build -t reachy-pi5 . |
| docker run --rm --privileged -v "$PWD/deploy:/pi-gen/deploy" reachy-pi5 |
| ``` |
|
|
| Image lands in `./deploy/*.zip`, then flash it (see [Getting started](#getting-started)). |
|
|
| > Override the daemon version with `docker build --build-arg DAEMON_VERSION=v1.8.4 -t reachy-pi5 .` |
| |
| ### CM5 variant (Wireless carrier) |
| |
| The **Reachy Mini Wireless** ships a CM4; a CM5 pops right into the carrier (see [the community swap thread](https://github.com/geerlingguy/raspberry-pi-pcie-devices/issues/800)). [Dockerfile.cm5](Dockerfile.cm5) builds the image for that swap: motor UART on `uart2-pi5` with the same udev alias, external antenna kept, the CSI camera keeps libcamera (do **not** use the Pi 5 image there, its camera fix targets the Lite's USB camera), and the WebRTC stream encodes with x264 in software since the CM5 has no hardware encoder ([docker/stage-cm5-fixes.sh](docker/stage-cm5-fixes.sh)). |
| |
| ```bash |
| docker build -f Dockerfile.cm5 -t reachy-cm5 . |
| docker run --rm --privileged -v "$PWD/deploy:/pi-gen/deploy" reachy-cm5 |
| ``` |
| |
| An eMMC CM5 flashes through `rpiboot`/usbboot rather than an SD card. ⚠️ Not yet tested on hardware: the [CM5 camera timeout](https://github.com/geerlingguy/raspberry-pi-pcie-devices/issues/800) reported by the community is an open question this image may still hit. |
| |
| ## First boot & SSH if needed |
| |
| The image ships the `pollen` user with SSH enabled — nothing to set up in Imager. |
| |
| ```bash |
| ssh pollen@reachy-mini.local # password: root |
| passwd # change it |
| ``` |
| |
| - Web UI / API: `http://reachy-mini.local:8000/` |
| - Pair from the app's **BLE SETUP** → `ReachyMini` |
| |
| Everything (services, the venv, sudo) is built around `pollen` — that's why you must not set a user in Imager. |
| |
| ## How it works |
| |
| The [Dockerfile](Dockerfile) downloads `reachy-mini-os`, patches `config.txt` (Pi 5 motor UART, antenna), pins the daemon, and bakes the fixes from [docker/stage-pi5-fixes.sh](docker/stage-pi5-fixes.sh). Each fix lives in `/etc`, `/usr/local`, or `sitecustomize.py`, so it survives reboots and daemon self-updates. |
| |
| ## Changelog |
| |
| Each release and what it brought is in [CHANGELOG.md](CHANGELOG.md). |
| |
