2026-11-14 12:19:16 +01:00
# Hexapod remote firmware (Teensy 4.0)
2026-09-28 18:14:00 +02:00
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.
2026-11-14 18:57:49 +01:00
## Planned
2026-11-17 14:42:37 +01:00
- **Battery level** (divider not built yet): read the 18650's voltage through a
2026-11-14 18:57:49 +01:00
~100k/100k divider from the cell's + (not the boost board's 5 V output)
2026-11-17 14:42:37 +01:00
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.
2026-11-14 18:57:49 +01:00
2026-09-28 18:14:00 +02:00
## Building
2026-10-25 17:30:35 +01:00
From the `2026-current` folder: `pio run -e remote` , flash with
2026-09-28 18:14:00 +02:00
`pio run -e remote -t upload` , monitor with `pio device monitor -e remote` .
2026-11-17 22:03:08 +01:00
## Wiring (edge headers only; edit `Config.h` if yours differs)
2026-09-28 18:14:00 +02:00
2026-11-14 12:19:16 +01:00
| Part | Signal | Teensy 4.0 pin |
2026-09-28 18:14:00 +02:00
|------|--------|----------------|
| 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 |
2026-11-17 22:03:08 +01:00
| MPU6050 | SDA / SCL | **18 / 19 (Wire)** |
2026-11-17 14:42:37 +01:00
| Nextion | TX → RX2, RX ← TX2 | 7 / 8 (Serial2), 5 V supply (found on the real remote) |
2026-11-17 22:03:08 +01:00
| 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) |
2026-10-01 15:29:21 +02:00
2026-11-17 22:03:08 +01:00
**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.
2026-09-28 18:14:00 +02:00
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 |
2026-09-29 00:37:12 +02:00
| 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.
2026-09-28 18:14:00 +02:00
2026-11-17 14:42:37 +01:00
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.
2026-09-28 18:14:00 +02:00
### Safety interlocks (in `RemoteState`)
- **Arming** is refused unless every stick axis is centered, and never
2026-11-17 14:42:37 +01:00
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.
2026-09-28 18:14:00 +02:00
- **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 |
2026-09-29 00:37:12 +02:00
| `]` / `[` | height up / down 10% | | |
2026-09-28 18:14:00 +02:00
| `c` | start / save calibration | `x` | cancel calibration |
| `p` | print status (raw + mapped sticks, IMU, link, state, cal) | `d` | toggle 10 Hz packet dump |
2026-10-01 15:29:21 +02:00
| `R` | reset stick cal to Config defaults | `U` | Nextion upload mode (USB ↔ display; power-cycle to leave) |
2026-11-17 14:42:37 +01:00
| `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.
2026-09-28 18:14:00 +02:00
## 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` .
2026-11-17 14:42:37 +01:00
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.
2026-09-28 18:14:00 +02:00
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.