Files
hexapod-robot/2026-current/shared/HexapodProtocol/HexapodProtocol.h
T
mangavalkandClaude Opus 5.5 0b836af8de 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>
2026-11-17 14:42:37 +01:00

126 lines
7.9 KiB
C++

#pragma once
#include <Arduino.h>
// =====================================================================
// Remote <-> robot wire protocol. SINGLE SOURCE OF TRUTH.
//
// Both robot/ and remote/ compile against this exact header (PlatformIO
// lib_dir = shared). Any change here changes the over-the-air format:
// rebuild and reflash BOTH boards together. Each end drops any packet whose
// length isn't sizeof() of what it expects, so a remote and robot running
// mismatched versions simply won't hear each other (the robot then fails
// safe on link timeout) instead of misinterpreting fields.
// Telemetry (below) comes back from the robot in the radio's ack payloads.
//
// Axis convention (right-handed body frame, viewed from above, like ROS
// REP-103): +X forward, +Y left, +Z up. Positive rotations follow the
// right-hand rule: +roll = right side down, +pitch = nose down,
// +yaw = counterclockwise (turn left).
//
// All analog fields are normalized -1000..1000. The robot owns the physical
// scaling (max mm/s, max tilt deg, max offset mm) in InputMapper, so the
// remote never needs to know robot geometry.
// =====================================================================
// Protocol version: bump on any change to CmdPacket, Telemetry or the radio
// settings below (the payload sizes are checked on both ends as well).
constexpr uint8_t HXP_PROTOCOL_VERSION = 4;
struct CmdPacket {
int16_t vx = 0; // left stick: + forward / - backward
int16_t vy = 0; // left stick: + strafe left / - strafe right
int16_t yaw_rate = 0; // left stick twist: + turn left (CCW)
int16_t rx = 0, ry = 0, rz = 0; // right stick: roll/pitch/yaw, or X/Y/Z offset if FLAG_RSTICK_XLATE
int16_t remote_roll = 0; // remote handset tilt (feedforward), only honored with FLAG_REMOTE_GYRO
int16_t remote_pitch = 0;
int16_t body_height = 0; // standing height setting: -1000 lowest, 0 = default, +1000 highest
int16_t cal_value = 0; // servo calibration: centre trim in us for cal_servo (CAL_SET only)
uint8_t speed_scale = 128; // 0-255, multiplies vx/vy
uint8_t flags = 0; // bit-packed, see FLAG_* below
uint8_t seq = 0; // increments every transmitted packet
uint8_t cal_cmd = 0; // servo calibration command, CAL_* below. 0 = normal operation
uint8_t cal_servo = 0xFF; // servo calibration: selected servo, leg * 3 + joint (0..17)
};
// Both ends are Teensy (Cortex-M, little-endian, 2-byte int16 alignment):
// 10 x int16 + 5 x uint8 = 25 bytes, padded to 26. If a different MCU family
// ever joins, pack the struct explicitly rather than trusting this.
static_assert(sizeof(CmdPacket) == 26, "CmdPacket layout changed - reflash both boards");
static_assert(sizeof(CmdPacket) <= 32, "nRF24L01 payloads are limited to 32 bytes");
constexpr uint8_t FLAG_ARMED = 1 << 0;
constexpr uint8_t FLAG_STAND = 1 << 1; // 0 = sit requested, 1 = stand requested
constexpr uint8_t FLAG_WALK = 1 << 2; // left stick past deadzone -> walking
// Mode B (steering), relative to where the body faces right now: the left
// stick's forward/back component walks forward/back, its sideways component
// steers - forward+left or back+left walk while turning left, left alone
// turns on the spot while held. Released, the robot holds its heading.
constexpr uint8_t FLAG_MODE_B = 1 << 3; // 0 = mode A direct, 1 = mode B heading
constexpr uint8_t FLAG_RSTICK_XLATE = 1 << 4; // 0 = right stick = rotation, 1 = translation
constexpr uint8_t FLAG_GAIT_WAVE = 1 << 5; // 0 = tripod requested, 1 = wave requested
constexpr uint8_t FLAG_REMOTE_GYRO = 1 << 6; // remote tilt feedforward enabled
constexpr uint8_t FLAG_ROBOT_GYRO = 1 << 7; // robot stabilization feedback enabled
// ---- Servo centre calibration (CmdPacket.cal_cmd) ----
// Only honoured while FLAG_ARMED is clear. Any CAL_* other than CAL_NONE puts
// the robot in its SERVO_CAL state: every servo is driven to its centre pose
// (coxa 0, femur 0, tibia -90 = legs straight out, shins straight down) through
// the per-servo trims, so a mis-centred horn shows. Every command is a state,
// not an event, so a repeated or lost packet does no harm. Leaving SERVO_CAL
// (CAL_NONE, arming, or link loss) relaxes the servos again.
constexpr uint8_t CAL_NONE = 0; // normal operation
constexpr uint8_t CAL_HOLD = 1; // hold the centre pose; select cal_servo, report its trim
constexpr uint8_t CAL_SET = 2; // ... and set cal_servo's trim to cal_value (us)
constexpr uint8_t CAL_SAVE = 3; // ... and store all trims in the robot's EEPROM (if changed)
constexpr uint8_t CAL_REVERT = 4; // ... and reload all trims from the EEPROM (drop unsaved changes)
constexpr int16_t CAL_TRIM_LIMIT_US = 200; // trims are clamped to +-this
constexpr uint8_t CAL_NO_SERVO = 0xFF;
// =====================================================================
// Robot -> remote telemetry. The robot preloads this as the nRF24 ACK
// PAYLOAD, so it rides back on the auto-ack of the remote's next packet:
// no extra transmissions, and nothing changes for the remote -> robot
// direction. Ack payloads need dynamic payload lengths on both radios, so
// each end checks the received length against sizeof() itself and drops
// anything else - a remote and robot on different protocol versions still
// don't understand each other's packets.
// =====================================================================
struct Telemetry {
int16_t roll_ddeg = 0; // robot IMU roll, 0.1 deg (+ = right side down)
int16_t pitch_ddeg = 0; // robot IMU pitch, 0.1 deg (+ = nose down)
uint16_t battery_mv = 0; // robot battery, mV. 0 = not measured
int16_t cal_trim_us = 0; // centre trim of cal_servo, us
uint8_t state = 0; // TSTATE_* below
uint8_t status = 0; // TSTAT_* bits below
uint8_t cal_servo = CAL_NO_SERVO; // echo of CmdPacket.cal_servo (the trim above belongs to it)
uint8_t rx_per_sec = 0; // remote packets the robot received in the last second
int8_t joint_deg[18] = {}; // commanded joint angles, leg * 3 + joint, degrees.
// Tibia is stored + 90 (its range -150..-20 doesn't fit an int8):
// tibia = joint_deg[i * 3 + 2] - 90.
};
static_assert(sizeof(Telemetry) == 30, "Telemetry layout changed - reflash both boards");
static_assert(sizeof(Telemetry) <= 32, "nRF24L01 ack payloads are limited to 32 bytes");
constexpr int TELEMETRY_TIBIA_OFFSET_DEG = 90;
constexpr uint8_t TSTATE_DISARMED = 0; // same numbering as the robot's RobotState
constexpr uint8_t TSTATE_SIT = 1;
constexpr uint8_t TSTATE_STAND = 2;
constexpr uint8_t TSTATE_WALKING = 3;
constexpr uint8_t TSTATE_SERVO_CAL = 4;
constexpr uint8_t TSTAT_IMU_OK = 1 << 0; // robot IMU responded at power-on
constexpr uint8_t TSTAT_GYRO_ON = 1 << 1; // robot-gyro self-leveling active
constexpr uint8_t TSTAT_SERVOS_ON = 1 << 2; // servos are being driven (not relaxed)
constexpr uint8_t TSTAT_CAL_DIRTY = 1 << 3; // servo trims changed since the last save
constexpr uint8_t TSTAT_TRIMS_STORED = 1 << 4; // the EEPROM holds a trim record
// ---- Radio link settings (must be identical on both ends) ----
constexpr uint8_t HXP_RADIO_ADDRESS[6] = "HXPD1"; // 5-byte pipe address + NUL
constexpr uint8_t HXP_RADIO_CHANNEL = 96; // 2400+96 MHz; pick one clear of your local Wi-Fi
constexpr uint8_t HXP_RADIO_PAYLOAD = sizeof(CmdPacket); // remote -> robot (checked per packet, see Telemetry)
// Data rate / PA level are RF24 enums; kept as plain ints here so this header
// doesn't depend on RF24.h. 2 == RF24_250KBPS, 1 == RF24_PA_LOW in RF24 1.x;
// both Comms.cpp (robot) and RadioLink.cpp (remote) static_assert this.
constexpr uint8_t HXP_RADIO_DATA_RATE = 2; // RF24_250KBPS
constexpr uint8_t HXP_RADIO_PA_LEVEL = 1; // RF24_PA_LOW