uhryniuk
4debdfa518
docs/CONTEXT.md captures the entire reverse-engineering effort in one place: KWP2000 protocol, AES-128 seed/key, the map format (dc decrypt -> flat-ROM unpack -> directory -> fe table pointers), the fuel/ignition table map, the validated SAI/O2 device flags, checksums, hardware, and a per-finding confidence table. docs/ROADMAP.md covers open-sourcing (legal/IP posture on proprietary maps and the AES keys, repo hygiene, packaging/CI, community) and the technical path to tuning the bike (first contact -> ROM dump -> calibration model -> write path -> editor), with immediate next steps and a risk register. Top-level README refreshed to describe the whole project (tool + viewer + research) and point at docs/.
131 lines
6.6 KiB
Markdown
131 lines
6.6 KiB
Markdown
# tunie — roadmap: open-sourcing + what's next
|
||
|
||
Two tracks: **getting this into a shippable open-source project**, and the
|
||
**technical work** still needed to actually tune the bike. Read
|
||
[CONTEXT.md](CONTEXT.md) first for the full state.
|
||
|
||
---
|
||
|
||
## Track A — open-sourcing
|
||
|
||
The code is original; the risk in publishing is the **third-party derived data**
|
||
and the **flashing capability**. Handle these deliberately before a public repo.
|
||
|
||
### A1. Legal / IP (do this first)
|
||
- **No proprietary binaries in the repo.** Already enforced: `*.hex`, `*.dec.bin`,
|
||
`maps_cache/`, `table_map.json` are gitignored. Keep it that way — map files are
|
||
Triumph/TuneECU calibration data and must not be redistributed.
|
||
- **APK-derived data** (`maps.json`, `mapdefs.json`, embedded `c.a`/`s.a`, the AES
|
||
keys, protocol constants) are facts extracted for **interoperability**. Frame the
|
||
project explicitly as independent interoperability research on hardware you own.
|
||
Add a clear NOTICE describing what's derived and why, and cite that it contains
|
||
no TuneECU source.
|
||
- **The AES seed/key** enables writing to the ECU. Decide the posture: keep the
|
||
key/flashing material in a clearly-separated `research/` area with a warning, or
|
||
gate the write path behind an explicit build flag. Do not make bricking a
|
||
one-liner.
|
||
- **License:** pick one (MIT/Apache-2.0 for the tool; note that embedded
|
||
extracted constants are facts, not licensed code). Add `LICENSE` and a top-level
|
||
legal/README section.
|
||
|
||
### A2. Repo hygiene
|
||
- Move `tunie/` out of the `samplez` grab-bag into its **own repo** for a real
|
||
project (keep samplez as the scratch mirror if you like).
|
||
- Add: `CONTRIBUTING.md`, `SECURITY.md` (responsible-disclosure + "don't flash
|
||
blindly" warning), issue templates, a CHANGELOG.
|
||
- Reproducible builds: pin deps, document `build_viewer.py` inputs (needs a
|
||
decompiled APK the repo can't ship — document how to produce it, don't include it).
|
||
|
||
### A3. Packaging & CI
|
||
- `pip install tunie` — the `pyproject.toml` is already there; add a wheel build.
|
||
- CI: run `tests/verify_protocol.py` + the reference-map self-tests (`decode_map.py`,
|
||
`reconstruct_rom.py`, `table_map.py` — but those need map binaries, so gate them
|
||
behind a locally-provided fixtures dir / skip in public CI).
|
||
- Lint/format (ruff/black), type-check (mypy) the `src/tunie` package.
|
||
|
||
### A4. Docs & polish
|
||
- A real top-level README with a quickstart, the safety stance, and a screenshot.
|
||
- Host the viewer as a static page (it's a single self-contained file).
|
||
- Turn `docs/CONTEXT.md` into a short "how the format works" explainer — it's
|
||
genuinely novel RE and good for the project's credibility.
|
||
|
||
### A5. Community
|
||
- The SuperH ECU community (npkern/FastECU/ScoobyRom authors, TunerPro forums,
|
||
triumphrat) is the natural audience. A working open Keihin decrypt + table map is
|
||
a real contribution. Coordinate rather than surprise — some of this overlaps
|
||
commercial XDF vendors.
|
||
|
||
---
|
||
|
||
## Track B — technical, to actually tune the bike
|
||
|
||
Ordered by dependency. Phases 1–2 are safe reads; 3+ is the write path.
|
||
|
||
### B1. First contact (READ) — the current blocker
|
||
1. Identify the VAG KKL chip (`tunie ports`); install CH340 driver if needed.
|
||
2. **Confirm the Triumph diagnostic-connector pinout** and build the adapter
|
||
(K-Line + switched 12V + ground). *This is the one real electrical risk.*
|
||
3. `tunie info` — read ECU ID, current map, DTCs. Confirms which stock map is on
|
||
the bike (should be 20187/20191 for production silencers, mechanical odo).
|
||
|
||
### B2. ROM dump (READ, deliberate)
|
||
- Enable `0x35` RequestUpload (currently blocked in the read-only tool) to dump the
|
||
stock ROM as a recovery image. Do this before any write work.
|
||
- Cross-check the dump against our decrypt/unpack: a stock dump should reconstruct
|
||
to the same flat ROM as the matching `.hex`, validating the whole pipeline on the
|
||
real bike's data.
|
||
|
||
### B3. Finish the calibration model
|
||
- **Absolute scaling** for fuel and ignition (units), via an XDF cross-check (~€70
|
||
OldSkull/Tuniverse) or more RE of `Nc`/`Lb`. Relative editing already works.
|
||
- **AFR table** dimensions/axes (partly reversed; 128 = λ1.00 confirmed).
|
||
- **Remaining device flags** (exhaust valve, air flap…) — needs the `x.a()` device
|
||
layout reverse (`x.t/x.s/x.q` for i27=72) or more single-mod reference maps.
|
||
- Individual **SAI-vs-O2** isolation — only matters if hand-editing flags; the
|
||
owner's path (a complete AIRBOXBONNY-style map) sidesteps it.
|
||
|
||
### B4. Write / flash path (the risky part — bench first)
|
||
- Port the **flash kernel**: `fenugrec/npkern` explicitly lists SH7054 (untested) —
|
||
the strongest lead. `miikasyvanen/FastECU` shows a full end-to-end flow.
|
||
- Finish **seed/key**: which of the 3 AES keys + the seed-block padding (one
|
||
captured pair from the bike/logging APK settles it).
|
||
- **ECU flash checksum** at write time.
|
||
- **Recovery**: `v-ladimir/audprog` (AUD debugger) for SH705x un-brick via the PCB
|
||
debug pins — mandatory backstop when developing a flasher.
|
||
- Develop against a **spare/bench ECU**, on a stable supply, never the bike's only
|
||
ECU, and validate output against TuneECU before trusting our own writes.
|
||
|
||
### B5. Editor completion
|
||
- Full flat-ROM edit → re-pack → `dc`-encode → `.hex` for **arbitrary** table edits
|
||
(device flags already round-trip; generalize to any chunk + fix the edit
|
||
checksum).
|
||
- In-viewer table editing with axes + a wideband/dyno-oriented diff workflow.
|
||
|
||
### B6. The owner's actual goal
|
||
2-1 exhaust + airbox removal + O2 + SAI delete:
|
||
1. Base on `20188Map2009AIRBOXBONNY` (validated: flags off + airbox fueling done).
|
||
2. Verify in the viewer (devices off, fuel tables sane vs stock).
|
||
3. Flash it — via the tunie write path once it exists, or TuneECU meanwhile.
|
||
4. Fine-tune midrange fuel for the 2-1 with a wideband (ideally a dyno).
|
||
|
||
---
|
||
|
||
## Immediate next steps (this week, if picking back up)
|
||
|
||
1. **Cable + pinout** → run `tunie info` on the bike (unblocks everything).
|
||
2. Pull `20188Map2009AIRBOXBONNY` into the viewer catalogue and diff it vs stock
|
||
20187 so the exact delete-tune changes are visible.
|
||
3. Decide the open-source posture on the AES keys / write path (Track A1) before
|
||
any public repo.
|
||
|
||
## Risk register
|
||
|
||
| Risk | Status |
|
||
|---|---|
|
||
| Software bricking via the read tool | eliminated (write path not implemented) |
|
||
| Electrical (wrong connector pin) | **live** — confirm pinout before plugging in |
|
||
| Bad tune from flags-only edit | mitigated by guidance; use a complete map |
|
||
| Flashing (comms drop / bad checksum) | future — needs bench ECU + recovery tooling |
|
||
| Legal (redistributing proprietary maps) | mitigated — binaries gitignored |
|
||
| One ECU, no spare | validate writes against TuneECU; get a spare before B4 |
|