samplez/tunie/docs/ROADMAP.md

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 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.
• Before implementing this ourselves, reverse-engineer TuneECU's own Recovery mode first (Aug 2026 finding, ../research/TUNING_IMPL_PLAN.md): TuneECU has a dedicated Recovery function (menu_recovery in the decompile, dispatched through the same mode-switch machinery as the rest of m.java's Ue()), with a multi-year, multi-ECU-family bug-fix history in the app's own changelog (5DM/7SM, Dorsoduro/Shiver 750, Walbro, Ducati recovery bugs fixed 2019-2021) — real evidence this isn't a trivial retry loop, it's hardened against failure modes only discoverable across many real units. Extracting and understanding that procedure statically, before ever attempting our own upload/write path on the one ECU we have, meaningfully de-risks this phase. Near-term (not blocked on this): use TuneECU's own app's "Read Map" for the actual first dump — this reverse-engineering is prep for when tunie builds its own upload path for real, not a prerequisite for getting one file off the bike today.

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. Solved, Aug 2026 — see ../research/reference-maps/checksum.py. 16-bit sum-of-words over the flat-ROM calibration region (0x50000-0x60000, the same range this project's own table_map.py already uses), stored in the region's last 2 bytes. Validated against 6 real, unmodified, official downloads — computed matches stored, exact, every time. Caveat that keeps this from being "done done": this is the app-side checksum TuneECU computes for its own map-info display (flags "*No-OEM"/"Error" on mismatch) — confirmed it's not a hard gate on its own, since a real community file with a stale (unrecomputed) checksum apparently still worked for people. Whether the ECU's own bootloader also independently verifies something during the actual 0x36 TransferData sequence is a separate, still-open question — this solves "how do I produce a checksum TuneECU accepts as valid," not necessarily "the ECU's own integrity check."
• Head start already done (Aug 2026): ../research/WRITE_PATH.md traced TuneECU's actual shared write/reprogram routine from the mode-flag entry point down through the connection/retry driver into a 5-baud slow-init bit-bang for the Triumph K-line address (0xD5) — real protocol detail, not a plan. Traced as far as the post-slow-init handoff (unopened). Read that before starting this section for real; it's ahead-of-time reconnaissance done opportunistically while tracing Recovery mode (../research/RECOVERY_MODE.md), not yet validated against a live ECU.
• 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