Files
hexapod-robot/2026-current/robot/README.md
T
mangavalkandClaude Opus 5.5 179afdb705 2026 docs: review of every README against today's state
- README / CLAUDE.md layout: dongle/, hardware/, tools/ submodule,
  make_remote_hmi.py; telemetry in the protocol; the PC can take the
  robot's place on the radio. CLAUDE.md: NextionUI is on Serial2 (said
  Serial1); remote-without-robot via the dongle + sim.
- remote/README: MPU6050 supply row; stick calibration button names of the
  new SETUP page; upload/USB-port hints.
- remote/NEXTION.md: display on Serial2, how the Editor upload goes.
- robot/README: Battery in the file list, Comms/ServoDriver roles, packet
  structs instead of payload size, check the IMU gives live data (the
  remote's MPU6050 needed a full reset; RobotIMU::begin() only wakes it).
- sim/README: smoke test covers telemetry and servo calibration;
  OpenScadModel.
- dongle/README: AT2401C test result, app command table, SignalRGB note,
  air settings incl. ack payloads.
- PLANNING.md: the display direction is in the generated HMI.
- Unity README: what the project is.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:56:14 +01:00

176 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Hexapod robot firmware (Teensy 3.6)
This is the **robot-side** firmware. It is fully functional on its own
(driven by the serial test harness below) and receives commands from the
remote (`../remote/`) over nRF24L01. The packet format lives in
`../shared/HexapodProtocol/HexapodProtocol.h` — the single definition both
sketches compile against.
## Building
From the `2026-current` folder (PlatformIO): `pio run -e robot`, flash with
`pio run -e robot -t upload`, monitor with `pio device monitor -e robot`.
RF24 is pulled in automatically via `lib_deps`. Servos are driven by the
Teensy's hardware PWM directly, so no servo library is needed.
Arduino IDE also works if you copy `shared/HexapodProtocol/` into your
sketchbook `libraries/` folder and install **RF24** by TMRh20.
## Before you trust this on the floor
The leg geometry in `Config.h` is taken from the Unity model
(`Hexapod_Simulation_Unity`, 1 unit = 10 mm). Everything else there is
still a placeholder. Check all of it against the real robot:
- `LEG_MOUNT_ANGLE_DEG` / `LEG_MOUNT_X_MM` / `LEG_MOUNT_Y_MM` — where each
coxa pivot actually sits on your chassis, and which way it points
- `COXA_LEN_MM` / `FEMUR_LEN_MM` / `TIBIA_LEN_MM` — your link lengths
- `COXA_MIN_DEG..TIBIA_MAX_DEG` — your servos' real safe range of motion
- `STANCE_RADIUS_MM` / `STANCE_HEIGHT_MM` — how far out/down you want the
resting foot position
- `LEG_CLEARANCE_MM`: how close neighbouring legs may get. Walking speed
and body pose are scaled down to keep it, so set it to about one leg's
width.
- `SERVOS`: one entry per servo with pin, pulse at 0°, signed µs per
degree (sign = direction) and pulse limits. It's prefilled from the old
robot sketch (`../../2019-teensy-nrf24/Hexapod_Teensy/config.h`): pins, ranges, trims, and
directions from the old Unity servo mapping. Check every joint's
direction on the bench.
- **Before powering up:** re-mount the rear-left and front-left coxa servo
horns 90° so those legs point straight out at servo center. The old code
needed ±90° offsets there, which left the servos at the end of their
travel.
- `RADIO_CE_PIN` / `RADIO_CSN_PIN` / `RADIO_SCK_PIN`: 39 / 15 / 14, as in
the old sketch. Address, channel, data rate, PA level and the packet
structs are in `shared/HexapodProtocol` so they can't drift from the
remote.
## Bench-check checklist (do this before the first stand-up)
These are sign conventions that depend on which way your hardware is
physically mounted, and the code has a best-guess default that may be wrong
for your build:
1. **IK knee direction** (`Kinematics.cpp`). The femur elevation sign bug
(the foot was solved *above* the hip) is fixed and verified in the
simulation: the stance pose comes out femur −1.2°, tibia −98.3°. Still
command one leg to a few known foot positions on the bench and check the
knee bends the way the sim shows.
2. **BodyPose roll/pitch sign** (`BodyPose.cpp`). Fixed in the simulation:
the pose was applied as the forward rotation, which inverted roll, pitch
and yaw. On the bench, command a small roll/pitch and verify the body
leans the way the protocol says (+roll = right side down, +pitch = nose
down).
3. **RobotIMU register map** (`RobotIMU.cpp`) — written for an MPU6050-style
chip (I2C addr `0x68`). If your gyro is a different part, its register
addresses and scale factors will differ; swap them in. Also check that
it gives live readings at all (the robot's roll/pitch on the remote's
STATUS page): the remote's MPU6050 answered and woke up but read all
zeros until it got a full device reset (`PWR_MGMT_1 = 0x80`), which
`RobotIMU::begin()` doesn't do.
4. **Sit-pose assumption** — the built-in sit pose in `robot.ino` assumes all
six feet stay grounded and simply lowers the body (a 0.4x height blend).
If your chassis is meant to rest its belly on the ground instead, this
needs a different, sequenced approach (fold legs up rather than just
lowering).
5. **Gait travel direction** (`GaitEngine.cpp`). Fixed: stance now sweeps
each foot opposite to the commanded motion. The smoke test checks that
`+vx` moves the body forward and `+yaw_rate` turns it left (CCW). On
the bench, confirm `w` walks forward and `z` turns left.
6. **Per-servo calibration** (`Config.h` `SERVOS`). Arm the robot,
stand it on a box, and move one joint at a time (or watch the sim next
to it): each servo must turn the way the sim shows. To flip a direction,
flip that entry's `dir`. Also check that a femur moves the commanded
angle: its old range gives only ≈6.7 µs/° against ≈10.4 for coxa and
tibia.
## Testing in the simulation
This exact code also compiles for the PC and runs in the Unity model. See
`../sim/README.md`. `sim/build/sim_smoke.exe` is a quick headless check
after every change. In Unity the simulated robot can also be driven by the
real remote over the radio, through the USB nRF24 dongle.
## Testing without a remote yet
`robot.ino` has `#define TEST_SERIAL_INPUT` enabled by default. With that on,
open the Arduino Serial Monitor (115200 baud, no line ending needed — single
keystrokes) and use:
| Key | Action |
|-----|--------|
| `a` | toggle armed |
| `s` | toggle sit / stand |
| `w` / `x` | walk forward / backward (`vx` ±) |
| `q` / `e` | strafe left / right (`vy` ±) |
| `z` / `c` | turn left / right (`yaw_rate` ±) |
| `g` | toggle gait: tripod ↔ wave |
| `m` | toggle walk mode: direct (A) ↔ heading-hold (B) |
| space | zero all velocity (stop walking, stay in current state) |
Each keystroke injects a `CmdPacket` through `Comms::injectPacket()` — the
exact same path a real remote's received radio packets go through, so the
rest of the pipeline (mapper → state machine → gait → pose → IK → servos)
runs identically to how it will with real hardware. Once you have a real
remote transmitting, just remove the `#define TEST_SERIAL_INPUT` line (or
leave it — injected packets simply won't happen if you don't type).
Arm (`a`), then stand (`s`), before trying to walk — the state machine
enforces `DISARMED → SIT → STAND → WALKING` in order and will otherwise
ignore walk commands.
## Link with the remote
- `CmdPacket` and the `FLAG_*` bits in `shared/HexapodProtocol` are the
exact wire format. `Comms` drops any packet whose length isn't
`sizeof(CmdPacket)`, so a robot and remote built from different protocol
versions won't receive each other at all (and the robot fails safe).
- **Telemetry back to the remote:** after every packet received, `Comms`
loads a fresh `Telemetry` (robot state, IMU roll/pitch, battery, the 18
commanded joint angles, packets per second, servo-cal echo) as the radio's
ack payload. It goes back on the auto-ack of the remote's next packet:
no extra transmissions. `sendTelemetry()` in `robot.ino` fills it every
loop. The IMU attitude is now estimated whether or not robot gyro is on
(the remote shows it); only the leveling is gated by `FLAG_ROBOT_GYRO`.
- **Servo centre calibration** (remote's CAL page): while disarmed, a
`cal_cmd` other than `CAL_NONE` puts the robot in SERVO_CAL. Every servo
is driven to the centre pose (coxa 0, femur 0, tibia −90: legs straight
out, shins straight down) and `CAL_SET` adjusts one servo's centre trim
(µs, ±200, on top of `Config.h` `SERVOS`; it shifts the whole pulse range
like the old `servoCallibration[]`). `CAL_SAVE` stores the 18 trims in
EEPROM (`ServoDriver`, address 0, loaded at power-on), `CAL_REVERT`
reloads them. `CAL_NONE`, arming or link loss relaxes the servos again.
Put the robot on a stand first.
- **Battery:** `Battery` reads `BATTERY_SENSE_PIN` through a divider
(`Config.h`). Not wired yet (pin 255): the remote shows "--".
- Failsafe: if no packet arrives for `LINK_TIMEOUT_SEC`, `Comms::linkOk()`
goes false and the main loop falls back to a zeroed `CmdPacket`, which
disarms the robot.
- The right stick's roll/pitch/yaw (or X/Y/Z) always apply. The remote's
handset tilt arrives in its own `remote_roll` / `remote_pitch` fields and
is added on top only while `FLAG_REMOTE_GYRO` is set, capped at
`MAX_TILT_DEG` total (`InputMapper`). `FLAG_ROBOT_GYRO` independently
enables the robot's own IMU stabilization.
- `FLAG_RSTICK_XLATE` switches the right stick between rotation-axes and
translation-axes interpretation, and `FLAG_MODE_B` switches between the
two walk modes, all inside the existing `InputMapper`.
## File layout
```
robot/
├── robot.ino - main sketch: setup/loop, state wiring, serial test harness
├── Config.h - all placeholder constants (edit this first)
├── SmoothedValue.h - generic rate-limited setpoint smoother
├── Kinematics.h/.cpp - per-leg 3-DOF analytical IK
├── GaitEngine.h/.cpp - tripod/wave gait, per-leg phase, dynamic gait swap
├── BodyPose.h/.cpp - 6-axis body pose composition (feedforward + IMU correction)
├── RobotIMU.h/.cpp - gyro/accel read + complementary filter
├── StateMachine.h/.cpp - DISARMED/SIT/STAND/WALKING with smoothed sit-stand blend
├── InputMapper.h/.cpp - CmdPacket -> twist/pose/mode decoding
├── Limits.h/.cpp - workspace clamp, joint rate limit, stance polygon check
├── Comms.h/.cpp - nRF24L01 receive + telemetry as ack payload (packets in shared/HexapodProtocol)
├── ServoDriver.h/.cpp - servo PWM write/relax, per-servo centre trims (EEPROM), SERVO_CAL
└── Battery.h/.cpp - battery voltage through a divider (not wired yet)
```