2026 remote: tabbed Nextion UI, robot telemetry, servo centre calibration

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>
This commit is contained in:
mangavalkandClaude Opus 5.5 committed 2026-11-17 14:42:37 +01:00
1 parent 481610c9fd
commit 0b836af8de
40 files changed
+1463 -281

No files matched your search

+84 -98
View File
@@ -1,112 +1,98 @@
# Nextion HMI build guide
# Nextion HMI
Work in `remote.HMI` in this folder (a copy of the old servo monitor,
`../../2019-teensy-nrf24/remote-nextion/remote.HMI`, re-saved by a newer
Nextion Editor) and **add one page named `control`** with the components below.
The old HMI's pages:
| # | Name | Contents |
|---|------|----------|
| 0 | `splashsceen` (sic) | start page |
| 1 | `main` | `t1` link status, `b2` (id 5) upload mode |
| 2 | `servocal` | servo calibration (not used by this firmware) |
| 3 | `page0` | servo sliders `h0`–`h17`, `t1` link status. Note the name: `page page0` opens this page, `page 0` (a number) opens the splash |
| 4 | `uploadscreen` | shown during upload mode |
| 5 | `joysticks` | not used by this firmware |
Your existing pages keep working:
| Existing | What the firmware does with it |
|----------|--------------------------------|
| page 1 `t1`, page 3 `t1` | writes `connected` / `not connected`, as the old firmware did, as `main.t1` and `page0.t1` (`NEXTION_STATUS_TEXTS` in `Config.h`). Set both to **vscope = global** |
| page 1 `b2` (id 5) | **upload mode**: keep "Send Component ID" ticked on it. The remote shows `uploadscreen` and passes USB straight through to the display, so Nextion Editor can upload over the remote's USB port. Power-cycle to leave. Serial key `U` does the same |
| page 4 `uploadscreen` | shown on entering upload mode |
| page 3 sliders `h0`–`h17` | not driven yet: the robot doesn't send servo positions back (that needs the planned telemetry channel) |
The firmware drives the display by **component name**, and the display
talks back with small custom frames sent from each button's touch event.
Layout, fonts and colors are up to you. The names and event code must
match exactly.
**Set every component on `control` to vscope = global.** The firmware
writes them as `control.<name>` and keeps them current whichever page is
showing. A local component on another page can't be written from outside,
and with `bkcmd=0` the display ignores those writes silently.
The remote is authoritative. Use **plain Button** components (not
Dual-state buttons) and don't toggle anything locally in the HMI. The
remote repaints every label and color from its own state, including a
full redraw every 2 s and whenever the display reboots.
## Program.s / page setup
In **Program.s**, before `page 0`, add:
`remote.HMI` in this folder is the touchscreen project (NX4832T035, 480×320).
It's **generated** by `../scripts/make_remote_hmi.py`: change the layout
there and re-run it, rather than editing the `.HMI` in Nextion Editor (an
Editor edit is lost on the next run). Then open `remote.HMI` in Nextion
Editor, compile, and upload the `.tft`: SETUP › UPDATE DISPLAY (tap twice)
or serial key `U` puts the remote in USB passthrough for the upload.
```
bauds=115200
python scripts\make_remote_hmi.py (from 2026-current)
```
This sets the display to the `NEXTION_BAUD` in `remote/Config.h`. The
display ships at 9600, and `bauds=` persists across power cycles. The old
firmware used the ITEAD library at 9600, so your HMI probably runs at 9600
today.
It needs the `tools/nextion-hmi-tools` submodule, Pillow, DejaVu Sans Mono
(found in matplotlib, or `--font-dir`), and the old remote HMI
(`../../2019-teensy-nrf24/remote-nextion/remote.HMI`, read only) for the
splash picture. To look at a page without the Editor, use the `nxhmi` MCP
server's `render_page`.
Name the new page `control`. The firmware never changes pages, except
into `uploadscreen` for upload mode. Add buttons on your other pages to
switch to it (`page control`).
## Pages
## Components
| id | Page | Contents |
|----|------|----------|
| 0 | `splash` | spider picture, 1.5 s, then `drive` |
| 1 | `drive` | ARM, SIT/STAND, gait, mode, right-stick mode, both gyros, speed + height sliders, messages |
| 2 | `status` | remote and robot IMU roll/pitch, the 6 stick axes, both batteries, radio |
| 3 | `servos` | all 18 joint angles (robot telemetry), laid out as a top view of the robot |
| 4 | `cal` | servo centre calibration: START/STOP, leg and joint, trim ±1/±10 µs, ZERO, REVERT, SAVE |
| 5 | `setup` | stick calibration, LEVEL REMOTE, UPDATE DISPLAY, backlight, versions |
| 6 | `upload` | shown during display update mode |
Text components need **txt_maxl** at least as large as the longest string
the firmware writes. Button bounds here allow some slack.
Pages 1–5 share a frame: a top bar (`tLink` link quality, `tState` robot
state + battery, red `bKill` DISARM) and tab buttons `bTab0`–`bTab4` that
switch pages locally (`page drive`, ...). The page order is the page id, and
must match `UiPage` in `UiTypes.h`.
| Name | Type | txt_maxl | Firmware writes |
|----------|---------|----------|----------------------------------------------|
| `bArm` | Button | 10 | `ARMED` / `DISARMED`, bco red / gray |
| `bKill` | Button | – | nothing (static "DISARM" label, make it red) |
| `bStand` | Button | 6 | `STAND` / `SIT`, bco green / gray |
| `bGait` | Button | 8 | `TRIPOD` / `WAVE` |
| `bMode` | Button | 8 | `DIRECT` / `HEADING` |
| `bRs` | Button | 10 | `R: ROTATE` / `R: MOVE` |
| `bRGyro` | Button | – | bco green / gray (label it "REMOTE GYRO") |
| `bBGyro` | Button | – | bco green / gray (label it "ROBOT GYRO") |
| `hSpeed` | Slider | – | `val` 0..255 (set **maxval = 255**) |
| `nSpeed` | Number | – | `val` 0..100 (speed %) |
| `hHeight`| Slider | – | `val` 0..200, 100 = default (set **maxval = 200**) |
| `nHeight`| Number | – | `val` -100..100 (height offset %) |
| `bCal` | Button | 9 | `CAL` / `SAVE CAL`, bco orange while active |
| `bCalX` | Button | – | nothing (static "CANCEL CAL") |
| `bZero` | Button | – | nothing (static "LEVEL") |
| `tLink` | Text | 10 | `LINK 97%` / `NO LINK`, pco green / red |
| `tMsg` | Text | 40 | status / rejection messages |
## How the firmware talks to it
## Touch events
- **Display → remote:** every touch sends a custom frame with `printh`:
`'#'` (0x23), length, command byte, optional value byte. "Send Component
ID" is off everywhere.
- **Page tracking:** each page's Preinitialize event sends `'P'` + its page
id, so the remote always knows which page is showing. After a remote
restart it asks with `sendme`.
- **Remote → display:** the remote writes only the showing page, by local
component name (no `vscope = global`, no display RAM spent), and only
what changed (`NextionUI` hashes every instruction). Everything is
re-sent every 2 s and after the display restarts (0x88), so a dropped
byte heals itself. Render rate is 20 Hz (SERVOS 10 Hz), and a render is
skipped rather than blocking when the TX buffer is full.
- **The remote is authoritative:** plain buttons only, nothing toggles
locally. Exceptions that are purely local: the tabs, and the backlight
slider (`dim` / `dims`).
- `Program.s` sets `bauds=115200` (= `NEXTION_BAUD` in `Config.h`), stored in the display.
Put this in each component's **Touch Release Event** (the Speed slider
uses **Touch Move** as well so the value tracks your finger). Frame format:
`'#'` (0x23), length, command byte, optional value byte.
## Commands (display → remote)
| Component | Event code | Command |
|-----------|------------------------------------------|--------------------------------|
| `bArm` | `printh 23 01 41` | `A` toggle arm (needs sticks centered) |
| `bKill` | `printh 23 01 4B` | `K` disarm, always accepted |
| `bStand` | `printh 23 01 53` | `S` toggle sit/stand |
| `bGait` | `printh 23 01 47` | `G` tripod ↔ wave |
| `bMode` | `printh 23 01 4D` | `M` direct ↔ heading-hold |
| `bRs` | `printh 23 01 58` | `X` right stick rotate ↔ translate |
| `bRGyro` | `printh 23 01 52` | `R` remote-gyro tilt on/off |
| `bBGyro` | `printh 23 01 42` | `B` robot self-stabilize on/off |
| `hSpeed` | `printh 23 02 56`<br>`prints hSpeed.val,1` | `V` + speed byte |
| `hHeight` | `printh 23 02 48`<br>`prints hHeight.val,1` | `H` + height byte (Touch Move + Release) |
| `bZero` | `printh 23 01 5A` | `Z` zero handset level |
| `bCal` | `printh 23 01 43` | `C` start / save stick calibration |
| `bCalX` | `printh 23 01 51` | `Q` cancel calibration |
| Component | Event code | Command |
|-----------|-----------|---------|
| every page | `printh 23 02 50 <id>` (Preinitialize) | `P` page shown |
| `bKill` | `printh 23 01 4B` | `K` disarm, always accepted |
| `bArm` | `printh 23 01 41` | `A` toggle arm (needs sticks centered) |
| `bStand` | `printh 23 01 53` | `S` toggle sit/stand |
| `bGait` | `printh 23 01 47` | `G` tripod ↔ wave |
| `bMode` | `printh 23 01 4D` | `M` direct ↔ heading-hold |
| `bRs` | `printh 23 01 58` | `X` right stick rotate ↔ translate |
| `bRGyro` | `printh 23 01 52` | `R` remote-gyro tilt on/off |
| `bBGyro` | `printh 23 01 42` | `B` robot self-stabilize on/off |
| `hSpeed` | `printh 23 02 56` + `prints hSpeed.val,1` (move + release) | `V` + speed 0..255 |
| `hHeight` | `printh 23 02 48` + `prints hHeight.val,1` (move + release) | `H` + height 0..200, 100 = default |
| `bCal` | `printh 23 01 43` | `C` start / save stick calibration |
| `bCalX` | `printh 23 01 51` | `Q` cancel stick calibration |
| `bZero` | `printh 23 01 5A` | `Z` zero handset level |
| `bUpd` | `printh 23 01 55` | `U` display update mode (second tap within 3 s) |
| `bCalOn` | `printh 23 01 4F` | `O` servo calibration start/stop |
| `bL0`–`bL5` | `printh 23 02 4C 0n` | `L` + leg (0 FR, 1 MR, 2 RR, 3 RL, 4 ML, 5 FL) |
| `bJ0`–`bJ2` | `printh 23 02 4A 0n` | `J` + joint (0 coxa, 1 femur, 2 tibia) |
| `bM10` `bM1` `bP1` `bP10` `bZeroT` | `printh 23 02 54 0n` | `T` + trim step: 0 −10, 1 −1, 2 +1, 3 +10, 4 zero (µs) |
| `bSave` | `printh 23 01 57` | `W` save trims on the robot |
| `bRevert` | `printh 23 01 45` | `E` reload trims from the robot's EEPROM |
**Uncheck "Send Component ID"** on every component on `control`: those
standard touch frames only add serial traffic. The one exception is the old
page 1 `b2` upload button (see the top).
To add a control: pick an unused command byte, add it to
`NextionUI::decodeCustom()` and `UiCmd`, handle it in `RemoteState::handle()`,
add the component in `make_remote_hmi.py`, and a row here.
Protocol details and the parser live in `NextionUI.h/.cpp`. To add a
control, pick an unused command byte, add it to `NextionUI::decodeCustom()`
and `UiCmd`, handle it in `RemoteState::handle()`, and add a row here.
## What the remote writes (remote → display)
| Page | Components |
|------|-----------|
| all but splash/upload | `tLink` txt/pco, `tState` txt/pco |
| drive | `bArm` `bStand` txt/bco, `bGait` `bMode` `bRs` txt, `bRGyro` `bBGyro` bco, `hSpeed` `hHeight` val, `tSpeed` `tHeight` `tMsg` txt |
| status | `tRRoll` `tRPitch` `tBRoll` `tBPitch` txt, `hRRoll` `hRPitch` `hBRoll` `hBPitch` val (0..90 = ±45°), `hLX` `hLY` `hLT` `hRX` `hRY` `hRT` val (0..200 = ±1000), `tBatt` `tRadio` txt. The indicator sliders have touch switched off (`tsw` in Preinitialize) |
| servos | `tJ0`–`tJ17` txt (index = leg × 3 + joint), `jJ0`–`jJ17` val (position in the servo's travel), `tSrv` txt/pco |
| cal | `bCalOn` txt/bco, `bL0`–`bL5` `bJ0`–`bJ2` bco (selected = green), `tTrim` txt, `bSave` bco (orange = unsaved), `tMsg` txt |
| setup | `bCal` txt/bco, `bUpd` txt/bco, `tVer` txt, `tMsg` txt |
`txt_maxl` of each text is set in the generator to fit the longest string
the firmware writes. Keep them in step when you change a format string.