hexapod-robot/2026-current/CLAUDE.md

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). This file is the persistent context for working on either side. Read it fully before changing anything.

Layout and toolchain

PlatformIO, one platformio.ini, two environments:

Env	Board	Sketch dir	Purpose
robot	teensy40	robot/	walking robot
remote	teensy41	remote/	handheld transmitter

• shared/ is PlatformIO's lib_dir. shared/HexapodProtocol/ is a header-only library both sketches #include <HexapodProtocol.h>.
• PlatformIO has a single global src_dir and only converts .ino files at its root, so scripts/select_src_dir.py (a pre: extra script) swaps PROJECT_SRC_DIR to each env's custom_src_dir. That keeps robot/ and remote/ plain Arduino sketch folders: one .ino plus paired .h/.cpp per concern. Keep that structure. No giant files, no src/ 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 at C:\Users\patri\.platformio\penv\Scripts\pio.exe. Both envs build clean. Build both after touching shared/.

Communication contract (shared/HexapodProtocol/HexapodProtocol.h)

CmdPacket, 20 bytes (static_asserted), 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
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)

• 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 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.
• 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 LINK_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 InputMapper logic in the remote.

Robot architecture (robot/, Teensy 4.0)

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
BodyPose	6-axis body pose (smoothed command + IMU roll/pitch correction) applied to foot targets
RobotIMU	MPU6050 complementary filter (α 0.98), 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. Mode B = heading-hold from stick angle. 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)
Comms	nRF24 RX, link timeout, injectPacket() for the harness
ServoDriver	attach/detach/write, skips invalid IK solutions

Remote architecture (remote/, Teensy 4.1)

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.

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)
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
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. HMI sends '#' len cmd [val] frames via printh. Remote pushes state by component name with diffing, a 2 s full refresh, and a redraw on the Nextion 0x88 "ready" frame
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

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).

Testing without the other board

• Robot without remote: #define TEST_SERIAL_INPUT in robot.ino (on by default). Serial 115200, single keys: a arm, s sit/stand, w/x vx ±200, q/e vy ±200 (left/right), z/c yaw_rate ∓/±200, g gait, m mode, space = zero velocity. Keys inject through Comms::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.
• 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 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):

• All of Config.h: leg mount angles/positions, link lengths, joint limits, stance radius/height, servo pins, µs/deg calibration, MAX_JOINT_DEG_S (in robot.ino), Limits envelope, InputMapper maxima.
• Pin conflict: SERVO_PINS leg 3 uses pins 11 and 12, which are Teensy 4.0 SPI MOSI/MISO needed by the nRF24. Must be moved. Some servo pins (26, 27, 30…) may also not be PWM-capable on the 4.0. Verify.
• IK knee direction (tibia_rad sign), BodyPose roll/pitch sign, IMU register map, and the sit pose assuming feet stay grounded.
• Suspected gait direction inversion: in GaitEngine::update the stance phase moves the foot from neutral - half to neutral + half, i.e. with the commanded direction. That pushes the body backward for +vx, and the same happens for yaw. Fix = swap start/end. Flagged to the owner, not changed. The harness z/c yaw keys currently rely on this behavior and need rechecking after the fix.
• 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):

• All pins in remote/Config.h (radio CE 9 / CSN 10, sticks A0–A3/A6/A7, MPU6050 on 18/19, Nextion on Serial2 7/8).
• STICK_INVERT[], calibration defaults, deadzones, expo.
• 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. No .HMI file is in the repo yet. The compiled .tft is gitignored.
• 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.
• Protocol changes go in shared/HexapodProtocol/ only. Update the size static_assert, this file's contract table, and both READMEs.
• Match the existing style: config constants at the top of Config.h 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/.