2026-11-17 14:42:37 +01:00
# Nextion HMI
2026-09-28 18:14:00 +02:00
2026-11-17 22:48:41 +01:00
`remote.HMI` in this folder is the touchscreen project (NX4832T035, 480× 320),
turned 180° (Editor display direction 270) because the display sits upside
down in the remote.
2026-11-17 14:42:37 +01:00
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.
2026-09-28 18:14:00 +02:00
```
2026-11-17 14:42:37 +01:00
python scripts\make_remote_hmi.py (from 2026-current)
2026-09-28 18:14:00 +02:00
```
2026-11-17 14:42:37 +01:00
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` .
2026-09-28 18:14:00 +02:00
2026-11-17 14:42:37 +01:00
## Pages
2026-09-28 18:14:00 +02:00
2026-11-17 14:42:37 +01:00
| 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 |
2026-09-28 18:14:00 +02:00
2026-11-17 14:42:37 +01:00
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` .
2026-09-28 18:14:00 +02:00
2026-11-17 14:42:37 +01:00
## How the firmware talks to it
2026-09-28 18:14:00 +02:00
2026-11-17 14:42:37 +01:00
- **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.
2026-09-28 18:14:00 +02:00
2026-11-17 14:42:37 +01:00
## Commands (display → remote)
2026-09-28 18:14:00 +02:00
2026-11-17 14:42:37 +01:00
| 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 |
2026-09-28 18:14:00 +02:00
2026-11-17 14:42:37 +01:00
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.
2026-09-28 18:14:00 +02:00
2026-11-17 14:42:37 +01:00
## 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.