2026-11-14 23:14:16 +01:00
|
|
|
# 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 |
|
2026-11-14 23:39:50 +01:00
|
|
|
| status LED (active-high) | **PA0** — confirmed by eye |
|
|
|
|
|
| AT2401C TX/RX enable + unused | PA1, PB1, PF0, PF1 — **not yet distinguished** |
|
2026-11-14 23:14:16 +01:00
|
|
|
|
2026-11-14 23:39:50 +01:00
|
|
|
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`).
|
2026-11-14 23:14:16 +01:00
|
|
|
|
|
|
|
|
### 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, replug the stick and re-run — it will catch the knock 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)
|
|
|
|
|
- [ ] radio hub app: carry `CmdPacket` both ways, per-node addressing, telemetry
|
|
|
|
|
- [ ] Unity serial bridge (PC as hub when online, robot as hub when not) — see
|
|
|
|
|
`../README.md` "Planned"
|