Fpv rover

FPV Rover

Monorepo for an FPV rover (LEGO Audi e-tron) controlled from a web UI with live video, telemetry OSD, and optional physical gamepad input.

Contents

• Overview
• Hardware requirements
• KiCad project
• Software requirements
• Installation and updates
  • Prerequisites on the Pi
  • First install (bootstrap)
  • Updating to a new version
• Technical reference
  • Repository structure
  • Backend modules
  • Environment variables
  • Local development
  • Backend ↔ frontend sync
  • Infra / Docker
  • Releasing a new version
  • Boot persistence (optional)

Overview

The project follows a modular architecture: each hardware capability (motion, power, thermal, IMU, light, camera, gamepad) is an independent backend module under backend/modules/<name>/. Gamepads connect over USB or Bluetooth (the bluetooth module handles wireless pairing; gamepad reads input via evdev). Modules are toggled at runtime via ROVER_MODULES_* feature flags in .env — only enabled modules are loaded, initialized, and exposed to the UI.

This design lets you mix and match hardware configurations without changing application code. A minimal bench setup might enable only camera and motion; a fully instrumented rover can enable every sensor. The frontend reads module flags from GET /config on startup and shows or hides controls accordingly.

The stack runs on Raspberry Pi (reference build: Pi Zero 2 W) inside Docker Compose: FastAPI backend, React SPA, nginx reverse proxy, MediaMTX for WebRTC video, and a pigpio sidecar for GPIO/PWM motor control.

Hardware requirements

The reference rover is built around a Raspberry Pi (64-bit). Peripherals connect over the buses listed below.

Host interfaces to enable

Before deployment, enable these on the Pi (see Prerequisites on the Pi):

Motion and gamepad modules require the pigpiod Docker sidecar. Without pigpio or when the daemon is unreachable, motion falls back to mock hardware (useful for local dev).

KiCad project

Electrical design lives in hardware/ as a KiCad 10 project. The schematic captures the wiring described in SCHEMA.md (main board + expansion board buses, power path, motor drivers, sensors); SCHEMA.md remains the physical wiring source of truth.

To view the design, open the PDF/SVG exports. To edit, open fpv-rover.kicad_pro in KiCad 10+ and re-export the PDF/SVG afterwards so the rendered files stay in sync.

Software requirements

For local development on any OS: Python 3.12+ with uv, Node.js 20+ for the frontend.

Installation and updates

On Raspberry Pi, backend, frontend, and mediamtx images are built in GitHub Actions (arm64) and pulled at runtime — no local npm run build or docker compose build on the device.

Prerequisites on the Pi

Bootstrap requires git, curl, Docker, and the Docker Compose plugin. On a fresh Raspberry Pi OS image these are often missing.

1. Git and curl

sudo apt update
sudo apt install -y git curl

2. Docker and Docker Compose

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker "$USER"
newgrp docker

Log out and back in (or run newgrp docker) so your user can run Docker without sudo.

Verify:

docker --version
docker compose version
docker ps

3. I2C and 1-Wire

Backend expects /dev/i2c-1 and /sys/bus/w1 on the host. Enable both before bootstrap — sensors do not need to be connected yet.

sudo raspi-config
# Interface Options → I2C → Enable
# Interface Options → 1-Wire → Enable
sudo reboot

Or add to /boot/firmware/config.txt (older images: /boot/config.txt):

dtparam=i2c_arm=on
dtoverlay=w1-gpio,gpiopin=4

After reboot, verify:

ls /dev/i2c-1
ls /sys/bus/w1

gpiopin=4 matches the default ROVER_W1_GPIO=4 in .env.example.

4. Arducam IMX462 camera drivers

The IMX462 is an Arducam Pivariety module. It requires Arducam's custom libcamera stack and a device-tree overlay on the host (outside Docker). Follow the Arducam Pivariety Quick Start Guide.

Step 1 — download the install script:

wget -O install_pivariety_pkgs.sh https://github.com/ArduCAM/Arducam-Pivariety-V4L2-Driver/releases/download/install_script/install_pivariety_pkgs.sh
chmod +x install_pivariety_pkgs.sh

Step 2 — install Arducam libcamera (on the Pi host, before or after bootstrap):

./install_pivariety_pkgs.sh -p libcamera_dev
./install_pivariety_pkgs.sh -p libcamera_apps

No reboot yet — proceed to Step 3.

Step 3 — enable the camera overlay in /boot/firmware/config.txt (Pi 4/5 Bookworm/Trixie; older images may use /boot/config.txt):

camera_auto_detect=0
dtoverlay=arducam-pivariety

On Pi 5 / CM5 with the camera on the CAM0 port, use dtoverlay=arducam-pivariety,cam0 instead.

Save and reboot:

sudo reboot

Verify after reboot:

rpicam-still --list-cameras    # Bookworm / Trixie
# or: libcamera-still --list-cameras   # Bullseye
ls /dev/video0

The MediaMTX container ships with Arducam libcamera libraries baked in (infra/mediamtx/Dockerfile); the host overlay and libcamera packages are still required for the camera device node to appear.

If you see Configuration file 'arducam-pivariety.json' not found for IPA module 'rpi/pisp', it can be safely ignored — the config is embedded in camera firmware.

5. SSH deploy key

Bootstrap can generate one interactively, or configure manually:

ssh-keygen -t ed25519 -f ~/.ssh/fpv_rover_deploy -N ""
cat ~/.ssh/fpv_rover_deploy.pub

Add the public key in GitHub → Settings → Deploy keys (read-only).

~/.ssh/config:

Host github.com
  IdentityFile ~/.ssh/fpv_rover_deploy
  IdentitiesOnly yes

6. GHCR login (only if images are private)

echo "$GITHUB_PAT" | docker login ghcr.io -u YOUR_GITHUB_USER --password-stdin

PAT needs read:packages. Public GHCR packages do not require login.

First install (bootstrap)

sudo mkdir -p /opt/fpv-rover && sudo chown "$USER" /opt/fpv-rover
git clone git@github.com:Aspience/fpv-rover.git /opt/fpv-rover
cd /opt/fpv-rover
./scripts/bootstrap.sh --enable-systemd
# or pin a release tag:
./scripts/bootstrap.sh --tag v0.1.5 --enable-systemd

Bootstrap creates .env from .env.example with production values (ROVER_OTA_ENABLED=true, VITE_RPI_HOST, IMAGE_TAG, etc.). It does not create .env.local.

Before pulling images, bootstrap pauses so you can edit env interactively (opens ${EDITOR:-nano} on request). Set module flags, confirm VITE_RPI_HOST, and optionally create .env.local for hardware IDs — then press Enter to continue.

Example .env.local (do not copy the full .env.example — .env.local overrides .env and would reset OTA settings to example defaults):

ROVER_MODULES_MOTION_ENABLED=true
ROVER_MODULES_GAMEPAD_ENABLED=true
ROVER_MODULES_CAMERA_ENABLED=true
ROVER_THERMAL_SENSOR_IDS={"motor_steering":"28-..."}

Use --non-interactive to skip the env edit pause when env is preconfigured.

Bootstrap options

Logs: /opt/fpv-rover/logs/bootstrap.log

tail -100 /opt/fpv-rover/logs/bootstrap.log

Updating to a new version

From the UI

Open Settings → Check for updates → Install update. The UI shows a fullscreen overlay while the rover restarts and polls GET /health every 3 seconds until the backend is back.

Requires ROVER_OTA_ENABLED=true (set by bootstrap on production installs).

Manual update / rollback (OTA script)

cd /opt/fpv-rover
./scripts/ota_update.sh v0.2.0        # upgrade (prompts for confirmation)
./scripts/ota_update.sh v0.1.0        # rollback (prompts for confirmation)
./scripts/ota_update.sh v0.2.0 --yes  # skip the confirmation prompt

The script waits 3 seconds (so the API can respond), fetches the git tag, resolves per-service image tags from image-tags.env (with nearest-tag fallback for older releases), pulls Docker images, and runs docker compose up -d. It never overwrites .env or .env.local.

Before any destructive step the script asks:

Update from v0.1.0 to v0.2.0? [y/N]

The prompt is skipped when running non-interactively (backend OTA API), with --yes/-y, or when ROVER_OTA_ASSUME_YES=1.

Logs: /opt/fpv-rover/logs/ota.log

tail -100 /opt/fpv-rover/logs/ota.log

Technical reference

Repository structure

fpv-rover/
├── backend/          # Python — FastAPI, hardware modules, WebSocket
│   ├── api/          # REST routes, WebSocket handler, command/telemetry schemas
│   ├── core/         # Settings, event bus, module registry, startup
│   ├── modules/      # Pluggable hardware modules (see below)
│   └── tests/
├── frontend/         # React SPA — live video, OSD, motion levers, settings
├── infra/            # Nginx reverse proxy, MediaMTX, systemd unit
├── scripts/          # Bootstrap and OTA update scripts
├── .env.example      # Shared environment template (backend + frontend)
└── docker-compose.yml

Each backend module typically has *.module.py, *.schema.py, *.config.py, and optional *.utils.py / *.service.py.

Backend modules

When ROVER_MODULES_MOTION_ENABLED=true, the backend runs steering calibration automatically on startup (core/startup.py). Physical gamepad input requires both ROVER_MODULES_GAMEPAD_ENABLED and ROVER_MODULES_MOTION_ENABLED.

Motion tuning constants (PID loop rate, homing power, throttle limits) live in motion.config.py. Gamepad evdev codes and poll intervals — in gamepad.config.py. GPIO pins, PID gains, and speed limits are runtime settings via ROVER_* env.

Environment variables

Both backend and frontend read from a single root .env file:

cp .env.example .env

On the Pi or in Docker, optional .env.local overrides .env without touching git-tracked files.

Feature flags

Backend loads ROVER_* via pydantic-settings (backend/core/config.py).
Frontend loads VITE_* via Vite with envDir pointing at the repo root (frontend/vite.config.ts).

Note: VITE_* variables are embedded at build time. After changing them, rebuild the frontend (npm run build or docker compose build frontend).

Motion & pigpio

Global backend

MediaMTX

Hardware addresses & devices

Frontend (build-time)

Docker / OTA (production)

Per-service tag precedence: on deploy/OTA, tags are resolved as (1) explicit pin in .env.local, then (2) image-tags.env from the checked-out release, then (3) nearest existing GHCR tag. To pin a specific service tag, put it in .env.local (not .env, which the OTA script rewrites).

Compose also uses PIGPIOD_IMAGE (default zinen2/alpine-pigpiod:pigpio-v79) for the GPIO sidecar.

Production images are pulled from ${FPV_ROVER_IMAGE_REGISTRY}/${ROVER_GITHUB_OWNER}/${ROVER_GITHUB_REPO}-{backend,frontend,mediamtx}.

Local development

Backend

uv sync --project backend
uv run --project backend pytest
uv run --project backend ruff check
uv run --project backend ruff format
uv run --project backend fpv-rover

API: http://localhost:8000 — OpenAPI docs at /docs.

Install pre-commit hooks (from repo root):

uv run --project backend pre-commit install

Frontend

React 19 SPA: live video (WebRTC), telemetry OSD, on-screen throttle/steer levers, keyboard shortcuts, light and camera controls. Physical gamepads are handled on the backend (evdev).

Stack: React 19, TypeScript, Vite 8, Tailwind CSS 4, Zustand, Zod, Axios.

cd frontend
npm ci
npm run dev          # http://localhost:5173
npm run build        # production bundle → dist/
npm run lint
npm run preview

Run backend and frontend in separate terminals:

# terminal 1
uv run --project backend fpv-rover

# terminal 2
cd frontend && npm run dev

Vite proxies /api and /ws to the backend using VITE_RPI_HOST and VITE_API_PORT.

Backend ↔ frontend sync

The UI talks to the backend over three channels. Keep their contracts aligned when you change either side.

1. Shared configuration (.env)

Module flags (ROVER_MODULES_*) are exposed via GET /config; the frontend fetches them on startup.

When deploying on a Pi or via Docker, REST and WebSocket use nginx on port 80 (/api, /ws). WebRTC/WHEP uses window.location.hostname and VITE_WEBRTC_PORT (not proxied through nginx).

2. REST — module flags

After changing the REST API:

1. Update Pydantic models in backend/modules/<name>/<name>.schema.py or backend/core/schemas/.
2. Run uv run --project backend pytest.
3. Mirror the shape in frontend/src/types/schemas.ts (Zod) and frontend/src/types/contracts.ts.
4. Optionally regenerate REST types (backend must be running): cd frontend && npm run generate:api

3. WebSocket — telemetry and commands

Message types:

• Telemetry (default 20 Hz): { type: "telemetry", modules: { power?, motion?, light?, thermal?, imu?, bluetooth?, gamepad? } }
• Commands (frontend): heartbeat (every 500 ms), move, calibrate, set_brightness
• Commands (backend only today): record — not yet sent from the UI
• Errors: { type: "error", message: string }

Motion control from the UI, keyboard, or physical gamepad converges on the same backend path. Use GET /ws-protocol on a running backend to inspect documented JSON shapes.

Note: STEER_MAX_DEG in frontend/src/constants.ts is hardcoded (default 45°). Keep it aligned with ROVER_MOTION_STEER_MAX_DEG when you change steering limits.

4. Video — WebRTC (WHEP)

Video does not go through FastAPI. MediaMTX serves the stream; the frontend connects via WHEP:

• Stream path: rover (see infra/mediamtx/mediamtx.yml)
• Frontend: POST http://{host}:{VITE_WEBRTC_PORT}/rover/whep
• Backend camera module controls recording via ROVER_MEDIAMTX_API_URL

Keep VITE_WEBRTC_PORT aligned with MediaMTX webrtcAddress (default 8889).

Sync checklist

When you add or change an API field:

• Pydantic model in backend/modules/<name>/<name>.schema.py (or backend/api/schemas/)
• Zod schema in frontend/src/types/schemas.ts
• TypeScript interface in frontend/src/types/contracts.ts (if applicable)
• Backend tests (pytest)
• Manual check: backend running + npm run dev or built frontend

Infra / Docker

cp .env.example .env
docker compose up --build

Pi device mounts in docker-compose.yml: /dev/i2c-1, /dev/video0, /dev/input (gamepad), /sys/bus/w1 (1-Wire), /dev/gpiochip0 (pigpiod sidecar).

Production UI on port 80: REST → /api, WebSocket → /ws. WebRTC/WHEP → http://<pi-ip>:8889/rover/whep.

Locally, mediamtx is built from infra/mediamtx/Dockerfile; production pulls a pre-built image from GHCR.

Releasing a new version

git tag v0.2.0
git push origin v0.2.0

GitHub Actions (.github/workflows/release.yml) builds arm64 backend, frontend, and mediamtx images and pushes them to GHCR. Each service is rebuilt only when its context changed since the previous v* tag. Skipped services keep their previous image tag.

The workflow writes image-tags.env with resolved tags per service. Release assets include image-tags.env, compose files, infra/**/*, OTA/bootstrap scripts, and .env.example.

Boot persistence (optional)

Bootstrap can install the systemd unit with --enable-systemd, or manually:

sudo cp infra/systemd/fpv-rover.service /etc/systemd/system/
sudo systemctl enable --now fpv-rover