Files
MeshTerm/scripts/xiao-radio
Jean-Pierre Martineau 3a02a14be7 XIAO radio: build upstream's serial env, not our own Serial1 patch
MeshCore has carried companion-over-hardware-UART for a long time — the defines
SERIAL_RX/SERIAL_TX, packaged per board as a *_companion_radio_serial env, and the
ESP32-S3 twin of this very board already uses the same D6/D7 pads. Our patch was
reimplementing it for the one platform it had never been wired into: at our old pin the
SERIAL_RX branches lived inside the ESP32 and RP2040 blocks and nRF52 fell through to
Serial. So the patch is now the two things actually missing, both upstream-shaped and
submitted: a Serial1 reference so the shared block compiles on nRF52, and the
Xiao_nrf52_companion_radio_serial env carrying the I2C escape in build_unflags rather
than editing the flags every XIAO env inherits.

Pin moves to a dev commit, since dev is the branch MeshCore takes work on.

flash.py grew the check that was missing when it mattered: a drive letter is not an
identity — when one board leaves the USB bus another inherits its letter — so it now
reads INFO_UF2.TXT and refuses a bootloader that isn't a XIAO, or that carries S140
6.1.1 and would take this S140-v7 image at the wrong address and never boot. It also
stops pretending copy-to-drive is the only route: our bootloader exposes a serial port
and no mass storage at all, so it prints the serial-DFU command instead of a dead end.

Verified from a clean clone at the new pin: env builds, uf2 converts to the same 811008
bytes at 0x27000 that is now running on the radio, and both Xiao_nrf52_companion_radio_usb
and Xiao_S3_WIO_companion_radio_serial still build, so neither side of the new #if moved.
2026-08-13 00:58:54 -04:00
..

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.

 MeshTerm ──serial──> /dev/ttyS1 ──UART1 (GP4/GP5)──> XIAO Serial1 (D6/D7) ──> SX1262 ──))) mesh
 (on the Lyra)         115200 8N1      matrix‑IO mux        companion fw

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).

cd scripts/xiao-radio
sh build-firmware.sh

This clones MeshCore, applies meshcore-uart1.patch, builds the Xiao_nrf52_companion_radio_serial environment, and writes meshcore-xiao-radio.uf2.

The patch makes two changes that are both required (see Why):

  • 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).

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:

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:

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

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).


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 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 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.