MeshTerm on hardware: one manual for the PicoCalc, the XIAO radio and the SPI bridge

docs/hardware.md is the single place a reader goes to put MeshTerm on a
PicoCalc or a uConsole, written in the shape of the command-line manual: what
the three targets are and which exclude each other, why the console font is
built on the device, every phase of the Calculinux bring-up and its knobs, the
XIAO UART radio from parts to a verified link, the SPI bridge with an honest
note that it was written against pymc_core 1.0.x while today's uConsole stack
depends on the renamed openhop-core, and a closing list of what has only ever
been proven on one bench. scripts/README.md and xiao-radio/README.md become
short indexes pointing at it; the old ones were stale in four places (trace
through the bridge works, the firmware env is _serial, two scripts were
unlisted). README links the manual, gains the two dependency rows it lacked
(markdown-it-py, PyYAML) and a fixed fonts anchor.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Fable 5.1 committed 2026-09-12 19:02:02 -04:00
1 parent 9ebc4bd2be
commit 8d3f5d8ed3
4 files changed
+666 -293

No files matched your search

+24 -120
View File
@@ -1,125 +1,29 @@
# scripts
Device-side helpers for running MeshTerm on real hardware. Independent, self-contained
targets live here:
Device-side helpers that put MeshTerm on real hardware: bringing up a ClockworkPi PicoCalc
(Luckfox Lyra, Calculinux) and building its console font, giving that handheld a real
MeshCore radio over UART, and fronting an SPI-attached LoRa chip as if it were a companion
device. They run **on the device**, most of them as root, and they are meant to be read
before they are run.
- **Calculinux device** (Luckfox Lyra / ClockworkPi PicoCalc) — one-time bring-up and
the console font.
- **XIAO nRF52840 UART radio** ([`xiao-radio/`](xiao-radio/)) — wire a Seeed XIAO +
Wio-SX1262 to the Lyra's hardware UART and run MeshTerm against it. Full build → flash →
setup guide with scripts. This is the way to give a PicoCalc a real MeshCore radio.
- **SPI-attached radio bridge** (`meshterm-spi-bridge`) — expose a bare SPI LoRa chip
to MeshTerm as if it were a companion device (uConsole AIO, Waveshare HATs).
**[`docs/hardware.md`](../docs/hardware.md) is the manual** — what each target is, what the
scripts assume about the machine, why each step is the way it is, and what has only ever
been proven on one bench. Start there and pick your target; the table below is the index.
## Calculinux device (Luckfox Lyra / ClockworkPi PicoCalc)
| File | Runs on | What it does |
| --- | --- | --- |
| [`calculinux-setup.sh`](calculinux-setup.sh) | the Lyra (root) | One-time bring-up: python packages, the Wi-Fi boot-scan kick, a boot clock sync (there is no RTC), the deploy user, the checkout, the venv and `pip install -e .`, the login PATH, and the console font. Idempotent. |
| [`calculinux-console-font.sh`](calculinux-console-font.sh) | the Lyra (root) | Just the console font: builds, installs and persists the 512-glyph **meshterm** PSF (braille, node marks, rounded frame corners, the list cursor) and restores the stock 16-slot palette. Run it alone after a MeshTerm update. |
| [`calculinux-wifi-set.sh`](calculinux-wifi-set.sh) | the Lyra (sudo) | Interactive Wi-Fi join: prompts for an SSID and passphrase, writes iwd's credentials, connects now. This is how a network *becomes* known to the boot kick. |
| [`calculinux-radio-bridge.sh`](calculinux-radio-bridge.sh) | the Lyra (root) | **Unfinished, unsupported.** An early UART-to-TCP pump, superseded by `xiao-radio/lyra-setup.sh`; its header describes routing it does not contain. See the manual before reading it. |
| [`meshterm-spi-bridge`](meshterm-spi-bridge) | the radio host (your user) | Runs a mesh node in software over an SPI-attached SX1262 (uConsole AIO, Waveshare HATs) and serves the companion protocol on `127.0.0.1:5000`. Setup menu, preflight, optional `systemd --user` service. **Written for `pymc_core` 1.0.x — see the manual's rename note before installing.** |
| [`xiao-radio/`](xiao-radio/) | see below | Everything for the XIAO nRF52840 + Wio-SX1262 radio wired to the Lyra's UART1. |
| [`xiao-radio/build-firmware.sh`](xiao-radio/build-firmware.sh) | dev machine | Clones and patches MeshCore, builds the `Xiao_nrf52_companion_radio_serial` environment, emits the `.uf2`. |
| [`xiao-radio/flash.py`](xiao-radio/flash.py) | dev machine | Flashes the `.uf2` to the XIAO over its UF2 bootloader, refusing the wrong board or SoftDevice; prints the serial-DFU command when the bootloader offers no drive. |
| [`xiao-radio/meshcore-uart1.patch`](xiao-radio/meshcore-uart1.patch) | — | The two firmware hunks: the companion on nRF52 `Serial1`, and I²C moved off the UART pads. Not upstream yet. |
| [`xiao-radio/lyra-setup.sh`](xiao-radio/lyra-setup.sh) | the Lyra (root) | Boot-persistent UART1 → GP4/GP5 mux service, `dialout` membership, and a default MeshTerm serial profile for `/dev/ttyS1`. |
| [`xiao-radio/uart1-mux.py`](xiao-radio/uart1-mux.py) | the Lyra (root) | The matrix-IO register poke that routes UART1 to the header pads, run once per boot by the service above. |
Helpers for running MeshTerm on a **Luckfox Lyra / ClockworkPi PicoCalc under Calculinux**
(the bare-framebuffer terminal target). They run *on the device* as root, not on your dev
machine.
| Script | What it does |
|---|---|
| [`calculinux-setup.sh`](calculinux-setup.sh) | Complete one-time bring-up: opkg python packages, the Wi-Fi boot-scan kick, a boot-time clock sync (no RTC on this board), the deploy user, the read-only clone, the venv + `pip install -e .`, the login PATH, and the console font. Idempotent. |
| [`calculinux-console-font.sh`](calculinux-console-font.sh) | Just the console font: builds/installs/persists the 512-glyph **meshterm** PSF (Terminus + braille + node glyphs + rounded frame corners + the list cursor). Called by the setup script; also runnable on its own after a MeshTerm update. |
### Usage
Copy the `scripts/` folder to the device and, as root:
```bash
sh calculinux-setup.sh
```
Two prerequisites the setup script checks for but cannot embed:
- **Deploy key** — place the read-only GitHub deploy key at
`/home/$DEPLOY_USER/.ssh/id_ed25519` (`DEPLOY_USER` defaults to `meshterm`; `KEY_PATH`
overrides the location outright)
(mode 600) before running; the clone uses it over SSH.
- **Wi-Fi credentials** — the kick only nudges a network iwd already knows. Either connect
once by hand (`iwctl station wlan0 connect <SSID>`) or export `WIFI_SSID` and `WIFI_PSK`
so the script writes the iwd config (secrets stay in your environment, never in the repo).
Both scripts are POSIX `sh`, idempotent, and safe to re-run.
## XIAO nRF52840 UART radio — give a PicoCalc a real radio
A **Seeed XIAO nRF52840 + Wio-SX1262** wired to the Luckfox Lyra's hardware UART1, running
MeshCore companion firmware over `Serial1` (D6/D7). MeshTerm talks to it directly on
`/dev/ttyS1` — no bridge process. Everything (parts, wiring, firmware build/flash, device
setup, the *why*) is in [`xiao-radio/README.md`](xiao-radio/), with scripts for each step:
| Script | Runs on | What it does |
|---|---|---|
| [`xiao-radio/build-firmware.sh`](xiao-radio/build-firmware.sh) | dev machine | clone + patch MeshCore, build the `_usb` env, emit the `.uf2` |
| [`xiao-radio/flash.py`](xiao-radio/flash.py) | dev machine | flash the `.uf2` to the XIAO via its UF2 bootloader |
| [`xiao-radio/lyra-setup.sh`](xiao-radio/lyra-setup.sh) | the Lyra (root) | boot-persistent UART1→GP4/GP5 mux service, `dialout`, default MeshTerm profile |
| [`xiao-radio/uart1-mux.py`](xiao-radio/uart1-mux.py) | the Lyra | the matrix-IO register poke that routes UART1 to the header pads |
Two things this depends on, both handled by the patch/guide: the firmware must bind the
companion to `Serial1` **and** move I²C off D6/D7 (MeshCore maps it there and it steals the
UART pins); and MeshTerm must include the platform-UART liveness fix (`serial_port_present`
treats a soldered `/dev/ttyS1` as present).
## meshterm-spi-bridge — expose an SPI-attached radio
Some boards wire the LoRa chip straight to the host's SPI bus — the ClockworkPi
uConsole with the hackergadgets AIO, Waveshare LoRa HATs, and similar. There is
**no companion microcontroller and no firmware to flash**: the mesh node runs in
software on the host via the [`pymc_core`](https://pypi.org/project/pymc-core/)
library (on the uConsole this arrives with the `meshcore-uconsole` apt package,
which also ships the `meshcore-console` GUI).
MeshTerm, however, speaks the MeshCore **companion protocol** over serial / BLE /
TCP and expects to talk to a *node*, not to drive a bare radio. This bridge fills
the gap: it runs the `pymc_core` node itself and puts the standard companion
protocol in front of it on a local TCP port, so that
```
meshterm --tcp 127.0.0.1:5000
```
connects exactly as if a real companion device were plugged in.
### Usage
Copy `meshterm-spi-bridge` onto the radio host and run it with any Python 3 —
it finds the `pymc_core` runtime and re-execs the bridge under it for you:
```
./meshterm-spi-bridge # interactive setup menu
./meshterm-spi-bridge --check # run prerequisite checks and exit
./meshterm-spi-bridge --run # run the bridge now, in this terminal
```
The menu offers:
1. **Run now** — runs in the foreground; Ctrl+C stops it.
2. **Install as a service** — a `systemd --user` unit that starts on boot and
restarts on failure, running as you (so it uses your node identity).
3. **Uninstall** — removes only the bridge service + its helper copy. It never
touches the `meshcore-console` / `pymc_core` packages.
### Caveats
- **Only one program may use the radio at a time.** Run *either* the
`meshcore-console` GUI *or* this bridge — never both. The bridge preflight
warns you when the GUI is running.
- The bridge and MeshTerm are two cooperating processes; keep the bridge running
while you use MeshTerm.
- **Same identity as the GUI:** when the `meshcore-console` stack is present, the
bridge loads the node key from `~/.local/share/meshcore-uconsole/identity.key`,
so MeshTerm sees the same node. On a generic `pymc_core`-only install it mints
and persists its own key under `~/.local/share/meshterm-spi-bridge/`.
- **Trace is not wired yet.** Messaging, contacts, adverts and config work
today; the node's trace / path-discovery replies aren't yet pushed to the
companion server, so MeshTerm's Trace screen won't populate until that's added.
### Overriding hardware pins
Defaults match the hackergadgets uConsole AIO. For other SPI boards, set env
vars before launching (read by the direct-`pymc_core` path):
`MESHCORE_BUS_ID`, `MESHCORE_CS_ID`, `MESHCORE_RESET_PIN`, `MESHCORE_BUSY_PIN`,
`MESHCORE_IRQ_PIN`, `MESHCORE_FREQUENCY`, `MESHCORE_TX_POWER`,
`MESHCORE_SPREADING_FACTOR`, `MESHCORE_BANDWIDTH`, `MESHCORE_CODING_RATE`. To
force a specific interpreter, set `MESHTERM_PYMC_PYTHON`.
The PicoCalc scripts and the SPI bridge belong to different machines and share nothing but
MeshTerm. On the Lyra, only one program may hold `/dev/ttyS1` — MeshTerm directly, or a pump
in front of it, never both.
+24 -170
View File
@@ -1,185 +1,39 @@
# PicoCalc mesh radio — XIAO nRF52840 over UART
Give a **PicoCalc (Luckfox Lyra, Calculinux)** a real MeshCore LoRa radio by wiring a
**Seeed XIAO nRF52840 + Wio‑SX1262** to the Lyra's hardware UART and running MeshTerm
against it. No BLE, no USB host, no SD‑slot sacrifice, and — with the firmware fixed the
right way — **no re‑soldering dead ends.**
A Seeed XIAO nRF52840 + Wio-SX1262 wired to the Luckfox Lyra's UART1, running MeshCore
companion firmware on `Serial1`, so MeshTerm on the PicoCalc opens `/dev/ttyS1` like any
other serial companion. No BLE, no USB host, no SD-slot sacrifice.
```
MeshTerm ──serial──> /dev/ttyS1 ──UART1 (GP4/GP5)──> XIAO Serial1 (D6/D7) ──> SX1262 ──))) mesh
(on the Lyra) 115200 8N1 matrix‑IO mux companion fw
```
**The manual is [`docs/hardware.md`](../../docs/hardware.md#a-real-radio-for-the-picocalc-xiao-nrf52840-over-uart)**
— parts, the firmware patch and why it is still needed, flashing a bootloader that offers no
drive, what the register poke does, troubleshooting, and what has only been proven on one
bench. This page is the bench card.
Three steps: **build firmware → flash the XIAO → set up the Lyra.** Each has a script.
---
## 1. Hardware
### Bill of materials
- **Seeed XIAO nRF52840** (plain or **Sense**) stacked with the **Wio‑SX1262** LoRa module
(the SX1262 uses XIAO pins D1–D5, D8–D10 — already wired inside the kit; nothing to do).
- **Luckfox Lyra** in *Pico* form factor (RK3506, SD‑boot), running **Calculinux** inside a
**ClockworkPi PicoCalc**.
- Four wires.
### Wiring — four connections
The XIAO's free UART pins go to the PicoCalc's Pico‑style header. **Crossed** TX/RX:
| XIAO pad | → | Lyra header | Physical pin | Carries |
|---|---|---|---|---|
| **D7** (Serial1 RX) | → | **GP4** | pin **6** | Lyra UART1 **TX** → XIAO RX |
| **D6** (Serial1 TX) | → | **GP5** | pin **7** | XIAO **TX** → Lyra UART1 RX |
| **GND** | → | **GND** | pin **8** | common ground |
| **3V3** | → | **3V3 OUT** | pin **36** | power (so it runs without USB) |
> ⚠️ **The Lyra does *not* use Raspberry Pi Pico GPIO numbering.** The 40‑pin header is
> physically Pico‑compatible, but each pad's function is Luckfox's own RK3506 mapping. The
> pins above are verified: GP4 = `gpio0-0`, GP5 = `gpio0-1`. Don't trust a Pico pinout for
> anything else here.
All signals are 3.3 V — no level shifter. There is **no 5 V rail** on this board; power the
XIAO from 3V3 only.
---
## 2. Build the firmware *(on your dev machine)*
Needs `git` and PlatformIO (`pip install platformio`).
Three steps on two machines:
```bash
cd scripts/xiao-radio
sh build-firmware.sh
```
# 1. dev machine: build (needs git + PlatformIO)
cd scripts/xiao-radio && sh build-firmware.sh
This clones MeshCore, applies [`meshcore-uart1.patch`](meshcore-uart1.patch), builds the
`Xiao_nrf52_companion_radio_serial` environment, and writes **`meshcore-xiao-radio.uf2`**.
# 2. dev machine: flash, with the XIAO's own USB-C plugged in
python flash.py # double-tap reset if the touch doesn't take
The patch makes two changes that are *both* required (see [Why](#why-it-works)):
- teaches MeshCore's existing **`SERIAL_RX` companion interface** to build on nRF52 — it was
written for ESP32 and declares a `HardwareSerial` the Adafruit nRF52 core doesn't have;
- adds the **`Xiao_nrf52_companion_radio_serial` env**, which puts the companion on D6/D7 and
moves the **I²C bus off those pads** (to internal pins 16/17) so it can't steal them.
Both changes are upstream-shaped and have been **submitted to MeshCore**. If they land, this
patch step disappears: the env ships with the firmware and you just build it.
---
## 3. Flash the XIAO *(on your dev machine)*
Plug the **XIAO's own USB‑C** into your computer (it may stay wired to the Lyra).
```bash
python flash.py
```
It pulses the XIAO's app port at 1200 baud to drop it into the bootloader, checks that the
bootloader it found really is a XIAO, and copies the firmware. If it can't get there,
**double‑tap the XIAO's reset button** and re‑run.
**If no UF2 drive appears**, that isn't necessarily a fault: on our board the bootloader came
up as a **serial port only, with no mass‑storage interface at all**, so there is nothing to
copy a file onto. `flash.py` detects that and prints the serial‑DFU command to run from your
MeshCore checkout instead:
```bash
pio run -e Xiao_nrf52_companion_radio_serial -t upload --upload-port <bootloader port>
```
That is the route that worked here — it ends in `Device programmed.` and the XIAO reboots
itself into the radio firmware.
> ⚠️ **Check which board you are flashing.** A drive letter is not an identity — when one
> board leaves the USB bus another can inherit its letter, so the volume you found may not be
> the one you just touched. `flash.py` reads `INFO_UF2.TXT` and refuses anything that isn't a
> XIAO, or that carries **SoftDevice S140 6.1.1** (which wants the app at `0x26000`, while
> this firmware links for S140 v7 at `0x27000` — it would flash and then not boot). Override
> with `--force` only if you know better than it does.
Sanity check: after flashing, the XIAO's USB serial port goes **silent to the companion
protocol** — because the companion now lives on D6/D7, not USB. That silence is correct.
---
## 4. Set up the Lyra *(on the device, as root)*
Copy `scripts/` to the Lyra and run:
```bash
# 3. the Lyra, as root
sh scripts/xiao-radio/lyra-setup.sh # MT_USER=meshterm by default
```
It installs a **systemd service** that routes UART1 → GP4/GP5 on every boot, adds your user
to `dialout`, and writes a default MeshTerm serial profile for `/dev/ttyS1`.
---
## 5. Run it
```bash
# then, as that user
meshterm
```
With the default profile in place, plain `meshterm` connects straight to the radio. You
should see your node come up (ours reports as `Johnputer-Pico`).
Four wires, TX and RX crossed:
---
| XIAO pad | → | Lyra header | Physical pin | Carries |
| --- | --- | --- | --- | --- |
| **D7** (Serial1 RX) | → | **GP4** | pin **6** | Lyra UART1 **TX** → XIAO RX |
| **D6** (Serial1 TX) | → | **GP5** | pin **7** | XIAO **TX** → Lyra UART1 RX |
| **GND** | → | **GND** | pin **8** | common ground |
| **3V3** | → | **3V3 OUT** | pin **36** | power, so it runs without USB |
## Why it works *(the short version)*
Everything below was the hard part; the scripts encode the answers so you don't repeat it.
- **MeshCore already had companion‑over‑UART; nRF52 was just never wired into it.** The
`SERIAL_RX`/`SERIAL_TX` defines and the per‑board `*_companion_radio_serial` envs have
shipped for a while — `Xiao_S3_WIO_companion_radio_serial` uses *the same D6/D7 pads* on the
ESP32‑S3 twin of this board. The nRF52 build just doesn't compile: the shared code declares
`HardwareSerial companion_serial(1)` and calls `setPins()`, and on the Adafruit nRF52 core
`HardwareSerial` is abstract with no numbered constructor. `Serial1` is the concrete `Uart`
the core always defines, and `Uart::setPins(pin_rx, pin_tx)` takes the same arguments in the
same order — so one reference fixes it and the call site is untouched.
- **Calculinux never wires UART1 to a pad.** The controller is enabled (so `/dev/ttyS1`
exists) but reaches no pin. The RK3506 *matrix IO* can carry UART1 on almost any pad, so
[`uart1-mux.py`](uart1-mux.py) pokes two register groups over `/dev/mem` to put UART1‑TX on
`gpio0-0` (GP4) and UART1‑RX on `gpio0-1` (GP5). No SD slot is sacrificed (the stock UART1
pads are the front SD‑card slot — we avoid them entirely).
- **MeshCore maps I²C onto D6/D7 on the XIAO.** `XiaoNrf52Board::begin()` *and*
`sensors.begin()` call `Wire` on those exact pins, so the I²C peripheral seizes them and the
UART goes silent — even with perfect wiring. The patch moves I²C to the internal IMU pins
(16/17). This was the single reason the link stayed dead through every other fix.
- **MeshTerm liveness for soldered UARTs.** pyserial's `comports()` doesn't enumerate
platform‑bus ports like `/dev/ttyS1`, so MeshTerm's liveness poll would falsely report the
radio unplugged. MeshTerm now treats an existing `/dev` character device as present
(`serial_port_present` in `meshterm/core/connection.py`) — so **use a MeshTerm build that
includes that fix.**
---
## Troubleshooting
| Symptom | Check |
|---|---|
| `meshterm` can't open the port | Is `MT_USER` in `dialout`? (`groups`) — needs a fresh login after setup. |
| Port opens but no node / silence | Re‑flash with the **`_serial`** env (not `_ble`/`_usb`); only that one defines `SERIAL_RX`/`SERIAL_TX`. Confirm the XIAO's USB serial is *silent* to companion frames. |
| Still silent, wiring confirmed | Confirm the firmware has the **I²C‑remap** (`PIN_WIRE_SCL=16`, `PIN_WIRE_SDA=17`). |
| Flashed fine, board never comes back | Wrong board, or wrong SoftDevice — check `INFO_UF2.TXT` said a XIAO and **S140 v7**, not 6.1.1. `flash.py` refuses both unless you passed `--force`. |
| `flash.py` finds no UF2 drive | Expected on a bootloader that exposes CDC only. Use the `pio … -t upload --upload-port` line it prints. |
| Nothing on `/dev/ttyS1` after reboot | `systemctl status uart1-radio-mux` — the mux must run each boot. |
| Verify the raw link, as root | Route the mux, open `/dev/ttyS1` @115200, send an `APP_START` frame (`3c 0e 00 01` + 7×`00` + name); a good radio replies with a `>`‑framed `05` (SELF_INFO). |
### Updating MeshCore
`build-firmware.sh` pins a tested commit on MeshCore's `dev` branch (that's where work lands
first). To track upstream, run it with `MESHCORE_COMMIT=dev`; if the patch no longer applies
cleanly, re‑apply the two edits in [`meshcore-uart1.patch`](meshcore-uart1.patch) by hand —
they're two hunks.
**This patch is upstream in review.** If it merges, drop the `git apply` line from
`build-firmware.sh` and delete the patch: `Xiao_nrf52_companion_radio_serial` becomes a stock
env and there is nothing left to carry.
---
## Optional: reach the radio from other machines (TCP)
The direct‑serial path above is for MeshTerm **on the PicoCalc itself**. If you also want the
radio on your LAN (`meshterm --tcp <lyra-ip>:5000` from a laptop), add a UART↔TCP pump in
front of `/dev/ttyS1`. That's a separate, optional piece and is not required for on‑device use.
> **The Lyra does not use Raspberry Pi Pico GPIO numbering** — the header is Pico-shaped, the
> mapping is Luckfox's own. GP4 is `gpio0-0`, GP5 is `gpio0-1`. All signals are 3.3 V and
> there is **no 5 V rail**: power the XIAO from 3V3 only.