docs(v0.5.0): real-car u8_enum validation harness - #72
Conversation
First PR of the v0.5.0 "Ground Truth" cycle. Doc-only. Auto-merge eligible per CLAUDE.md rule 2. What this ships: - docs/validation/u8_enum-validation.md — the actual validation harness. Pre-flight checklist (cable, adapter, ignition, simulator NOT in use), per-DID test procedure for the three example enum DIDs shipped in v0.4.0 (gear / DA0A, engine_state / 4004, knock_detect / 401F), results-submission instructions (PR the [verified YYYY-MM-DD] labels back into b58.toml / n55.toml), and a 'what if a byte doesn't match' section for the most-likely failure mode. - docs/v0.5.0_first_pr.md — the cycle's written record of why this PR exists. Mirrors the v0.4.0_first_pr.md shape so future contributors can follow the same pattern. Why this is the first PR of v0.5.0: The v0.5.0 cycle plan (docs/v0.5.0_plan.md, PR #70) lists three PRs in order: 1. THIS PR — validation harness (doc-only, lands first because it unblocks the rest) 2. Real-car fuel-trim readout (PR #2) 3. Real-car knock visualisation polish (PR #3) Real-car evidence was the only 🟡 blocker for the v0.4.0 'Tuner Friendly' cycle to retire. The example enum DIDs shipped in PR #60 all carry [needs verification] markers because the byte-to-state mappings came from OBDb (CC-BY-SA 4.0) and have not been validated on real hardware. This harness is the smallest possible next step for an F/G-series owner with an ENET adapter to retire that blocker: a checklist they can fill in and PR back, with no developer hand-holding required. What this PR does NOT do: - No code change. Doc-only. - No new tests. Validation is manual (a person running the app against a real car). - No change to the [needs verification] markers in b58.toml / n55.toml. Those stay until a results PR lands. Verification: - node --test server/dtc/test/ingestor.test.js → all green (no regression) - node --test src/js/histogram.test.js → all green - git diff origin/main...HEAD --stat → 2 files, 305 insertions, 0 deletions (clean; both files new) - This PR does not touch code, workflows, or protected paths. A reviewer with an F/G-series car + ENET adapter is the authoritative verifier. Note on the broken package.json: origin/main's package.json has a missing-comma bug (introduced by a sibling agent in the PR #68/#69 area; noted in PR #70 and #71 bodies). It breaks 'npm run test:*' but does NOT break 'node --test' directly. A separate doc-only PR can fix it. Not fixed here per commit-discipline's 'discovering a broken sibling commit is not license to fix it.'
|
🤖 Doc-only change — auto-merge enabled. Will merge once required checks pass. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 134ce15bdf
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 3. Verify the **byte values the decoder reports match the car's | ||
| actual state**: | ||
| - For `gear` — put the car in each gear (or P/N) and read | ||
| back the value from BeeEmUu. |
There was a problem hiding this comment.
This procedure asks validators to confirm the byte value from Live Data, but the current u8_enum path resolves known bytes to LiveValue.text and sends value: 0.0, and the gauge hides the numeric value whenever text is present (src-tauri/src/commands.rs:248-260, src/js/gauges.js:25-31). For known enum values, the screenshot/session will only show the mapped label, so a swapped or incorrect byte-to-label mapping can appear to pass; the harness needs to direct users to Parameter Explorer/raw response capture or otherwise include the raw byte before marking these mappings verified.
Useful? React with 👍 / 👎.
| The PR edits `community/profiles/b58.toml` and | ||
| `community/profiles/n55.toml` to: | ||
| - Change the `[needs verification]` label suffix to | ||
| `[verified YYYY-MM-DD on chassis XYZ]` for the three | ||
| DIDs. |
There was a problem hiding this comment.
For a validator who only tested one chassis/profile, this instruction would remove [needs verification] from both B58 and N55 entries even though the other engine family was not exercised; the repository explicitly treats N55 as a separate profile covering E/F-series variants (community/profiles/n55.toml:1-6). That can make an untested profile look real-car verified, so the result PR should update only the profile/chassis that produced the evidence unless both were actually tested.
Useful? React with 👍 / 👎.
| gauge list. The label should NOT have `[needs verification]` | ||
| — that's the marker that the byte→state mapping is still | ||
| unvalidated. (The marker is on the profile-side label; once | ||
| you start recording, the live-data label comes from the | ||
| decoder.) |
There was a problem hiding this comment.
In the current UI, the Live Data caption is the profile label (ensureGauge writes v.label into .gauge-label), and the existing unverified enum rows still carry [needs verification] on the profile-side label. A correctly configured car can therefore fail this checklist step before validation has happened, causing validators to think they selected the wrong build/profile; the doc should tell them to expect the marker until the evidence PR removes it, while the decoded enum text appears inside the gauge.
Useful? React with 👍 / 👎.
| - Confirmation that all checkboxes are ✅ | ||
| - Attached screenshots (one per DID, embedded in the PR body) |
There was a problem hiding this comment.
This success criterion requires every checkbox to be ✅, but the table explicitly allows the gear Error row to remain unchecked and the knock section says an always-None stock car is not a failure. In normal safe validation, Error/Light/Moderate/Severe may never occur, so requiring all rows to pass either blocks legitimate evidence PRs or encourages unsafe attempts to trigger fault states; define those rows as N/A/observed-only and state the actual pass criteria.
Useful? React with 👍 / 👎.
| 5. **Stop recording. Save the session JSON** — it'll help if you | ||
| need to file an issue. |
There was a problem hiding this comment.
After stopping a recording, the Logging UI exposes an Export CSV action, while autoSaveSession() only writes a recoverable copy into localStorage and the full snapshot JSON is a separate vehicle/session export path rather than a saved logging session. A validator following this step has no way to produce the requested session JSON from the recording, so the harness should ask for the CSV, a full snapshot/traffic export, or give the actual recovery/export steps that exist.
Useful? React with 👍 / 👎.
1 participant
Summary
First PR of the v0.5.0 "Ground Truth" cycle. Doc-only.
Auto-merge eligible per CLAUDE.md rule 2.
Ships the validation harness that an F/G-series owner with an
ENET adapter uses to retire the
[needs verification]markerson the three example enum DIDs shipped in v0.4.0 (
gear,engine_state,knock_detect).What this PR contains
New docs
docs/validation/u8_enum-validation.md— the actualharness. Six sections:
profile, simulator NOT in use.
tables (gear /
DA0A, engine_state /4004,knock_detect /
401F), each with expected byte → statemappings, pass/fail checkbox, and notes column.
checklist as a PR that removes
[needs verification]markers and adds
[verified YYYY-MM-DD on chassis XYZ].failure mode. Don't fake a pass; log it; open an issue
with the actual byte + actual state + screenshot.
u8_enumspec, the v0.5.0cycle plan, the ENET cable pinout doc, and the profile
TOMLs to PR against.
[verified]PR lands.
docs/v0.5.0_first_pr.md— the cycle's written recordof why this PR exists. Mirrors
docs/v0.4.0_first_pr.md'sshape so future contributors can follow the same pattern
when kicking off a cycle's first PR.
What does NOT ship (deliberately)
running the app against a real car. Hardware bench
automation is out of scope for v0.5.0.
[needs verification]markers incommunity/profiles/{b58,n55}.toml. Those stay until areal-owner results PR lands.
Why this is first
The v0.5.0 cycle plan (
docs/v0.5.0_plan.md,PR #70) lists three PRs in order:
because it unblocks the rest. It's the smallest possible
next step, with no developer hand-holding required.
Real-car evidence was the only 🟡 blocker for the v0.4.0
"Tuner Friendly" cycle to retire. This PR is the path.
Verification
node --test server/dtc/test/ingestor.test.js→ all greennode --test src/js/histogram.test.js→ all greengit diff origin/main...HEAD --stat→ 2 files, 305insertions, 0 deletions (clean; both files new)
ENET adapter. No automated tests substitute for real
hardware.
Note on the broken
package.jsonorigin/main'spackage.jsonhas a missing-comma bug(introduced by a sibling agent in the PR #68/#69 area;
noted in PR #70 and #71 bodies). It breaks
npm run test:*but does NOT breaknode --testdirectly. Aseparate doc-only PR can fix it. Not fixed here per
commit-discipline's "discovering a broken sibling commitis not license to fix it."
Files
Related
docs/v0.5.0_plan.md(PR docs(v0.5.0): cycle plan ("Ground Truth") #70).
ROADMAP.md§ "v0.5.0 — Ground Truth (Active cycle)" (PR docs(roadmap): rewrite ROADMAP for v0.4.0 Done + v0.5.0 active #71).
docs/DECODE_FUNCTIONS.md§ 8(
u8_enum).docs/hardware/enet-cable-pinout.md(PR docs(hardware): BMW ENET cable DIY pinout ($5 AliExpress version) #61).
community/profiles/b58.toml+
community/profiles/n55.toml(PR feat(data): u8_enum decoder + per-parameter enum-map pipeline #60).
readout (adds DIDs to the profile TOMLs, marked
[needs verification]).Author note
Commit authored with
ohgeeceee@users.noreply.github.comto bypass GH007 (private-email push block). Content
unchanged.