yukart/contracts
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Z27AG capture steps as data, for the app's one-button page
/ crosscheck (push) Successful in 1s
Details

Browse Source 
checklists/z27ag-captures.json is now the source of the steps; the plan
describes the Captures page and the mark texts it records.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DDwfd6Ki8UfG4hK6W5YpJz
This commit is contained in:
Mikkeli Matlock
2026-10-13 11:12:43 +09:00
parent f7c7a3533a
commit 635e2d1304
3 changed files with 265 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+1
View File
@@ -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.
checklists/z27ag-captures.json
+226
View File
@@ -0,0 +1,226 @@
{
"id": "z27ag-captures",
"version": 1,
"title": "Z27AG decoding captures",
"about": "docs/impl/plans/Z27AG-CAPTURES.md",
"mark_format": "<step> <action>[ #<n>] start|end for a span, <step> <action>[ #<n>] 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" }]
}
]
}
]
}
docs/impl/plans/Z27AG-CAPTURES.md
+38 -52
View File
@@ -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