# Lofi-12 XT custom-firmware tools

Stdlib-only Python (`tools/`). Verified against v1.1.156 / v1.2.179 / v1.5.205.

| Script | Purpose |
|---|---|
| `lofi_image.py` | Shared parser/packer library (import, not CLI) |
| `lofi_unpack.py` | `image.bin outdir/` — verify chain, dump `headers.json` + `sectN_addr*.bin` |
| `lofi_pack.py` | `indir/ out.bin [--checksum HEX]` — rebuild exact-fit image |
| `lofi_patch_string.py` | Same-length UI string swap (Level-0 mod, addresses stable) |
| `lofi_xref.py` | Count code/self pointers, list slack zero-gaps, locate string + refs |
| `lofi_checksum.py` | Quick check: CRC/adler/fletcher/sum/xor over obvious spans |
| `lofi_checksum_crack.py` | Long-running cracker: Phase A fast hashes + xor-mask detect, Phase B generic CRC param search (1,008 combos, multiprocessed), Phase C seeded CRC32-IEEE brute force 0..2²⁴ (hours) |

## Safe first loop (do not flash until checksum is cracked)

```bash
python3 tools/lofi_unpack.py "Lofi-12XT_v1.5.205/Lofi-12XT_v1.5.205/Lofi-12 XT.bin" /tmp/opencode/fw/unpack-1.5.205
python3 tools/lofi_pack.py /tmp/opencode/fw/unpack-1.5.205 /tmp/opencode/fw/rebuilt.bin
cmp "Lofi-12XT_v1.5.205/Lofi-12XT_v1.5.205/Lofi-12 XT.bin" /tmp/opencode/fw/rebuilt.bin  # must be identical
python3 tools/lofi_patch_string.py "Lofi-12XT_v1.5.205/Lofi-12XT_v1.5.205/Lofi-12 XT.bin" /tmp/opencode/fw/patched.bin Threshold ThresholX
python3 tools/lofi_xref.py "Lofi-12XT_v1.5.205/Lofi-12XT_v1.5.205/Lofi-12 XT.bin" --find "AUDIO EXPORT"
python3 tools/lofi_checksum.py
```

## Cracking the checksum (the blocker)

```bash
# smoke tests (seconds):
python3 tools/lofi_checksum_crack.py --quick-only
python3 tools/lofi_checksum_crack.py --jobs 2 --limit 40 --out /tmp/opencode/ck-smoke.txt

# full long run (Phase B ~minutes, Phase C ~hours, all cores):
python3 tools/lofi_checksum_crack.py --jobs $(nproc) --out /tmp/opencode/ck-results.txt

# Phase D batch — CRC-16 family, ones-complement, chained per-sect, FNV-1/DJB2/Murmur (~1 min):
python3 tools/lofi_checksum_phaseD.py --jobs $(nproc) --out /tmp/opencode/ck-phaseD.txt
```

Results (exact or constant-xor-mask hits) append to the `--out` file;
progress checkpoints go to `--out.progress`. Any hit must match **all 3**
builds to be reported. Re-run with `--seed-max 4294967296` for the full
2³² seed space only if 2²⁴ finds nothing.

## Blockers / rules

- `cmtd+0x08` checksum: **solved** — `lofi_image.compute_checksum`
  (CRC32-IEEE, init 0, over the image with bytes `[8:12]` replaced by
  `0xC27C6282`; proven 3/3 against stock images). `lofi_pack` and
  `lofi_patch_string` apply it automatically.
- Keep a known-good stock `.bin` on SD for revert; never touch SPI flash / USB MCU.
- Distribute mods as patches against user-supplied stock `.bin`, not full images.
- See `tweakability-report.md` (levels 0–4) and `rev-diff.md` for what is feasible.