Repository navigation
feat(tools): add a Mac-side UBOOT rescue for a crash-looping BlackBox - #14
Merged
isod89 merged 4 commits intoNov 8, 2026
Merged
Conversation
…ckBox tools/uboot_rescue.py waits for the pedal in its JieLi mask-ROM USB boot state (4C4A:8057), loads the pinned wl82loader.bin into RAM, backs up the whole flash, checks the head against the official package and, only with --write, rewrites the differing 4 KiB sectors in [0x4000, end of image) with read-back. It is read-only by default, whitelists the loader commands (no chip erase, no key burn), refuses a wrong chip key or flash size, and resumes on rerun. libusb is called through ctypes; no pip packages. Tested against a simulated UBOOT pedal (make rescue-check, part of make test); the protocol has not yet been run on the real pedal beyond finding it and reading its descriptor.
…ake rescue, make rescue-write) node tools/op.mjs rescue [--write] runs tools/uboot_rescue.py through sudo, read-only unless --write; make rescue and make rescue-write call it. op.mjs doctor now reports the rescue prerequisites (libusb, official package, cached loader, root) through uboot_rescue.py --check. docs/RESCUE.md records what the captain's first real run left behind (two identical pre-write backups: BlackBox_936, head matching, 159 of 160 sectors differing) and marks the rest unknown. The installer page and the README point a looping pedal at the Mac route first and the SD-card route second. A new project skill, openpocket-rescue, tells an agent when and how to rescue, the safety rules and who runs the sudo write. tests/test_op.mjs covers the op.mjs and Makefile wiring and the doctor call; test_uboot_rescue.py covers --check.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This adds a Mac-side rescue for a pedal that is stuck crash-looping, such as after a bad test image, without SD-card hardware. Between crashes the pedal sits in the JieLi mask-ROM USB boot state (
WL80UBOOT1.00), andtools/uboot_rescue.pyspeaks its USB protocol through libusb to restore the official firmware from the official package.It is run as
node tools/op.mjs rescue,make rescueormake rescue-write. It is read-only by default and writes only with--write, only inside the app area, with a verified read-back of each sector; it never erases the chip or burns a key.op.mjs doctorchecks and explains the libusb andsudoprerequisites.docs/RESCUE.mddocuments the procedure and the recorded real run, the README Install section lists the Mac route before the SD-card route, the installer page gains a hint, and theopenpocket-rescueskill lists the safety rules.The protocol, guards and resume behaviour are tested on host against a simulated pedal (
tests/uboot_sim.py,tests/test_uboot_rescue.py), and the full host suite passes. It was proven on a real crash-looping BlackBox, which it restored.