fallout.nav
A 2001 black‑and‑white reversing monitor, a Raspberry Pi Compute Module 4 and a wasteland navigator.
fallout.nav turns a Raspberry Pi CM4 into an in‑car computer for an old van:
- Dashcam — OV5647 camera, full 2592×1944 sensor (widest field of view) → hardware H.264 1440×1080 @ 15 fps,
loop recording in 10‑minute MPEG‑TS segments with
fsync every second: a power cut loses ≤ 2 s of video.
- Navigation screen in a Fallout / Mad Max style on a 5″ monochrome CRT (WAECO Mobitronic RV‑50):
Esri satellite imagery with streets, heading‑up rotation (the vehicle icon turns first, the map catches up),
zoom by speed, the camera view when stopped, three compass designs, a wasteland muscle‑car icon.
- Sensors — Holybro M8N GPS (u‑blox NEO‑M8N, 10 Hz, configured over UBX, Static Hold) and IST8310 compass
with automatic calibration against the GPS course while driving; heading fusion compass ↔ GPS.
- Web UI (laptop over Wi‑Fi) — dashboard, live camera (WebRTC), recordings with in‑browser playback,
navigation/compass/GPS/system settings, and a 1:1 physical‑size preview of the car screen.
- Composite video straight from the SoC — a wire on CM4 pin 111 (
VDAC_COMP), NTSC 480i/60 Hz with output
margins and mirroring tuned for the RV‑50. The button on the GPS module switches the video output off so it
does not bleed into the monitor's other camera input.
- Remote access over the internet — the device keeps an outgoing ssh tunnel to a public server (it sits behind
a phone hotspot), so the same web UI opens at
https://<server>/fnadmin/; live video there is a low‑bitrate
H.264 stream that is only encoded while someone watches.
- Internet radio on a Bluetooth speaker — stations from the radio-browser.info directory by mood, genre and era
(or by name), played by mpv through BlueZ + bluez-alsa (A2DP) on the CM4's on-board Bluetooth; the speaker is
paired from the web UI and reconnects by itself; the station resumes after a reboot. The car screen shows a
tuner panel with the station and the scrolling track title.
- Position log (Tracking) — a GPS point every minute, queued on the device while offline, merged on the server
into places and visits (the same spot within 50 m is not recorded twice); a hybrid Esri map with parking and
transit points, the visit history of each place, and the live vehicle position.
Project page with a live demo: https://ptrs.ltd/apps/fallout.nav/
Hardware
| Part | Notes |
|---|
| Raspberry Pi CM4 (eMMC, Wi‑Fi, 4 GB) on Waveshare CM4‑NANO‑B | Raspberry Pi OS (Debian 13 trixie) |
| OV5647 camera | CSI0, dtoverlay=ov5647,cam0 |
| Holybro M8N GPS + IST8310 compass (10‑pin JST‑GH) | UART5 /dev/gps0 + I2C‑1 |
| WAECO Mobitronic RV‑50 monitor | composite input, B/W CRT |
GPS module → 40‑pin header
| GH pin | Signal | → | 40‑pin | Pi signal |
|---|
| 1 | VCC 5V | → | 2 | 5V |
| 2 | RX (GPS input) | → | 32 | GPIO12 TXD5 |
| 3 | TX (GPS output) | → | 33 | GPIO13 RXD5 |
| 4 | SCL | → | 5 | GPIO3 SCL |
| 5 | SDA | → | 3 | GPIO2 SDA |
| 6 | SAFETY_SWITCH | → | 16 | GPIO23 — short press: video output on/off, long press: protect recording |
| 7 | SAFETY_SWITCH_LED | → | 18 | GPIO24 — blinks while recording |
| 8 | VDD_3V3 | → | 1 | 3.3V |
| 10 | GND | → | 6 | GND |
The GPS uses the PL011 UART5 (dtoverlay=uart5) so that the primary UART0 stays with the on‑board Bluetooth,
which plays the internet radio on a Bluetooth speaker.
Composite video
CM4 connector J2, pin 111 VDAC_COMP (inner/odd row, 6th from the pin‑101 end; its neighbours are
109 PCIe_nRST and 113 GND — "ground immediately on the far side" is the reliable check) → video pin of the
monitor input, GND → its ground. See docs/device-report.md.
Software
fnav/core FastAPI backend: auth, settings, 10 Hz WebSocket telemetry, nav logic, Esri tile cache, recordings, system
fnav/camera Picamera2 pipeline, crash-safe MPEG-TS recorder, RTSP to MediaMTX (WebRTC), MJPEG for the screen
fnav/sensors gpsd client, UBX configuration, IST8310 driver, calibration + GPS auto-calibration, heading fusion, GPIO
web/display the car screen (Canvas renderer for Esri tiles + Pip-Boy HUD), also runs as an in-browser demo (?demo=1)
web/admin the web UI
pi/ install.sh, deploy.sh, systemd units, boot config, MediaMTX, sudoers/polkit
server/ fnav-relay (position log, login while the device is offline; stdlib Python) and the nginx snippet
tools/ remote.sh (server + tunnel setup), publish_site.sh, UBX/I2C helpers
site/ the project page
Services on the device: fnav-core (port 80; 127.0.0.1:8090 for the tunnel), fnav-camera, mediamtx,
fnav-display (cage + Chromium kiosk), fnav-radio (mpv), bluetooth + bluealsa, fnav-tunnel, gpsd, chrony.
Weather on the car screen (now + the next two days while the radio is off, wind streaks around the vehicle):
Open-Meteo for the GPS position, every 30 min or after 25 km, cached for offline use
(fnav/core/weather.py). Weather data by Open-Meteo.com, CC BY 4.0.
Speed limit sign next to the speedometer: offline OpenStreetMap roads. tools/speedlimits.sh builds the database on
the server from the Geofabrik extract (Poland by default; implicit limits such as PL:urban and defaults by road
class) and copies it to /var/lib/fnav/speedlimits.sqlite; fnav/core/speedlimit.py matches the GPS position and
course to the road once a second. Rerun the script now and then for fresh data. Data © OpenStreetMap contributors, ODbL.
Install on the device
pi/deploy.sh --stage # from a PC (Git Bash / Linux): upload the repo to the device
ssh <device> 'cd ~/fallout.nav && sudo ./pi/install.sh && sudo reboot'
pi/deploy.sh # later updates
Remote access and the position log
browser ─ https://<server>/fnadmin/ ─ nginx ─┬─ static copy of web/ (opens even when the device is off)
├─ /api/tracking/ → fnav-relay (the log lives on the server)
└─ /api, /ws → 127.0.0.1:18080 ─ ssh -R ─ device fnav-core :8090
device: fnav-core ─ a point a minute → SQLite outbox ─ ssh -L 127.0.0.1:18095 → fnav-relay
Requests through the tunnel arrive at a separate listener with no localhost trust; the password is the same as on
the device (the server checks the same session cookie). One-time setup from a PC, after pi/deploy.sh:
cp tools/remote.env.example tools/.remote.env # server login, site name, nginx site file
tools/remote.sh setup # relay, nginx, tunnel user/key, device config, web copy
tools/remote.sh web # after UI changes
Details: docs/contracts/remote.md.
Develop on a PC (no hardware)
pip install -e .[dev]
python -m fnav.core --mock --port 8000 # http://127.0.0.1:8000/admin/ (password: fnav-dev)
python -m fnav.camera --fake # synthetic camera + recorder
python -m pytest # Python tests (core, camera, sensors, server)
node --test tests/display/*.test.mjs # display tests
How it was built
The project was designed and written in about a day by Claude acting as lead/integrator with seven parallel
sub‑agents (backend, map renderer, HUD design, web UI, camera/recorder, sensors, system), coordinated through
written contracts in docs/contracts/. Plan and decisions: PLAN.md; hardware bring‑up notes:
docs/device-report.md.
Map imagery © Esri and its data providers (Esri, Maxar, Earthstar Geographics and the GIS user community).
License
MIT — see LICENSE. Third‑party parts keep their own licenses: fonts in web/display/ui/fonts/
(SIL OFL 1.1, see LICENSES.md there) and web/admin/vendor/mpegts.js (Apache‑2.0).
