# 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 |