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>
Hexapod remote firmware (Teensy 4.0)
Handheld transmitter for the hexapod. It reads two 3-axis twist-grip
joysticks and an MPU6050, takes operator commands from a Nextion
touchscreen, and sends a CmdPacket (defined in
../shared/HexapodProtocol/HexapodProtocol.h) to the robot over nRF24L01
at 100 Hz.
Planned
-
Battery level (divider not built yet): read the 18650's voltage through a ~100k/100k divider from the cell's + (not the boost board's 5 V output) into A6 (pin 20, free), with 100 nF to GND. Details in
../hardware/openscad/PLANNING.md(notes for future designs). The firmware side is done (Battery, shown on the STATUS page): setBATTERY_SENSE_PIN = A6inConfig.honce it's wired. A low-battery warning is still to do. -
IMU on the normal pin headers (suggestion, not done): with the GY-521 on the main board, wire it to Wire (SDA 18 / SCL 19) instead of Wire2 (the 24/25 pads under the Teensy 4.0). 18/19 are A4/A5, used by two stick axes now, so move those two axes to A7 (pin 21) and A8 (pin 22): all on the edge headers. A6 (pin 20) stays free for the battery divider, A9 (23) is spare. Firmware: in
Config.hSTICK_PINS = { A0, A1, A2, A3, A7, A8 }and#define IMU_WIRE Wire;Sticks.cppreads throughSTICK_PINS, so nothing else changes. Redo the stick axis check (pdump) and calibration afterwards. (Wire1 is no way out: its 16/17 are stick pins A2/A3 too.)
Building
From the 2026-current folder: pio run -e remote, flash with
pio run -e remote -t upload, monitor with pio device monitor -e remote.
Wiring (from the old remote sketch in ../../2019-teensy-nrf24/remote/; edit Config.h if yours differs)
| Part | Signal | Teensy 4.0 pin |
|---|---|---|
| nRF24L01 | MOSI / MISO / SCK | 11 / 12 / 13 (SPI0) |
| nRF24L01 | CE / CSN | 9 / 10 |
| nRF24L01 | VCC | 3.3 V, with a 10–100 µF cap right at the module |
| MPU6050 | SDA / SCL | 25 / 24 (Wire2), solder pads on the underside of the 4.0: not 18/19, those are stick pins A4/A5 |
| Nextion | TX → RX2, RX ← TX2 | 7 / 8 (Serial2), 5 V supply (found on the real remote) |
| Sticks | 6 axes | A0–A5. Which axis is on which pin isn't known yet: reorder STICK_PINS until the p dump reads right |
MPU6050 rewiring: the old remote had its MPU code switched off, probably because A4/A5 double as Wire's pins. Move the MPU's SDA/SCL to pins 25/24 (the pads under the board).
Stick pots are wired 3.3 V – wiper – GND. Never feed 5 V into a Teensy 4.x analog pin.
Control scheme
| Input | Packet field | Meaning on the robot |
|---|---|---|
| Left stick forward/back | vx |
walk forward/back |
| Left stick left/right | vy |
strafe (mode A); heading target direction (mode B) |
| Left stick twist | yaw_rate |
turn rate (mode A only; ignored in mode B) |
| Right stick, ROTATE (default) | rx/ry/rz |
body roll / pitch / yaw |
Right stick, MOVE (FLAG_RSTICK_XLATE) |
rx/ry/rz |
body X / Y / Z (height, via twist) offset |
| Handset tilt | remote_roll/pitch |
extra body roll/pitch while REMOTE GYRO is on |
| Height slider | body_height |
standing height, default ± STANCE_HEIGHT_RANGE_MM (robot rate-limits the change) |
In HEADING mode the left stick steers, relative to where the robot faces at that moment. Forward/back walks forward/back, and sideways steers: forward+left or back+left walk while turning left, and left alone turns on the spot for as long as you hold it. Let go and the robot holds its heading.
Touchscreen (NEXTION.md has the details), with tabs along the bottom and
a red DISARM on every page:
- DRIVE: ARM / DISARM, SIT/STAND, TRIPOD/WAVE, DIRECT/HEADING, R: ROTATE/MOVE, REMOTE GYRO, ROBOT GYRO, speed and height sliders.
- STATUS: handset and robot IMU roll/pitch, the six stick axes, both batteries, radio quality and the robot's received packet rate.
- SERVOS: all 18 joint angles the robot is commanding, as a top view.
- CAL: servo centre calibration (see below).
- SETUP: stick calibration (CAL STICKS / CANCEL), LEVEL REMOTE (re-zero the handset tilt), UPDATE DISPLAY, backlight.
Everything about the robot comes from its telemetry, which rides back on
the radio's ack payloads (Telemetry in HexapodProtocol.h): RadioLink
reads it after every send, and it counts as stale after
TELEMETRY_STALE_MS.
Servo centre calibration (CAL page)
- Put the robot on a stand, legs free, and disarm.
- Tap START. The robot drives every servo to its centre pose: coxa 0, femur 0, tibia −90 (legs straight out, shins straight down).
- Pick a leg (FR MR RR RL ML FL) and a joint. The remote first reads that
servo's trim back from the robot (the trim box shows
...until then). - Step the trim with −10 / −1 / +1 / +10 µs (or ZERO) until the horn is exactly square. SAVE TO ROBOT turns orange while there are unsaved trims.
- SAVE TO ROBOT stores all 18 trims in the robot's EEPROM. REVERT drops unsaved changes. STOP, leaving the page, or a link loss relaxes the servos. Arming is refused while calibrating.
Safety interlocks (in RemoteState)
- Arming is refused unless every stick axis is centered, and never allowed during stick or servo calibration. Servo calibration only starts while disarmed, and stops when you leave the CAL page or the link drops.
- UPDATE DISPLAY needs a second tap within 3 s and is refused while armed.
- Disarming always clears the stand request. The robot arms into SIT, so re-arming never stands it up by itself.
- Link loss: if no ack arrives for
LINK_LOST_MS(300 ms, matching the robot's failsafe), the remote disarms itself. When the link comes back the robot stays down until you re-arm deliberately. - Sit/stand requests are only accepted while armed.
FLAG_WALKis only sent while standing is requested. - While disarmed or calibrating, all motion fields are sent as zero.
Smoothing
- Speed scale ramps toward the slider at
SPEED_SCALE_RATE_PER_SEC. The robot uses speed scale directly on the walking twist, so a slider jump would otherwise be a velocity step. - Remote tilt fades in/out over ~0.5 s when REMOTE GYRO is toggled, and the handset re-zeroes its "level" at the moment you enable it.
- FLAG_WALK lingers 250 ms after the left stick centers, so hovering at the deadzone edge doesn't make the robot chatter between STAND and WALKING.
- Body pose smoothing is left to the robot's
BodyPoserate limiters.
Stick calibration
- Power on with both sticks released and the remote held still. Each axis's resting center is captured automatically.
- For full calibration, disarm, then tap CAL (or press
con 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. - If any axis moved less than
CAL_MIN_HALF_SPANeither side of center, the save is refused and you stay in calibration mode. CANCEL CAL (x) aborts. pprints the calibration in a form you can paste intoConfig.hdefaults.Rwipes EEPROM back to theConfig.hdefaults.
Serial console (USB, 115200, single keystrokes)
Every touchscreen control is available here, so you can bench-test with no display attached.
| Key | Action | Key | Action |
|---|---|---|---|
a |
toggle arm | k |
disarm |
s |
toggle sit/stand | g |
tripod ↔ wave |
m |
direct ↔ heading-hold | t |
right stick rotate ↔ translate |
r |
remote gyro on/off | b |
robot gyro on/off |
+ / - |
speed ±25 | z |
zero handset level |
] / [ |
height up / down 10% | ||
c |
start / save calibration | x |
cancel calibration |
p |
print status (raw + mapped sticks, IMU, link, state, cal) | d |
toggle 10 Hz packet dump |
R |
reset stick cal to Config defaults | U |
Nextion upload mode (USB ↔ display; power-cycle to leave) |
o |
servo calibration start/stop | n |
next servo (leg × 3 + joint) |
, / . |
trim −1 / +1 µs | < / > |
trim −10 / +10 µs |
0 |
trim to zero | w / e |
save trims on the robot / revert |
p also prints the robot's telemetry (state, IMU, battery, joint angles)
and the servo-calibration state.
Bench-check checklist
- Stick directions: with
p, confirm each logical axis reads positive for right / forward / counterclockwise twist. Flip it inSTICK_INVERT[]if not. - IMU mounting: with
p, dip the right edge down to get +roll, and tip the far edge down to get +pitch. If not, fixIMU_AXIS_FROM_CHIP/IMU_AXIS_SIGN. - Nextion baud: the generated HMI sets
bauds=115200in Program.s. The display still runs the old HMI (probably 9600) until you upload the new one; Nextion Editor finds the baud rate by itself. For that first upload use serial keyU: the old HMI's UPLOAD button isn't recognised any more. - Radio: with the robot powered,
tLink/pshould show ~100%, andpshould print robot telemetry. If it reads NO LINK, check that both boards were built from the sameHexapodProtocol.h: each end drops packets of the wrong size. - End to end with the robot on a stand: use
dto dump packets and confirm each field changes the way the table above says.