# USB nRF24 dongle A cheap "USB NRF24L01+ 2.4G" stick (AliExpress, board marked **USB_24RF Ver 3.1**, Rainsun chip antenna) reflashed with our own firmware so it can be the PC-side radio for the hexapod: same nRF24 air settings as the robot and the remote, talking to Unity over USB serial. It shipped with a closed "AT command" bridge firmware. We replaced that with the two-stage firmware in `firmware/`. **The factory firmware could not be backed up** (read-protected, see below), so this is a one-way change — done on the owner's say-so. ## Hardware (reverse-engineered from the board) | Part | Chip | Notes | |------|------|-------| | MCU | **STM32F030F4P6** | Cortex-M0, 16 KB flash, 4 KB RAM, TSSOP-20 | | USB-serial | **CH330N** | shows up as "USB-SERIAL CH340" on Windows (COM port) | | Radio | **Si24R1** | nRF24L01+ clone, driven over SPI; 16 MHz crystal | | PA/LNA | **AT2401C** | 2.4 GHz power amp + low-noise amp (range booster) | | antenna | Rainsun chip antenna | | ### Pin map (MCU) Found by probing the board over SWD and confirmed at runtime by our firmware: | Function | STM32 pin | |----------|-----------| | USB serial (USART1) TX / RX | PA9 / PA10 → CH330N | | SPI1 SCK / MISO / MOSI | PA5 / PA6 / PA7 → Si24R1 | | nRF CSN / CE / IRQ | PA3 / PA4 / PA2 | | status LED (active-high) | **PA0** — confirmed by eye | | AT2401C TX/RX enable + unused | PA1, PB1, PF0, PF1 — **not yet distinguished** | PA0 drives the LED (HIGH = on). The AT2401C control lines are among PA1, PB1, PF0, PF1 (the TSSOP-20 has no other GPIO). Listening for ambient 2.4 GHz with the radio's carrier-detect bit was too noisy to tell them apart, so they need a real link test (dongle ↔ robot/remote, trying each pin while watching whether packets get through). The radio still works without driving the amplifier, just at reduced range. The app firmware can drive any pin (`0`-`4`), sweep them all (`a`), and run a carrier-detect finder (`f`/`n`). ### Programming header (5 holes next to the CH330N) Square pad = hole 1. | Hole | Signal | |------|--------| | 1 | BOOT0 | | 2 | 3V3 | | 3 | GND | | 4 | SWDIO (PA13) | | 5 | SWCLK (PA14) | The factory firmware repurposed PA13/PA14, so SWD only answered with **BOOT0 tied high** (hole 1 → hole 2) at power-up. With our firmware this header is not needed at all — see flashing below. ### Flash readout protection The STM32 was at **RDP level 1**: reads of flash are refused over both SWD and the ROM bootloader, so the factory firmware cannot be dumped. Level 1 (not the permanent level 2) still allows reflashing — unlocking does a mass-erase, which is what wiped the factory firmware. The only way past RDP1 to read it would be the F0 cold-boot stepping exploit (thousands of power cycles); not worth it. ## Firmware: two stages, so wire-free flashing can never break The whole point of the design: **once installed, the dongle is reflashed over USB forever, with no BOOT0 wire and no ST-Link — and no firmware update can take that ability away.** ``` flash (16 KB): 0x08000000 +--------------------+ page 0 | safeboot (4 KB) | stage 1: permanent recovery bootloader 0x08001000 +--------------------+ page 4 | app (12 KB) | stage 2: the radio firmware 0x08004000 +--------------------+ page 16 RAM (4 KB): 0x20000000 = magic word (app -> safeboot signal); .data/.bss from +4 ``` - **`safeboot`** (`firmware/safeboot.c`) runs first on every reset. It speaks a tiny, fixed-baud (115200 8N1) flash protocol over USB and can always erase and rewrite the app. It has no dependencies and is flashed once. - **`app`** (`firmware/app.c`) is the actual radio firmware. It is the only part future updates rewrite. - **The app updater only erases pages 4-15 — never safeboot.** So a buggy app can't remove the recovery path. Recovery is guaranteed three ways, none needing the wire: 1. normal update — the running app resets into safeboot on the `b` command (the CH330N keeps its USB power across an MCU reset, so the COM port doesn't drop); 2. a corrupt/missing app — safeboot sees the app's reset vector is invalid and stays in flash mode; 3. a booting-but-wedged app — safeboot opens a 1.5 s knock window on every cold boot; the updater spams `S` after a replug to catch it. The only thing that could break it is corrupting safeboot itself, which the updater never writes. ### safeboot flash protocol (115200 8N1) Each command replies one byte, `K` = ok / `E` = error, unless noted. | Cmd | Bytes | Action | |-----|-------|--------| | `P` | | ping | | `V` | | prints `SBV1` (identify) | | `E` | | erase app region (pages 4-15) | | `W` | addr(LE32) n data[n] | program n bytes (n even, ≤128) | | `R` | addr(LE32) n | read n bytes (returns n bytes, no `K`) | | `G` | | `K`, then boot the app | Banners: `SBF` = entered flash mode via the app; `SB1` = cold boot (knock window open); `SBR` = no valid app, staying in flash mode. ## Building Needs the ARM toolchain PlatformIO ships: ``` C:\Users\you\.platformio\penv\Scripts\pio.exe pkg install -g -p ststm32 ``` Then, from `firmware/`: ``` .\build.ps1 ``` Produces `build/safeboot.bin`, `build/app.bin`, and `build/dongle_combined.bin` (safeboot padded to 4 KB + app), plus the sizes. ## Flashing ### One-time install (the only time the BOOT0 wire is used) Puts safeboot + app on a stick that still has the factory (or any) firmware. 1. Wire **hole 1 → hole 2** (BOOT0 high) and plug the stick into USB. 2. `python tools/dongle_flash.py firmware/build/dongle_combined.bin` - unlocks (mass-erase, the step that wipes the factory firmware), - writes and verifies the combined image, - starts it. 3. Remove the wire. Never needed again. `dongle_flash.py` drives the STM32 **ROM** UART bootloader (one-shot auto-baud per power-up, so power-cycle between attempts). ### App updates (normal, wire-free, forever after) ``` python tools/safeboot_flash.py firmware/build/app.bin ``` This resets the running app into safeboot and rewrites only the app region. If the app is dead or doesn't answer, start it with `--knock` and then replug the stick: it keeps knocking (reopening the port as it comes back) until it lands in safeboot's 1.5 s cold-boot window. ## Air settings Matches `shared/HexapodProtocol/HexapodProtocol.h`: 2.4 GHz channel 96 (2.496 GHz), 250 kbps, 5-byte address `HXPD1`, 16-bit CRC. The app sets these on the Si24R1 over SPI (same register layout as the nRF24L01+). ## Status / next - [x] identify the hardware, map the radio + serial pins - [x] permanent two-stage firmware, wire-free USB flashing - [ ] identify the LED and AT2401C TX/RX-enable pins (app toggles the 5 free pins) - [x] bridge mode: the dongle stands in for the robot's radio, Unity runs the robot firmware (sim) behind it — see "Bridge mode" below - [ ] the other direction: Unity as the remote, driving the real robot - [ ] AT2401C pins: at desk range and even a few rooms away with the remote at minimum power, every on/off combination of PA1/PB1/PF0/PF1 received every packet, so they couldn't be told apart; the link works without driving them ## Bridge mode (Unity ↔ real remote) The app listens on the hexapod's air settings as if it were the robot (ch 96, 250 kbps, `HXPD1`, auto-ack, dynamic payload lengths, ack payloads) and passes everything to the PC. Framing both ways over the USB serial (115200 8N1): ``` A5 type len payload[len] sum sum = type + len + payload bytes (mod 256) ``` | Direction | Type | Payload | |-----------|------|---------| | PC → dongle | `L` | — : start bridging (LED on) | | PC → dongle | `X` | — : stop | | PC → dongle | `A` | ≤ 32 bytes: the robot's `Telemetry`, sent back on the auto-ack of the remote's next packet (reloaded after every packet, like `robot/Comms.cpp`). Dropped if not refreshed for ~0.5 s, so the remote never shows stale telemetry as live | | dongle → PC | `R` | a packet the remote sent (its `CmdPacket`, any length; the firmware checks it) | | dongle → PC | `S` | once a "second": packets received (u16 LE), ack payloads loaded (u16 LE). Its second runs ~30% long (blocking UART sends miss SysTick ticks); it's only for display | Plain text never contains `A5`, so the PC skips anything between frames; while bridging the app prints no text and only takes frames (and `b` for a reflash). USB serial input goes through DMA into a ring buffer (no interrupts in this app), and the USART's overrun stall is disabled, so a burst can't deafen it. Unity's side is `Hexapod_Simulation_Unity/Assets/HexapodSim/DongleLink.cs`.