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, 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 the recorder 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.
• Marks: the Mark button → a quick chip, or type in Other and press enter. A mark is stamped when the recorder receives it, on the same clock as the frames.
• Check it landed: the Commands list, at the top of the raw-messages pane (right side, or the lower half on a narrow screen), shows ✓ ok: mark 3 in 000042-…. ✗ error: no session means 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 in the mark.
• 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.

Marks

Type the step number first, then what is happening: 3 brake on, 3 brake off. One mark when an action starts and one when it ends is enough; a slow, steady action between them beats a quick one. Wait about 3 s between steps.

Checklist

Before: PEAK on the OBD port, Orin up, tablet connected. Engine off, doors shut.

Parked, ignition on, engine off

#	Do	Mark	Finds
1	Nothing for 20 s	1 baseline	the resting values of every ID
2	Accelerator: slowly to the floor over 5 s, hold 3 s, slowly back	2 accel start / 2 accel end	pedal position (engine off: no rpm to confuse it)
3	Brake: press, hold 3 s, release; three times	3 brake on / 3 brake off each time	brake switch, maybe pressure
4	Clutch: same, three times	4 clutch on / 4 clutch off	clutch switch
5	Steering: centre → full left → full right → centre, slowly	5 steer start / 5 steer end	steering angle
6	Gears: 1, 2, 3, 4, 5, R, neutral, 3 s each	6 gear 1 … 6 gear R, 6 neutral	reverse, likely as the reverse-light bit (diesel forfour: 423 byte 1 bit 3); no other gearbox signal expected — gear comes from rpm ÷ speed (step 22)
7	Handbrake up, down, up	7 handbrake on / off	handbrake switch
8	Indicator left 5 s, right 5 s, hazards 5 s	8 left, 8 right, 8 hazard, 8 off	indicator states
9	Side lights, dipped, main beam, flash, fogs, off	one mark each	light states
10	Each door open/close, boot, bonnet	one mark each	door switches
11	Wipers int / low / high / off, washer	one mark each	wiper states
12	A/C on / off, blower up / down	one mark each	A/C request
13	Seatbelt on / off	13 belt on / off	belt switch

Engine running, parked

#	Do	Mark	Finds
14	Cold start if possible; idle 60 s	14 engine start	coolant and oil warming; idle control
15	Revs in steps: hold 1500, 2000, 3000 rpm 5 s each, back to idle	15 rpm 1500 … 15 idle	engine speed (OBD rpm is the reference), throttle against pedal
16	Three sharp blips	16 blips	response timing of throttle, rpm, MAP
17	A/C on 20 s, off	17 ac on / off	compressor clutch, idle-up
18	Idle until the radiator fan cuts in, if it will	18 fan	fan state, coolant threshold

Driving (a passenger types the marks, or skip them)

#	Do	Mark	Finds
19	Pull away; steady 20, 40, 60 km/h for 10 s each where safe	19 steady 20 … (optional)	road and wheel speeds against OBD and GNSS speed
20	A gentle stop, a firmer stop	20 stop (optional)	brake pressure, deceleration
21	A few corners each way	—	yaw / lateral g, wheel speed differences
22	Each gear through the box	—	gear (from rpm ÷ speed if not broadcast)

Speed needs no marks: OBD speed and GNSS speed are recorded continuously. The drive is the important part; the parked steps can be split over several sessions.

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.