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 (nothing transmits on CAN: OBD-II is on the K-line) |
| `vehicle.ndjson` | `decoder` and `obd-poller` via the bus | decoded CAN signals, and the `obd_*` references from the K-line through the ELM327 (rpm, speed, throttle, load, MAF, timing, O2 every round; coolant, intake air, trims every 5 s); `env.timestamp` is the reply's arrival at the Orin |
| `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 `obd_engine_rpm`, `obd_coolant_temp_c` and the rest appear
  in the signal list and move (the ELM on the OBD port, through the Y harness beside
  the PEAK). 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), and the signal list's `elm_connected` shows the Bluetooth link:

- `ELM …: … (unplugged, asleep or out of range)`: no Bluetooth link. The ELM in the
  port? Its light on? A phone app holding it (it takes one connection)? Retried
  every minute.
- `ECU not answering (…): ignition off?`: the ELM is there, the car is not. The
  adapter's own words are in the brackets (`BUS INIT: ...ERROR`, `NO DATA`).
- `ECU silent for 60 s: adapter released`: ignition off for a minute; the poller let
  go so the ELM can sleep, and tries again every minute.
- To see what answers, on the Orin: `sudo systemctl stop yukart-obd-poller`,
  `yukart-obd-poller --elm $(. /etc/default/yukart-elm; echo $ELM_ADDR) --once`
  (adapter, protocol, supported PIDs and one value each, with reply times), then
  `sudo systemctl start yukart-obd-poller`.

## 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.