docs: update Hardware and Architecture sections — dual-radio, GPIO power, 4G modem, phone hotspot uplink

This commit is contained in:
Mathieu Moran
2026-08-11 22:06:05 -04:00
parent 44cd8bd192
commit 7de8948e08
+24 -12
View File
@@ -12,11 +12,19 @@ pick up the project without needing prior chat history.
- **Board**: Raspberry Pi 3 Model B Rev 1.2, 906MB RAM. Confirmed too weak to run an AI coding - **Board**: Raspberry Pi 3 Model B Rev 1.2, 906MB RAM. Confirmed too weak to run an AI coding
agent — all agent-assisted dev work happens on a separate local machine; the Pi is only used agent — all agent-assisted dev work happens on a separate local machine; the Pi is only used
for hardware bring-up/testing/deployment via SSH (`yaris@<pi-ip>`). for hardware bring-up/testing/deployment via SSH (`yaris@<pi-ip>`).
- **GPS/GSM**: Waveshare **SIM868 GSM/GPRS/GNSS/Bluetooth HAT**. Also has unused cellular - **WiFi**: Dual-radio setup — **TP-Link Archer T3U (RTL8812BU)** USB dongle as `wlan1` for
(GSM/GPRS) data capability, earmarked as a fallback internet uplink (see Remote Server phase). Internet uplink (home WiFi, phone hotspot), onboard BCM43438 as `wlan0` running a permanent
AP ("yaris 911" at 10.42.0.1, password "yaris911!"). Both radios active simultaneously.
- **GPS/GSM**: Waveshare **SIM868 GSM/GPRS/GNSS/Bluetooth HAT**. GNSS provides live GPS fixes
(confirmed working, ~7 satellites, ~80s cold-start TTFF). GSM/GPRS cellular is **not in use**
(no SIM card available); a Huawei **E3372h-153 4G LTE modem** has been purchased as a future
cellular uplink replacement (FEAT-04). SIM868 GPS antenna confirmed connected to correct u.FL
port (was briefly disconnected — reconnected and verified 2026-08-11).
- **OBD-II adapter**: a cheap unbranded USB adapter using a **PL2303** USB-to-serial chip, - **OBD-II adapter**: a cheap unbranded USB adapter using a **PL2303** USB-to-serial chip,
presumed ELM327-compatible (works with the `python-obd` library). Originally the project used ELM327-compatible (works with the `python-obd` library). Originally Bluetooth, switched to USB.
a Bluetooth OBD adapter; this has been switched to USB. - **Power**: Hard-wired 5V/GND directly to GPIO header (red to Pin 2, black to Pin 6), bypassing
the worn micro-USB connector. `vcgencmd get_throttled` returns `0x0` — no undervoltage or
throttling. Pi runs at full 1.2 GHz (was ~600 MHz downclocked before the fix).
- **Car**: 2013 Toyota Yaris. - **Car**: 2013 Toyota Yaris.
### SIM868 HAT bring-up notes (important gotchas) ### SIM868 HAT bring-up notes (important gotchas)
@@ -58,12 +66,13 @@ pick up the project without needing prior chat history.
OSM tile usage policy. Bounding box is a required CLI arg (the user's own driving area, not OSM tile usage policy. Bounding box is a required CLI arg (the user's own driving area, not
committed here), zoom 8-15 by default (~14k tiles for a city-plus-suburbs-sized area, well committed here), zoom 8-15 by default (~14k tiles for a city-plus-suburbs-sized area, well
under MapTiler's 100k/month free quota). under MapTiler's 100k/month free quota).
2. **WiFi hotspot mode**: Auto-switch — the Pi joins home WiFi when in range (for 2. **WiFi hotspot mode**: **Dual-radio** — the TP-Link Archer T3U (wlan1) handles all internet
syncing/updates), and falls back to broadcasting its own AP otherwise. **Important scope uplink traffic (home WiFi, phone hotspot), while the onboard WiFi (wlan0) runs a permanent
clarification**: the hotspot is *only* for local web-UI viewing on a phone/laptop while AP ("yaris 911" at 10.42.0.1) that is never taken down by the uplink manager. The hotspot
driving — it is not part of the upload path. Remote-server uploads happen independently via is *only* for local web-UI viewing on a phone/laptop while driving — it is not part of the
home WiFi (when in range) or the SIM868 cellular fallback (decision #5) — the phone connecting upload path. Remote-server uploads happen independently via home WiFi (when in range),
to the hotspot never relays/carries upload traffic. phone hotspot (Phase 22), or cellular fallback (decision #5). Phone-hotspot auto-connects
on wlan1 within ~60s of appearing, falls back to home-wifi when it disappears.
3. **Local/remote persistence**: Keep SQLite locally (reliable local write path per trip). The 3. **Local/remote persistence**: Keep SQLite locally (reliable local write path per trip). The
original plan paired this with MongoDB Atlas for remote sync (`modules/app_db.py`, fixed in original plan paired this with MongoDB Atlas for remote sync (`modules/app_db.py`, fixed in
Phase 7) — **superseded by decision #4/Phase 9**: the actual remote store is the self-hosted Phase 7) — **superseded by decision #4/Phase 9**: the actual remote store is the self-hosted
@@ -71,8 +80,11 @@ pick up the project without needing prior chat history.
into `app.py` and is effectively dead code at this point, kept only for reference. into `app.py` and is effectively dead code at this point, kept only for reference.
4. **Remote server**: Self-hosted — a custom server/API (e.g. on a home server or VPS) receives 4. **Remote server**: Self-hosted — a custom server/API (e.g. on a home server or VPS) receives
itinerary and dashcam uploads, rather than 3rd-party managed cloud services. itinerary and dashcam uploads, rather than 3rd-party managed cloud services.
5. **Remote upload uplink**: Use the SIM868's GSM/GPRS cellular connection as a fallback uplink 5. **Remote upload uplink**: Three paths, tried in order: (1) WiFi/Ethernet via `requests`,
for uploads when no WiFi is available (e.g. while driving), not just "sync when on home WiFi." (2) phone hotspot via wlan1 when configured and in range (Phase 22), (3) SIM868 GSM/GPRS
cellular fallback (AT-command HTTP client, tracking batches only — no dashcam video).
Cellular is **untested** (no SIM card). A Huawei E3372h-153 4G LTE modem has been purchased
to replace the 2G-only SIM868 cellular path once a SIM is available (FEAT-04).
## Phases ## Phases