docs/impl/plans/Z27AG-CAPTURES.md

---
type: plan
status: ready
updated: 2026-10-13
---
# 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 from the app's **Captures** page, 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 it 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.
- **Captures** (top bar) opens the checklist. Each step shows what to do and one big
  button: **Start** as the action begins, **End** as it ends (a running timer shows
  the suggested hold); a single moment is one **Mark**. When a step's actions are done
  the button says **Next step**: a natural pause, about 3 s, before the next.
  **Redo step** and **Skip step** say so in the recording; the step list (left, or
  the list icon on a narrow screen) jumps anywhere. Leaving a step mid-action marks
  that action aborted.
- **Check it landed:** under the button, the last mark and `✓`, or `✗ error: no
  session` when there is 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.
- The **Mark** button on the main screen is still there for anything off-plan.
- **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*.

## The steps

They are data: [`checklists/z27ag-captures.json`](../../../checklists/z27ag-captures.json),
bundled into the app as an exact copy (app-flutter `tool/sync-contracts.sh`;
crosscheck fails if the copy drifts). Edit them there; bump `version` when steps
change meaning, since every recording names the version it was made with. Before
starting: PEAK on the OBD port, Orin up, tablet connected; engine off, doors shut.

- **Parked, ignition on, engine off** (1–13): baseline, pedals, steering, gears
  (reverse likely shows as the reverse light: the diesel forfour carries it in
  `423` byte 1 bit 3; no other gearbox signal expected), handbrake, indicators,
  lights, doors, wipers, A/C, belt.
- **Engine running, parked** (14–18): start and idle, held revs (OBD rpm is the
  reference), blips, A/C load, radiator fan.
- **Driving** (19–22): steady speeds, stops, corners, each gear. A passenger presses,
  or skip the marks: OBD and GNSS speed are recorded continuously, and gear comes
  from rpm ÷ speed.

The parked steps can be split over several sessions; the drive is the important part.

## Marks, as recorded

`events.ndjson` holds each mark's text, stamped on arrival at the recorder:

| Text | Meaning |
|---|---|
| `checklist z27ag-captures v1` | before the first mark from the page: which steps these are |
| `3 brake #2 start` / `3 brake #2 end` | a span; `#n` only on repeated actions |
| `14 engine start` | a point |
| `3 brake #2 abort` | a span left open (redo, skip, another step) |
| `3 redo`, `3 skip` | the step is being done again / was skipped: use the last attempt |

## 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/<session>/ …` into
`yukart-data`, with a line in its README of what was done.