Init

2026-09-30 22:48:06 +02:00
commit 8913cb4314
37 changed files with 3190 additions and 0 deletions
@@ -0,0 +1,53 @@
+# 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.