#pragma once #include // ===================================================================== // 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