diff --git a/README.md b/README.md index 0c9c1a7..d298f6b 100644 --- a/README.md +++ b/README.md @@ -182,8 +182,9 @@ meshterm --mock --platform picocalc meshterm specimen ``` -Handheld bring-up (fonts, palette, boot services) lives in -`scripts/calculinux-setup.sh` + `scripts/calculinux-console-font.sh`. +Putting MeshTerm on that handheld — the console font, the boot services, a soldered radio for +it, and the bridge that fronts a uConsole's SPI LoRa chip as a companion — is +[`scripts/`](scripts/), and **[`docs/hardware.md`](docs/hardware.md) is its manual**. ## Features @@ -479,7 +480,7 @@ format. MeshTerm ships **Cascadia Mono PL**, © 2019–present Microsoft Corporation, redistributed unmodified under the [SIL Open Font License 1.1](meshterm/assets/fonts/CascadiaMono-OFL.txt). It's offered to Windows users whose console can't draw the charts — see -[A word about fonts](#a-word-about-fonts). Microsoft doesn't endorse MeshTerm; the font is +[A word about terminals, on Windows](#a-word-about-terminals-on-windows). Microsoft doesn't endorse MeshTerm; the font is simply the right tool, being one of the very few monospace faces that carries the braille block the timelines are drawn from. @@ -497,6 +498,8 @@ respective project for the authoritative terms): | [Typer](https://typer.tiangolo.com/) | Scripted CLI (subcommands mirror the menu) | MIT | | [Rich](https://github.com/Textualize/rich) | Console rendering | MIT | | [prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) | Full-screen interactive TUI | BSD-3-Clause | +| [markdown-it-py](https://github.com/executablebooks/markdown-it-py) | CommonMark parser behind the written About pages | MIT | +| [PyYAML](https://pyyaml.org/) | The preferences file | MIT | | [Segno](https://github.com/heuer/segno) | Pure-Python QR codes (channel share links) | BSD-3-Clause | | [tomli](https://github.com/hukkin/tomli) / [tomli-w](https://github.com/hukkin/tomli-w) | TOML config read/write | MIT | diff --git a/docs/hardware.md b/docs/hardware.md new file mode 100644 index 0000000..0fc5428 --- /dev/null +++ b/docs/hardware.md @@ -0,0 +1,612 @@ +# MeshTerm on hardware + +MeshTerm talks to a **node** — a MeshCore radio that speaks the companion protocol over +serial, Bluetooth LE or TCP. Plug a companion board into USB and none of this document +applies: MeshTerm finds it, and the [command line manual](cli.md) is all you need. + +This is the manual for the hardware that *doesn't* present a node that way, and for the +handheld whose console can't draw the interface until you build it a font. Everything under +[`scripts/`](../scripts/) is here: what each script does, what it assumes about the machine +it runs on, why it does it the way it does, and what has only ever been proven on one bench. + +The scripts are small, POSIX `sh` or stdlib Python, and meant to be read before they are +run. They are also *device-side* — they change the machine they run on, most of them as +root — so read the section for your target first and run the script second. + +- [Three targets, and which one is yours](#three-targets-and-which-one-is-yours) +- [The regular and picocalc platforms](#the-regular-and-picocalc-platforms) +- [Calculinux bring-up](#calculinux-bring-up) + - [Before you run it](#before-you-run-it) + - [What the nine phases do](#what-the-nine-phases-do) + - [The console font on its own](#the-console-font-on-its-own) + - [Joining a network by hand](#joining-a-network-by-hand) + - [Re-running, and undoing](#re-running-and-undoing) +- [A real radio for the PicoCalc: XIAO nRF52840 over UART](#a-real-radio-for-the-picocalc-xiao-nrf52840-over-uart) + - [Parts and wiring](#parts-and-wiring) + - [Build the firmware](#build-the-firmware) + - [Flash the XIAO](#flash-the-xiao) + - [Set up the Lyra](#set-up-the-lyra) + - [Run it, and check the link](#run-it-and-check-the-link) + - [Troubleshooting](#troubleshooting) +- [The SPI radio bridge](#the-spi-radio-bridge) + - [Before you start: the runtime rename](#before-you-start-the-runtime-rename) + - [Setting it up](#setting-it-up) + - [Identity, and one program at a time](#identity-and-one-program-at-a-time) + - [Hardware knobs](#hardware-knobs) + - [What works through the bridge](#what-works-through-the-bridge) +- [The unfinished UART-to-TCP pump](#the-unfinished-uart-to-tcp-pump) +- [What is verified and what is not](#what-is-verified-and-what-is-not) + +--- + +## Three targets, and which one is yours + +There are three independent jobs in `scripts/`, and they belong to different machines. + +| I have… | Read | +| --- | --- | +| a ClockworkPi **PicoCalc** with a Luckfox Lyra running Calculinux, and I want MeshTerm on its own screen | [Calculinux bring-up](#calculinux-bring-up) | +| …and I want a **radio** in it | [XIAO nRF52840 over UART](#a-real-radio-for-the-picocalc-xiao-nrf52840-over-uart) | +| a **uConsole** with the hackergadgets AIO, or a Pi with a Waveshare LoRa HAT — an SX1262 on the host's own SPI bus | [The SPI radio bridge](#the-spi-radio-bridge) | +| a MeshCore companion on USB, BLE or WiFi | nothing here — the [main README](../README.md) | + +The PicoCalc target and the SPI target have nothing in common but MeshTerm itself. The +console font applies only to the PicoCalc's framebuffer console; the SPI bridge runs a mesh +node in software on a Debian host and never touches a console font. Do not run one target's +scripts on the other's machine. + +Within the PicoCalc target the two radio routes are mutually exclusive, and the reason is +the kernel's, not MeshTerm's: **only one program may hold `/dev/ttyS1`.** Either MeshTerm +opens the UART directly, which is what [`lyra-setup.sh`](../scripts/xiao-radio/lyra-setup.sh) +configures and what you want on the device itself, or a pump holds the UART and fronts it on +TCP for other machines — never both at once. + +--- + +## The regular and picocalc platforms + +MeshTerm resolves one frozen platform spec at boot and draws everything through it. The +**regular** platform is a desktop or ssh terminal: 72 readable columns, truecolour, emoji, +a footer hint line. The **picocalc** platform is the PicoCalc's framebuffer console, and +every number in it comes from the panel: 53 columns, 26 rows on the 6×12 console font (40 +on the 6×8 candidate), no panel border, no emoji anywhere, an F-key lane instead of a hint +line, and sixteen colour slots rather than a colour space — the RGB565 panel is not the +limit, the Linux VT layer is. Nothing loses its colour for being on the console; the node +hue and the recency heat gradient **quantise** to those slots rather than switching rules. +The platform is detected when `/proc/device-tree/model` reads exactly `Luckfox Lyra`, and +`--platform picocalc` or `MESHTERM_PLATFORM=picocalc` forces it anywhere — which is how you +preview the handheld layout on a desktop, alongside `meshterm specimen` for the whole +visual language on one card. + +The console font is the part that needs building, and it is built **on the device** by +[`calculinux-console-font.sh`](../scripts/calculinux-console-font.sh) rather than shipped as +a binary. Its only inputs are the stock Terminus console font the Calculinux image already +carries and `python3`; every added glyph is generated geometry in the script itself. So +nothing binary lives in the repo, and the base font is whatever your image installed rather +than whatever a maintainer's was. What it adds is what the bare console cannot draw and +MeshTerm cannot do without: the 256 braille cells every chart and map is made of, eighteen +marks (`●` `◉` `★` `✓` `✗` `▶` `❯` `▸` `⚠` `⌫` `⚙` `↻` among them), and rounded frame +corners aliased onto the square ones. + +The budget is the interesting constraint. The framebuffer console caps a font at **512 +glyphs**, and braille alone is 256 of them on top of the base font's 256 — so the budget is +full before a single mark is drawn. Each mark is therefore drawn *into a donor slot*: a +pictograph MeshTerm never emits, whose Unicode entry is repointed at the new bitmap. PSF +Unicode tables alias several codepoints onto one glyph, so a careless donation takes a +bystander with it — donating `π` once erased a Cyrillic letter that shared its slot. The +script aborts if a donor is missing, and after the build it verifies a list of keepers with +`π` and `пе` as canaries. A repo test parses the script's own mark, alias and donor tables +and pins them to `meshterm/ui/fontset.py`, the device-verified inventory of the installed +font: the script and the inventory move in the same commit or the test fails. + +> **Licensing.** The installed 6×12 font is a **derivative of Terminus**, which is under the +> SIL Open Font Licence 1.1 with "Terminus" as a Reserved Font Name — so the output is named +> `meshterm`, which is exactly what the OFL requires of a renamed derivative, and it must not +> be called Terminus. Nothing Terminus itself is in this repo. The optional 6×8 candidate is +> different: its base bitmap is the Linux kernel's `font_6x8`, which is **GPL-2.0**, embedded +> base64 in the script. That sits awkwardly beside an Apache-2.0 repo and a decision on it is +> pending; the 6×12 Terminus-derived font is the installed default, and the 6×8 build is an +> A/B candidate you flip to by hand. + +--- + +## Calculinux bring-up + +[`calculinux-setup.sh`](../scripts/calculinux-setup.sh) turns a freshly flashed Calculinux +SD card into a machine that runs MeshTerm as a dedicated user, with Wi-Fi that survives a +cold boot, a clock that is correct, and a console font. It runs **on the Lyra, as root**, +and the serial console is a fine place to run it from. It is idempotent: every phase checks +before it acts. + +```bash +# on the Lyra, as root, with scripts/ copied over +sh calculinux-setup.sh +passwd meshterm # the script deliberately sets no password +``` + +Then log in as that user and look at it: + +```bash +meshterm --mock # the interface, with a simulated radio +meshterm specimen # the visual language on one card +``` + +### Before you run it + +The script assumes Calculinux as shipped — Yocto, systemd, a read-only root with writable +overlays, `opkg` reachable over the network — and that `sh`, `su`, `useradd` or busybox +`adduser`, `systemctl`, `timedatectl`, `sed`, `grep`, `ssh-keyscan`, `git` and `kbd` are +present. It installs `git` and `kbd` anyway rather than trusting the base image. + +One thing it cannot embed, and one choice it makes by looking: + +- **Wi-Fi credentials.** The boot-time kick only nudges a network `iwd` already knows. + Either export `WIFI_SSID` and `WIFI_PSK` before running, and the script writes iwd's PSK + file (mode 600, secrets staying in your environment and never in the repo), or join once + by hand with [`calculinux-wifi-set.sh`](#joining-a-network-by-hand). +- **How the clone gets in.** MeshTerm is a public repository, so this needs no credential at + all: with no key file at `$KEY_PATH` the phase clones `$REPO_URL` over public HTTPS and + says so. Put a read-only GitHub deploy key there (mode 600) and it clones `$REPO_SSH` over + SSH instead — pinning github.com's host key with `ssh-keyscan` first so the clone never + blocks on a prompt, and baking the key into the checkout's `core.sshCommand` so later + pulls need no environment. Either way an existing checkout at + `/home/$DEPLOY_USER/MeshTerm` is pulled `--ff-only` rather than replaced. + +| Knob | Default | Effect | +| --- | --- | --- | +| `DEPLOY_USER` | `meshterm` | the login MeshTerm runs under; its home holds the checkout | +| `TIMEZONE` | `America/Toronto` | any IANA zone; see phase 4 for what happens without tzdata | +| `REPO_URL` | the project's HTTPS URL | cloned when there is no deploy key | +| `REPO_SSH` | the project's SSH URL | cloned when there is one | +| `KEY_PATH` | `/home/$DEPLOY_USER/.ssh/id_ed25519` | the read-only deploy key, if you want the SSH route | +| `WIFI_SSID`, `WIFI_PSK` | empty | set **both** to have iwd's credentials written for you | + +### What the nine phases do + +Each phase exists because of something that went wrong on the real device, and the *why* is +the part worth reading. + +| Phase | What it does, and why | +| --- | --- | +| **1. opkg packages** | Installs `python3-modules`, `python3-pip`, `git`, `kbd`. Calculinux ships a stripped Python 3.13 — no `pip`, no `venv`, no `ensurepip`, and missing `sqlite3`, `ctypes`, `curses` and more — so MeshTerm cannot even import until `python3-modules` restores the interpreter. `/usr` is a writable overlay, so the install persists. | +| **2. Wi-Fi kick** | Writes `/etc/wifi-kick.sh` and a oneshot `wifi-kick.service`. On cold boot the USB RTL8188EU's firmware finishes loading *after* iwd's first scans, so iwd's own scans come back empty and `wlan0` sits UP/NO-CARRIER forever. The kick waits for the interface, then runs **raw `iw dev wlan0 scan`** in rounds until a lease appears. Raw `iw` and not `iwctl scan`: a completed raw scan fills the mac80211 scan results and iwd then associates by itself, whereas `iwctl scan` makes iwd hold the device and the raw scan fails busy. | +| **3. Clock sync** | Writes `/etc/time-sync.sh` and a oneshot ordered after the kick. This board has no battery-backed RTC, so every cold boot starts at the kernel's build epoch — fatal for "heard" ordering and message timestamps. It waits for a real route, then tries `chronyd`, busybox `ntpd`, `sntp`, and finally an HTTPS `Date:` header, and writes the hardware clock best-effort. It always exits 0. | +| **4. Timezone** | Sets `$TIMEZONE` — `America/Toronto` unless you say otherwise — through `timedatectl` once tzdata is installed, and falls back to a POSIX `TZ` rule in `/etc/environment` and the deploy user's `~/.profile` when it is not, because glibc honours a POSIX rule with no zoneinfo database at all and the opkg feed index has been seen to 404. The fallback rule is only known for the default zone; another zone on a device with no tzdata is set through `timedatectl` alone, with a warning. | +| **5. Deploy user** | Creates `$DEPLOY_USER` and puts it in `wheel` for sudo and in `input`, `dialout` and `video`. `input` is not optional: the picocalc platform watches modifier keys directly, and `dialout` is what lets MeshTerm open the radio. Group changes need a fresh login. | +| **6. Clone** | The checkout at `/home/$DEPLOY_USER/MeshTerm`, pulled `--ff-only` if it is already there. See [Before you run it](#before-you-run-it). | +| **7. venv and install** | `python3 -m venv ~/MeshTerm/.venv`, then `pip install -e .` with **`TMPDIR=$HOME/tmp`** — `/tmp` is a small RAM tmpfs and pip's C builds hit ENOSPC in it. | +| **8. Login PATH** | Appends the venv's `bin` to the deploy user's `~/.profile` once, so `meshterm` is just a word. | +| **9. Console font** | Hands off to `calculinux-console-font.sh` if it sits alongside, and otherwise tells you to run it yourself. | + +> **A Lyra with no Wi-Fi dongle attached takes about six minutes to boot past the kick**, +> which waits a minute for the interface and then burns thirty rounds before exiting 0 — and +> the clock sync is ordered after it. Nothing is broken; it is a oneshot giving a slow radio +> every chance. Disable `wifi-kick.service` if the device is permanently wired or offline. + +### The console font on its own + +The font script stands alone, which is what you want after a MeshTerm update that adds a +glyph: + +```bash +sh calculinux-console-font.sh +``` + +It builds both fonts, applies the 6×12 one live with `setfont` on `/dev/tty1`, and persists +it as `FONT=meshterm` in `/etc/vconsole.conf` so systemd loads it at boot. If `setfont` +fails it aborts *before* persisting, so you are never left with a font that only exists in +`vconsole.conf`. It prints the A/B commands as it finishes — `setfont +/usr/share/consolefonts/meshterm8.psf.gz` for 53×40, the same with `meshterm.psf.gz` for +53×26 — and whichever you prefer goes in `vconsole.conf` by hand. + +The same script owns the sixteen colour slots. A **default run restores the stock kernel VT +palette** and removes any previous remap: it disables and deletes the `meshterm-vtrgb` +boot unit, `/etc/vtrgb` and the applier, programmes the stock table with `setvtrgb`, and +then writes the sixteen `OSC P` sequences to the tty as well. Both, and not just the +escape-sequence reset, because a previous `setvtrgb` overwrote the kernel's *default* +colormap — so a reset alone would faithfully restore the custom colours you were trying to +get rid of. `MESHTERM_CUSTOM_PALETTE=1` installs the archived custom remap instead, as +`/etc/vtrgb` plus a oneshot that re-applies it after `systemd-vconsole-setup`; a repo test +pins that remap to the palette table in `meshterm/ui/theme.py`. There is no uninstall of +the fonts themselves — delete the two `.psf.gz` files and the `FONT=` line. + +### Joining a network by hand + +[`calculinux-wifi-set.sh`](../scripts/calculinux-wifi-set.sh) is how a network *becomes* +known, which is the half the boot kick cannot do. It lists known networks and a fresh scan, +prompts for an SSID and a passphrase with the echo off, writes iwd's PSK file for it, and +connects now. It re-execs itself under `sudo` if you are not root. + +```bash +sh calculinux-wifi-set.sh +``` + +It uses `iwctl` where the boot kick deliberately uses raw `iw`, and that is not a +contradiction: the kick's problem is a cold-boot firmware race with iwd's scanner, and this +is an interactive join on a machine that is already up. + +### Re-running, and undoing + +Re-running is safe and is the normal way to update: the packages, the user, the checkout, +the venv and the PATH line are all checked first, the two helper scripts and their units are +rewritten with identical content, `pip install -e .` runs again cheaply, and the fonts are +rebuilt. Two things to know. Re-running under a **different `DEPLOY_USER` creates a second +user and a second checkout** rather than moving anything, so a device provisioned under one +name must keep being given that name. And there is **no uninstall** of any of it: to undo, +disable `wifi-kick.service` and `time-sync.service`, delete the two helper scripts, drop the +`FONT=` line from `/etc/vconsole.conf`, and remove the user. + +--- + +## A real radio for the PicoCalc: XIAO nRF52840 over UART + +The PicoCalc has no radio and no USB host to hang a companion off, so the radio is soldered +to the header: a Seeed XIAO nRF52840 with a Wio-SX1262, running MeshCore's companion +firmware on its own second serial port, wired to the Lyra's UART1. MeshTerm then opens +`/dev/ttyS1` like any other serial companion — no bridge process, no BLE, no SD slot +sacrificed. + +``` +MeshTerm ──serial──> /dev/ttyS1 ──UART1 (GP4/GP5)──> XIAO Serial1 (D6/D7) ──> SX1262 ──))) mesh +(on the Lyra) 115200 8N1 matrix-IO mux companion firmware +``` + +Three steps on two machines: **build** the firmware and **flash** the XIAO from your dev +box, then **set up the Lyra** as root. + +### Parts and wiring + +- A **Seeed XIAO nRF52840**, plain or Sense, stacked with the **Wio-SX1262** LoRa module. + The SX1262 uses XIAO pins D1–D5 and D8–D10 and is already wired inside the kit. +- A **Luckfox Lyra** in Pico form factor (RK3506, SD boot) running Calculinux in a + ClockworkPi PicoCalc. +- 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 | + +> **The Lyra does not use Raspberry Pi Pico GPIO numbering.** The 40-pin header is +> physically Pico-compatible and each pad's function is Luckfox's own RK3506 mapping: GP4 is +> `gpio0-0` and GP5 is `gpio0-1`. Don't read a Pico pinout for anything else here. Every +> signal is 3.3 V, so no level shifter, and there is **no 5 V rail** on this board — power +> the XIAO from 3V3 only. + +### Build the firmware + +On your dev machine, with `git` and PlatformIO (`pip install platformio`): + +```bash +cd scripts/xiao-radio +sh build-firmware.sh +``` + +It clones MeshCore into `./_meshcore-build` (override with `MESHCORE_DIR`), checks out the +pinned commit **`e9edfc8e`** on the `dev` branch (override with `MESHCORE_COMMIT`), applies +[`meshcore-uart1.patch`](../scripts/xiao-radio/meshcore-uart1.patch), builds the +`Xiao_nrf52_companion_radio_serial` environment, and converts the result into +`meshcore-xiao-radio.uf2` beside the script. The `.uf2` is a build product and is not +committed. + +The patch is two hunks, and both are required: + +- **Teach the existing companion-over-UART path to build on nRF52.** MeshCore has had the + `SERIAL_RX`/`SERIAL_TX` companion interface and per-board `*_companion_radio_serial` + environments for a while — the ESP32-S3 twin of this board uses the *same* D6/D7 pads — + but the shared code declares `HardwareSerial companion_serial(1)`, and on the Adafruit + nRF52 core `HardwareSerial` is abstract with no numbered constructor. `Serial1` is the + concrete `Uart` that core always defines and `Uart::setPins(rx, tx)` takes the same + arguments in the same order, so one reference fixes the build and the call site is + untouched. +- **Move I²C off D6/D7.** The base `Xiao_nrf52` environment maps the I²C bus onto exactly + those two pads, and both `XiaoNrf52Board::begin()` and `sensors.begin()` start `Wire` on + them — so the I²C peripheral seizes the UART pins and the link stays dead with perfect + wiring and a correct build. The new environment moves I²C to the internal IMU pins 16 and + 17. This was the single reason the link stayed silent through every other fix. + +Both changes are upstream-shaped and have been submitted to MeshCore. **They are not merged +yet**: as of 2026-09-12, upstream `dev` still carries the bare `HardwareSerial` declaration +with no nRF52 branch, and `variants/xiao_nrf52/platformio.ini` still has no +`companion_radio_serial` environment. So the patch step stays for now, and when it lands the +patch and the `git apply` line can both be deleted. To track upstream instead of the pin, +run with `MESHCORE_COMMIT=dev`; if the patch no longer applies, its two hunks are small +enough to re-apply by hand. Only the pinned commit is known to build. + +### Flash the XIAO + +Plug the **XIAO's own USB-C** into your computer — it can stay wired to the Lyra — and: + +```bash +python flash.py +``` + +It pulses the application port at 1200 baud, the Arduino-style touch that drops the board +into its bootloader, then looks for a UF2 drive and copies the firmware onto it. It only +ever touches Seeed's USB vendor id, never Adafruit's, so another nRF52840 board on the same +bench is left alone. If the touch doesn't take, **double-tap the XIAO's reset button** and +run it again. + +Two things it refuses to guess. A drive letter is not an identity — when one board leaves +the USB bus another can inherit its letter — so it reads `INFO_UF2.TXT` and declines a +volume whose model is not a XIAO, and declines **SoftDevice S140 6.1.1**, which wants the +application at `0x26000` while this firmware links for S140 v7 at `0x27000` (it would flash +and then not boot). `--force` overrides both, if you know better than it does. + +**If no UF2 drive appears at all, that is not necessarily a fault.** On the bench where this +was developed the bootloader came up as a serial port with no mass-storage interface +whatsoever, so there was nothing to copy a file onto. `flash.py` recognises the bootloader's +serial port — on the plain XIAO and on the Sense — 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 +``` + +That is the route that worked: it ends in `Device programmed.` and the XIAO reboots itself +into the radio firmware. Afterwards the XIAO's USB serial port goes **silent to companion +frames** — the companion now lives on D6/D7, not on USB. That silence is correct. + +### Set up the Lyra + +Copy `scripts/` to the Lyra and, as root: + +```bash +sh scripts/xiao-radio/lyra-setup.sh # MT_USER=meshterm by default +``` + +It does three things. It installs [`uart1-mux.py`](../scripts/xiao-radio/uart1-mux.py) as +`/usr/local/bin/uart1-radio-mux.py` behind a oneshot `uart1-radio-mux.service` that runs on +every boot; it adds `$MT_USER` to `dialout` (a fresh login is needed before that counts); +and, **only if the file is absent**, it writes a MeshTerm profile: + +```toml +default_profile = "picocalc" +[profiles.picocalc] +port = "/dev/ttyS1" +baudrate = 115200 +transport = "serial" +default_tx_power = 22 +description = "XIAO nRF52840 + SX1262 via Lyra UART1 on GP4/GP5" +``` + +If a `config.toml` is already there it prints those lines for you to paste rather than +touching your configuration. Because `default_profile` is set, a bare `meshterm` connects +straight to the radio. + +The mux service is the interesting half. **Calculinux enables the UART1 controller but wires +it to no pad**, which is why `/dev/ttyS1` exists and yet nothing ever comes out of it. The +RK3506's matrix IO can carry UART1 on almost any pad, so `uart1-mux.py` makes three 32-bit +writes through a one-page `/dev/mem` mapping: two RMIO signal-select words that put UART1-TX +on `gpio0-0` and UART1-RX on `gpio0-1`, and one PMU IOC word that switches those two pins +into matrix mode. The writes are idempotent, which is why a oneshot at boot is enough, and +they need root and a kernel that permits `/dev/mem` writes to that range. Choosing those two +pads is what saves the front SD-card slot: UART1's *default* pads belong to SPI1, which +drives the slot, so the mux avoids them entirely. + +> The register addresses, the signal ids and the claim that `gpio0-0`/`gpio0-1` are header +> GP4/GP5 come from the maintainer's live probing of one board. They are **not verified +> against an RK3506 reference manual**, and neither is the assumption that this kernel allows +> those `/dev/mem` writes. See [What is verified and what is +> not](#what-is-verified-and-what-is-not). + +### Run it, and check the link + +```bash +meshterm +``` + +Your node should come up with whatever name the firmware adverts — the device page and the +dashboard header both show it. If you want to prove the wire itself before blaming anything +else, route the mux, open `/dev/ttyS1` at 115200 as root and send an `APP_START` frame +(`3c 0e 00 01`, seven zero bytes, then a name); a live radio answers with a framed `05`, +`SELF_INFO`. The frame's command byte and reply code are the companion protocol's; the +`<`/`>` plus little-endian length framing around them is from the firmware and is worth +confirming against it rather than taking from here. + +### Troubleshooting + +| Symptom | Check | +| --- | --- | +| `meshterm` can't open the port | Is `MT_USER` in `dialout`? (`groups`) — it needs a fresh login after setup. | +| Port opens but nothing is there | Re-flash with the **`_serial`** environment, not `_ble` or `_usb`; only that one defines `SERIAL_RX`/`SERIAL_TX`. The XIAO's USB serial should be *silent* to companion frames. | +| Still silent, wiring confirmed | Confirm the firmware carries the **I²C remap** (`PIN_WIRE_SCL=16`, `PIN_WIRE_SDA=17`). This is the failure that looks like bad wiring and isn't. | +| Flashed fine, board never comes back | Wrong board, or the wrong SoftDevice — `INFO_UF2.TXT` must say a XIAO and **S140 v7**, not 6.1.1. `flash.py` refuses both without `--force`. | +| `flash.py` finds no UF2 drive | Expected on a CDC-only bootloader. Use the `pio … -t upload --upload-port` line it prints. | +| Nothing on `/dev/ttyS1` after a reboot | `systemctl status uart1-radio-mux` first, then `journalctl -b -u uart1-radio-mux` — the poke must run every boot, and a oneshot that failed says why. | +| MeshTerm says the radio is unplugged | Use a MeshTerm build with the soldered-UART liveness fix: pyserial's port enumeration doesn't list platform-bus ports like `/dev/ttyS1`, so liveness stats the device node instead. It is in this repo. | + +--- + +## The SPI radio bridge + +On some boards the LoRa chip hangs straight off 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**, so there is no node for MeshTerm to +talk to: the mesh node itself has to run in software on the host, through the `pymc_core` +library (which on the uConsole arrives with the `meshcore-uconsole` package, alongside its +own `meshcore-console` GUI). + +[`scripts/meshterm-spi-bridge`](../scripts/meshterm-spi-bridge) fills that gap. It runs the +software node and puts the **standard companion protocol in front of it on a local TCP +port**, so + +```bash +meshterm --tcp 127.0.0.1:5000 +``` + +connects exactly as if a companion were plugged in. One file is both halves: a setup menu +that runs under any Python 3, and the bridge process itself, which the menu re-execs under +whichever interpreter has the radio library. That split is deliberate — the library lives in +a packaged virtual environment, and you should never need to know that. + +It runs on the radio host as **your normal user, never root**: the node identity and the +service are per-user. + +### Before you start: the runtime rename + +> **On a current uConsole install this bridge does not start, and the fix is a port nobody +> has done yet.** It was written against **`pymc_core` 1.0.12** and every one of its +> interfaces was checked against that release. Since then the library was renamed: the +> `pyMC_core` project became `openhop_core`, PyPI's `pymc-core` stopped at 1.0.12 in May +> 2026, and the current `meshcore-uconsole` package depends on `openhop-core` instead. That +> virtual environment has no `pymc_core` module at all, and the helper module the bridge +> imports from now exports a differently named entry point. What you will see is the +> bridge's own preflight reporting the runtime as **not found**, and nothing running. +> +> That is the whole of what has been verified: the rename, the package dependency, and that +> the preflight therefore fails. Whether the bridge's three compatibility shims are still +> needed under the new library, and what else moved inside it, has **not** been checked. If +> you are on an older, pre-rename install — `pymc-core` 1.0.x — everything below applies as +> written. + +### Setting it up + +```bash +./meshterm-spi-bridge # the interactive setup menu +./meshterm-spi-bridge --check # run the prerequisite checks and exit +./meshterm-spi-bridge --run # run the bridge now, in this terminal +``` + +The preflight is worth running first. It finds the interpreter that has the radio library, +checks that a `/dev/spidev*` node and `/dev/gpiochip0` are readable and writable by you — +the uConsole needs `dtoverlay=spi1-1cs` in `/boot/firmware/config.txt` for the first, and +membership of the `spi` and `gpio` groups for both — and tells you if the GUI is holding the +radio or if something is already listening on the port. + +The menu then offers to **run the bridge in the foreground** (Ctrl+C returns to the menu), +to **install it as a service**, to **uninstall** it, or to show its status. Installing copies +the script to `~/.local/bin/` and writes a `systemd --user` unit that restarts on failure and +starts with your session; it also asks systemd to enable lingering for your user, which is +what makes the service come up at boot rather than at your first login, and prints the `sudo` +command if it cannot. Either way it offers to add a MeshTerm profile for you: + +```toml +[profiles.bridge] +host = "127.0.0.1" +tcp_port = 5000 +description = "Local SPI radio via meshterm-spi-bridge" +``` + +It sets no `default_profile`, so a bare `meshterm` offers the bridge in the picker rather +than connecting to it behind your back. Uninstalling removes the service and the copied +script and nothing else: it never touches the `meshcore-console` or radio-library packages, +and it deliberately leaves your identity and contact files, and the lingering setting, where +they are. + +### Identity, and one program at a time + +**Only one program may use the radio at a time.** Run *either* the `meshcore-console` GUI or +this bridge, never both — the preflight warns you when the GUI is up, and refuses to start a +second bridge over a running service. + +Which node you are depends on what is installed. Where the `meshcore-console` stack is +present the bridge loads that stack's identity key, so **MeshTerm is the same node as the +GUI** and your contacts and your public key follow you between them. On a library-only +install it mints its own key the first time and persists it under +`~/.local/share/meshterm-spi-bridge/`, so the node is stable across restarts. Contacts are +snapshotted to a file in that same directory on every change, because the library's contact +store is memory-only — without that, direct messages to a contact you added before a restart +came back "not found". + +### Hardware knobs + +The defaults match the hackergadgets uConsole AIO: SPI bus 1, chip-select 0, reset on 25, +busy on 24, IRQ on 26, 910.525 MHz, 22 dBm, SF7, 62.5 kHz, coding rate 4/5. For another SPI +board, export what differs before launching. + +| Variable | What it sets | +| --- | --- | +| `MESHCORE_BUS_ID`, `MESHCORE_CS_ID`, `MESHCORE_CS_PIN` | which SPI bus, device and chip-select pin the radio is on | +| `MESHCORE_RESET_PIN`, `MESHCORE_BUSY_PIN`, `MESHCORE_IRQ_PIN` | the three control lines | +| `MESHCORE_FREQUENCY`, `MESHCORE_TX_POWER` | frequency in Hz, power in dBm | +| `MESHCORE_SPREADING_FACTOR`, `MESHCORE_BANDWIDTH`, `MESHCORE_CODING_RATE` | the modem preset — all three must match the mesh you are joining | +| `MESHTERM_PYMC_PYTHON` | force a specific interpreter instead of letting the bridge discover one | + +Where the `meshcore-console` stack is installed, the bridge builds the radio through *its* +hardware configuration, which reads a longer list of variables — transmit/receive enable +pins, the GPIO chip, the Waveshare and DIO options, and the enable pins an AIO v2 needs to +power its radio at all. Those come from that package's documentation. On a library-only +install the table above is the whole of it, so an AIO v2 without that package present may +not power its radio. + +### What works through the bridge + +The bridge exposes the companion protocol as the radio library implements it, plus two +pushes of its own. In MeshTerm's terms: messaging, contacts, channels, adverts, device +configuration, traces and the live packet feed all work. Three things do not, because the +library has no handler for them — **reboot and factory reset have no effect, and a device +PIN cannot be set**. MeshTerm reports the device model as `pyMC-spi-bridge`, which is a +useful way to tell a bridged node from a real companion in the logs. + +Traces and the live feed reach MeshTerm through compatibility shims the bridge installs on +the library: it subscribes to raw packets to feed the live feed, reassembles a completed +trace reply and pushes it, and relaxes an acknowledgement length check that newer firmware +trips by appending bytes after the CRC. None of that is MeshTerm's protocol being bent — +the library simply never registered those two pushes — and upstream wiring would make the +shims redundant. Their **on-air behaviour was validated on one bench**, against the radios +that were in range of it. + +--- + +## The unfinished UART-to-TCP pump + +[`calculinux-radio-bridge.sh`](../scripts/calculinux-radio-bridge.sh) is a work in progress +and is not a supported route. It was written to put the UART-attached XIAO radio on a TCP +port so other machines could reach it, before the direct-serial path above existed, and it +is superseded by `lyra-setup.sh` for on-device use. As it stands its own header describes a +pin-routing phase that the body does not contain, on a theory of which pads carry UART1 that +`uart1-mux.py` later replaced; it binds to every interface by default, unauthenticated; and +it writes a competing default profile into the same `config.toml` that `lyra-setup.sh` +writes. Read it if you want the shape of a UART-to-TCP pump — a single-client pump is the +right shape, since companion frames from two clients would interleave — but don't run it +expecting a finished tool. + +--- + +## What is verified and what is not + +Most of what this manual explains is checked in code: the platform spec, the font and +palette contracts (a test parses the font script itself and pins it to MeshTerm's glyph +inventory), the profile keys the scripts write, the soldered-UART liveness fix, and every +interface the SPI bridge calls in `pymc_core` 1.0.12. The upstream firmware state is checked +too: the pinned MeshCore commit exists, the patch's two hunks are still needed on `dev` +today, and the nRF52840 UF2 family id and both XIAO bootloader ids match Adafruit's board +files. + +The rest is one maintainer's bench, reported honestly rather than dressed up. None of the +following is confirmable from code in this repository, and a second device may disagree: + +- **The RK3506 register map** in `uart1-mux.py` — the two register blocks, the UART1 signal + ids, matrix mode, and that `gpio0-0`/`gpio0-1` are header GP4 and GP5. Probed live on one + board, not read from a reference manual. +- **That the Calculinux kernel permits those `/dev/mem` writes**, and that the mux oneshot + really does run at every boot. +- **The PicoCalc header pin numbers** 6, 7, 8 and 36 for GP4, GP5, GND and 3V3 on the Lyra + carrier. The Pico-side numbering is right; the carrier's wiring is a bench observation. +- **The Calculinux specifics the scripts assert**: the stripped Python and the package names + that fix it, which overlays are writable, that `/tmp` is a small RAM tmpfs, the rtl8xxxu + cold-boot race with iwd, the opkg feed's occasional 404, the absolute `ip` and `iw` paths, + that the stock Terminus console font is installed, and that `kbd` brings `setvtrgb`. +- **That this board has no RTC.** Only the script says so, and everything about the clock + phase follows from it. +- **The XIAO bootloader that exposed no mass storage**, and the S140 v7 / `0x27000` + requirement — public references agree, but neither is a primary source. +- **Whether the firmware patch still applies at MeshCore `dev` HEAD.** It is unmerged; only + the pinned commit is known to build. +- **MeshCore's serial framing** around the raw `APP_START` check above. The command byte and + the `SELF_INFO` reply code are verified against the protocol documentation; the framing + bytes are not. +- **Everything on-air about the SPI bridge** — the per-hop trace semantics it reassembles and + the acknowledgement bytes "newer firmware" appends. The code is internally consistent with + the library's API; the wire behaviour was seen on one mesh. +- **Whether the renamed radio library still needs the bridge's three shims**, and where the + current package installs itself. +- **The framebuffer console's 512-glyph cap.** Well known, taken as given, not re-measured + here. + +If you have the hardware and any of it is wrong on your bench, that is worth an issue — the +scripts encode a set of discoveries, and a second device is the only way to learn which of +them were about the hardware and which were about one unit. diff --git a/scripts/README.md b/scripts/README.md index a82039b..4d46d3f 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -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 `) 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. diff --git a/scripts/xiao-radio/README.md b/scripts/xiao-radio/README.md index 5e2cc10..a5f2451 100644 --- a/scripts/xiao-radio/README.md +++ b/scripts/xiao-radio/README.md @@ -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 -``` - -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 :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.