2026 remote: tabbed Nextion UI, robot telemetry, servo centre calibration
Protocol v4: CmdPacket grows to 26 bytes (cal_cmd, cal_servo, cal_value); new 30-byte Telemetry rides back on the nRF24 ack payload (robot state, IMU, battery, 18 joint angles, packets/s, servo-cal echo). Each end drops wrong-length packets, so version mismatches still fail closed. Robot (owner-approved): SERVO_CAL state while disarmed, per-servo centre trims (+-200 us) in EEPROM, telemetry, battery reading; the IMU estimate now always runs (leveling still gated by ROBOT GYRO). Remote: generated HMI (scripts/make_remote_hmi.py) with pages splash, drive, status, servos, cal, setup, upload; page-aware NextionUI that only writes the showing page and only what changed; servo calibration and UPDATE DISPLAY on the touchscreen and serial console; battery module. The display is on Serial2 (pins 7/8), found on the real remote; the old sketch's Serial1 was never connected to it. Sim: RF24 shim supports ack payloads, API version 8 (hxsim_get_ack_payload); sim_smoke checks telemetry and every CAL command. Unity CmdPacket mirror updated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
481610c9fd
commit
0b836af8de
40 files changed
+1463
-281
No files matched your search
+67
-33
@@ -1,7 +1,7 @@
|
||||
# Hexapod: project memory
|
||||
|
||||
Hexapod walking robot plus a custom handheld remote, both Teensy-based and
|
||||
linked one-way over nRF24L01 (remote → robot, with hardware auto-ack only).
|
||||
linked over nRF24L01: commands remote → robot, telemetry back in the radio's ack payloads.
|
||||
A Unity simulation runs the *unchanged* robot firmware as a DLL. This file
|
||||
is the persistent context for working on any part of it. Read it fully
|
||||
before changing anything.
|
||||
@@ -51,7 +51,7 @@ PlatformIO, one `platformio.ini`, two environments:
|
||||
|
||||
## Communication contract (`shared/HexapodProtocol/HexapodProtocol.h`)
|
||||
|
||||
`CmdPacket`, 22 bytes (static_asserted; protocol v3), sent remote → robot at 100 Hz
|
||||
`CmdPacket`, 26 bytes (static_asserted; protocol v4, `HXP_PROTOCOL_VERSION`), sent remote → robot at 100 Hz
|
||||
(robot `CONTROL_HZ` is 60):
|
||||
|
||||
| Field | Range | Meaning |
|
||||
@@ -65,6 +65,16 @@ PlatformIO, one `platformio.ini`, two environments:
|
||||
| `speed_scale` | 0–255 | multiplies vx/vy on the robot |
|
||||
| `flags` | bits | `ARMED, STAND, WALK, MODE_B, RSTICK_XLATE, GAIT_WAVE, REMOTE_GYRO, ROBOT_GYRO` (bits 0–7) |
|
||||
| `seq` | 0–255 | increments per packet (robot doesn't check it yet) |
|
||||
| `cal_cmd` | `CAL_*` | servo centre calibration, only while not armed: `CAL_NONE` normal, `HOLD` centre pose, `SET` trim, `SAVE` / `REVERT` EEPROM. States, not events: repeats are harmless |
|
||||
| `cal_servo`, `cal_value` | 0–17, ±200 µs | selected servo (leg × 3 + joint) and its trim for `CAL_SET` |
|
||||
|
||||
`Telemetry`, 30 bytes, robot → remote as the **ack payload** of the remote's
|
||||
next packet (`Comms::loadAckPayload` after every packet received; no extra
|
||||
transmissions): robot state (`TSTATE_*`, 4 = SERVO_CAL), status bits
|
||||
(`TSTAT_*`: IMU ok, gyro on, servos driven, trims dirty / stored), IMU
|
||||
roll/pitch in 0.1°, battery mV (0 = not measured), the 18 commanded joint
|
||||
angles as int8 (tibia stored + 90), packets received per second, and the
|
||||
echo of `cal_servo` with its trim.
|
||||
|
||||
- **Axis convention** (ROS REP-103 style): body +X forward, +Y left, +Z up.
|
||||
+roll = right side down, +pitch = nose down, +yaw = CCW.
|
||||
@@ -72,11 +82,15 @@ PlatformIO, one `platformio.ini`, two environments:
|
||||
`InputMapper` owns the scaling: `MAX_LINEAR_MM_S` 150,
|
||||
`MAX_TURN_RATE_DEG_S` 90, `MAX_TILT_DEG` 20, `MAX_POSE_OFFSET_MM` 40.
|
||||
- **Radio settings** live in the same header: address `"HXPD1"`, channel
|
||||
96, 250 kbps, PA LOW, **static payload size = sizeof(CmdPacket)** on both
|
||||
radios. That makes version mismatches fail closed: packets are not
|
||||
received, the robot times out, and it disarms.
|
||||
- **Changing the protocol means reflashing both boards.** Keep it ≤ 32
|
||||
bytes and update the `static_assert`.
|
||||
96, 250 kbps, PA LOW. Ack payloads need dynamic payload lengths
|
||||
(`enableAckPayload()` on both radios), so **each end drops any packet
|
||||
whose length isn't sizeof() of its struct**. That keeps version
|
||||
mismatches failing closed: packets are ignored, the robot times out, and
|
||||
it disarms.
|
||||
- **Changing the protocol means reflashing both boards.** Keep both
|
||||
structs ≤ 32 bytes, update the `static_assert`s, bump
|
||||
`HXP_PROTOCOL_VERSION`, and mirror `CmdPacket` in the Unity
|
||||
`HexapodSimNative.cs`.
|
||||
- **Failsafes:** the robot sets `linkOk()` false after `LINK_TIMEOUT_SEC`
|
||||
(0.3 s) without packets and then uses a default `CmdPacket` (flags 0 =
|
||||
disarmed, servos detached). The remote disarms itself after
|
||||
@@ -101,33 +115,41 @@ joint-rate clamp → servos.
|
||||
| `Kinematics` | per-leg 3-DOF analytic IK, `neutralStance()` |
|
||||
| `GaitEngine` | tripod/wave patterns, per-leg phase, pattern swap only at touchdown. `limitTwist()` (called in robot.ino right after InputMapper, so the heading estimate integrates the *achieved* ω) scales the walk command until its stride envelope (`strideEnvelope()`: even/odd legs at opposite stride ends, plus a lifted set) is feasible, so full-rate turning can't make neighbouring legs collide. Stance feet are *integrated* each tick from the current twist (v + ω×r at the foot); swing feet arc from lift-off to the next leading edge. `resetFeet()` on entering WALKING restarts the cycle with grounded legs at mid-stance |
|
||||
| `BodyPose` | 6-axis body pose (smoothed command + IMU roll/pitch correction), applied to foot targets as the *inverse* rotation, so the body moves as commanded. `fitToReach()` scales the *whole* pose by one factor (binary search on `Limits::feetFeasible`; drops at once, recovers at 1/s) so combined poses never bend individual legs out of a rigid foot pattern or into each other. While walking it fits against the stride envelope, not the current feet, so it doesn't saw with the step cycle |
|
||||
| `RobotIMU` | MPU6050 complementary filter (α 0.98), gated by `FLAG_ROBOT_GYRO` |
|
||||
| `RobotIMU` | MPU6050 complementary filter (α 0.98). Always estimates (the remote shows it); only the self-leveling in robot.ino is gated by `FLAG_ROBOT_GYRO` |
|
||||
| `StateMachine` | DISARMED → SIT → STAND → WALKING, sit/stand blend at 1/s. Disarm is instant |
|
||||
| `InputMapper` | CmdPacket → Twist + PoseCommand + mode flags + stance height. Mode B = steering **relative to where the body faces right now**: the forward/back stick component sets walking direction (vx sign), the sideways component steers (target = current heading + atan2(vy, |vx|) every tick). So W = straight on, S = straight **back** (not turn around; owner's request), W/S+A = walk while turning left, A alone = turn on the spot while held. On release the target freezes at the current heading (hold). An earlier version froze the reference at the first push, so heading only changed after releasing W; the owner rejected that. Mode A keeps the target = current heading so switching to B never jumps. Forward speed × max(0, cos(heading error)), so big corrections turn in place first. Adds remote tilt on top of stick pose when `FLAG_REMOTE_GYRO`, clamped to `MAX_TILT_DEG` |
|
||||
| `Limits` | workspace clamp (70 mm horiz / 60 mm vert), joint rate clamp, ≥3-legs-in-stance check (not acted on yet). `feetFeasible()` = every foot in its workspace with valid IK **and** neighbouring legs' segments (coxa/femur/tibia, via `Kinematics::jointPositions`) ≥ `LEG_CLEARANCE_MM` apart. This is the single "physically possible" test used by gait and pose limiting |
|
||||
| `Comms` | nRF24 RX, link timeout, `injectPacket()` for the harness |
|
||||
| `ServoDriver` | 18 servos on hardware PWM (50 Hz, 16-bit), per-servo calibration from `Config.h` `SERVOS`, duty 0 = relaxed, skips invalid IK solutions |
|
||||
| `Comms` | nRF24 RX (drops wrong-length packets), link timeout, telemetry as ack payload, packets/s, `injectPacket()` for the harness |
|
||||
| `ServoDriver` | 18 servos on hardware PWM (50 Hz, 16-bit), per-servo calibration from `Config.h` `SERVOS` plus a per-servo centre trim (µs, EEPROM record at address 0, loaded in setup), duty 0 = relaxed, skips invalid IK solutions. `calibrate()` = SERVO_CAL: applies a `CAL_*` command and holds `CAL_POSE` (coxa 0, femur 0, tibia −90) |
|
||||
| `Battery` | battery voltage through a divider; `BATTERY_SENSE_PIN` 255 = not wired yet |
|
||||
|
||||
`robot.ino` also runs SERVO_CAL (disarmed + `cal_cmd != CAL_NONE`; leaving
|
||||
it relaxes the servos) and fills the `Telemetry` every loop
|
||||
(`sendTelemetry`).
|
||||
|
||||
## Remote architecture (`remote/`, Teensy 4.0)
|
||||
|
||||
Loop: drain Nextion + USB serial input every pass. On each `TX_HZ` (100)
|
||||
tick: sticks → IMU → radio link status → RemoteState (smoothers,
|
||||
link-loss disarm) → PacketBuilder → `radio.write` → Nextion render.
|
||||
tick: sticks → IMU → radio link status → battery → RemoteState (smoothers,
|
||||
link-loss disarm, servo-trim read-back from telemetry) → PacketBuilder →
|
||||
`radio.write` (+ read the ack payload's telemetry) → Nextion render.
|
||||
|
||||
| Module | Role |
|
||||
|--------|------|
|
||||
| `remote.ino` | loop wiring, status print, packet dump |
|
||||
| `Config.h` | **all placeholder pins, calibration defaults, deadzones, rates** |
|
||||
| `UiTypes.h` | `UiCmd`/`UiEvent` (operator requests), `UiView` (what the display shows) |
|
||||
| `UiTypes.h` | `UiCmd`/`UiEvent` (operator requests), `UiPage` (HMI page ids), `UiView` (what the display shows, incl. robot telemetry) |
|
||||
| `Sticks` | 6 analog axes: ADC averaging + IIR, piecewise calibration around center, invert, deadzone with rescale, expo → ±1000. Boot-time center capture, sweep calibration saved to EEPROM (magic/version/checksum) |
|
||||
| `RemoteIMU` | MPU6050, same complementary filter as the robot, axis remap for mounting, boot gyro-bias capture, "level" zero |
|
||||
| `RemoteState` | authoritative operator state and interlocks: arm needs centered sticks, disarm clears stand, stand needs armed, calibrate needs disarmed, link-loss auto-disarm. Smooths speed scale and fades remote tilt in/out |
|
||||
| `RemoteState` | authoritative operator state and interlocks: arm needs centered sticks, disarm clears stand, stand needs armed, calibrate needs disarmed, link-loss auto-disarm. Smooths speed scale and fades remote tilt in/out. Servo calibration: only while disarmed and on the CAL page; a newly selected servo is `CAL_HOLD` until its trim has been read back from telemetry, then `CAL_SET`; SAVE/REVERT go out for 300 ms. UPDATE DISPLAY needs a second tap |
|
||||
| `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 % |
|
||||
| `NextionUI` | library-free Nextion driver on `Serial1`. HMI sends `'#' len cmd [val]` frames via `printh`. Remote pushes state by component name, as `control.<name>` (the owner adds a `control` page with vscope-global components to the old HMI), with diffing, a 2 s full refresh, and a redraw on the Nextion 0x88 "ready" frame. Also writes the old HMI's `t1` status texts (`NEXTION_STATUS_TEXTS`). The old page-1 `b2` sends a standard 0x65 touch frame, which triggers `runUploadPassthrough()`: USB ↔ display bridge for Nextion Editor, following `Serial.baud()`, never returns. Serial key `U` does the same |
|
||||
| `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 |
|
||||
| `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` | HMI build guide: component names, txt_maxl, touch event code |
|
||||
| `NEXTION.md` | the HMI: pages, command bytes, which components the firmware writes |
|
||||
| `remote.HMI` | **generated** by `scripts/make_remote_hmi.py` (pages splash, drive, status, servos, cal, setup, upload; tabs + top bar with DISARM). Change the layout in the script, not in the Editor |
|
||||
|
||||
Remote stick-frame convention: logical X + = right, Y + = forward, twist +
|
||||
= CCW. The mapping into the packet is in `PacketBuilder.cpp` (e.g.
|
||||
@@ -235,7 +257,7 @@ Robot (`robot/README.md` has detail):
|
||||
limits now in `Config.h`: coxa limits are **per leg**
|
||||
(`COXA_MIN_DEG[i]`/`COXA_MAX_DEG[i]`; all ±60 in the hexagon layout, but in
|
||||
the old sideways layout a corner leg only swung ~36° towards its mid leg),
|
||||
and `LEG_CLEARANCE_MM` is 56 (a leg is 55.2 mm wide at the joints). The sim API exports the per-leg coxa limits (version 7).
|
||||
and `LEG_CLEARANCE_MM` is 56 (a leg is 55.2 mm wide at the joints). The sim API exports the per-leg coxa limits (version 7). Version 8 adds `hxsim_get_ack_payload` (the robot's telemetry); sim_smoke checks telemetry and every `CAL_*` command.
|
||||
- **Fixed (owner-approved):** the `Kinematics.cpp` femur elevation sign
|
||||
(`atan2(local_z, horiz)`; it used to solve for a foot above the hip, so
|
||||
every solution was invalid). Stance pose is now femur −1.2°, tibia
|
||||
@@ -365,7 +387,7 @@ Robot (`robot/README.md` has detail):
|
||||
|
||||
Remote (`remote/README.md` has detail):
|
||||
- Pins in `remote/Config.h`, taken from the old remote sketch: radio CE 9 /
|
||||
CSN 10, sticks A0–A5, Nextion on Serial1 (0/1). The MPU6050 is on
|
||||
CSN 10, sticks A0–A5, Nextion on **Serial2 (7/8)**, confirmed on the real remote. The MPU6050 is on
|
||||
**Wire2 (25/24, solder pads under the Teensy 4.0)**, since A4/A5 = Wire's SDA/SCL are stick pins; that's
|
||||
the owner's choice and needs rewiring the MPU. Which stick axis is on
|
||||
which pin is still unknown.
|
||||
@@ -373,14 +395,25 @@ Remote (`remote/README.md` has detail):
|
||||
- `IMU_AXIS_FROM_CHIP` / `IMU_AXIS_SIGN` depend on how the MPU6050 is
|
||||
mounted in the handset.
|
||||
- The Nextion must have `bauds=115200` in Program.s, and the HMI must match
|
||||
`NEXTION.md`. The owner's old 6-page HMI is in `../2019-teensy-nrf24/remote-nextion/remote.HMI`;
|
||||
its component names aren't readable outside Nextion Editor. The compiled
|
||||
`.tft` is gitignored.
|
||||
`NEXTION.md`. The working HMI is `remote/remote.HMI`, generated by
|
||||
`scripts/make_remote_hmi.py` (owner-approved design, 2026-11-17; the old 6-page one in
|
||||
`../2019-teensy-nrf24/remote-nextion/` only lends its splash picture). The display still
|
||||
runs the old HMI until the new `.tft` is uploaded: use serial key `U` for that first upload,
|
||||
the old UPLOAD button isn't recognised any more. Edit and render it with the `nxhmi` MCP server
|
||||
(registered in the repo root `.mcp.json`; code is the git submodule `tools/nextion-hmi-tools`,
|
||||
run `git submodule update --init` after cloning; CLI `python -m nxhmi` with `PYTHONPATH` =
|
||||
`tools/nextion-hmi-tools/src`): `info`, `get_page`, `render_page`, `set_attributes`,
|
||||
`set_event`, `add_component`, `add_page`, `verify`, `build_tft`. Its `.tft` builder is
|
||||
partial and needs the Nextion firmware files, which aren't in the submodule (they're kept
|
||||
locally in `D:\Claude\nextion-hmi-tools\firmware`), so compile the upload `.tft` in Nextion
|
||||
Editor. The compiled `.tft` is gitignored.
|
||||
- What the old remote sketch (`../2019-teensy-nrf24/remote/`, last ran on a
|
||||
Teensy) tells us about the real hardware:
|
||||
- **Nextion on `Serial1` (pins 0/1)**, driven by the ITEAD Nextion
|
||||
library, whose `nexInit()` runs at 9600. `remote/Config.h` now uses
|
||||
Serial1 and expects 115200 via `bauds=` in the HMI.
|
||||
- **Nextion on `Serial2` (pins 7/8)**, driven by the ITEAD Nextion
|
||||
library (its `nexSerial` is Serial2). The sketch's `Serial1.begin()` and
|
||||
its USB ↔ Serial1 passthrough never reached the display: a probe on the
|
||||
real remote (2026-11-17) got `comok` only on Serial2, at 115200.
|
||||
`remote/Config.h` uses Serial2 at 115200 (`bauds=` in the HMI).
|
||||
- The old HMI is a *servo monitor*, not the control UI in `NEXTION.md`:
|
||||
- page 1: `t1` "connected"/"not connected", and `b2` = enter
|
||||
upload mode;
|
||||
@@ -388,11 +421,12 @@ Remote (`remote/README.md` has detail):
|
||||
`t1` status;
|
||||
- page 4: `uploadscreen`.
|
||||
|
||||
None of the arm/stand/gait/mode/gyro/speed/height controls exist yet.
|
||||
The owner chose to add a `control` page per `NEXTION.md`.
|
||||
It had none of the arm/stand/gait/mode/gyro/speed/height controls.
|
||||
It was replaced by the generated tabbed HMI (see above).
|
||||
- `b2` → **Nextion upload passthrough**: shows `uploadscreen`, then
|
||||
bridges USB ↔ Serial1 forever, so Nextion Editor can upload a `.tft`
|
||||
through the remote's USB port. The new firmware keeps this.
|
||||
bridges USB ↔ the display serial forever, so Nextion Editor can upload a `.tft`
|
||||
through the remote's USB port. The new firmware keeps this as SETUP ›
|
||||
UPDATE DISPLAY (page `upload`).
|
||||
- Sticks on **A0–A5**, contiguous (`analogInPin + i`). On the Teensy 4.0,
|
||||
A4/A5 are pins 18/19 = Wire SDA/SCL, which the MPU6050 needs. The old
|
||||
code had the MPU code disabled (`if (false)`). Owner's decision: keep
|
||||
@@ -424,7 +458,7 @@ Remote (`remote/README.md` has detail):
|
||||
with BENCH comments for anything hardware-dependent, `SmoothedValue`
|
||||
rate limiting on any setpoint that can jump, and paired `.h/.cpp` per
|
||||
concern.
|
||||
- Planned or possible next steps: an ack-payload telemetry channel from
|
||||
robot → remote (state, battery, link) to show real robot state on the
|
||||
Nextion, battery monitoring on both sides, a `.HMI` file checked into
|
||||
`remote/`.
|
||||
- Planned or possible next steps: wire the battery dividers (firmware is
|
||||
ready on both sides, pins still 255) and add a low-battery warning; try
|
||||
ack-payload telemetry and servo calibration on the real radios (only
|
||||
simulated so far).
|
||||
Reference in new issue
Block a user