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
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>`).
- **GPS/GSM**: Waveshare **SIM868 GSM/GPRS/GNSS/Bluetooth HAT**. Also has unused cellular
(GSM/GPRS) data capability, earmarked as a fallback internet uplink (see Remote Server phase).
- **WiFi**: Dual-radio setup — **TP-Link Archer T3U (RTL8812BU)** USB dongle as `wlan1` for
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,
presumed ELM327-compatible (works with the `python-obd` library). Originally the project used
a Bluetooth OBD adapter; this has been switched to USB.
ELM327-compatible (works with the `python-obd` library). Originally Bluetooth, 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.
### 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
committed here), zoom 8-15 by default (~14k tiles for a city-plus-suburbs-sized area, well
under MapTiler's 100k/month free quota).
2. **WiFi hotspot mode**: Auto-switch — the Pi joins home WiFi when in range (for
syncing/updates), and falls back to broadcasting its own AP otherwise. **Important scope
clarification**: the hotspot is *only* for local web-UI viewing on a phone/laptop while
driving — it is not part of the upload path. Remote-server uploads happen independently via
home WiFi (when in range) or the SIM868 cellular fallback (decision #5) — the phone connecting
to the hotspot never relays/carries upload traffic.
2. **WiFi hotspot mode**: **Dual-radio** — the TP-Link Archer T3U (wlan1) handles all internet
uplink traffic (home WiFi, phone hotspot), while the onboard WiFi (wlan0) runs a permanent
AP ("yaris 911" at 10.42.0.1) that is never taken down by the uplink manager. The hotspot
is *only* for local web-UI viewing on a phone/laptop while driving — it is not part of the
upload path. Remote-server uploads happen independently via home WiFi (when in range),
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
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
@@ -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.
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.
5. **Remote upload uplink**: Use the SIM868's GSM/GPRS cellular connection as a fallback uplink
for uploads when no WiFi is available (e.g. while driving), not just "sync when on home WiFi."
5. **Remote upload uplink**: Three paths, tried in order: (1) WiFi/Ethernet via `requests`,
(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