Files
hexapod-robot/2026-current/dongle
mangavalkandClaude Opus 5.5 179afdb705 2026 docs: review of every README against today's state
- README / CLAUDE.md layout: dongle/, hardware/, tools/ submodule,
  make_remote_hmi.py; telemetry in the protocol; the PC can take the
  robot's place on the radio. CLAUDE.md: NextionUI is on Serial2 (said
  Serial1); remote-without-robot via the dongle + sim.
- remote/README: MPU6050 supply row; stick calibration button names of the
  new SETUP page; upload/USB-port hints.
- remote/NEXTION.md: display on Serial2, how the Editor upload goes.
- robot/README: Battery in the file list, Comms/ServoDriver roles, packet
  structs instead of payload size, check the IMU gives live data (the
  remote's MPU6050 needed a full reset; RobotIMU::begin() only wakes it).
- sim/README: smoke test covers telemetry and servo calibration;
  OpenScadModel.
- dongle/README: AT2401C test result, app command table, SignalRGB note,
  air settings incl. ack payloads.
- PLANNING.md: the display direction is in the generated HMI.
- Unity README: what the project is.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:56:14 +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
status LED (active-high) PA0 — confirmed by eye
AT2401C TX/RX enable + unused PA1, PB1, PF0, PF1 — not distinguishable (see below)

PA0 drives the LED (HIGH = on). The AT2401C control lines would be 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. The real link test (2026-11-17: receiving the remote while switching all 16 on/off combinations, at the desk and a few rooms away with the remote at minimum power) got every packet in every combination, so either the link has plenty of margin or the amplifier is switched in hardware. The firmware leaves them low; the link works.

App commands (USB serial, 115200, single keys, when not bridging)

Key Action
v banner: version and a few radio registers
r dump nRF registers
x RX test on the hexapod's air settings; prints packets/s once a second
0-4 toggle PA0 (LED) / PA1 / PB1 / PF0 / PF1
a sweep every free pin high for 3 s each
f / n carrier-detect finder on / next channel
b reset into safeboot (what safeboot_flash.py uses)

SignalRGB (if installed) opens every CH340 COM port it sees and holds it; quit it while using the dongle.

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, auto-ack with dynamic payload lengths and ack payloads (protocol v4). 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
  • LED pin (PA0)
  • 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.