yaris-obd
A Raspberry Pi 3-based OBD-II, GPS, and dashcam system for a 2013 Toyota Yaris. Reads live vehicle data over USB, tracks position with a SIM868 GNSS/GSM HAT, logs everything locally, and serves a web UI over the car's own WiFi hotspot. The dashboard and pre-cached map work fully offline, while trip data and dashcam footage sync to a self-hosted remote server whenever an internet uplink is available.
|
rené lévesque bangers i have a dream |
Screenshots
Dashboard — mobile (390 px) and desktop (1280 px):
Features
- Live OBD-II data — speed, RPM, coolant temp, fuel level, throttle, MIL/DTC via USB ELM327. Automatic reconnects with clear adapter/ECU diagnostics. DTC codes persist across reboots and can be cleared straight from the DTC page.
- Real GPS tracking — Waveshare SIM868 GNSS HAT with GPIO PWRKEY auto-power-on. Live position plotted on an offline Leaflet map (pre-cached tiles, no internet needed).
- WiFi hotspot — fast 5GHz in-car AP on a T3U (wlan1), internet uplink (home WiFi + phone hotspot) on a second T3U (wlan2); the onboard radio is a fallback. SSID/password configurable from the Settings page.
- Dashcam workflow — auto-detects any USB dashcam, mounts read-only, browses files before importing. Import one, selected, or all files. Delete individual or all files directly from the dashcam. Verified against real 28GB/87-file hardware.
- Local video library — browse imported clips with cached thumbnails and upload status. Inline H.264 playback with seeking. Local-only delete. Optional auto-retention after confirmed upload.
- Remote sync — trip logs and dashcam footage upload to a self-hosted Flask + Postgres server. Dashcam videos stream in resumable 40MB chunks. Independent toggles for trip and dashcam uploads.
- Remote web portal — login-protected at the server URL. Trip history with CARTO live map and route replay, dashcam archive with inline player, overview stats, device management (create/delete/rotate keys), and server-side device identity sync that hot-reloads on the Pi.
- Trip history and replay — motion-aware detection (OBD wheel speed primary, GPS displacement fallback). Metric summaries, offline route polyline, play/pause timeline with moving marker and live reverse-geocoded location names. Tap-to-replay on mobile. Captures OBD speed before the first GPS fix so rolling starts aren't lost.
- Status page — Pi health (temp, RAM, disk, uptime, throttling), service states, uplink/server/ GPS/OBD diagnostics, and quick actions (test server, sync now, reconnect uplink, restart app).
- Offline-first alerts — notification bell on every page for check-engine, storage pressure, upload backlog, temperature/power faults, and GPS loss while moving. Optional ntfy push.
- Manual odometer — Pi Settings page accepts a baseline reading; dashboard computes
odometer = baseline + trip distance. Synced to the remote server; portal shows read-only value. - Device config sync — server-side owner name, car model, display name, avatar path, and sync toggle hot-reload on the Pi without restart. Multi-device management on the portal with create/rotate/delete keys and one-time API-key reveal.
- Reverse geocoding —
/api/geocodeusesreverse_geocoderoffline (no internet needed), upgrades to Nominatim street-level when online. LRU-cached. Results pre-loaded for trip scrubbing. - Android companion app — native Kotlin app in
android/(Phase 28, in progress). Dual-network on the phone: browse + download dashcam clips over the car's WiFi, relay uploads over cellular. Networking gate + dashcam browser/download verified on a Pixel; cellular upload in progress. - Offline web UI — Flask, Bootstrap 5, Socket.IO, Chart.js, Leaflet. All assets served locally. Responsive with collapsible sidebar and mobile bottom nav.
- Headless deployment — systemd service with auto-restart, 10-second hardware watchdog, and
nftables port-80 redirect. Deploy scripts in
deploy/.
Hardware
| Part | Notes |
|---|---|
| Raspberry Pi 3 Model B Rev 1.2 | Web UI host, logger, uploader, and WiFi hotspot |
| Waveshare SIM868 HAT | GNSS (GPS) + optional GSM/GPRS uplink, unused Bluetooth |
| USB OBD-II adapter | PL2303-based, ELM327-compatible (originally Bluetooth, switched to USB) |
| 2× TP-Link Archer T3U (RTL8812BU) | USB WiFi dongles — AC1300 dual-band. wlan1 hosts the 5GHz in-car AP; wlan2 carries the internet uplink since 2026-08-14 |
| Onboard BCM43438 (wlan0) | Fallback only — was the internet uplink until 2026-08-14 |
| USB dashcam | Any brand — detected as generic USB mass storage |
| 2013 Toyota Yaris | The patient |
See PLAN.md for full hardware bring-up notes (SIM868 jumper/UART setup, antenna gotchas, etc.) and the detailed project history.
Getting started
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 app.py
The app serves on http://<host>:5000. On the Pi it runs as a systemd service and is reachable
with no port number at http://yaris.local after installing the mDNS and port-redirect setup.
Deployment helpers for the app service, hotspot watcher, port redirect, and hardware watchdog are
in deploy/. For a clean-install walkthrough on a fresh Pi, use
deploy/readme.md. See PLAN.md for the full hardware/project history.
For the remote server (receives trip logs + dashcam uploads), see server/README.md.
Customizing device identity
The Pi displays an owner name, car model, device name, and avatar. You can manage those values in two ways:
- Locally on the Pi through the Settings page
- From the server portal when Sync with server is enabled on the Pi
The local fallback/default source remains config/device.json, so the car still boots with sensible identity values even when fully offline.
Edit device configuration
Edit config/device.json:
{
"owner_name": "quoije",
"car_model": "Yaris 2013",
"device_name": "Yaris OBD",
"avatar_path": "img/yaris.png"
}
| Field | Location | Purpose |
|---|---|---|
owner_name |
Top-right of app topbar | Your name/username |
car_model |
Left sidebar (next to car icon) | Vehicle model/year |
device_name |
Local settings / remote portal | Device identity used by server sync/provisioning |
avatar_path |
Top-right avatar circle | Profile picture (relative to static/) |
If you edit the JSON file directly, restart the app:
# If running as a systemd service:
sudo systemctl restart yaris-obd.service
# If running manually:
# Ctrl+C and python3 app.py
Changing the profile picture
Option 1: Replace the default image file:
cp /path/to/your/image.png static/img/yaris.png
Option 2: Add your image to static/img/ and update avatar_path:
{
"avatar_path": "img/my-avatar.png"
}
Important: Username and database filename
The local SQLite database filename is based on owner_name: db/sql/<owner_name>_<car_model>.db (via modules/app_sql.py).
If you change owner_name and already have trip data:
- The app will create a new database with the new name
- Your old database remains at
db/sql/quoije_Yaris2013.db(orphaned)
To preserve your data:
# Option 1: Rename the database file
mv db/sql/quoije_Yaris2013.db "db/sql/YourName_YourCar.db"
# Option 2: Start fresh
rm db/sql/quoije_Yaris2013.db
Project status
The Pi app, remote server, device sync, and the Android companion app are implemented and verified on real hardware. Phase 25 (road test) ✅, Phase 26 (road-test bug fixes — 13 bugs) ✅, Phase 27 (feature additions — DTC history sync, manual odometer, hotspot settings + 5GHz WiFi swap, trip-history odometer) ✅. Phase 28 (Android companion app) 🚧 in progress — networking gate + dashcam browser/download done, cellular upload queue in progress.
Full phase history and verification notes live in PLAN.md. Open issues in BUGS.md. Feature requests in FEATURES.md.
Diagnostics & recovery
If something goes wrong in the car, SSH in and run:
bash ~/app/yaris-obd/scripts/diagnose.sh # read-only health check
bash ~/app/yaris-obd/scripts/diagnose.sh --fix # attempt auto-fix
Checks service state, OBD/UART hardware, disk/DB health, upload backlog, Pi throttling, and prints a cheatsheet of recovery commands. Exit code = number of critical issues found.
Hardware photo
