Files
hexapod-robot/2026-current/dongle/README.md
T
mangavalkandClaude Opus 5.5 2a4f6335dd 2026 dongle: LED is PA0, add RX/finder/sweep pin-finding modes to the app
- Confirmed the status LED is on PA0 (active-high). README pin table updated:
  amplifier (AT2401C) control is one of PA1/PB1/PF0/PF1, still to distinguish.
- app.c gains bring-up modes for mapping the amplifier pins:
  - 'x' RX on the hexapod protocol (ch96/250k/HXPD1, 22-byte) + packet counter,
    to find the RX-enable pin by which pin lets the remote's packets arrive;
  - 'f'/'n' carrier-detect (RPD) finder (too noisy alone, kept for reference);
  - 'a' sweep every usable pin HIGH ~3s for LED/scope checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 23:39:50 +01:00

6.6 KiB

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, 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

  • identify the hardware, map the radio + serial pins
  • 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"