diff --git a/README.md b/README.md index 3bab73d..cb678c3 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ definitions from here. | [`schema/envelope.json`](schema/envelope.json) | JSON Schema for the decoded-signal envelope | | [`schema/signals.json`](schema/signals.json) | Signal registry — the single source for name, unit, type and range | | [`docs/BOUNDARY.md`](docs/BOUNDARY.md) | Display boundary protocol: what crosses between `svc-gw` and the app | +| [`checklists/`](checklists/) | Recording checklists as data; the app bundles exact copies (its **Captures** page) | The Z27AG DBC lands here too, once Phase 2 produces one. diff --git a/checklists/z27ag-captures.json b/checklists/z27ag-captures.json new file mode 100644 index 0000000..56600f4 --- /dev/null +++ b/checklists/z27ag-captures.json @@ -0,0 +1,226 @@ +{ + "id": "z27ag-captures", + "version": 1, + "title": "Z27AG decoding captures", + "about": "docs/impl/plans/Z27AG-CAPTURES.md", + "mark_format": " [ #] start|end for a span, [ #] for a point", + "sections": [ + { + "title": "Parked, ignition on, engine off", + "steps": [ + { + "id": "1", + "title": "Baseline", + "do": "Touch nothing.", + "finds": "the resting value of everything", + "actions": [{ "label": "baseline", "hold_s": 20 }] + }, + { + "id": "2", + "title": "Accelerator", + "do": "Slowly to the floor over 5 s, hold 3 s, slowly back. Start as the foot moves, end when it is off.", + "finds": "pedal position, with no rpm to confuse it", + "actions": [{ "label": "accel" }] + }, + { + "id": "3", + "title": "Brake", + "do": "Start as you press, hold 3 s, end as you release.", + "finds": "brake switch, maybe pressure", + "actions": [{ "label": "brake", "hold_s": 3, "repeat": 3 }] + }, + { + "id": "4", + "title": "Clutch", + "do": "Start as you press, hold 3 s, end as you release.", + "finds": "clutch switch", + "actions": [{ "label": "clutch", "hold_s": 3, "repeat": 3 }] + }, + { + "id": "5", + "title": "Steering", + "do": "Centre, full left, full right, back to centre, slowly.", + "finds": "steering angle", + "actions": [{ "label": "steer" }] + }, + { + "id": "6", + "title": "Gears", + "do": "Start when the gear is in, end as you take it out. Clutch down throughout.", + "finds": "reverse (likely as the reverse light); no other gearbox signal expected", + "actions": [ + { "label": "gear 1", "hold_s": 3 }, + { "label": "gear 2", "hold_s": 3 }, + { "label": "gear 3", "hold_s": 3 }, + { "label": "gear 4", "hold_s": 3 }, + { "label": "gear 5", "hold_s": 3 }, + { "label": "gear R", "hold_s": 3 }, + { "label": "neutral", "hold_s": 3 } + ] + }, + { + "id": "7", + "title": "Handbrake", + "do": "Start as you pull it up, end as you release it.", + "finds": "handbrake switch", + "actions": [{ "label": "handbrake", "hold_s": 3, "repeat": 2 }] + }, + { + "id": "8", + "title": "Indicators", + "do": "Start when switched on, end when off.", + "finds": "indicator states", + "actions": [ + { "label": "left", "hold_s": 5 }, + { "label": "right", "hold_s": 5 }, + { "label": "hazard", "hold_s": 5 } + ] + }, + { + "id": "9", + "title": "Lights", + "do": "Start when switched on, end when off.", + "finds": "light states", + "actions": [ + { "label": "side lights", "hold_s": 3 }, + { "label": "dipped", "hold_s": 3 }, + { "label": "main beam", "hold_s": 3 }, + { "label": "flash", "point": true }, + { "label": "front fogs", "hold_s": 3 }, + { "label": "rear fog", "hold_s": 3 } + ] + }, + { + "id": "10", + "title": "Doors", + "do": "Start as it opens, end when it is shut. Skip what the car does not have.", + "finds": "door switches", + "actions": [ + { "label": "driver door" }, + { "label": "passenger door" }, + { "label": "rear left door" }, + { "label": "rear right door" }, + { "label": "boot" }, + { "label": "bonnet" } + ] + }, + { + "id": "11", + "title": "Wipers", + "do": "Start when switched on, end when off.", + "finds": "wiper states", + "actions": [ + { "label": "wipers int", "hold_s": 5 }, + { "label": "wipers low", "hold_s": 5 }, + { "label": "wipers high", "hold_s": 5 }, + { "label": "washer" } + ] + }, + { + "id": "12", + "title": "A/C and blower", + "do": "A/C: start on, end off. Blower: start as you turn it up, end when it is back down.", + "finds": "A/C request, blower", + "actions": [ + { "label": "ac", "hold_s": 5 }, + { "label": "blower" } + ] + }, + { + "id": "13", + "title": "Seatbelt", + "do": "Start as it clicks in, end as it comes out.", + "finds": "belt switch", + "actions": [{ "label": "belt", "hold_s": 3 }] + } + ] + }, + { + "title": "Engine running, parked", + "steps": [ + { + "id": "14", + "title": "Engine start", + "do": "Cold start if possible: mark as the starter turns, then idle 60 s.", + "finds": "starting, coolant and oil warming, idle control", + "actions": [ + { "label": "engine start", "point": true }, + { "label": "idle", "hold_s": 60 } + ] + }, + { + "id": "15", + "title": "Revs", + "do": "Start when the revs are steady at the target, end as you leave it.", + "finds": "engine speed against OBD rpm, throttle against pedal", + "actions": [ + { "label": "rpm 1500", "hold_s": 5 }, + { "label": "rpm 2000", "hold_s": 5 }, + { "label": "rpm 3000", "hold_s": 5 } + ] + }, + { + "id": "16", + "title": "Blips", + "do": "Three sharp blips of the throttle.", + "finds": "response timing of throttle, rpm, pressure", + "actions": [{ "label": "blips" }] + }, + { + "id": "17", + "title": "A/C under load", + "do": "A/C on for 20 s, then off.", + "finds": "compressor clutch, idle-up", + "actions": [{ "label": "ac", "hold_s": 20 }] + }, + { + "id": "18", + "title": "Radiator fan", + "do": "Idle until the fan cuts in, if it will; mark when you hear it.", + "finds": "fan state, coolant threshold", + "actions": [{ "label": "fan", "point": true }] + } + ] + }, + { + "title": "Driving (a passenger presses, or skip the marks)", + "steps": [ + { + "id": "19", + "title": "Steady speeds", + "do": "Where safe, hold each speed 10 s.", + "finds": "road and wheel speeds against OBD and GNSS speed", + "actions": [ + { "label": "steady 20", "hold_s": 10 }, + { "label": "steady 40", "hold_s": 10 }, + { "label": "steady 60", "hold_s": 10 } + ] + }, + { + "id": "20", + "title": "Stops", + "do": "Start as you brake, end when stopped.", + "finds": "brake pressure, deceleration", + "actions": [ + { "label": "gentle stop" }, + { "label": "firm stop" } + ] + }, + { + "id": "21", + "title": "Corners", + "do": "A few corners each way.", + "finds": "yaw, lateral g, wheel speed differences", + "actions": [{ "label": "corners" }] + }, + { + "id": "22", + "title": "Through the box", + "do": "Each gear in turn.", + "finds": "gear from rpm / speed", + "actions": [{ "label": "gears" }] + } + ] + } + ] +} diff --git a/docs/impl/plans/Z27AG-CAPTURES.md b/docs/impl/plans/Z27AG-CAPTURES.md index 6790133..e9c41eb 100644 --- a/docs/impl/plans/Z27AG-CAPTURES.md +++ b/docs/impl/plans/Z27AG-CAPTURES.md @@ -6,7 +6,7 @@ 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, and OBD-II mode 01 values are recorded alongside as the +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 @@ -18,69 +18,55 @@ ground truth. Prior art and first candidates: [the prior-art report](../reports/ | `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 +## 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. -- **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. +- **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*. -## Marks +## The steps -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. +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; engine off, doors shut. -## Checklist +- **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. -**Before:** PEAK on the OBD port, Orin up, tablet connected. Engine off, doors shut. +The parked steps can be split over several sessions; the drive is the important part. -### Parked, ignition on, engine off +## Marks, as recorded -| # | 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 | +`events.ndjson` holds each mark's text, stamped on arrival at the recorder: -### 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. +| 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