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