# Lofi-12 XT custom firmware research

> **Disclaimer:** everything here is for educational and entertainment purposes
> only. Modifying firmware can brick your device, void your warranty, or worse.
> Use at your own risk — the authors take no responsibility for damaged units,
> lost projects, or voided warranties.

Reverse engineering + modding toolkit for the **Sonicware Lofi-12 XT**
(TI TMS320C6748: ARM9 + C674x DSP). Status: **SD-update checksum solved 3/3** —
custom `.bin` images can be forged and flashed with the stock updater, no
hardware mods needed.

## Layout

| Path | What |
|---|---|
| `FINDINGS.md` | Device knowledge library (hardware, flash map, formats, checksum, updater) |
| `RE-PROCESS.md` | How it was done: dumping, Ghidra lab, C6000 notes, cracking playbook |
| `rev-diff.md` | v1.1.156 → v1.2.179 → v1.5.205 firmware diff |
| `tweakability-report.md` | What mods are feasible, risk ladder |
| `tools/` | Stdlib-only Python: parse/pack/patch/verify SD images |
| `analysis/` | Function mapping, checksum solver + prover |
| `ghidra/` | Ghidra helpers (vtable CSV, section mapper, headless PyGhidra drivers) |
| `docs/` | `hardware.md`, `bootloader.md`, `firmware-update.md`,
  `flash-dumping.md`, `firmware/v1.5.205.md`, own board photos |
| `docs/photos/` | Board + flash-chip photos (own work) |
| `docs/captures/` | Saleae Logic captures (`.sr`) |

## Quickstart (Level-0 mod)

You supply the stock `.bin` (official updates:
https://sonicware.jp/pages/downloads — see test vectors below) as `stock.bin`:

```bash
python3 tools/lofi_unpack.py stock.bin unpack/
python3 tools/lofi_pack.py unpack/ rebuilt.bin   # must be byte-identical: cmp stock.bin rebuilt.bin
python3 tools/lofi_patch_string.py stock.bin mod.bin Threshold ThresholX
python3 tools/prove_checksum.py mod.bin          # must print MATCH
```

Copy `mod.bin` to SD root as `Lofi-12 XT.bin`, hold PAD while powering on,
watch `SYSTEM UPDATE` on the OLED. Keep a stock SD for revert.

## Test vectors (verify your stock files first)

| Version | Size | SHA-256 | Entry | Sect |
|---|---|---|---|---|
| v1.1.156 | 1,595,605 | `617c3efe…1908ac5` (`617c3efea92399b0e3ed40890dd67a75013b0132059fa713076cae68a1908ac5`) | `C26C4820` | 7 |
| v1.2.179 | 1,606,197 | `30ea9eeb…616a212` (`30ea9eeb58cfeb2cddc68f1b15f65f2586d6956df27009eb9045ca78b616a212`) | `C26CA4C0` | 6 |
| v1.5.205 | 1,707,049 | `a8bffa65…198026` (`a8bffa65919c0a2d4ff2ce77d16301551af4d2964497b8804deed49ce4198026`) | `C2CD1AA0` | 7 |

`python3 tools/prove_checksum.py` must print `MATCH` for every stock image
(checksums `F58AF539 / DFF0D8C2 / B17C0857`).

## Safety + legal

- Mods here touch only the SYSTEM image on SD. The updater lives in separate SPI
  flash, so a bad image fails safe back to `SYSTEM UPDATE`. Still: no guarantees,
  flash at your own risk, keep the stock revert SD.
- **No vendor binaries or flash dumps are shipped in this repo** (Sonicware IP).
  Bring your own `.bin` from an official update ZIP; distribute mods as scripts,
  never as full images.

## License

MIT — see `LICENSE`. Covers the code, docs, and photos in this repo (own work
only); no vendor binaries are shipped.