From 179afdb705c2af4e7e9e01feceb300ff3644e4a3 Mon Sep 17 00:00:00 2001 From: MangaValk Date: Tue, 17 Nov 2026 22:56:06 +0100 Subject: [PATCH] 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 --- 2026-current/CLAUDE.md | 10 ++++- .../Hexapod_Simulation_Unity/README.md | 4 ++ 2026-current/README.md | 15 +++++--- 2026-current/dongle/README.md | 37 ++++++++++++++----- 2026-current/hardware/openscad/PLANNING.md | 3 +- 2026-current/remote/NEXTION.md | 9 ++++- 2026-current/remote/README.md | 16 +++++--- 2026-current/robot/README.md | 19 +++++++--- 2026-current/sim/README.md | 12 ++++-- 9 files changed, 92 insertions(+), 33 deletions(-) diff --git a/2026-current/CLAUDE.md b/2026-current/CLAUDE.md index 5926a55..770b27f 100644 --- a/2026-current/CLAUDE.md +++ b/2026-current/CLAUDE.md @@ -14,7 +14,10 @@ remote/ Teensy 4.0 firmware (PlatformIO env remote) shared/HexapodProtocol/ wire protocol, used by robot, remote and sim sim/ robot firmware -> hexapod_sim.dll (CMake + g++), headless smoke test Hexapod_Simulation_Unity/ Unity 6000.6 project that loads the DLL (Assets/HexapodSim/) -scripts/ PlatformIO helper +dongle/ USB nRF24 stick firmware (STM32F030): the PC's radio, bridge mode for Unity +hardware/ OpenSCAD rebuild + new remote case, Fusion 360 designs, PCB notes +scripts/ PlatformIO helper, make_remote_hmi.py (generates remote/remote.HMI) +tools/nextion-hmi-tools/ git submodule: nxhmi (.HMI read/write/render, MCP server) ``` This folder is `2026-current/` inside the `hexapod-robot` repo. The older generations sit next to it @@ -145,7 +148,7 @@ link-loss disarm, servo-trim read-back from telemetry) → PacketBuilder → | `PacketBuilder` | the inverse of InputMapper: stick frame → body frame per the contract, per-submode right-stick mapping, `FLAG_WALK` with 250 ms linger (twist ignored in mode B), tilt deadzone/scale × fade, zeros motion when disarmed | | `RadioLink` | nRF24 TX, short retries (1, 3), ack-based link status and 32-packet quality %, telemetry from the ack payloads (stale after `TELEMETRY_STALE_MS`) | | `Battery` | handset battery through a divider; `BATTERY_SENSE_PIN` 255 = not wired yet (planned A6) | -| `NextionUI` | library-free Nextion driver on `Serial1`. HMI sends `'#' len cmd [val]` frames via `printh`; every page's Preinitialize sends `'P'` + page id (and `sendme` / 0x66 recovers the page after a remote restart). The remote writes **only the showing page**, by local component name, and only what changed (FNV hash per instruction in a per-page slot cache), 20 Hz (SERVOS 10 Hz), never blocking on a full TX buffer; full refresh every 2 s and on the 0x88 "ready" frame. UPDATE DISPLAY (tapped twice) or serial `U` runs `runUploadPassthrough()`: USB ↔ display bridge for Nextion Editor, following `Serial.baud()`, never returns | +| `NextionUI` | library-free Nextion driver on `Serial2` (pins 7/8). HMI sends `'#' len cmd [val]` frames via `printh`; every page's Preinitialize sends `'P'` + page id (and `sendme` / 0x66 recovers the page after a remote restart). The remote writes **only the showing page**, by local component name, and only what changed (FNV hash per instruction in a per-page slot cache), 20 Hz (SERVOS 10 Hz), never blocking on a full TX buffer; full refresh every 2 s and on the 0x88 "ready" frame. UPDATE DISPLAY (tapped twice) or serial `U` runs `runUploadPassthrough()`: USB ↔ display bridge for Nextion Editor, following `Serial.baud()`, never returns | | `SerialConsole` | USB keystrokes that mirror every UI command plus diagnostics | | `SmoothedValue.h` | copy of the robot's (kept separate so robot/ stays untouched) | | `NEXTION.md` | the HMI: pages, command bytes, which components the firmware writes | @@ -236,6 +239,9 @@ Remote stick-frame convention: logical X + = right, Y + = forward, twist + - **Robot firmware in simulation:** `sim/build/sim_smoke.exe` (headless, scripted checks), or Unity Play mode with Keyboard input or the real remote over the radio (USB nRF24 dongle). +- **Remote without robot:** the Unity sim behind the USB nRF24 dongle + answers like the robot (telemetry, servo calibration), see + `sim/README.md`. - **Remote without robot or display:** the USB serial console (see `remote/README.md`). `p` shows raw/mapped sticks, IMU, link and state. `d` dumps packets at 10 Hz. With no robot, the link shows DOWN and diff --git a/2026-current/Hexapod_Simulation_Unity/README.md b/2026-current/Hexapod_Simulation_Unity/README.md index 1043e02..69442be 100644 --- a/2026-current/Hexapod_Simulation_Unity/README.md +++ b/2026-current/Hexapod_Simulation_Unity/README.md @@ -1 +1,5 @@ Hexapod + +The Unity side of the firmware simulation: it runs the unchanged robot firmware +(`../sim/build/hexapod_sim.dll`) on the 3D model, driven by the keyboard or by the +real remote over the radio (USB nRF24 dongle). See `../sim/README.md`. diff --git a/2026-current/README.md b/2026-current/README.md index 9d53105..bcd451d 100644 --- a/2026-current/README.md +++ b/2026-current/README.md @@ -1,7 +1,9 @@ # Hexapod A six-legged walking robot (Teensy 3.6) and its handheld remote -(Teensy 4.0 + Nextion touchscreen), linked over nRF24L01. +(Teensy 4.0 + Nextion touchscreen), linked over nRF24L01: commands from the +remote, telemetry back from the robot. A USB nRF24 stick lets the PC (the +Unity simulation) take the robot's place on the radio. ![The hexapod, OpenSCAD model in its standing pose](hardware/openscad/renders/hexapod.png) ![The remote (v2), OpenSCAD model: black ASA with a red honeycomb and white ON/OFF inlay](hardware/openscad/renders/remote_v2.png) @@ -11,16 +13,19 @@ printed yet). The original printed remote is on the [archive page](hardware/openscad/ARCHIVE.md). ``` -robot/ robot firmware: IK, gait, body pose, IMU stabilization, state machine -remote/ remote firmware: 2 x 3-axis sticks, MPU6050 tilt, Nextion UI, RF24 TX -shared/ HexapodProtocol: the CmdPacket wire format + radio settings used by both +robot/ robot firmware: IK, gait, body pose, IMU stabilization, state machine, + servo centre calibration, telemetry +remote/ remote firmware: 2 x 3-axis sticks, MPU6050 tilt, Nextion UI, RF24 link + (+ remote.HMI, the touchscreen project) +shared/ HexapodProtocol: CmdPacket + Telemetry wire formats + radio settings sim/ the unchanged robot firmware compiled into a DLL for the simulation Hexapod_Simulation_Unity/ Unity project that runs that DLL on the 3D model dongle/ USB nRF24 stick firmware (STM32F030): the PC-side radio, see dongle/README.md hardware/openscad/ OpenSCAD model of the robot (rebuilt from the Fusion designs) and the new remote hardware/openscad/stl/ print-ready STL exports hardware/fusion360/ Fusion 360 designs: body, legs, servo, servo horn, remote case -scripts/ PlatformIO helper (per-environment sketch folder) +scripts/ PlatformIO helper (per-environment sketch folder), make_remote_hmi.py +tools/nextion-hmi-tools/ git submodule: .HMI reader/writer/renderer (nxhmi), used by the HMI generator ``` This is the `2026-current/` folder of the hexapod-robot repo; the earlier diff --git a/2026-current/dongle/README.md b/2026-current/dongle/README.md index 0d19733..e550062 100644 --- a/2026-current/dongle/README.md +++ b/2026-current/dongle/README.md @@ -30,15 +30,31 @@ Found by probing the board over SWD and confirmed at runtime by our firmware: | 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** | +| AT2401C TX/RX enable + unused | PA1, PB1, PF0, PF1 — **not distinguishable** (see below) | -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`). +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) @@ -162,14 +178,15 @@ 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 +(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 - [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] LED pin (PA0) - [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 diff --git a/2026-current/hardware/openscad/PLANNING.md b/2026-current/hardware/openscad/PLANNING.md index b14fa34..947ba83 100644 --- a/2026-current/hardware/openscad/PLANNING.md +++ b/2026-current/hardware/openscad/PLANNING.md @@ -159,7 +159,8 @@ charge/on LEDs show through two slots in the floor. plate into the box (no nuts). Reaches 28.5 mm down. Pots (d16.5, 9.2 out) towards the middle and towards the user. - Display mounted turned 180 deg so its J1 connector is on the right, clear - of the Teensy's USB plug: set display direction 180 in the Nextion Editor. + of the Teensy's USB plug. `remote/remote.HMI` is generated for that + (direction 270 in the Nextion Editor's terms; done 2026-11-17). Glass 1.0 mm under the top face, board on 4 posts tapped M3 (3.66 mm of thread, 1.2 mm under the top face); LCD 85.7 x 55 x 3.86 plus a 1.3 mm flex cable on one side, 11.21 mm glass to back of J1 (owner measured). diff --git a/2026-current/remote/NEXTION.md b/2026-current/remote/NEXTION.md index 7a16949..6e736c2 100644 --- a/2026-current/remote/NEXTION.md +++ b/2026-current/remote/NEXTION.md @@ -7,7 +7,14 @@ It's **generated** by `../scripts/make_remote_hmi.py`: change the layout there and re-run it, rather than editing the `.HMI` in Nextion Editor (an Editor edit is lost on the next run). Then open `remote.HMI` in Nextion Editor, compile, and upload the `.tft`: SETUP › UPDATE DISPLAY (tap twice) -or serial key `U` puts the remote in USB passthrough for the upload. +or serial key `U` puts the remote in USB passthrough for the upload. In the +Editor, upload to the Teensy's COM port with the baud rate on auto. When the +Editor is newer than the display's firmware, the upload first updates that +firmware: don't interrupt it. Power-cycle the remote afterwards to leave +upload mode. + +The display is on the remote's **Serial2** (Teensy RX2 = pin 7, TX2 = pin 8), +at 115200. ``` python scripts\make_remote_hmi.py (from 2026-current) diff --git a/2026-current/remote/README.md b/2026-current/remote/README.md index ec85efa..b35f9a2 100644 --- a/2026-current/remote/README.md +++ b/2026-current/remote/README.md @@ -22,6 +22,10 @@ USB nRF24 dongle (`../sim/README.md`). From the `2026-current` folder: `pio run -e remote`, flash with `pio run -e remote -t upload`, monitor with `pio device monitor -e remote`. +The upload opens Teensy Loader; if the Teensy doesn't reboot into it by +itself, press its program button. If flashing works but the USB serial port +then won't open or goes quiet, try another USB port or cable before +suspecting the firmware (a bare Teensy 4.0 showed exactly that on one port). ## Wiring (edge headers only; edit `Config.h` if yours differs) @@ -31,6 +35,7 @@ From the `2026-current` folder: `pio run -e remote`, flash with | nRF24L01 | CE / CSN | 9 / 10 | | nRF24L01 | VCC | 3.3 V, with a 10–100 µF cap right at the module | | MPU6050 | SDA / SCL | **18 / 19 (Wire)** | +| MPU6050 | VCC | 3.3 V (a GY-521 runs fine on it). Check the polarity: one supply reversal killed the first board's regulator | | Nextion | TX → RX2, RX ← TX2 | 7 / 8 (Serial2), 5 V supply (found on the real remote) | | Sticks | 6 axes | left stick X / Y / twist on **A3 / A7 / A8** (17 / 21 / 22), right stick on **A0 / A1 / A2** (14 / 15 / 16). A7/A8 hold the two wires that were on A4/A5 (18/19). All but the right twist read inverted (`STICK_INVERT`). Checked on the real remote | | Battery (planned) | divider | A6 (20) | @@ -124,12 +129,13 @@ reads it after every send, and it counts as stale after 1. Power on with both sticks released and the remote held still. Each axis's resting center is captured automatically. -2. For full calibration, disarm, then tap **CAL** (or press `c` on the - serial console). Move every axis of both sticks to both limits, release - them, and tap **SAVE CAL** (`c`). The result is saved to EEPROM. +2. For full calibration, disarm, then tap **CAL STICKS** on the SETUP page + (or press `c` on the serial console). Move every axis of both sticks to + both limits, release them, and tap **SAVE CAL** (`c`). The result is + saved to EEPROM, so it survives power cycles and reflashing. 3. If any axis moved less than `CAL_MIN_HALF_SPAN` either side of center, - the save is refused and you stay in calibration mode. **CANCEL CAL** - (`x`) aborts. + the save is refused and you stay in calibration mode. **CANCEL** (`x`) + aborts. 4. `p` prints the calibration in a form you can paste into `Config.h` defaults. `R` wipes EEPROM back to the `Config.h` defaults. diff --git a/2026-current/robot/README.md b/2026-current/robot/README.md index 71438f9..5131951 100644 --- a/2026-current/robot/README.md +++ b/2026-current/robot/README.md @@ -41,8 +41,9 @@ still a placeholder. Check all of it against the real robot: needed ±90° offsets there, which left the servos at the end of their travel. - `RADIO_CE_PIN` / `RADIO_CSN_PIN` / `RADIO_SCK_PIN`: 39 / 15 / 14, as in - the old sketch. Address, channel, data rate, PA level and payload size - are in `shared/HexapodProtocol` so they can't drift from the remote. + the old sketch. Address, channel, data rate, PA level and the packet + structs are in `shared/HexapodProtocol` so they can't drift from the + remote. ## Bench-check checklist (do this before the first stand-up) @@ -62,7 +63,11 @@ for your build: down). 3. **RobotIMU register map** (`RobotIMU.cpp`) — written for an MPU6050-style chip (I2C addr `0x68`). If your gyro is a different part, its register - addresses and scale factors will differ; swap them in. + addresses and scale factors will differ; swap them in. Also check that + it gives live readings at all (the robot's roll/pitch on the remote's + STATUS page): the remote's MPU6050 answered and woke up but read all + zeros until it got a full device reset (`PWR_MGMT_1 = 0x80`), which + `RobotIMU::begin()` doesn't do. 4. **Sit-pose assumption** — the built-in sit pose in `robot.ino` assumes all six feet stay grounded and simply lowers the body (a 0.4x height blend). If your chassis is meant to rest its belly on the ground instead, this @@ -83,7 +88,8 @@ for your build: This exact code also compiles for the PC and runs in the Unity model. See `../sim/README.md`. `sim/build/sim_smoke.exe` is a quick headless check -after every change. +after every change. In Unity the simulated robot can also be driven by the +real remote over the radio, through the USB nRF24 dongle. ## Testing without a remote yet @@ -163,6 +169,7 @@ robot/ ├── StateMachine.h/.cpp - DISARMED/SIT/STAND/WALKING with smoothed sit-stand blend ├── InputMapper.h/.cpp - CmdPacket -> twist/pose/mode decoding ├── Limits.h/.cpp - workspace clamp, joint rate limit, stance polygon check -├── Comms.h/.cpp - nRF24L01 receive (packet definition is in shared/HexapodProtocol) -└── ServoDriver.h/.cpp - servo attach/relax/write +├── Comms.h/.cpp - nRF24L01 receive + telemetry as ack payload (packets in shared/HexapodProtocol) +├── ServoDriver.h/.cpp - servo PWM write/relax, per-servo centre trims (EEPROM), SERVO_CAL +└── Battery.h/.cpp - battery voltage through a divider (not wired yet) ``` diff --git a/2026-current/sim/README.md b/2026-current/sim/README.md index 1fc0b0a..dfd7242 100644 --- a/2026-current/sim/README.md +++ b/2026-current/sim/README.md @@ -65,15 +65,21 @@ It drives the firmware the way the remote would and checks: - **`+vx` moves the body forward**, - link loss disarms, - a wrong-size packet is ignored, -- the serial harness still works. +- the robot's telemetry comes back in the ack payload, and every servo + calibration command (HOLD / SET / SAVE / REVERT, arming refused) works, +- the serial harness still works, +- plus the body-pose, leg-clearance, heading and robot-gyro checks listed + in the file. ## Using it in Unity Open `Hexapod_Simulation_Unity` and press Play in `Main.unity`. No scene edits are needed: `HexapodSimBootstrap` adds a `HexapodSimulation` object, disables the old movement scripts (`Walk`, `RotationControl`, `Leg`), and -binds the existing leg rig by name (`Leg` → `hip1` / `Hip2` / `Knie`). The -on-screen panel (F1 toggles it) offers two input sources: +binds the existing leg rig by name (`Leg` → `hip1` / `Hip2` / `Knie`). By +default `OpenScadModel` swaps the old scene's robot for the OpenSCAD model +of the real one (`HexapodSimulation.useOpenScadModel`). The on-screen panel +(F1 toggles it) offers two input sources: - **Keyboard:** test without a remote. WASD walks, Q/E turns, IJKL + U/O drive the right stick, 1–7 flip the toggles, Backspace disarms, +/-