# tunie — full technical context

Everything we've reverse-engineered and built for an open-source Triumph Keihin
ECU toolchain. This is the pick-it-up-cold reference; if you read one file, read
this one. Companion docs: [ROADMAP.md](ROADMAP.md) (open-source + next steps),
and the deeper per-topic writeups linked throughout.

---

## 1. The target

- **Bike:** 2010 Triumph Bonneville T100, 865cc air-cooled parallel twin,
  **mechanical/analog odometer** variant.
- **ECU:** Keihin, on a Renesas SH7054 (32-bit SuperH RISC). ~384 KB internal
  flash (corroborated: the app has a 393216-byte code path; npkern lists SH7054).
- **Goal:** an open, offline toolchain to read, view, edit, and (eventually)
  flash the calibration — replacing the closed TuneECU app.
- **Owner's end state for the bike:** 2-1 exhaust, airbox removal, O2 delete, SAI
  delete. This matches the community map `20188Map2009AIRBOXBONNY` almost exactly.

## 2. What exists today

| Piece | Path | State |
|---|---|---|
| Read-only KWP2000 diagnostic tool | `src/tunie/` | built, unit-tested; **not yet run on the bike** |
| Map catalogue (1811 maps) | `maps.json` | extracted from the APK |
| Seed/key (AES-128) reference | `research/keihin_seedkey.py` | reversed + FIPS-verified |
| Map decrypt / unpack / table map | `research/reference-maps/` | reversed + validated on real maps |
| Self-contained viewer/editor | `viewer/tunie-viewer.html` | renders real fuel/ignition tables + device toggles |

Nothing has electrically touched the ECU yet. Everything is software + RE against
downloaded map files.

## 3. KWP2000 diagnostic protocol (read path)

Recovered from the TuneECU APK (`m.java`, `MainActivity.java`), validated
byte-for-byte in `tests/verify_protocol.py`:

- **ECU address `0xD5`**, **tester `0xF5`** on K-Line (NOT the common `0xF1`).
  CAN-era Triumphs use `0xF1`; K-line uses `0xF5`.
- **Framing:** format byte `0x80 | length`; long form (`0x80` + separate length
  byte) when payload > 120 B; **additive mod-256 checksum**.
- **Init:** fast init (`ATTP5`) or 5-baud (`ATTP4` + `ATIIAD5`), address `0xD5`.
- **ECU type char:** `0` = Keihin, `1` = Sagem, `P` = Bosch (from `ecu` array).
- Reference frames: `81 d5 f5 81 cc` (StartComms), `82 d5 f5 1a 80 e6`
  (ReadEcuIdentification), `84 d5 f5 18 00 ff 00 65` (ReadDtcByStatus).

The tool (`src/tunie/`) is **read-only by construction**: `safety.assert_read_only`
runs on every outbound request and refuses all write/flash services (0x27, 0x31,
0x34/0x36, 0x35, 0x37, 0x14, 0x11, 0x2E) and programming sessions. A bug can't
brick the ECU because the write path isn't implemented. Details: top-level
`README.md`, `STATUS.md`.

## 4. Security Access seed/key — AES-128

`m.java` `Vb()`. **Standard AES-128**, not the Honda XOR scheme the early brief
guessed. Verified: all 256 T-table entries match AES Te0; the port passes the
FIPS-197 known-answer test. `Vb()` AES-encrypts a 128-bit seed with one of three
embedded keys (selected by an ECU-code index) and returns the first ciphertext
word as the 4-byte key. Reference + keys: `research/keihin_seedkey.py`,
`research/FINDINGS.md`. This is **write-path** material, kept out of the read-only
tool.

Still open (framing, not crypto): which of the 3 keys for this ECU, and the exact
seed-block padding. One captured seed/key pair resolves both.

## 5. Map file format (this was the big reverse)

The full chain, all reversed from `l.java`/`MainActivity.java` and validated
against real stock maps. See `viewer/FORMAT.md` and
`research/reference-maps/README.md`.

### 5a. Download & decryption
- Maps download from `https://www.tuneecu.fr/Maps/<path>` (e.g.
  `Triumph/Bonneville/20187Map.hex`), ~300 KB, **encrypted** (entropy ~7.99).
- Decryptor is `l.dc()`: a **self-synchronising CBC-style XOR stream cipher**
  seeded by the plaintext 4-byte header. Bytes 0–3 stay plaintext (the magic);
  from byte 4: `plain = prev_cipher ^ cipher ^ ((key>>((i%4)*8))&0xFF)`, where
  `key = i2 | le32(header)` and `i2` is a constant from `header[3]-24`.
  Reversed + round-trip-verified in `research/reference-maps/decode_map.py`.
- Header magic: `le32(bytes[0:4]) & 0xFF00FFE0 == 0x18001360`, i.e.
  `byte0 ∈ {0x67,0x68,0x69}` (family), `byte1==0x13`, `byte3==0x18`.

### 5b. Unpack to the flat ROM
The decoded map is **packed** — which is why a naive diff of two decoded maps
showed 96% difference (misaligned chunks). Each decoded map carries an **unpack
directory** (base `le16(dec[28])`, a `0x6F66` marker, a count, then
`(dest_offset, length)` entries) that scatters chunks into a **384 KB (0x60000)
flat ROM** = the real ECU address space. In the flat ROM, production (20187) vs
aftermarket (20188) differ only **1.4%** — the real fuel enrichment.
Reversed in `research/reference-maps/reconstruct_rom.py`.

### 5c. Directory lookup → calibration metadata
Decoded signature at offset 20 → `s.a` directory record → `Qd = field[1]` →
`fe = c.a[Qd*48]` (the 48-int per-calibration metadata that holds all the table
pointers). Validated: sig `0x0187CA84` → `s.a` #541 → Qd 32.

## 6. Calibration tables

`research/reference-maps/TABLES.md` + `table_map.py`. Base `= (fe[0]&0x2F0)<<12 =
0x50000`; **table offset = base + fe[k]**. Tables are **32 RPM rows × 20 throttle
cols, 16-bit big-endian**.

| Table | fe | Offset (20187) | Confidence |
|---|---|---|---|
| Main fuel cyl 1 / 2 | 11 / 12 | 0x56990 / 0x56E90 | high (75/67% aftermarket diff, smooth VE) |
| Low-throttle fuel cyl 1 / 2 | 15 / 16 | 0x55590 / 0x55A90 | high |
| Fuel base/idle | 9 | 0x55500 | high |
| Ignition advance gear 1 / 2–5 / 6 / neutral | 19–22 | 0x587D0 … 0x596D0 | high |
| AFR / target lambda | 2 | 0x52260 | medium (128 = λ1.00 confirmed) |

Axes: RPM = `fe[8]` (32 breakpoints, real RPM); throttle = `fe[27]` (20, 0–100%×10).
**Validated end-to-end:** the main fuel table renders as a clean VE surface, and
the aftermarket map is richer in 284/320 cells — physically correct enrichment.

**Scaling** (relative changes are exact; absolute units still approximate): fuel
values are the ECU's internal VE/fuel-mass units (~0–10800); ignition 13–600 is an
internal advance unit; AFR 128 = λ1.00. Exact fuel/ignition constants: TBD (an XDF
cross-check or more RE).

## 7. Device-enable flags (SAI / O2)

`research/reference-maps/DEVICES.md`. Byte-boolean array at `base + fe[33]`
(=`0x53801`), 1=on/0=off. Validated against the real NO-SAI-NO-O2 map
`20188Map2009AIRBOXBONNY`, which cleared exactly three bytes:

| Offset | Device | Confidence |
|---|---|---|
| `0x53801` | **SAI** | ~90% (code `lc()` → Devices[0] via fe[33], **and** the delete map) |
| `0x53818` / `0x53819` | **O2 sensor 1 / 2** | ~80% (two O2 sensors ↔ two adjacent bytes; not individually isolated) |

**Critical caveat:** correct flags ≠ a good tune. Disabling O2 forces open-loop —
the bike runs on the base fuel map with no live trim; on a stock map that can run
lean/rough. A proper delete pairs flags-off with fuel enrichment (which is why the
reference map changed the fuel tables too). **Flash a complete matching delete map,
not hand-toggled flags on a stock one.** The owner's target = the AIRBOXBONNY map
(SAI/O2 off + airbox fueling done); only the 2-1-vs-2-2 midrange fuel needs
fine-tuning.

## 8. Checksums

Two distinct ones:
- **Table write-back (edit) checksum:** a running 16-bit word, `chk = (chk + old -
  new) & 0xFFFF`, used when a cell changes. Location is per-calibration.
- **Distribution `.hex` integrity:** the `dc` cipher + unpack directory. The `caXX`
  header/tail bytes are **map-ID metadata, not a cal checksum**, so re-encoding an
  edit is complete for the file format.
- **ECU flash checksum:** applied by the flashing tool at write time — out of scope
  for the read/edit tool, part of the write path.

## 9. Hardware / cable

Owner has a **VAG KKL 409.1** cable (right class — K-Line) and a Bluetooth
ELM327. The VAG cable is wired for a VW OBD-II socket; the 2010 Bonneville uses
Triumph's proprietary diagnostic connector, so it needs an adapter/re-pin
(K-Line + switched 12V + ground). **Confirm the connector pinout before plugging
in — that's the one genuine electrical risk.** Identify the chip first
(`tunie ports`: FTDI = `/dev/cu.usbserial-*`; CH340 = `/dev/cu.wchusbserial*`).

## 10. The viewer

`viewer/tunie-viewer.html` — one self-contained file, no server, no external refs.
Tabs: Map catalogue (1811, filterable, "my bike" filter) · Tune capabilities
(devices/params/sensors from the APK) · **Triumph tables** (drop a real `.hex` →
decode → unpack → render real fuel/ignition tables with axes + A→B diff + device
checkboxes) · Raw table viewer. Build with `viewer/build_viewer.py`
(`--tuneecu-src` enables the Triumph tab by embedding the `c.a`/`s.a` directory).
`download_maps.py` + `serve.py` add a catalogue dropdown of locally cached maps.

## 11. Validation status & confidence (honest)

| Finding | Confidence | How validated |
|---|---|---|
| KWP2000 addressing/framing | high | byte-identical to TuneECU |
| Seed/key = AES-128 | high | FIPS-197 + T-table match |
| Map decrypt (`dc`) | high | round-trip + readable strings on real maps |
| Flat-ROM unpack | high | sibling diff 96%→1.4%, directory lookup resolves |
| Fuel/ignition table offsets | high | render as real tables; enrichment physically correct |
| Table scaling (absolute units) | low–med | relative exact; absolute TBD |
| SAI flag (0x53801) | high (~90%) | code + real delete map |
| O2 flags (0x53818/9) | probable (~80%) | group-validated, not isolated |
| Anything on the actual bike | **none yet** | no hardware connected |

## 12. What is NOT done

- No comms with the real ECU (blocked on the cable adapter/pinout).
- No ROM dump from the bike.
- No write/flash path (seed/key which-key + padding, flash kernel, ECU checksum).
- Editor exports the distribution `.hex` but re-packing an edited **flat ROM** back
  through the unpack directory + `.hex` for arbitrary edits is only partly wired
  (device flags work because they live in one chunk).
- Absolute fuel/ignition scaling constants.
- Individual SAI-vs-O2 isolation and the other device flags (exhaust valve, etc.).

## 13. Key source references (in the decompile)

`l.java`: `dc()` decrypt, `zc()`/`Nc()`/`Lb()` map load + tables, `sc()` directory,
`lc()` device list. `m.java`: `Vb()` seed/key, KWP framing (`Ld`/`Ub`), `uc()`
ROM packer. `MainActivity.java`: `p8()` load pipeline, unpack directory build,
`a3`/`W2` init sequences, Maps/ URLs. `c/r/s/t.java`: directory + geometry arrays.
`x.java` `a()`: per-ECU device layout (`x.t/x.s/x.q`) — not fully traced.