- 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>
186 lines
9.6 KiB
Markdown
186 lines
9.6 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. The robot's `Telemetry` comes back in the radio's ack payloads.
|
||
Without the robot, the Unity simulation can answer instead, through the
|
||
USB nRF24 dongle (`../sim/README.md`).
|
||
|
||
## 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`.
|
||
The upload opens Teensy Loader; if the Teensy doesn't reboot into it by
|
||
itself, press its program button. If flashing works but the USB serial port
|
||
then won't open or goes quiet, try another USB port or cable before
|
||
suspecting the firmware (a bare Teensy 4.0 showed exactly that on one port).
|
||
|
||
## 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)** |
|
||
| MPU6050 | VCC | 3.3 V (a GY-521 runs fine on it). Check the polarity: one supply reversal killed the first board's regulator |
|
||
| 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 STICKS** on the SETUP page
|
||
(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, so it survives power cycles and reflashing.
|
||
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** (`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.
|