diff --git a/docs/impl/plans/Z27AG-CAPTURES.md b/docs/impl/plans/Z27AG-CAPTURES.md new file mode 100644 index 0000000..bb8d6b9 --- /dev/null +++ b/docs/impl/plans/Z27AG-CAPTURES.md @@ -0,0 +1,102 @@ +--- +type: plan +status: ready +updated: 2026-10-12 +--- +# Z27AG decoding captures: what to do in the car + +Recordings that let the broadcast frames be decoded: one thing changes at a time, +each change is marked, and OBD-II mode 01 values are recorded alongside as the +ground truth. Prior art and first candidates: [the prior-art report](../reports/Z27AG-CAN-PRIOR-ART.md). + +## What records what + +| In the session directory | From | Use | +|---|---|---| +| `can-*.log(.zst)` | the PEAK, every frame, kernel timestamps | what gets decoded; also holds every OBD request (`7DF`) and reply (`7E8`) | +| `vehicle.ndjson` | `obd-poller` via the bus | the same OBD replies as values (rpm, speed, throttle, load, MAP, MAF ~10 Hz; coolant, intake air, fuel 1 Hz); `env.timestamp` equals the reply frame's timestamp | +| `events.ndjson` | marks from the app | when each step happened | +| `gnss.ndjson` | gpsd (SIM7600) | speed and position for the drive | + +## Operating the recorder from the app + +- **Sessions start by themselves** when the PEAK sees traffic (ignition on) and end + 15 s after it stops. There is no start/stop button; nothing to do. +- **Marks:** the **Mark** button → a quick chip, or type in *Other* and press enter. + A mark is stamped when the recorder receives it, on the same clock as the frames. +- **Check it landed:** the *Commands* list, at the top of the raw-messages pane (right + side, or the lower half on a narrow screen), shows `✓ ok: mark 3 in + 000042-…`. `✗ error: no session` means no traffic yet: ignition on, PEAK plugged. + A mark sent with the link down waits (`unacked`) and goes when it is back, with its + delay noted in the mark. +- **OBD is working** when `engine_rpm`, `vehicle_speed_kph` and the rest appear in + the signal list and move. If they never appear, see *If OBD stays silent*. + +## Marks + +Type the step number first, then what is happening: `3 brake on`, `3 brake off`. +One mark when an action starts and one when it ends is enough; a slow, steady +action between them beats a quick one. Wait about 3 s between steps. + +## Checklist + +**Before:** PEAK on the OBD port, Orin up, tablet connected. Engine off, doors shut. + +### Parked, ignition on, engine off + +| # | Do | Mark | Finds | +|---|---|---|---| +| 1 | Nothing for 20 s | `1 baseline` | the resting values of every ID | +| 2 | Accelerator: slowly to the floor over 5 s, hold 3 s, slowly back | `2 accel start` / `2 accel end` | pedal position (engine off: no rpm to confuse it) | +| 3 | Brake: press, hold 3 s, release; three times | `3 brake on` / `3 brake off` each time | brake switch, maybe pressure | +| 4 | Clutch: same, three times | `4 clutch on` / `4 clutch off` | clutch switch | +| 5 | Steering: centre → full left → full right → centre, slowly | `5 steer start` / `5 steer end` | steering angle | +| 6 | Gears: 1, 2, 3, 4, 5, R, neutral, 3 s each | `6 gear 1` … `6 gear R`, `6 neutral` | reverse switch (gear position if broadcast) | +| 7 | Handbrake up, down, up | `7 handbrake on` / `off` | handbrake switch | +| 8 | Indicator left 5 s, right 5 s, hazards 5 s | `8 left`, `8 right`, `8 hazard`, `8 off` | indicator states | +| 9 | Side lights, dipped, main beam, flash, fogs, off | one mark each | light states | +| 10 | Each door open/close, boot, bonnet | one mark each | door switches | +| 11 | Wipers int / low / high / off, washer | one mark each | wiper states | +| 12 | A/C on / off, blower up / down | one mark each | A/C request | +| 13 | Seatbelt on / off | `13 belt on` / `off` | belt switch | + +### Engine running, parked + +| # | Do | Mark | Finds | +|---|---|---|---| +| 14 | Cold start if possible; idle 60 s | `14 engine start` | coolant and oil warming; idle control | +| 15 | Revs in steps: hold 1500, 2000, 3000 rpm 5 s each, back to idle | `15 rpm 1500` … `15 idle` | engine speed (OBD rpm is the reference), throttle against pedal | +| 16 | Three sharp blips | `16 blips` | response timing of throttle, rpm, MAP | +| 17 | A/C on 20 s, off | `17 ac on` / `off` | compressor clutch, idle-up | +| 18 | Idle until the radiator fan cuts in, if it will | `18 fan` | fan state, coolant threshold | + +### Driving (a passenger types the marks, or skip them) + +| # | Do | Mark | Finds | +|---|---|---|---| +| 19 | Pull away; steady 20, 40, 60 km/h for 10 s each where safe | `19 steady 20` … (optional) | road and wheel speeds against OBD and GNSS speed | +| 20 | A gentle stop, a firmer stop | `20 stop` (optional) | brake pressure, deceleration | +| 21 | A few corners each way | — | yaw / lateral g, wheel speed differences | +| 22 | Each gear through the box | — | gear (from rpm ÷ speed if not broadcast) | + +Speed needs no marks: OBD speed and GNSS speed are recorded continuously. The +drive is the important part; the parked steps can be split over several sessions. + +## If OBD stays silent + +`yukart/system/obd-poller` says why (visible in `mosquitto_sub -v -t 'yukart/system/#'` +on the Orin): + +- `bus idle: not polling`: no traffic: ignition off or PEAK unplugged. +- `no ECU answers 01 00`: the engine ECU does not do standard mode 01 on this bus. + Then OBDb's MUT-III (`21 xx`) requests are the next thing to try. +- To see what answers, on the Orin: `sudo systemctl stop yukart-obd-poller`, + `yukart-obd-poller --once` (supported PIDs and one value each, with reply times), + `sudo systemctl start yukart-obd-poller`. Never two pollers at once: their + replies would cross. + +## Afterwards + +Sessions are in `/var/lib/yukart/recordings/` on the car Orin. Copy one off with +`rsync -a mikkeli-orin-nano:/var/lib/yukart/recordings// …` into +`yukart-data`, with a line in its README of what was done. diff --git a/schema/topics.json b/schema/topics.json index 7e5c61c..032d55d 100644 --- a/schema/topics.json +++ b/schema/topics.json @@ -12,7 +12,7 @@ "payload": "envelope", "retained": true, "rate": "1-50/s", - "publisher": "decoder", + "publisher": "decoder, obd-poller", "description": "One topic per signal, named exactly as in signals.json." }, "yukart/gnss/fix": {