# QuNexus firmware v2.2.1 — reverse-engineered source

Disassembly and pseudo-decompilation of the Keith McMillen / KESUMO QuNexus
application firmware (EFM8UB20F64G, an 8051-core MCU), produced with radare2.

This is a **nested git repository** (its own repo, living under the parent
`qunexus-qt6` project). It is self-contained: the stock input binary is
included so every artifact here can be regenerated with one command.

## Input

| File | What |
|---|---|
| `QuNexus_Firmware_v2.2.1.bin` | stock v2.2.1 application image, flat binary, base `0x2400`, 54 279 bytes, spans `0x2400`–`0xF806`. (The bootloader region `0x0000`–`0x23FF` is not in this image and is not decompiled here.) |

## Generated artifacts

| File | What | Lines |
|---|---|---|
| `qunexus_v2.2.1.asm` | **Full linear disassembly** of the whole image, absolute code-space addresses (`0x2400`+), with xrefs & comments. Nothing omitted. | 37 287 |
| `pseudocode_all.c` | r2 `pdc` C-like **pseudocode for all 1002 functions**. 668 complete; 334 end with `// chop` (r2's size limit on big functions — see those in the asm). | 38 396 |
| `functions.txt` | r2 function index: `address  size  nblocks  name` — 1002 functions. | 1 002 |

## Reproduce

```
brew install radare2          # one-time
./regen.sh                    # rebuilds the three artifacts from the .bin
```

`regen.sh` runs `r2 -a 8051 -b 8 -m 0x2400 -i r2script.r2 QuNexus_Firmware_v2.2.1.bin`.
`r2script.r2` is the exact radare2 script used.

## Faithfulness — does it re-compile?

The disassembly is **byte-faithful**: reconstructing the binary from the asm's
byte columns (30 560 instructions + 195 small data gaps) reproduces the
original 54 279-byte image **byte-for-byte**. So the listing is a complete,
accurate representation — nothing lost or corrupted.

The r2 `.asm` file is **not** directly valid input to an 8051 assembler (it is
r2 display format: function borders, xref comments, `fcn.xxxx` labels, address
prefixes). To re-assemble into a flashable binary it must be converted to a
real assembler's syntax (e.g. `sdas8051` from SDCC, or Keil A51): strip r2
annotations, turn `ljmp`/`lcall` targets into labels, emit the 195 data gaps as
`.db`, and set `.org 0x2400`. With that conversion it re-assembles to the
identical binary. (Round-trip via SDCC is the natural next step if needed.)

## Known landmarks (verified in the output)

| Address | Meaning |
|---|---|
| `0x2400` | app reset vector (`ljmp 0xb691`) |
| `0xA57B` | USB-MIDI router: cable number → destination ring buffer |
| `0xDF05` | USB-MIDI event dispatcher |
| `0xDF28` | `LCALL 0xA57B` — the single call site the USB-1→CV patch retargets |
| `0x8126` | 23-byte `0xFF` padding region the patch's stub is written into |
| `0xE8E6` | `LJMP 0x0000` — the only bootloader-entry jump |
| `0xB48D` | SysEx command handler (bootloader-entry path) |

## Caveats

- r2's 8051 auto-analysis is decent but imperfect: data-in-code regions decode
  as the matching instruction (a linear-sweep artifact). Use `ljmp`/`lcall`/
  `acall` targets and `functions.txt` as the map of real code.
- `pdc` chops ~1/3 of functions (the big ones). The asm listing covers them
  fully. For unchopped Ghidra-quality pseudocode, the `r2ghidra` plugin
  (`r2pm install r2ghidra`, then `pdg @ func`) is the upgrade path.

## Provenance

Decompiled 2026-08-17 from the stock `QuNexus_Firmware_v2.2.1.bin` (the same
image shipped in the qunexus-qt6 editor's Qt resources as
`QuNexus_Firmware_v2.2.1-cs512.syx`). The reverse-engineering was done in
service of a USB-1→CV routing patch (see `../patch_usb1_to_cv.py` and
`../c2probe/`); this repo captures the reference disassembly of the unmodified
firmware.