Dongle (app):
- bridge mode: stands in for the robot's radio (ch 96 / 250k / HXPD1,
auto-ack, dynamic payloads, ack payloads). Received packets go to the PC
as A5-framed 'R' frames; the PC's 'A' frames become the ack payload of
the next packet, like robot/Comms.cpp; dropped after ~0.5 s without a
refresh. 'S' status once a second.
- USART RX through circular DMA into a ring buffer, overrun stall
disabled, error flags cleared: a burst (e.g. SignalRGB probing the port)
used to deafen the app until a replug.
- RX test mode ('x') accepts protocol v4's dynamic-length packets.
- safeboot_flash.py --knock: keeps knocking across a replug to catch
safeboot's cold-boot window when the app doesn't answer.
Unity:
- SimRemote sources: Keyboard, or the real remote via the dongle
(DongleLink.cs: kernel32 serial, auto-finds the CH340, all port I/O on
one background thread). Packets go into the firmware byte for byte, the
robot's telemetry goes back on the ack, so the remote's display shows
the sim. Tested end to end with the real remote.
- Dropped the USB joystick and robot-serial-harness inputs and the old
Serial/Serial2/Serial3/HandleHoystick scripts (and their components in
Main.unity): no USB links to remote or robot any more.
- Test panel: dongle status; no sideways scroll bar.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
206 lines
8.4 KiB
Markdown
206 lines
8.4 KiB
Markdown
# 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`.
|