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>
183 lines
9.2 KiB
Markdown
183 lines
9.2 KiB
Markdown
# 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.
|
||
|
||
- **IMU on the normal pin headers** (suggestion, not done): with the GY-521 on
|
||
the main board, wire it to Wire (SDA 18 / SCL 19) instead of Wire2 (the
|
||
24/25 pads under the Teensy 4.0). 18/19 are A4/A5, used by two stick axes
|
||
now, so move those two axes to A7 (pin 21) and A8 (pin 22): all on the
|
||
edge headers. A6 (pin 20) stays free for the battery divider, A9 (23) is
|
||
spare. Firmware: in `Config.h` `STICK_PINS = { A0, A1, A2, A3, A7, A8 }`
|
||
and `#define IMU_WIRE Wire`; `Sticks.cpp` reads through `STICK_PINS`, so
|
||
nothing else changes. Redo the stick axis check (`p` dump) and calibration
|
||
afterwards. (Wire1 is no way out: its 16/17 are stick pins A2/A3 too.)
|
||
|
||
## 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 (from the old remote sketch in `../../2019-teensy-nrf24/remote/`; 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 | **25 / 24 (Wire2)**, solder pads on the underside of the 4.0: not 18/19, those are stick pins A4/A5 |
|
||
| Nextion | TX → RX2, RX ← TX2 | 7 / 8 (Serial2), 5 V supply (found on the real remote) |
|
||
| Sticks | 6 axes | A0–A5. Which axis is on which pin isn't known yet: reorder `STICK_PINS` until the `p` dump reads right |
|
||
|
||
**MPU6050 rewiring:** the old remote had its MPU code switched off, probably
|
||
because A4/A5 double as Wire's pins. Move the MPU's SDA/SCL to pins 25/24 (the pads under the board).
|
||
|
||
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.
|
||
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`.
|
||
3. **Nextion baud:** the generated HMI sets `bauds=115200` in Program.s.
|
||
The display still runs the old HMI (probably 9600) until you upload
|
||
the new one; Nextion Editor finds the baud rate by itself. For that
|
||
first upload use serial key `U`: the old HMI's UPLOAD button isn't
|
||
recognised any more.
|
||
4. **Radio:** with the robot powered, `tLink` / `p` should show ~100%, and
|
||
`p` should print robot telemetry. If it reads NO LINK, check that both
|
||
boards were built from the same `HexapodProtocol.h`: each end drops
|
||
packets of the wrong size.
|
||
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.
|