- Nextion is on Serial2 (pins 7/8) - already in the last commit; docs updated. - MPU6050 on Wire (18/19) so everything is on the edge headers (owner's choice); the two stick wires from 18/19 move to A7/A8 (21/22). - Stick mapping checked on the real remote: left stick X/Y/twist on A3/A7/A8, right on A0/A1/A2, all inverted but the right twist. - RemoteIMU: full device reset before waking. The remote's MPU6050 (likely a clone) answers and wakes without it but every data register reads 0. Axis defaults confirmed (+pitch nose down, +roll right side down). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
32 KiB
Hexapod: project memory
Hexapod walking robot plus a custom handheld remote, both Teensy-based and 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.
Layout and toolchain
robot/ Teensy 3.6 firmware (PlatformIO env robot)
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
This folder is 2026-current/ inside the hexapod-robot repo. The older generations sit next to it
(paths below are relative to this folder) and are the owner's reference material:
../2019-teensy-nrf24/Hexapod_Teensy/ old robot sketch: servo passthrough only, no IK - see "Old robot sketch" below
../2019-teensy-nrf24/remote/ old remote sketch
../2019-teensy-nrf24/remote-nextion/ remote.HMI = old Nextion UI, 6 pages
../2016-ssc32-processing-port/Hexapod_NEW/ older generations with their own IK, driving an external
../2014-ik-core-task-queue/HexapodRobot/ SSC-32-style servo controller
../README.md timeline of every generation since 2009
PlatformIO, one platformio.ini, two environments:
| Env | Board | Sketch dir | Purpose |
|---|---|---|---|
robot |
teensy36 |
robot/ |
walking robot |
remote |
teensy40 |
remote/ |
handheld transmitter |
shared/is PlatformIO'slib_dir.shared/HexapodProtocol/is a header-only library both sketches#include <HexapodProtocol.h>.- PlatformIO has a single global
src_dirand only converts.inofiles at its root, soscripts/select_src_dir.py(apre:extra script) swapsPROJECT_SRC_DIRto each env'scustom_src_dir. That keepsrobot/andremote/plain Arduino sketch folders: one.inoplus paired.h/.cppper concern. Keep that structure. No giant files, nosrc/folders. - RF24 (nrf24/RF24, resolved 1.6.x) comes from
lib_deps. Servo, Wire, SPI and EEPROM ship with the Teensy framework. - Build:
pio run(both),pio run -e robot,pio run -e remote. On this machine pio lives atC:\Users\patri\.platformio\penv\Scripts\pio.exe. Both envs build clean. Build both after touchingshared/.
Communication contract (shared/HexapodProtocol/HexapodProtocol.h)
CmdPacket, 26 bytes (static_asserted; protocol v4, HXP_PROTOCOL_VERSION), sent remote → robot at 100 Hz
(robot CONTROL_HZ is 60):
| Field | Range | Meaning |
|---|---|---|
vx |
±1000 | + forward |
vy |
±1000 | + strafe left |
yaw_rate |
±1000 | + turn left (CCW). Ignored by the robot in mode B |
rx, ry, rz |
±1000 | right stick: roll/pitch/yaw, or X/Y/Z offset when FLAG_RSTICK_XLATE |
remote_roll, remote_pitch |
±1000 | handset tilt feedforward, used only when FLAG_REMOTE_GYRO |
body_height |
±1000 | standing height setting: STANCE_HEIGHT_MM ± STANCE_HEIGHT_RANGE_MM (150 ± 50), 0 = default; the robot rate-limits it (STANCE_HEIGHT_RATE_MM_S) and everything built on Kinematics::neutralStance() follows |
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.
- Normalized fields. The remote never knows robot geometry. The robot's
InputMapperowns the scaling:MAX_LINEAR_MM_S150,MAX_TURN_RATE_DEG_S90,MAX_TILT_DEG20,MAX_POSE_OFFSET_MM40. - Radio settings live in the same header: address
"HXPD1", channel 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_asserts, bumpHXP_PROTOCOL_VERSION, and mirrorCmdPacketin the UnityHexapodSimNative.cs. - Failsafes: the robot sets
linkOk()false afterLINK_TIMEOUT_SEC(0.3 s) without packets and then uses a defaultCmdPacket(flags 0 = disarmed, servos detached). The remote disarms itself afterLINK_LOST_MS(300 ms) without acks, so the robot can't re-arm itself when the link returns. - Division of labor: the remote only fills fields per this contract.
Mode A/B interpretation, heading-hold, pose scaling and all smoothing of
pose happen on the robot. Don't duplicate
InputMapperlogic in the remote.
Robot architecture (robot/, Teensy 3.6)
Loop at CONTROL_HZ (60): comms → InputMapper → IMU → heading integrate →
StateMachine → gait/sit-stand targets → BodyPose → Limits clamp → IK →
joint-rate clamp → servos.
| Module | Role |
|---|---|
robot.ino |
setup/loop wiring, open-loop heading estimate, sit/stand blend, TEST_SERIAL_INPUT harness |
Config.h |
all placeholder geometry/pins/rates |
SmoothedValue.h |
rate-limited setpoint smoother used for every discrete command |
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). 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, |
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 (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 → 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), 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. 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 %, 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 |
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.
vy = -L_X, translate mode ry = -R_X).
Simulation (sim/ + Hexapod_Simulation_Unity/), details in sim/README.md
- Principle: the robot firmware is compiled unmodified for the PC. No
#ifdef SIMinrobot/, ever. Hardware is replaced beneath it bysim/shim/stand-ins (Arduino.h,Servo.h,Wire.hwith a register-level MPU6050,RF24.hwith a matching-config radio,SPI.h,EEPROM.h). - Build:
.\sim\build.ps1(configure + build + smoke test; uses g++/cmake/ninja fromC:\Strawberry\c\binif they're not on PATH). Rebuild after anyrobot/orshared/change. - The dev PC is Windows, and the owner uses Windows PowerShell 5.1.
Every documented command must work there: no
&&, one command per line, or a.ps1script. - Gotchas (already solved; don't undo them):
robot/must never be on any include path, not even-iquote. On Windows' case-insensitive filesystem GCC's<limits.h>chain would pick uprobot/Limits.h. So eachrobot/*.cppis compiled through a generated wrapper insim/build/robot_src/, and sim sources include"../robot/..."directly.- The shim's
min/maxreturnstd::common_typeby value; adecltypereturn type gave dangling references.
robot_ino.cppcompilesrobot.inoand exposes read-only views of its globals (SimRobotAccess.h). The API is inHexapodSimApi.h(HXSIM_API_VERSION, mirrored byHexapodSimNative.ExpectedApiVersionin C#). The FK inHexapodSimApi.cppis deliberately independent ofrobot/Kinematics.cpp.- Joint convention the sim (and Config.h limits) assume: coxa + = CCW
from the mount angle; femur = elevation, + = up; tibia relative to the
femur, + = up (knee-down stance is about −98°). Rig mapping:
hip1.y = −(coxa + mount offset),Hip2.x = −femur,Knie.x = −(tibia + 90). - Unity (
Assets/HexapodSim/):HexapodSimBootstrapauto-addsHexapodSimulationin any scene and disables the old scripts (Walk,RotationControl,Leg,HandleHoystick). Those are kept for reference only.OpenScadModelreplaces the old scene's robot with the OpenSCAD model (meshes fromhardware/openscad/export_unity.pyinResources/OpenScadModel/): it builds a new rig with the same names at the Config.h geometry, whose rest pose (coxa 0, femur 0, tibia -90) is the zero rotation.HexapodSimulation.useOpenScadModelturns it off.HexapodSimNativeloads a temp copy of the DLL via LoadLibrary/GetProcAddress, so there's no file lock and each Play is a fresh power-on.SimRemotestands in for the remote (Joystick axes "1"–"6" as in the old project, Keyboard, or the robot's own serial harness) and mirrorsremote/PacketBuilder.cpp+RemoteState.cpprules. Keep them in sync.SimTestPanelis the IMGUI panel (F1).- Body motion is kinematic and lives in the DLL (
sim/SimBody.cpp,hxsim_get_body), so Unity shows exactly whatsim_smokechecks. The ground is the support plane (a plane all feet are on or above; prefer most contacts, then continuity with the last ground), and 2D Kabsch on the feet that stayed grounded gives planar motion. The simulated MPU6050 is fed from it after every control tick. Ground tilt comes fromhxsim_set_ground_tilt. The old C# "lowest feet + plane fit" model flipped the body as soon as it rolled (only one side counted as grounded); don't reintroduce it. - Robot forward = Unity −X, 1 Unity unit = 10 mm.
- The Unity project grew out of the 2018-2023 Unity simulation, which is in
../2018-unity-sim/with its full history.
Testing without the other board
- Robot without remote:
#define TEST_SERIAL_INPUTinrobot.ino(on by default). Serial 115200, single keys:aarm,ssit/stand,w/xvx ±200,q/evy ±200 (left/right),z/cyaw_rate ±200 (left/right),ggait,mmode, space = zero velocity. Keys inject throughComms::injectPacket(), the same path radio packets take. Order: arm → stand → walk. The harness does not exercise the right stick or remote tilt. Add keys if needed. - Robot firmware in simulation:
sim/build/sim_smoke.exe(headless, scripted checks), or Unity Play mode with Keyboard / Joystick / Robot serial input. - Remote without robot or display: the USB serial console (see
remote/README.md).pshows raw/mapped sticks, IMU, link and state.ddumps packets at 10 Hz. With no robot, the link shows DOWN and arming still works; the link-loss disarm only fires after the link was up once.
Placeholders and bench-check items (not yet verified on hardware)
Robot (robot/README.md has detail):
-
Config.hgeometry now comes from the Unity model (owner's request), 1 unit = 10 mm:- legs at X ±100 / 0, Y ±50 / ±65 mm,
- mount angles ±30° / ±90° / ±150° (hexagon layout, owner's request: mid legs sideways, corner legs 60° further round; coxa direction at servo centre — the corner brackets sit 60° round on their splines),
- coxa/femur/tibia 55/100/150 mm,
- stance radius 75 (so 130 mm out from the coxa pivot), height 150 mm.
The old scene's
Leg.translateX= ±5 was only the old code's rotation pivot; the rig hips are at x ±10. Still to confirm on the real chassis: servo pins, µs/deg calibration,MAX_JOINT_DEG_S(in robot.ino), the Limits envelope, InputMapper maxima. -
Geometry and limits confirmed against the CAD (owner's request): the OpenSCAD rebuild of the real chassis (
hardware/openscad/, see itsPLANNING.md) has exactly these mounts and 55/100/150 mm links (tibia to the centre of a 10 mm foot ball; femur/knee axes in the coxa pivot plane, 13.5 mm above the bottom plate). Its collision sweep gave the joint limits now inConfig.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), andLEG_CLEARANCE_MMis 56 (a leg is 55.2 mm wide at the joints). The sim API exports the per-leg coxa limits (version 7). Version 8 addshxsim_get_ack_payload(the robot's telemetry); sim_smoke checks telemetry and everyCAL_*command. -
Fixed (owner-approved): the
Kinematics.cppfemur 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 −98.3°, feet exactly at −150 mm.sim_smokeguards this. -
Servos (owner-approved):
- The robot board is a Teensy 3.6 (owner confirmed), and
platformio.initargetsteensy36. Config.hSERVOS[6][3]is a per-servo table: pin,us_at_0deg, signedus_per_deg(the sign is the direction), andus_min/us_max. It's built byoldServo()from the old sketch's numbers (range, trim, zero, direction, offset) so they stay readable.ServoDriverdrives all 18 servos with hardware PWM: 50 Hz, 16-bitanalogWrite, and duty 0 = relaxed. The Teensy 3.6Servolibrary stops at 12 servos, which is why the old sketch used PWMServo.- Radio: CE 39 / CSN 15, with SPI SCK moved to pin 14
(
SPI.setSCK(RADIO_SCK_PIN)inComms::begin). - The sim's shims implement
analogWrite/analogWriteFrequency/analogWriteResolution, and decode pulses through the same table (API version 6). - The old ±90° offsets on the rear-left/front-left coxas left those servos at the end of their travel, and the sim showed those legs clamping (8 failing checks). The owner chose to re-horn both by 90°, so the offsets are 0. Must be done on the robot before running this firmware.
- BENCH: every direction, plus the femur's ≈6.7 µs/° (vs ≈10.4 for coxa/tibia).
- The robot board is a Teensy 3.6 (owner confirmed), and
-
IK knee direction (
tibia_radsign), BodyPose roll/pitch sign, IMU register map, and the sit pose assuming feet stay grounded. -
Fixed after the owner saw them in Unity (sim_smoke now guards each):
- Right-stick rotations were inverted:
BodyPose::applyrotated the feet by the pose instead of by its inverse. This also made the robot-gyro correction positive feedback. - Heading mode was off. The body turned at only 41% of the commanded ω (the gait used the hip as the yaw lever arm instead of the foot). The heading estimate also integrated while standing. Stance feet were interpolated between endpoints recomputed each tick, so a changing command undid part of the motion. And walking started with the feet at neutral but at arbitrary phases, so grounded legs overran the workspace clamp.
- Now: mode A turns at about 95% of command, and mode B turns 83° of a commanded 90°. The rest is open-loop estimate error; fusing IMU yaw is the next step.
- Combined right-stick poses (e.g. full roll+pitch+yaw) used to clamp
each foot on its own, distorting the planted feet by up to 29 mm. Now
the whole pose is reach-scaled (
BodyPose::fitToReach). sim_smoke checks that four full-deflection combos keep the feet rigid within 3 mm with no frozen servos. The Unity panel shows the scale ("body pose 63% (leg reach limit)"), viaHxStatus.pose_reach_scale(API version 2). - Legs could collide (full-rate turning needs ~60 mm half-strides, and
neighbouring feet are ~100 mm apart), and walking while posing made
the pose scale saw with the step cycle. Both are now handled by leg
clearance in
Limits::feetFeasibleplusGaitEngine::limitTwistand envelope-basedfitToReach. sim_smoke checks clearance with its own FK, and checks rigidity and steadiness while walking and posing. The panel shows "walk NN%" (HxStatus.twist_scale, API version 3). - Walking + rotate keys still freaked out. Changing the command
mid-step ran planted feet out of reach, and the pose scale snapped
down, which the per-joint rate clamp then tore out of formation. Now:
GaitEngine::updatemoves all planted feet by one common factor that keeps them feasible (with the pose applied), and the heading integratesappliedTwist().- The pose scale moves at a bounded rate both ways
(
REACH_DROP_PER_SEC3/s, recover 1/s). - While walking, the pose fits the requested stride and the current
feet (walking has priority), and the walk is limited again against
the current pose (
limitTwist(..., pose, chained)), so it slows during the handover. - sim_smoke's "toggling rotate keys" check mimics a keyboard.
- Robot-gyro self-leveling was
correction = -measured tilt, which only halves a slope because the measurement includes the correction. It's now an integrator (ROBOT_GYRO_KI3/s, clamped toROBOT_GYRO_MAX_CORR_DEG) on (measured tilt − operator's commanded tilt). sim_smoke: an 8° ground is levelled to < 1° without oscillation.
- Right-stick rotations were inverted:
-
Fixed (owner-approved): the
GaitEngine::updatestance direction. Stance now runs fromneutral + halftoneutral - half, so the feet push opposite to the commanded motion. The harnessz/ckeys were corrected toz=yaw_rate+ (turn left).sim_smokechecks that +vx goes forward and +yaw_rate turns left. -
Old robot sketch (
../2019-teensy-nrf24/Hexapod_Teensy/): real hardware facts. It received 18 servo angles (0–180) over RF24Network (channel 90) from the old remote/Unity and wrote them with PWMServo. No IK, no gait.- Board: Teensy 3.6 (pins 36–39 and
SPI.setSCK(14), confirmed by the owner). - Radio: CE 39, CSN 15, SPI SCK 14 / MOSI 11 / MISO 12. Now in
robot/Config.h. - Servo pins (servo index 0–17 = 6 × coxa, femur, tibia):
4,3,2, 7,6,5, 10,9,8, 23,22,21, 20,36,37, 17,16,38. No 11/12 conflict with SPI. - Index → leg (from the old Unity
Leg.startServo):- 0 = rear-right, 3 = mid-right, 6 = front-right (firmware legs 2, 1, 0);
- 9 = rear-left, 12 = mid-left, 15 = front-left (legs 3, 4, 5).
- Pulse ranges (PWMServo maps 0–180° linearly onto min..max):
- coxa and tibia 553–2425 µs (≈10.4 µs/°);
- femur 840–2050 µs (≈6.7 µs/°);
- plus a per-servo µs trim
servoCallibration[](0,100,0, 0,100,-30, 0,80,-50, -120,0,0, -10,20,0, 0,20,-80).
- Angle offsets:
servoOffset[]is +90° on index 9 (RL coxa) and −90° on index 15 (FL coxa), so those two horns are mounted rotated. The owner will re-horn them; the new firmware uses offset 0. - Direction mapping (derived from the old Unity
Leg.cs, in this repo's joint convention):- coxa servo = 90 − coxa;
- femur servo = 90 + femur (right), 90 − femur (left);
- tibia servo = −tibia (right), 180 + tibia (left), so 90 = knee bent 90°.
- All of this is now in
Config.hSERVOS(see "Servos" above).
- Board: Teensy 3.6 (pins 36–39 and
-
Older sketches (
../2016-ssc32-processing-port/Hexapod_NEW/,../2014-ik-core-task-queue/HexapodRobot/, 2014–2016 era): an earlier electronics generation. They did IK on the board and sent#n Pxxxx … T0text commands overSerial1to an external SSC-32-style servo controller (channels 0–9 and 16–24).- Femur range: it was already narrower there (600–2400 µs coxa/tibia,
960–2100 µs femur over 0–180°), which corroborates the ≈6.7 µs/° femur
in
SERVOS. - Links: femur 10, tibia 15 (cm), with no coxa length in that IK.
- Hip layout comment in
../2016-ssc32-processing-port/Hexapod_NEW/HexapodClass.h: width 9.5 cm (front/rear) and 14 cm (middle), 10 cm front-to-middle-to-rear. The Unity model has 10 / 13 / 10. Whichever chassis is current, measure before trustingLEG_MOUNT_*. - Nothing else from them applies to the current Teensy 3.6 hardware.
- Femur range: it was already narrower there (600–2400 µs coxa/tibia,
960–2100 µs femur over 0–180°), which corroborates the ≈6.7 µs/° femur
in
-
RobotIMU.cppreads(Wire.read() << 8) | Wire.read(), and C++ leaves the order of those two calls unspecified (fixed in the remote's copy). -
Heading for mode B is open-loop (integrated commanded ω). Fusing IMU yaw is a planned upgrade.
-
Limits::stancePolygonOk()is computed but not acted on.
Remote (remote/README.md has detail):
- Pins in
remote/Config.h, taken from the old remote sketch: radio CE 9 / CSN 10, Nextion on Serial2 (7/8), confirmed on the real remote. Owner's choice (2026-11-17): edge headers only, no pads underneath. So the MPU6050 is on Wire (18/19) and the two stick wires that were on A4/A5 (18/19) move to A7/A8 (21/22): sticks{ A0, A1, A2, A3, A7, A8 }. A6 (20) is kept for the battery divider. Checked on the real remote (2026-11-17): left stick X/Y/twist = A3/A7/A8, right = A0/A1/A2, all inverted but the right twist; each stick only moves about ±700 counts from centre, so run the sweep calibration. The IMU axis defaults are right. Its MPU6050 (likely a clone) reads all zeros until it gets a full device reset, soRemoteIMU::begin()resets it first.RobotIMUonly wakes its chip (owner-verified code, not changed): check the robot's IMU once it's flashed. STICK_INVERT[], calibration defaults, deadzones, expo.- The Nextion must have
bauds=115200in Program.s, and the HMI must matchNEXTION.md. The working HMI isremote/remote.HMI, generated byscripts/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.tftis uploaded: use serial keyUfor that first upload, the old UPLOAD button isn't recognised any more. Edit and render it with thenxhmiMCP server (registered in the repo root.mcp.json; code is the git submoduletools/nextion-hmi-tools, rungit submodule update --initafter cloning; CLIpython -m nxhmiwithPYTHONPATH=tools/nextion-hmi-tools/src):info,get_page,render_page,set_attributes,set_event,add_component,add_page,verify,build_tft. Its.tftbuilder is partial and needs the Nextion firmware files, which aren't in the submodule (they're kept locally inD:\Claude\nextion-hmi-tools\firmware), so compile the upload.tftin Nextion Editor. The compiled.tftis gitignored. - What the old remote sketch (
../2019-teensy-nrf24/remote/, last ran on a Teensy) tells us about the real hardware:-
Nextion on
Serial2(pins 7/8), driven by the ITEAD Nextion library (itsnexSerialis Serial2). The sketch'sSerial1.begin()and its USB ↔ Serial1 passthrough never reached the display: a probe on the real remote (2026-11-17) gotcomokonly on Serial2, at 115200.remote/Config.huses 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", andb2= enter upload mode; - page 3: sliders
h0–h17showing the 18 servo positions, plust1status; - page 4:
uploadscreen.
It had none of the arm/stand/gait/mode/gyro/speed/height controls. It was replaced by the generated tabbed HMI (see above).
- page 1:
-
b2→ Nextion upload passthrough: showsuploadscreen, then bridges USB ↔ the display serial forever, so Nextion Editor can upload a.tftthrough the remote's USB port. The new firmware keeps this as SETUP › UPDATE DISPLAY (pageupload). -
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: MPU on Wire (18/19), those two stick wires move to A7/A8 (21/22). -
nRF24 on CE 9 / CSN 10, the same as
remote/Config.h. It used RF24Network on channel 90, which the new protocol doesn't. -
Stick calibration was a 10 s min/max sweep saved to EEPROM, output 0–255, with no center or deadzone.
-
USB serial at 250000. It received 18 servo bytes + checksum +
0xFEfrom the old UnitySerial.cs(servo passthrough, forwarded over RF to the robot) and printedi_value,...stick lines.
-
- The Unity remote stand-in's joystick axis assignment (which of axes 4/6 is forward) couldn't be recovered from the old code. Check it with the panel's raw-axis readout.
- Radio retry timing (
RADIO_RETRY_*) is untested under real link loss.
Working rules for this repo
- The robot side is owner-verified code. Don't edit
robot/unless something is factually wrong relative to the protocol, and ask the owner first even then. Flag suspected robot bugs instead of fixing them. To try a robot fix, copyrobot/ shared/ sim/to a scratch dir, patch the copy and runsim_smokethere. - The older generations (
../20xx-*/, incl.../2009-fpga/original-frame/) are reference material from the owner. Don't modify them. - Protocol changes go in
shared/HexapodProtocol/only. Update the sizestatic_assert, this file's contract table, and both READMEs. - Match the existing style: config constants at the top of
Config.hwith BENCH comments for anything hardware-dependent,SmoothedValuerate limiting on any setpoint that can jump, and paired.h/.cppper concern. - 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).