contracts/docs/impl/plans/Z27AG-CAPTURES.md

type, status, updated

type	status	updated
plan	ready	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.

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