138 lines
7.8 KiB
Markdown
138 lines
7.8 KiB
Markdown
# yaris-obd 🚗📡
|
|
|
|
A Raspberry Pi 3-based OBD-II, GPS, and dashcam system for my 2013 Toyota Yaris. It 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.
|
|
|
|
<table>
|
|
<tr>
|
|
<td width="120">
|
|
<a href="https://open.spotify.com/playlist/5u9vSw39FrIz7KghBkmgH4">
|
|
<img src="https://image-cdn-fa.spotifycdn.com/image/ab67706c0000d72c979ac180a23a70139d1ebd81" width="100" />
|
|
</a>
|
|
</td>
|
|
<td>
|
|
|
|
**rené lévesque bangers**
|
|
i have a dream
|
|
|
|
[](https://open.spotify.com/playlist/5u9vSw39FrIz7KghBkmgH4)
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
## Screenshot
|
|
|
|
|
|
|
|
## Features
|
|
|
|
- 📊 **Live OBD-II data** over a cheap USB ELM327-compatible adapter: speed, RPM, coolant
|
|
temperature, fuel level, throttle position, MIL status, stored DTCs, and odometer when the ECU
|
|
supports it. Includes automatic background reconnects, serialized queries, and clear
|
|
adapter/ELM327/ECU diagnostics
|
|
- 🛰️ **Real GPS tracking** via a Waveshare SIM868 GNSS/GSM/Bluetooth HAT, plotted live on an
|
|
offline Leaflet map (pre-cached map tiles — no internet needed in the car). The module powers
|
|
itself on through the HAT's GPIO PWRKEY wiring after a Pi power cycle
|
|
- 📶 **Self-hosted WiFi hotspot** so you can load the web UI on your phone from inside the car,
|
|
with automatic switching back to home WiFi when it is available (`http://yaris.local` — no
|
|
port number)
|
|
- 🎥 **Dashcam file retrieval** — detects a USB dashcam automatically (any brand/folder layout,
|
|
no hardcoded device path), mounts it read-only, and safely copies footage locally. Verified
|
|
against a real 28GB/87-file import. The web UI can also browse, sort, and delete individual or
|
|
all videos directly from the connected dashcam with confirmed, temporary read-write operations,
|
|
plus import one file or any checkbox selection instead of always importing the whole card
|
|
- ▶️ **Local video library** — browse imported clips with cached thumbnails and upload status,
|
|
play H.264 footage inline with seeking, and delete only the local Pi copy. Optional retention
|
|
can automatically remove older local copies after their exact content is confirmed uploaded
|
|
- ☁️ **Remote upload** — a self-hosted server (Flask + Postgres, `server/`) receives trip/GPS
|
|
logs and dashcam footage over the internet (via Cloudflare Tunnel or a plain port-forward).
|
|
Dashcam videos upload in resumable 40MB chunks (works around tunnel body-size limits and keeps
|
|
the Pi's memory footprint flat regardless of file size); a UI toggle can pause dashcam uploads
|
|
independently while trip logs keep syncing
|
|
- 📡 **Optional cellular fallback** through the SIM868 for small trip-log uploads when normal
|
|
WiFi/Ethernet is unavailable (dashcam video stays off cellular)
|
|
- 🗄️ **Motion-aware local-first SQLite logging** — five-second motion checks without five-second
|
|
parked writes, plus retry-safe remote sync and automatic backoff
|
|
- 🌡️ **Pi health monitoring** — dashboard temperature, RAM, disk space, uptime, and explicit
|
|
undervoltage/throttling warnings from the Raspberry Pi firmware
|
|
- 🔔 **Offline-first alerts** — a notification bell on every page reports check-engine state,
|
|
storage pressure, upload backlog, temperature/power faults, and GPS loss while moving. Optional
|
|
ntfy delivery is available but remains disabled until configured
|
|
- 🛣️ **Trip history and route replay** — detects motion from OBD wheel speed with sustained GPS
|
|
displacement as a fallback, summarizes distance and speed in metric/imperial units, and replays
|
|
each route as a line on the offline map with a timestamped play/pause timeline and moving marker
|
|
- 🖥️ **Offline web UI** built with Flask, Jinja, Bootstrap 5, Socket.IO, Chart.js, and Leaflet,
|
|
all served locally with a shared responsive page shell
|
|
- 🔌 **Headless Pi deployment** as a self-restarting `systemd` service with a 10-second BCM2835
|
|
hardware watchdog, verified across a real reboot
|
|
|
|
## 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) |
|
|
| USB dashcam | Any brand — detected as generic USB mass storage |
|
|
| 2013 Toyota Yaris | The patient |
|
|
|
|
See [PLAN.md](./PLAN.md) for full hardware bring-up notes (SIM868 jumper/UART setup, antenna
|
|
gotchas, etc.) and the detailed project history.
|
|
|
|
## Getting started
|
|
|
|
```bash
|
|
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/](./deploy); see [PLAN.md](./PLAN.md) for the complete Pi setup and hardware notes.
|
|
|
|
For the remote server (receives trip logs + dashcam uploads), see [server/README.md](./server/README.md).
|
|
|
|
## Project status
|
|
|
|
This project was revived after a couple of years on the shelf. Phases 1-13 and 15-20 are complete:
|
|
real GNSS, hardened OBD support, offline maps/UI, automatic WiFi hotspot switching, local logging,
|
|
dashcam import, resumable remote upload, trip history/replay, deployment, and the shared UI
|
|
foundation are implemented.
|
|
The pipeline has been exercised on the real Pi and dashcam, including a complete 28GB import and
|
|
remote upload. Actual OBD PID availability still needs the first in-car test.
|
|
|
|
Phase 14 is partially complete: the Pi's hardware watchdog is deployed and reboot-verified.
|
|
Read-only-root storage hardening is deferred until persistent storage is moved off the SD root
|
|
partition, and clean shutdown still needs delayed-power or ignition-sense hardware.
|
|
|
|
The browser-based phone relay was removed after real-world testing confirmed that mobile browsers
|
|
cannot reliably use the Pi's WiFi and cellular data simultaneously. A native Android companion is
|
|
planned later instead. The next roadmap work is settings, followed by a final UI polish pass.
|
|
After the redesign, the same interface will become a secure remote trip portal backed by the
|
|
self-hosted server, including trip replay and browsing/playing/downloading archived dashcam videos,
|
|
with clear Local Pi/Remote Server labeling and hardware-only Pi sections omitted remotely. Full
|
|
phase history, verification notes, and current scope live in
|
|
[PLAN.md](./PLAN.md).
|
|
|
|
A temporary, removable real-vehicle compatibility test in the 2013 Yaris precedes the final
|
|
low-priority Android phase; bench and synthetic verification alone are not treated as
|
|
ready-to-install sign-off. Permanent installation is owner-handled and is not a roadmap phase.
|
|
|
|
The local Web UI also includes a Settings page for safe runtime configuration: dashcam uploads,
|
|
uploaded-video retention, cellular APN fallback, optional ntfy delivery, and alert thresholds.
|
|
Notification secrets are write-only in the browser API, and network credentials that could lock
|
|
the Pi out remain SSH/file-managed. When cellular is configured, small ntfy notifications use the
|
|
SIM868 first and WiFi/Ethernet only as fallback; that modem path is implemented and mock-tested but
|
|
still needs real-SIM/carrier verification.
|
|
|
|
A planned pre-redesign phase will also let the Pi join a configured phone hotspot for outbound
|
|
internet when no SIM is available, including queued trip/alert synchronization and WiFi dashcam
|
|
uploads, with automatic recovery to the Pi-hosted local hotspot when the phone is unavailable.
|