qunexus-firmware/RECOVERY.md

QuNexus unresponsive after flashing a modified firmware image — technical report

Prepared for KMI support (or anyone attempting recovery). Everything below is observed fact except where marked as hypothesis.

Device

Product	QuNexus (RED), USB VID 0x1F38 PID 0x0018, bcdDevice 0x0200
Bootloader version	1.1.0 (reported by identity request before the flash)
Application version before flash	2.2.1
Host	macOS (Apple silicon), CoreMIDI

What was flashed

A modified copy of QuNexus_Firmware_v2.2.1-cs512.syx (the image shipped in the qunexus-qt6 editor's Qt resources, resources.qrc:83).

Sent with SendSysEx v0.10.0 in raw send mode (-n <port> -f <file>) after QunexusEnterBootloader.syx, using the default transfer settings: -cs 512 -cd 100 -pd 500.

Open question: it is not known whether the transfer ran to completion. Per SendSysEx --help, for multi-message (chunked) files an identity-reply handshake is performed between every chunk, with -cd (default 100 ms) as the timeout, "aborting the transfer otherwise". The console output was not retained. If the transfer aborted partway, the application region is partially written, which would be an additional and independent defect on top of the modification below.

The modification

Two edits relative to the stock v2.2.1 image (which spans 0x2400–0xF806):

1. 0xDF28: LCALL 0xA57B → LCALL 0xE8F2 (2 bytes changed, at 0xDF29)
2. 0xE8F2: a new 23-byte routine:

E8F2:  12 a5 7b   LCALL 0xA57B       ; original USB-MIDI cable routing
E8F5:  90 0f 9b   MOV DPTR,#0x0F9B   ; the 4-byte USB-MIDI event buffer
E8F8:  e0         MOVX A,@DPTR
E8F9:  54 f0      ANL A,#0F0h        ; isolate the cable number
E8FB:  70 0b      JNZ 0xE908         ; not cable 0 -> done
E8FD:  e0         MOVX A,@DPTR
E8FE:  44 20      ORL A,#020h        ; retag cable 0 as cable 2
E900:  f0         MOVX @DPTR,A
E901:  7e 0f      MOV R6,#00Fh
E903:  7f 9b      MOV R7,#09Bh
E905:  12 a5 7b   LCALL 0xA57B       ; route again, into the USB-3/CV ring
E908:  22         RET

Intent: have MIDI arriving on USB port 1 also reach the CV engine, since CV_Out_Source only offers Expander / USB 3.

The mistake: 0xE8F2 lies in a 270-byte address range (0xE8F2–0xE9FF) that no hex record in the stock image covers. A new record was added for it. Whether the bootloader erases a flash page it otherwise never writes was never verified.

Symptoms after flashing

• Device enumerates normally and repeatedly: correct VID/PID, correct product string, correct MIDI port names ("QuNexus Control Surface" / "Expander" / "CV"). So USB init, the descriptor tables, and the USB interrupt path are intact.
• No response to any MIDI input. A universal identity request (F0 7E 7F 06 01 F7) gets no reply at an 8-second timeout.
• QunexusEnterBootloader.syx has no effect, sent to any of the three ports.
• No CV output, from USB or from the local keys.

Diagnostics performed

Check	Result
USB presence / PID (ioreg)	present, PID 0x0018 = application
Identity request, Control Surface port	no reply (8 s)
Bootloader-entry SysEx to all 3 ports	no state change
Power-on bootloader window	none — kernel log shows exactly one enumeration per attach, always PID 0018; the bootloader never appears on the bus
USB vendor control request path	none — the EP0 handler at 0x7873 dispatches only Class (0x20) and Standard requests
DIN MIDI in	separate UART path exists (0xA90D reads SBUF0 → 0xE2AA → 24-byte ring at 0x0F31), but no Expander hardware available to test

Most probable mechanism: a second page erase destroyed 236 bytes of code

0xE8F2 lies in the 512-byte flash page 0xE800–0xE9FF. The absence of a stock record for 0xE8F2–0xE9FF meant only that the linker placed nothing there — not that the page was unused. In the stock image, 0xE800–0xE8F1 (the same page, just below the stub address) contains:

• 236 bytes of real code
• 27 branch targets, 19 of them functions with live callers
• 40+ call sites spread across the entire firmware (0xE888 from 9 sites, 0xE893 from 5, 0xE8D5 from 4, 0xE834 from 4) — the profile of compiler runtime helpers

The added record was appended as a new SysEx message immediately before the EOF record, i.e. last in the transfer, long after the bootloader had already erased page 0xE800 and programmed those 236 bytes. To program into that page again the bootloader must erase all 512 bytes of it. That erase would have destroyed the 236 bytes of legitimate code, leaving only the 23 stub bytes.

This accounts for every observed symptom simultaneously: calls to any of those 19 addresses now land in erased flash (0xFF = MOV R7,A) and run forward into unrelated code, so MIDI input never completes and the main loop derails, while interrupt-driven USB enumeration continues to work.

This has not been confirmed by reading the device's flash back, which is not possible without C2 access. A transfer aborted by the 100 ms inter-chunk handshake (see "Open question" above) would be an additional, independent cause of missing data.

Implication for recovery: a full reflash of 0x2400–0xF806 from the stock image restores everything; no permanent damage is expected.

C2 flash read — confirmed actual state (2026-08-17)

The hypothesis above ("a second page erase destroyed 236 bytes of code") is DISPROVEN by reading the device's flash back over C2. An RP2040 was wired to the EFM8 (GP2→C2CK/pin 13, GP3→C2D/pin 14) and a read-only C2 flash reader was built (firmware-tools/c2probe/, Pico SDK, implements only FPDAT Block Read 0x06 — no erase/write path). DEVICEID=0x28 (EFM8UB2) confirmed. The full 64 KB was dumped to firmware-tools/out/qunexus_device_dump.bin and diffed against the stock image. Findings:

Address range	Stock	Device	Verdict
0xE800–0xE8EB (236 B of code)	real code	identical to stock	INTACT — page was never erased
0xE8F2–0xE908 (23-B stub site)	0xFF (gap)	0xFF	stub never programmed
0xDF29–0xDF2A (LCALL target)	A5 7B	E8 F2	retarget was written
0xFBFF (lock byte)	—	0xFF	unlocked
0xFC00–0xFFFF (top 1 KB)	—	read fails	reserved/lock page (not app)

So the actual mechanism is the transfer-abort branch of the "Open question", not the page-erase branch: the 0xDF29 retarget sits in an existing record early in the transfer and was programmed; the appended 0xE8F2 record was last and was never sent before the 100 ms inter-chunk handshake aborted the transfer. Page 0xE800 was therefore never erased, the 236 bytes survived, and the stub was never written. The call at 0xDF28 now does LCALL 0xE8F2, which lands in 0xFF flash (MOV R7,A then runs forward into 0xFF...) and derails the USB-MIDI dispatcher 0xDF05 for every event on every USB port — matching "no response to any MIDI input" while interrupt-driven USB enumeration survives.

Other differences from the stock image are not damage:

• 0xF000–0xF806: user configuration (MIDI routing / per-channel / CV settings). The stock .syx carries factory defaults; this unit was personalized. The per-channel blocks at 0xF200/0xF400/0xF600 carry channel-index bytes 01/02/03 and differ only in config values (64 0F 14→64 01 0A, etc.). Expected on a used device.
• 0xEE00–0xEF5A: ~348 bytes in a stock gap (no record covers it). The bootloader only erases pages it has records for, so data written here by an earlier image persists across reflashes. Harmless — stock code does not reference it.

This revises the recovery outlook materially. The "no software recovery path" conclusion below was premised on 0xE8C5 (UART MIDI byte processor) and 0xE8E6 (LJMP 0x0000, the bootloader-entry jump) being erased. They are not erased — both are intact (inside the surviving 236 bytes). The only thing broken is the single LCALL at 0xDF28. Consequently:

• Minimal C2 fix: erase page 0xDF00–0xDFFF (app region — not the bootloader) and reprogram it with the stock bytes, restoring 0xDF29=A5 7B. That alone un-breaks the USB-MIDI receive path.
• Then normal recovery works: with MIDI input restored, the SysEx bootloader-entry command reaches 0xB48D → 0xE744 → 0xE8E6 (LJMP 0x0000) → bootloader, and the stock image can be reflashed over USB exactly as before the incident. No permanent damage; the bootloader region 0x0000–0x23FF was never touched and must still not be erased.

Either way only 0x2400–0xF806 should be programmed; no mass erase.

C2 flash write — recovery executed (2026-08-17)

The minimal C2 fix above was performed. The c2probe firmware was extended with guarded Page Erase (0x08) and Block Write (0x07) commands, hard-limited to the app region 0x2400–0xF9FF (bootloader 0x0000–0x23FF and lock/reserved 0xFA00+ are refused; no Device Erase / mass-erase command exists at all). The host script c2probe/reflash_page.py ran the verified sequence:

1. piinit (halt core) + wsetup (AN127 Table 3.6 SFR setup: FLSCL=0x90, VDM0CN=0x80, CLKSEL=0x03, RSTSRC=0x02).
2. Read page 0xDE00–0xDFFF (the 512-byte flash page containing 0xDF28; note the page base is 0xDE00, not 0xDF00 — pages are 512-byte aligned).
3. Page Erase page 0x6F → verified all 512 bytes read back 0xFF.
4. Block Write the stock bytes for 0xDE00 and 0xDF00 (256 + 256).
5. Read back and verify byte-identical to stock — MATCH.
6. C2 reset → EFM8 reboots into the restored app.

Result: 0xDF28 = 12 A5 7B (LCALL 0xA57B), the stock dispatcher call. The bad retarget to 0xE8F2 is gone. The bootloader region was never written or erased. The USB-MIDI receive path is intact again, so SysEx / bootloader entry should work; from here a full factory reflash of v2.2.1 over USB is possible but not required — only the one corrupted LCALL ever needed fixing.

Two firmware bugs found and fixed during the write: (a) Page Erase step 8 must poll OutReady until set (then read the 0x0D page-number ack), not until clear — AN127's "poll until clear" wording is misleading; the EFM8UB2 presents the ack byte with OutReady set. (b) The CDC command line buffer was 160 bytes, truncating the 522-char bw command; enlarged to 1024.

USB-1→CV patch applied via C2 (2026-08-17)

With the device recovered, the corrected patch (patch_usb1_to_cv.py, STUB_ADDR=0x8126) was applied surgically over C2 by c2probe/patch_c2.py: erase+reprogram page 0x8000 (23-byte stub into verified 0xFF padding at 0x8126) first, then page 0xDE00 (retarget 0xDF28→LCALL 0x8126) second — stub-page-first ordering means a mid-failure never leaves a dangling retarget. Both pages read back byte-exact, and only the intended bytes changed. The device was reset and functionally verified on an oscilloscope: MIDI sent to USB port 1 (Control Surface) now drives the CV gate and 1 V/octave pitch outputs, which it never did before. User personalization at 0xF000–0xF806 was preserved (only two pages touched). The patch is fully reversible over C2 (reflash_page.py restores 0xDE00 to stock; the stub page can be restored the same way).

The application has no alternative bootloader-entry path

Established by recursive-descent disassembly of the whole image:

• The only bootloader-entry trigger is the SysEx command. Handler at 0xB48D checks category 0x11 (SYX_SYSTEM) and command 0x00 (SYX_SYS_RESET) at 0xB499/0xB49E, then calls 0xE744.
• 0xE744 disables interrupts and falls through to 0xE8E6, which is LJMP 0x0000 — the only LJMP 0x0000 in the entire 54 KB image.
• 0xE744 has exactly one caller (0xB4A6); 0xE8E6 has exactly one referrer (0xE751, inside 0xE744).
• There is no software reset anywhere: every RSTSRC write is VDD-monitor init (RSTSRC = 0x02 following VDM0CN = 0x80). No watchdog-forced reset path either.
• No key/button code reaches 0xB48D; its entire caller chain is MIDI message processing.

Two of the destroyed functions are exactly the ones needed for recovery, both inside the erased range 0xE800–0xE8F1:

Address	Function	Consequence
0xE8C5	UART/DIN MIDI byte processor, called from the main service loop at 0xE045	Expander-port (J2) MIDI input is dead, so the enter-bootloader SysEx cannot be delivered over the UART either
0xE8E6	LJMP 0x0000 — the bootloader entry jump	bootloader entry is dead even if a command were received

The UART is configured for MIDI (SCON0 = 0x50, Timer 1 mode 2, reload 0xC0 → 31250 baud at 48 MHz), and the receive ISR at 0xA90D reads SBUF0 into a 24-byte ring at 0x0F31 via 0xE2AA; the ring is drained at 0xE042/0xE47E and each byte handed to the now-missing 0xE8C5.

Consequently no software recovery path exists: not USB MIDI, not DIN MIDI via the Expander port, not a key/button combination, not a USB vendor request, and not a power-on bootloader window (verified by kernel USB logs — exactly one enumeration per attach, always PID 0x0018).

Note also that the application does ACALL 0x21D4 at 0x265E, i.e. it calls a routine inside the bootloader region, so the bootloader exposes an API to the application.

What is needed

The key question for KMI: does the bootloader at 0x0000–0x23FF check a button/key at power-on, or offer any entry path that does not require the application to be functional? That region is not present in any .syx file, so it could not be analysed here.

Failing that, either:

1. EFM8 factory bootloader (AN945). The MCU is an EFM8UB20F64G in QFP48. Per the EFM8UB2 data sheet (Rev 1.3) Table 3.3, the 48-pin package enters bootload mode by holding P3.7 (QFP48 pin 23) low at reset; the bootloader lives in the last three pages of code flash and runs after any reset when the Bootloader Signature Byte (the byte before the Lock Byte) is 0xA5. The application image ends at 0xF806 and so never overlaps that region — but whether KMI erased the factory bootloader in production is unknown. For reference, QFP48 pin 13 = RST/C2CK, pin 14 = C2D.
2. Direct reflash over the C2 debug interface.

In either case only 0x2400–0xF806 should be programmed, and no mass erase should be performed: that would destroy KMI's bootloader and/or the factory bootloader, neither of which is recoverable from available files.

Files available

In firmware-tools/out/:

File	Contents
QuNexus_Firmware_v2.2.1.bin	stock v2.2.1 application image, flat binary, base 0x2400, 54 279 bytes
QuNexus_Firmware_v2.2.1.hex	the same as standard ASCII Intel HEX
QuNexus_Firmware_v2.2.1-cs512-usb1cv-v2.syx	corrected patch (stub relocated to 0x8126, inside an existing stock record) — not the image that was flashed

The image that was flashed is reproducible from the stock .syx with patch_usb1_to_cv.py by setting STUB_ADDR = 0xE8F2 and using the add-a-new-record path.

Note that these images cover only 0x2400–0xF806. The bootloader region 0x0000–0x23FF is not present in any .syx and must not be erased.