lofi-12xt-firmware/tools/README.md

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)

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)

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