Files
hexapod-robot/2026-current/remote/README.md
T
mangavalkandClaude Opus 5.5 175a1a0da8 2026 docs: catch the READMEs up with today's state
- README: the HMI is generated turned round (nothing to set in the Editor);
  PC radio link: bridge mode done, no USB links any more, what's left
  (Unity driving the real robot, three nodes at once).
- remote/README checklist: sticks and IMU checked, display uploaded, radio
  checked against the sim through the dongle; replace the IMU board.
- CLAUDE.md: display runs the new HMI; next steps.

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

178 lines
8.9 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 remote firmware (Teensy 4.0)
Handheld transmitter for the hexapod. It reads two 3-axis twist-grip
joysticks and an MPU6050, takes operator commands from a Nextion
touchscreen, and sends a `CmdPacket` (defined in
`../shared/HexapodProtocol/HexapodProtocol.h`) to the robot over nRF24L01
at 100 Hz.
## Planned
- **Battery level** (divider not built yet): read the 18650's voltage through a
~100k/100k divider from the cell's + (not the boost board's 5 V output)
into A6 (pin 20, free), with 100 nF to GND. Details in
`../hardware/openscad/PLANNING.md` (notes for future designs). The
firmware side is done (`Battery`, shown on the STATUS page): set
`BATTERY_SENSE_PIN = A6` in `Config.h` once it's wired. A low-battery
warning is still to do.
## Building
From the `2026-current` folder: `pio run -e remote`, flash with
`pio run -e remote -t upload`, monitor with `pio device monitor -e remote`.
## Wiring (edge headers only; edit `Config.h` if yours differs)
| Part | Signal | Teensy 4.0 pin |
|------|--------|----------------|
| nRF24L01 | MOSI / MISO / SCK | 11 / 12 / 13 (SPI0) |
| nRF24L01 | CE / CSN | 9 / 10 |
| nRF24L01 | VCC | 3.3 V, with a 10–100 µF cap right at the module |
| MPU6050 | SDA / SCL | **18 / 19 (Wire)** |
| Nextion | TX → RX2, RX ← TX2 | 7 / 8 (Serial2), 5 V supply (found on the real remote) |
| Sticks | 6 axes | left stick X / Y / twist on **A3 / A7 / A8** (17 / 21 / 22), right stick on **A0 / A1 / A2** (14 / 15 / 16). A7/A8 hold the two wires that were on A4/A5 (18/19). All but the right twist read inverted (`STICK_INVERT`). Checked on the real remote |
| Battery (planned) | divider | A6 (20) |
**Rewiring from the old remote:** move the two stick wires from 18/19 to
21/22, then put the MPU on 18/19 (Wire). The old remote had its MPU code
switched off, probably because A4/A5 double as Wire's pins. Redo the stick
axis check (`p` dump) and the sweep calibration afterwards.
Stick pots are wired 3.3 V – wiper – GND. **Never feed 5 V into a Teensy
4.x analog pin.**
## Control scheme
| Input | Packet field | Meaning on the robot |
|-------|--------------|----------------------|
| Left stick forward/back | `vx` | walk forward/back |
| Left stick left/right | `vy` | strafe (mode A); heading target direction (mode B) |
| Left stick twist | `yaw_rate` | turn rate (mode A only; ignored in mode B) |
| Right stick, **ROTATE** (default) | `rx/ry/rz` | body roll / pitch / yaw |
| Right stick, **MOVE** (`FLAG_RSTICK_XLATE`) | `rx/ry/rz` | body X / Y / Z (height, via twist) offset |
| Handset tilt | `remote_roll/pitch` | extra body roll/pitch while REMOTE GYRO is on |
| Height slider | `body_height` | standing height, default ± `STANCE_HEIGHT_RANGE_MM` (robot rate-limits the change) |
In **HEADING** mode the left stick steers, relative to where the robot
faces at that moment. Forward/back walks forward/back, and sideways
steers: forward+left or back+left walk while turning left, and left alone
turns on the spot for as long as you hold it. Let go and the robot holds
its heading.
Touchscreen (`NEXTION.md` has the details), with tabs along the bottom and
a red DISARM on every page:
- **DRIVE:** ARM / DISARM, SIT/STAND, TRIPOD/WAVE, DIRECT/HEADING,
R: ROTATE/MOVE, REMOTE GYRO, ROBOT GYRO, speed and height sliders.
- **STATUS:** handset and robot IMU roll/pitch, the six stick axes, both
batteries, radio quality and the robot's received packet rate.
- **SERVOS:** all 18 joint angles the robot is commanding, as a top view.
- **CAL:** servo centre calibration (see below).
- **SETUP:** stick calibration (CAL STICKS / CANCEL), LEVEL REMOTE (re-zero
the handset tilt), UPDATE DISPLAY, backlight.
Everything about the robot comes from its **telemetry**, which rides back on
the radio's ack payloads (`Telemetry` in `HexapodProtocol.h`): `RadioLink`
reads it after every send, and it counts as stale after
`TELEMETRY_STALE_MS`.
## Servo centre calibration (CAL page)
1. Put the robot on a stand, legs free, and disarm.
2. Tap **START**. The robot drives every servo to its centre pose: coxa 0,
femur 0, tibia −90 (legs straight out, shins straight down).
3. Pick a leg (FR MR RR RL ML FL) and a joint. The remote first reads that
servo's trim back from the robot (the trim box shows `...` until then).
4. Step the trim with −10 / −1 / +1 / +10 µs (or ZERO) until the horn is
exactly square. SAVE TO ROBOT turns orange while there are unsaved
trims.
5. **SAVE TO ROBOT** stores all 18 trims in the robot's EEPROM. **REVERT**
drops unsaved changes. **STOP**, leaving the page, or a link loss relaxes
the servos. Arming is refused while calibrating.
### Safety interlocks (in `RemoteState`)
- **Arming** is refused unless every stick axis is centered, and never
allowed during stick or servo calibration. Servo calibration only starts
while disarmed, and stops when you leave the CAL page or the link drops.
- **UPDATE DISPLAY** needs a second tap within 3 s and is refused while
armed.
- **Disarming** always clears the stand request. The robot arms into SIT,
so re-arming never stands it up by itself.
- **Link loss:** if no ack arrives for `LINK_LOST_MS` (300 ms, matching the
robot's failsafe), the remote disarms itself. When the link comes back
the robot stays down until you re-arm deliberately.
- **Sit/stand** requests are only accepted while armed. `FLAG_WALK` is only
sent while standing is requested.
- While disarmed or calibrating, all motion fields are sent as zero.
### Smoothing
- **Speed scale** ramps toward the slider at `SPEED_SCALE_RATE_PER_SEC`.
The robot uses speed scale directly on the walking twist, so a slider
jump would otherwise be a velocity step.
- **Remote tilt** fades in/out over ~0.5 s when REMOTE GYRO is toggled, and
the handset re-zeroes its "level" at the moment you enable it.
- **FLAG_WALK** lingers 250 ms after the left stick centers, so hovering at
the deadzone edge doesn't make the robot chatter between STAND and
WALKING.
- Body pose smoothing is left to the robot's `BodyPose` rate limiters.
## Stick calibration
1. Power on with both sticks released and the remote held still. Each
axis's resting center is captured automatically.
2. For full calibration, disarm, then tap **CAL** (or press `c` on the
serial console). Move every axis of both sticks to both limits, release
them, and tap **SAVE CAL** (`c`). The result is saved to EEPROM.
3. If any axis moved less than `CAL_MIN_HALF_SPAN` either side of center,
the save is refused and you stay in calibration mode. **CANCEL CAL**
(`x`) aborts.
4. `p` prints the calibration in a form you can paste into `Config.h`
defaults. `R` wipes EEPROM back to the `Config.h` defaults.
## Serial console (USB, 115200, single keystrokes)
Every touchscreen control is available here, so you can bench-test with no
display attached.
| Key | Action | Key | Action |
|-----|--------|-----|--------|
| `a` | toggle arm | `k` | disarm |
| `s` | toggle sit/stand | `g` | tripod ↔ wave |
| `m` | direct ↔ heading-hold | `t` | right stick rotate ↔ translate |
| `r` | remote gyro on/off | `b` | robot gyro on/off |
| `+` / `-` | speed ±25 | `z` | zero handset level |
| `]` / `[` | height up / down 10% | | |
| `c` | start / save calibration | `x` | cancel calibration |
| `p` | print status (raw + mapped sticks, IMU, link, state, cal) | `d` | toggle 10 Hz packet dump |
| `R` | reset stick cal to Config defaults | `U` | Nextion upload mode (USB ↔ display; power-cycle to leave) |
| `o` | servo calibration start/stop | `n` | next servo (leg × 3 + joint) |
| `,` / `.` | trim −1 / +1 µs | `<` / `>` | trim −10 / +10 µs |
| `0` | trim to zero | `w` / `e` | save trims on the robot / revert |
`p` also prints the robot's telemetry (state, IMU, battery, joint angles)
and the servo-calibration state.
## Bench-check checklist
1. **Stick directions:** with `p`, confirm each logical axis reads
positive for right / forward / counterclockwise twist. Flip it in
`STICK_INVERT[]` if not. Done on the real remote (2026-11-17), then
the sweep calibration.
2. **IMU mounting:** with `p`, dip the right edge down to get +roll, and
tip the far edge down to get +pitch. If not, fix `IMU_AXIS_FROM_CHIP` /
`IMU_AXIS_SIGN`. Done (defaults are right). The first GY-521 got its
supply reversed once and its regulator now runs hot: redo this check
on the replacement, and see whether it still needs the reset in
`RemoteIMU::begin()`.
3. **Nextion:** the generated HMI sets `bauds=115200` in Program.s and is
on the display (upload through SETUP › UPDATE DISPLAY or serial `U`).
4. **Radio:** with the robot (or the Unity sim behind the USB dongle)
running, `tLink` / `p` should show ~100%, and `p` should print robot
telemetry. If it reads NO LINK, check that both ends were built from
the same `HexapodProtocol.h`: each end drops packets of the wrong size.
Done against the Unity sim through the dongle; not yet with the robot.
5. **End to end with the robot on a stand:** use `d` to dump packets and
confirm each field changes the way the table above says.