contracts/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, and `can_pcan` UP (the
recorder refuses marks with "no session" otherwise); engine off, doors shut.

- **Parked, ignition on, engine off, handbrake on** (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 in neutral (no OBD
  on this car's CAN: the revs are approximate, read off the tacho), blips, A/C load, radiator fan.
- **Driving** (19–22): steady speeds, stops, corners, each gear. A passenger presses,
  or skip the marks: GNSS speed is recorded continuously, and gear comes from
  rpm ÷ speed.
- **On jack stands** (23–26, since v2): front wheels up, rears chocked, handbrake
  off. Unpowered steering; speedometer readings held in 2nd and 3rd (fronts turn,
  rears stay still, which tells the wheels apart); braking from speed with vacuum
  assist; reverse. Stands replace the driving speeds where a drive is not practical.

Version 2 (2026-10-13) adds the stands section and writes down the conditions the
first run showed matter: engine off and handbrake on for 1–13, foot brake held for
the handbrake step, neutral with the clutch up for the revs.

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.