Decision 31: DTC clearing allowed, driver-initiated and confirmed, codes recorded first

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDwfd6Ki8UfG4hK6W5YpJz

OVERVIEW.md

@@ -3,6 +3,10 @@ type: reference
 ---
 # Project Yukart Overview
 
+**The goal:** take the car's telemetry, add more of our own, and do the calculations off the car's
+ECUs, so the results inform the **driver**. Yukart controls the driver's information, never the car
+(architecture decision 31).
+
 A Mitsubishi Z27AG Colt Ralliart, plus  
 
 A Jetson Orin Nano that can:

README.md

@@ -34,7 +34,7 @@ Planned repositories and the reasoning behind the split are described in
 |---|---|
 | NVIDIA Jetson Orin Nano Super (`mikkeli-orin-nano`) | Car unit: main compute, JetPack r36.4 / Ubuntu 22.04 |
 | NVIDIA Jetson Orin Nano Super (`mikkeli-orin-nano-2`) | Development unit: builds, CI, bench (see [REPOS](docs/REPOS.md)) |
-| PEAK PCAN-USB | Car CAN bus access (`can_pcan`, 500 kbps measured at the OBD port; `obd-poller` is its single writer) |
+| PEAK PCAN-USB | Car CAN bus access (`can_pcan`, 500 kbps measured at the OBD port; nothing transmits on it; OBD-II is on the K-line, through a Bluetooth ELM327) |
 | Onboard MTTCan | Second CAN interface (`can_onboard`) |
 | Waveshare SIM7600G-H-M.2 | LTE Cat 4 (povo, fallback uplink below WiFi/Ethernet) + GNSS |
 

docs/ARCHITECTURE.md

@@ -30,7 +30,7 @@ The Orin runs headless: no local video out. The tablet app is the display.
 | Service | Responsibility | Transmits on CAN |
 |---|---|---|
 | `can-bridge` | Read SocketCAN frames, timestamp, publish raw | No |
-| `obd-poller` | Active OBD-II PID request/response | **Yes** |
+| `obd-poller` | Active OBD-II PID request/response, on the K-line through the Bluetooth ELM327 (decision 30); never on CAN | **Yes** |
 | `gnss` | gpsd client → position, speed, time fix | No |
 | `decoder` | Raw frames → named signals via DBC | No |
 | `recorder` | Persist raw + decoded sessions to disk; raw CAN and GNSS read directly, not via the bus (decision 25) | No |
@@ -52,7 +52,8 @@ protocol, so it necessarily transmits onto a 2008 car's bus. Constraints that
 follow:
 
 - `can-bridge` runs listen-only and must never transmit.
-- `obd-poller` is the **single writer**. No other service opens a TX-capable socket.
+- `obd-poller` is the **single writer**: the only service that sends anything to the car, OBD-II
+  requests on the K-line through the ELM. No service transmits on CAN; none opens a TX-capable CAN socket.
 - Transmission is rate-limited and restricted to standard OBD-II diagnostic IDs.
 - TX is a distinct, explicitly enabled mode — not the default state on boot.
 
@@ -378,3 +379,5 @@ rewriting the document.
 | 27 | Camera live view is the one video stream to the tablet: its own connection beside the boundary, paced to the link (≤ ~4 MB/s), never on the bus. Exception to 20 | **Proposed** | 2026-10-11 |
 | 28 | Every Orin → tablet sender caps its socket (`SO_MAX_PACING_RATE`, ~5 MB/s); unpaced bursts stall the USB link for seconds | **Proposed** | 2026-10-11 |
 | 29 | `svc-vision` is Python: camera pipelines and inference live in that ecosystem. Exception to 5 | Accepted | 2026-10-12 |
+| 30 | The car's CAN broadcast is the source for every displayed vehicle value. OBD-II (K-line, ISO 9141-2, through the Bluetooth ELM327) is calibration, recorded beside the frames; a value proven absent from CAN may be displayed from OBD-II, and keeps its `obd_` name either way. GNSS speed is shown beside the decoded speed, to show their error. The ELM is the Orin's only way onto the K-line, so DTC scans go through it too; it is reached over classic Bluetooth serial (SPP, no pairing), BLE only if it proves as easy | Accepted | 2026-10-13 |
+| 31 | Yukart informs the driver; it never controls the car. It extracts the car's telemetry (CAN, OBD-II), adds its own (GNSS, IMU, camera), and does its calculations off the car's ECUs; the results go to the driver (display, voice). No actuation of any kind (locks, lights, throttle), by CAN transmit or by wiring into the car's switches. Asking is allowed: OBD-II requests over the K-line (live data, DTC reads) are active but leave the ECU as it was. Anything that changes an ECU's state is not (no actuator tests, no coding), with one exception: **DTC clearing** (mode 04) is allowed as a deliberate, driver-initiated action at the driver's own risk. It is never automatic, it asks for confirmation, and it reads and records the codes and freeze frame first, since mode 04 wipes them along with readiness. Decision 3's "no TX on CAN" follows from this rather than only from caution | Accepted | 2026-10-15 |

docs/ORIN-RUNTIME.md

@@ -17,7 +17,7 @@ repo, so it lives in the hub rather than in any one of them.
   ─────────────────────────────────────────────────────────
   serving        svc-gw, svc-nav
   processing     decoder, recorder
-  acquisition    can-bridge, obd-poller, gnss
+  acquisition    can-bridge, obd-poller, gnss, imu
   bus            mosquitto
   ─────────────────────────────────────────────────────────
   host           kernel modules, gpsd, ALSA, network         orin-nano-env-setup
@@ -68,7 +68,7 @@ Ordered by what is lost if a tier is late.
 |---|---|---|
 | 0 | kernel modules, gpsd, network | Host layer; nothing of ours can precede it |
 | 1 | `mosquitto`, `can-bridge`, `recorder` | **Data is lost if late.** Must reach ready fastest |
-| 2 | `decoder`, `gnss`, `obd-poller`, `orin-status` | Derive from tier 1; a late start loses nothing |
+| 2 | `decoder`, `gnss`, `imu`, `obd-poller`, `orin-status` | Derive from tier 1; a late start loses nothing |
 | 3 | `svc-gw`, `svc-nav`, `svc-vision` | Serving; a display can wait |
 | 4 | voice — ASR, TTS | Interactive; seconds late is harmless |
 

docs/REPOS.md

@@ -24,7 +24,7 @@ contracts repo, not copied into each consumer.
 | [orin-nano-env-setup](gitea:yukart/orin-nano-env-setup) | Jetson host bring-up |
 | [app-flutter](gitea:yukart/app-flutter) | Flutter display client |
 | [contracts](gitea:yukart/contracts) | Topic namespace, payload schemas, signal registry |
-| [svc-core](gitea:yukart/svc-core) | Acquisition + processing cluster: `recorder`, `decoder`, `orin-status`, `obd-poller` now; `can-bridge`, `gnss` to come |
+| [svc-core](gitea:yukart/svc-core) | Acquisition + processing cluster: `recorder`, `decoder`, `gnss`, `imu`, `orin-status`, `obd-poller` now; `can-bridge` to come |
 | [svc-gw](gitea:yukart/svc-gw) | Telemetry gateway — aggregation and the display boundary |
 | [svc-nav](gitea:yukart/svc-nav) | Navigation service — routing and guidance |
 | [svc-vision](gitea:yukart/svc-vision) | Camera: capture and the live view; recording and inference to come |

docs/ROADMAP.md

@@ -21,7 +21,7 @@ Getting the Jetson to see the hardware at all.
 - [x] SIM7600 LTE data path: QMI (self-built `qmi_wwan`), povo, metered, ranked
       below Ethernet/WiFi; failover tested, Tailscale stays reachable over LTE
 - [x] SIM7600 GNSS via gpsd (`/dev/sim7600-gps`): 3D fix in the car
-- [x] Kernel-update procedure for the out-of-tree modules (`pcan`, `qmi_wwan`) —
+- [x] Kernel-update procedure for the out-of-tree modules (`pcan`, `qmi_wwan`, `pl2303`) —
       documented, sources kept in `~/infra`; still manual, and breaks silently
       if forgotten
 - [x] Network time pinned to NICT; timezone `Asia/Tokyo`
@@ -70,14 +70,17 @@ mark …`, or the app's Mark button), on the same clock as the frames.
 - [x] `obd-poller` — active OBD-II PIDs, single writer, 2026-10-12: mode 01, the
       nine `obd2` signals (~10 Hz fast, 1 Hz slow), only while the bus is alive;
       `can_pcan` out of listen-only. Recorded beside the frames (`vehicle.ndjson`).
-      **Disabled 2026-10-13:** the Z27AG doesn't answer OBD-II on CAN (likely
-      K-line, pin 7); kept for later active-send use
+      2026-10-13: the Z27AG answers OBD-II only on the K-line (ISO 9141-2), so the
+      poller now goes through the Bluetooth ELM327 (classic serial, no pairing):
+      the `obd_*` signals, calibration references per decision 30
 - [ ] OBD-II beyond mode 01: DTC scan (modes 03/07/0A) and MUT-III `21 xx`
       requests, both needing multi-frame (ISO-TP) replies
 - [ ] First decoding captures in the car, per contracts
       `docs/impl/plans/Z27AG-CAPTURES.md` — first checklist session 2026-10-13
       (117 marks, yukart-data `can-captures/`); jack-stands section still to do
-- [ ] `gnss` — position/speed, useful as ground truth for validating decoded speed
+- [x] `gnss` — position/speed, useful as ground truth for validating decoded speed,
+      2026-10-13: svc-core `gnss`, the fix as `yukart/gnss/<signal>` (speed, heading,
+      position, altitude, satellites); `yukart/gnss/fix` for navigation still to come
 
 OBD-II gives standardised signals quickly and is worth doing early; it also
 provides a cross-check for reverse-engineered ones.