MultiRoombaRover/docs/pi-deployment.md

Pi Deployment Guide

Tooling

Fedora 43:

sudo dnf install golang libgpiod

Cross-compiling roverd for Pi Zero 2 W (ARMv7):

cd pi/roverd
mkdir -p ../../dist
make pi-build

The binary is placed in dist/roverd (relative to the repo root).

Dummy rover build (for local testing)

If you need extra “virtual” rovers on your laptop/CI box, build the dummy binary:

cd pi/roverd
mkdir -p ../../dist
make dummy

Run the resulting dist/roverd-dummy on any machine; it will connect to the server, stream fake Group 100 sensor data, and log drive commands so you can test multi-rover features without additional hardware.

Automated installation (recommended)

Once the binary (and repo) are on the Pi, run the helper script from the repo root:

cd ~/MultiRoombaRover
sudo ./pi/install_roverd.sh --mediamtx

What the script does:

• creates the roverd (and optionally mediamtx) service users if missing and installs /usr/local/bin/roverd
• copies pi/roverd/roverd.sample.yaml to /etc/roverd.yaml if the file is absent (existing configs are left untouched)
• installs/enables the roverd.service systemd unit, restarting it automatically when a config already exists
• when --mediamtx is passed, downloads the requested mediaMTX release for the Pi’s architecture, installs it to /usr/local/bin/mediamtx, drops the sample config + unit, enables the service, and restarts it

Flags:

Flag	Purpose
-b PATH	use a different roverd binary (defaults to dist/roverd)
-c PATH	seed /etc/roverd.yaml from another template
--mediamtx	download/install mediaMTX plus the provided config + unit
--mediamtx-version X.Y.Z	override the mediaMTX release tag (default 1.15.3)

If the script installs the sample config, it will remind you to edit /etc/roverd.yaml before manually restarting the service: set name, serverUrl, serial device, BRC pin, battery thresholds, and the media.publishUrl that points at your central mediaMTX WHIP endpoint (for example https://control-server.local/whip/roomba-alpha).

Manual installation

1. Copy the binary and config:

   sudo useradd -r -s /usr/sbin/nologin roverd || true
   sudo install -o roverd -g roverd -m 0755 dist/roverd /usr/local/bin/roverd
   sudo install -o roverd -g roverd -m 0640 pi/roverd/roverd.sample.yaml /etc/roverd.yaml
   

   Adjust /etc/roverd.yaml for each rover: name, serverUrl (e.g. ws://control-server:8080/rover), serial port path, battery thresholds, GPIO pin for BRC, and the media publishUrl that points at the central media server’s WHIP endpoint for that rover.

2. Install the systemd unit:

   sudo install -m 0644 pi/systemd/roverd.service /etc/systemd/system/roverd.service
   sudo systemctl daemon-reload
   sudo systemctl enable --now roverd.service
   

roverd requires access to /dev/ttyAMA0 and /dev/gpiochip*; keeping it under its own user ensures the rest of the system stays isolated—just make sure the account belongs to the dialout and gpio groups so it can reach the UART and libgpiod.
mediamtx needs read access to the camera devices (/dev/media*, /dev/video*), so the install script adds its service account to the video group; if you created the user manually, make sure it belongs to video.
BRC note: configure brc.gpioPin (and brc.gpioChip if you’re not using gpiochip0) and ensure the roverd user has permission to toggle that line—no root privileges are required anymore.
If you set media.manage: true in /etc/roverd.yaml, make sure the roverd service account can invoke systemctl <action> <media.service> (either run the unit as root or grant sudo privileges for that command).

Configuring mediaMTX

1. Download the latest mediaMTX release for ARMv7 and place the binary at /usr/local/bin/mediamtx.
2. Copy the provided config:

   sudo useradd -r -s /usr/sbin/nologin mediamtx || true
   sudo install -d -o mediamtx -g mediamtx /etc/mediamtx
   sudo install -o mediamtx -g mediamtx -m 0644 pi/mediamtx/mediamtx.yml /etc/mediamtx/mediamtx.yml
   sudo install -m 0644 pi/systemd/mediamtx.service /etc/systemd/system/mediamtx.service
   sudo systemctl daemon-reload
   sudo systemctl enable --now mediamtx.service
   

The sample config uses the Raspberry Pi camera module as the source and enables the local mediaMTX HTTP API so roverd can health-check the service. Edit /etc/mediamtx/mediamtx.yml to point its WHIP client at your central media server (see mediamtx_server_integration.md for details).
Expose the mediaMTX HTTP API locally (default http://127.0.0.1:9997) and set media.healthUrl so roverd can monitor the pipeline; media.service should match the systemd unit name (default mediamtx.service).
Finally, edit /etc/mediamtx/mediamtx.yml so the Pi publishes the camera feed to your central control server via WHIP (for example by pointing it at https://control.example.com/whip/<roverName>). The Pi never serves viewers directly—drivers and spectators always watch through the control server.

Server + UI

From the repo root:

cd server
npm install
npm run start

This launches the HTTP server (serving the barebones UI) and the rover WebSocket endpoint at ws://<server>:8080/rover. The UI expects roverd instances to send hello frames so it can populate the rover list. Use the mode buttons to emit Start/Safe/Full/Passive/Dock commands (they send the raw OI opcode bytes), tap the sensor toggle to request Group 100 streaming, and use WASD for drive testing; the UI emits Drive Direct commands ~8 times per second, so the rover sees them immediately.