MeshTerm/docs/picocalc.md

MeshTerm on the PicoCalc

You start with a stock ClockworkPi PicoCalc — the kit that ships with a Raspberry Pi Pico — and a short shopping list. You end with a Linux handheld: MeshTerm running full-screen on the PicoCalc's own display and keyboard, a LoRa radio soldered inside, and no laptop needed to use it day to day. There are three phases: build the machine (swap the Pico for a Linux board), install the OS and MeshTerm, and add the radio. Budget an afternoon for the first two phases, most of it spent waiting for a toolchain to download; the radio phase needs a soldering iron and can be done later — MeshTerm's --mock mode runs perfectly well without a radio in the meantime.

⚠ Read this first. This build takes the PicoCalc apart, swaps its core board, and solders to it. It assumes you can already solder cleanly, use a multimeter, and work with small electronics without forcing anything. There is a real risk of damaging the hardware if a step goes wrong — a cracked screen, a snapped shell post, a dead board, or an overcharged lithium cell — and some of that damage is not repairable. You do this at your own risk.

Read the whole manual through once before you buy anything or open anything. Several steps only make sense in light of a later one — where the SD card goes, what must be out of the case before a board is pressed in, which USB port is never to be powered — and the shopping list is easier to get right when you know what each part is for.

This is a guide, not a prescription. Despite the author's best efforts it may contain errors, and parts of it will go out of date as boards, images and firmware change. It is up to you to check every fact in it against your own hardware and the current sources before you act on it, and every decision along the way is yours. The author accepts no responsibility for any damage, loss or injury that results from following this guide, and nothing in it is a warranty that your parts, your tools or your hands will behave the way the author's did. If you are not comfortable with any step, stop and get help from someone who is.

• Shopping list
• Before you start
• Three ways to break it
• Phase 1 — Build the machine
  • Step 1 — Assemble the PicoCalc
  • Step 2 — Swap the Pico for the Lyra
  • Step 3 — Attach the Wi-Fi dongle
• Phase 2 — Install Calculinux and MeshTerm
  • Step 4 — Write the image to the microSD
  • Step 5 — First boot
  • Step 6 — Open the serial console
  • Step 7 — Join Wi-Fi
  • Step 8 — Copy the setup scripts to the device
  • Step 9 — Run calculinux-setup.sh
  • Step 10 — Log in as meshterm
• Phase 3 — Add the radio
  • Step 11 — Install PlatformIO
  • Step 12 — Build the firmware
  • Step 13 — Flash the XIAO
  • Step 14 — Wire the radio
  • Step 15 — Set up the Lyra
  • Step 16 — Run it
• Day-to-day
• Troubleshooting
• What has been tested

---

Shopping list

The machine

Item	Product / what to search for	Approx. price	Link	Note
PicoCalc kit	ClockworkPi PicoCalc	$89	clockworkpi.com/product-page/picocalc	Comes with a Raspberry Pi Pico 1H, screen, keyboard, shell, hex key and a 32 GB SD card. 18650 batteries are not included.
Luckfox Lyra	"Luckfox Lyra 128MB, pre-soldered header, no NAND"	$20–25	luckfox.com/Luckfox-Lyra	Buy the plain 128 MB RAM, Pico-form-factor variant, with the header pre-soldered. See the note below — this is the one part of the list where the wrong SKU won't work.
microSD card	16 GB+, Class 10 or better	$6–10	—	The PicoCalc's stock 32 GB card works fine — it's more than the 8 GB minimum. You can reuse it instead of buying a new one.
Two 18650 batteries	e.g. Samsung 30Q, Molicel P26A, Sony VTC6 (examples, not endorsements)	$10–20	—	Unprotected, flat-top or button-top, Ø18 × 65–69 mm. See the battery note below.
USB Wi-Fi dongle	TP-Link TL-WN725N (an RTL8188EU nano dongle), or search the chipset name: RTL8192CU, R8712U, RTL8188EU	$5–10	amazon.ca/dp/B008IFXQFU	The TL-WN725N is the dongle this guide was built with. Must run at 3.3 V — see Step 3. Only needed for setup and updates; MeshTerm itself runs offline.
MX1.25 4-pin pigtail	"MX1.25 4P cable with leads" (a pack of pre-crimped pigtails, 10–15 cm)	$2–4	—	One end of the DIY USB lead in Step 3. Pre-crimped, because MX1.25 contacts need a crimper you don't otherwise own.
USB-A female socket	"USB 2.0 type A female socket, solder / through-hole"	$2–3	—	The other end of the DIY lead. A ready-made MX1.25 4P to USB-A cable (about $1, 30 cm) works too, but it is a lot of cable to fold into the shell.

The radio

Item	Product / what to search for	Approx. price	Link	Note
XIAO nRF52840 + Wio-SX1262 kit	"XIAO nRF52840 & Wio-SX1262 Kit for Meshtastic", SKU 102010710	$13.49	seeedstudio.com	Includes the XIAO nRF52840, the Wio-SX1262 LoRa board (stacked and wired together) and an antenna. Covers both 868 and 915 MHz. Plain or Sense XIAO both work. Do not buy the "-N" variant — it has no antenna connector.

Tools and consumables

Item	Note
Soldering iron, fine tip, and solder	For the four radio wires.
Hookup wire, 26–30 AWG, four short lengths	TX and RX get crossed — see Step 14.
2.5 mm hex key	Comes with the PicoCalc kit.
USB-C data cable	For the serial console, and later for flashing the XIAO. A charge-only cable won't do; it has to carry data.
microSD card reader	For writing the Calculinux image from your PC.
Small side cutters	For trimming wire ends, and a section of the case grille if the Wi-Fi lead needs the room.
Small needle file	To open the back panel's USB-C cutout a little if the Lyra's connector doesn't clear it.
Kapton (polyimide) tape	Wraps the XIAO stack and the DIY USB lead so nothing bare touches the board or the shell. Heat-proof, thin, and it peels off cleanly.
A PC (Windows/macOS/Linux) with Python 3 and git	Runs the image-writing, firmware-build and flashing steps.

Optional

Item	Why
A second 18650 battery	The holder takes two; one is enough to run, two roughly double your runtime.
Powered USB hub	If you want the Wi-Fi dongle and something else on the Lyra's single USB host socket at once, or a 5 V dongle.
Foam tape	To secure the XIAO board inside the shell once it's wired in.

Approximate total: $130–150 for the machine and radio together, before batteries — most of that is the two boards ($89 + ~$22) and the radio kit ($13.49).

What you do NOT need:

• A level shifter. Every signal in this build — the Lyra's header, the XIAO, the SX1262 — is 3.3 V.
• A separate USB-to-serial adapter. The PicoCalc mainboard already has one built in.
• Bluetooth anything. Neither the Lyra nor this radio path uses it.
• A new SD card, if your stock 32 GB card is handy — it's well over the 8 GB minimum Calculinux asks for.

A note on batteries

ClockworkPi has not published an official battery spec for the PicoCalc — a still-open GitHub issue asking for one has gone unanswered. What's known from the kit itself: the holder takes two 18650 cells, one cell is enough to power the board, and the physical envelope is about Ø18 mm × 65–69 mm, which rules out most protected cells — the protection circuit adds length that doesn't fit. Unprotected flat-top or button-top cells both work; the PicoCalc mainboard has its own charge circuit built in. Buy from a reputable brand rather than a cheap unbranded listing — Samsung 30Q, Molicel P26A and Sony VTC6 are commonly recommended examples, not an endorsement of any one of them.

---

Before you start

Work happens on two machines, and it helps to keep straight which is which:

• Your PC writes the Calculinux image to the microSD card, builds the radio firmware, and flashes the XIAO. Nothing in these three jobs touches the PicoCalc itself.
• The PicoCalc (really, the Luckfox Lyra inside it) does everything else — setup, Wi-Fi, running MeshTerm — either over the serial console from your PC or on its own screen and keyboard. Both work identically; the serial console is just easier for pasting long commands.

The device has two logins you'll use for different things: root, which you use once to run the setup script and fix Wi-Fi, and meshterm, the unprivileged account MeshTerm actually runs under day to day.

Calculinux is a console-only Linux — no desktop, no window manager. That's deliberate: the PicoCalc's screen and keyboard are a terminal, and MeshTerm is a full-screen terminal program built for exactly that.

---

Three ways to break it

The PicoCalc is a kit, and its forum has a well-worn list of the ways people have damaged theirs. Three of them apply directly to this build, and the first two are not theoretical: the author of this guide cracked a screen and snapped screw posts building the very machine it describes. Read this section before you open the shell.

⚠ The screen is extremely fragile. It is a bare glass panel with no frame of its own, and when the case is closed it sits directly against the mainboard. Anything that flexes the mainboard flexes the glass: pushing a board into the Pico socket, prying one out, closing the shell with the screen not sitting square in its opening, or pressing a key while the halves are being screwed together. Forum members have cracked screens doing each of those, and the swap in Step 2 is the classic one — pressing a new board into the socket with the mainboard still in the case is enough on its own. That is exactly how the screen in this guide's own PicoCalc broke. (Before replacing the Pico, Avoid breaking your screen)

What to do instead:

• Never push a board into the socket, or pull one out, with the mainboard in the case. Unplug the display's ribbon cable (the FPC) from the mainboard, lift the mainboard out, and do the swap on a flat, padded surface — a folded microfibre cloth is ideal. Ease a board out a little at each end in turn, never by levering one end.
• Secure the screen with Kapton tape along its edges so it cannot shift in the opening while you work and while the case is closed. Kapton is the right tape: thin, it stays put, and it peels off cleanly. Don't use anything that sets hard.
• Before the back goes on, check the screen sits flush and square in the front half's opening with no pressure on any corner. If the mainboard doesn't sit perfectly flush on the front half, stop and find out why before you add the back.
• Handle the panel as little as possible, and keep your fingers off the keyboard while closing the shell.

⚠ Don't overtighten the screws. The shell's screw posts are brass inserts moulded into plastic, and forcing a screw snaps the post out of the shell — a repair that needs epoxy and never quite comes back (Broken screw thread). This guide's author snapped several on the first assembly; it takes less force than you would think. Turn each screw until it just seats, then stop. If a screw won't go in easily, the halves aren't aligned, or something inside is in the way; more force is never the answer.

⚠ Never power the Lyra through its own USB-C while the batteries are in. The PicoCalc charges its cells only through the mainboard's USB-C port, under the control of its power-management chip (an AXP2101). Power fed in through the core board's USB port — the Pico's originally, the Lyra's now — arrives on the header's system-power pin and bypasses that charge control. Forum members who powered the Pico's port directly measured their cells at 4.46 V and 4.74 V afterwards, well over the 4.2 V a lithium cell is allowed to reach (New PicoCalc — battery charging). An overcharged cell is a fire risk, not just a worn one.

Nothing in this guide needs the Lyra's USB-C: the serial console, charging and power all use the mainboard's port on the side of the case, and the Wi-Fi dongle uses the 4-pin socket on top of the Lyra. If you ever must plug the Lyra's USB-C into a PC — to reflash it with Luckfox's tools, say — take both batteries out first.

---

Phase 1 — Build the machine

Step 1 — Assemble the PicoCalc

Follow ClockworkPi's own assembly guidelines (a PDF in the PicoCalc repository, which also has a wiki) to put the kit together: mainboard, screen, keyboard, speakers and shell. Insert your two 18650 batteries, watching the +/- marks in the battery compartment.

⚠ Two of the warnings in Three ways to break it apply here: tape the screen's edges with Kapton before you close the shell and check it sits square, and turn the screws only until they seat. You will open the shell again in the next step, so there is no reason to make the screws tight now.

Power it on once with the stock Pico still in place. You should see the stock BASIC firmware boot on the screen, and the keyboard should respond. This confirms the screen, keyboard and battery are all good before you start swapping boards.

Power it back off.

Step 2 — Swap the Pico for the Lyra

Remove the back of the shell with the hex key.

⚠ Do the swap with the mainboard out of the case. This is the step that cracks screens (see Three ways to break it). Unplug the display's ribbon cable from the mainboard, lift the mainboard out, and lay it on a padded surface. Only then ease the Raspberry Pi Pico out of its socket, a little at each end in turn — keep it, you're just setting it aside.

If your Luckfox Lyra has SPI NAND on board (a "Lyra B"), erase it first — the boot ROM otherwise ignores the SD card entirely and boots the on-board flash instead. See Calculinux's hardware requirements page for how.

Seat the Lyra into the same socket the Pico came out of, in the same orientation — its USB-C port at the end where the Pico's USB port was, so it lines up with the cutout in the back of the shell. Press it down fully with the mainboard still on the padded surface; a Lyra that isn't fully seated won't boot. Then reconnect the ribbon cable and set the mainboard back into the front half, checking the screen sits square before anything is screwed down.

You should see the Lyra sitting flat on the socket with no gap at either end, and, once the mainboard is back in, its USB-C port centred in the back-panel cutout.

The cutout was made for the Pico's micro-USB, and the Lyra's USB-C connector is a different shape. Depending on the connector Luckfox fitted to your board, the back panel may not close over it. If it catches, open the hole a little with a small needle file, testing the fit as you go, until the panel sits down without pressing on the board.

Leave the back off for now. The microSD card goes into the Lyra's own slot in Step 4, and that slot is easier to reach with the board exposed.

Step 3 — Attach the Wi-Fi dongle

The Lyra has two USB connectors. The USB-C on its edge is for power and flashing and is not used here. The tiny 4-pin socket on top of the board (an MX1.25 connector, next to the two buttons by the USB-C end) is the USB host. The Wi-Fi dongle hangs off it through a short lead you make yourself: a ready-made cable is 30 cm long and a struggle to fold into the shell, and you have the soldering iron out for the radio anyway.

Make the lead. Solder the four wires of an MX1.25 pigtail to a USB-A female socket, keeping the run short — 5 to 8 cm is enough to reach a spot where the dongle sits flat. The pigtail's pins are in the standard USB order, which the pre-made cable's wire colours follow:

MX1.25 pin	USB-A socket pin	Signal	Pigtail wire colour (usually)
1	1	VBUS (3.3 V on this board)	red
2	2	D−	white
3	3	D+	green
4	4	GND	black

USB-A socket pins are numbered 1 to 4 across the connector's opening: VBUS on one edge, GND on the other, the data pair between them. Colours on a pigtail are a convention, not a promise, so check pin 1 before you plug anything in: with the Lyra powered, the socket's pin 1 reads 3.3 V against a GND header pin and the pin at the other end reads 0 V. Swapping VBUS and GND is the one mistake that damages the dongle.

Once soldered, wrap the socket's solder side and the exposed wire in Kapton tape. Plug the MX1.25 end into the socket on the Lyra — it is keyed and only goes in one way — and the Wi-Fi dongle into the USB-A end. Lead and dongle stay inside the shell; tuck them where they don't press on the board.

The MX1.25 socket sits on top of the Lyra, and the lead leaves it upward, which is where the back panel's grille is. The wire may interfere with the grille when the back goes on. If it does, snip a small section out of the grille with the side cutters where the wire passes and shape the edge until nothing presses on the plug or the wire. Better to remove a sliver of plastic than to close the case against a connector.

The Lyra's USB port is 3.3 V, not 5 V. A standard 5 V USB Wi-Fi dongle will not work and may damage the board. Stick to the tested chipsets — RTL8192CU, R8712U, or RTL8188EU — which is why the shopping list names a known dongle (the TP-Link TL-WN725N) and otherwise tells you to search by chipset rather than by brand.

Don't power the device on yet — Wi-Fi is set up later, once Calculinux is installed.

---

Phase 2 — Install Calculinux and MeshTerm

Step 4 — Write the image to the microSD

On your PC, download the latest calculinux-image-luckfox-lyra.rootfs.wic.gz from the Calculinux releases page.

Decompress it:

# on the PC
gunzip calculinux-image-luckfox-lyra.rootfs.wic.gz

(The Calculinux installation page mentions unxz, but the file is a .gz, so use gunzip. 7-Zip works on any platform if you'd rather not use the command line.)

Write the resulting .wic file to your microSD card. Three options:

• Balena Etcher (recommended, all platforms) — open it, select the .wic file, select your SD card, click Flash.
• dd, on Linux/macOS. Check the device name first — writing to the wrong device destroys its contents:

# on the PC
lsblk                                        # find your SD card's device, e.g. /dev/sdb
sudo dd if=calculinux-image-luckfox-lyra.rootfs.wic of=/dev/sdX bs=4M status=progress conv=fsync

• Rufus, on Windows — select the device and the image, choose the MBR partition scheme, and start.

This erases everything already on the card. Once it finishes, eject it and put it in the Luckfox Lyra's own microSD slot — not the PicoCalc's front-facing slot. The Lyra boots from its own slot; the front slot is only reachable once MeshTerm (or anything else) is already running on Linux.

Step 5 — First boot

With the card in the Lyra, power the PicoCalc on. Give it 30–60 seconds — the first boot is slower than later ones. You should see boot messages scroll on the PicoCalc's own screen, ending in a Calculinux GNU/Linux login prompt.

Log in:

login: root
Password: root

Change the password immediately:

# on the PicoCalc, as root
passwd

Step 6 — Open the serial console

The PicoCalc's own screen and keyboard work fine, so you can skip this step. The serial console makes pasting the longer commands in this guide much easier, though, so it is recommended.

The PicoCalc mainboard's USB-C port carries a USB-to-UART bridge (a CH340 chip). Plug a USB-C cable from that port into your PC. It shows up as:

• /dev/ttyUSB0 on Linux (you may need to be in the dialout group),
• a COM port on Windows,
• /dev/cu.usbserial-* on macOS.

Settings: 1500000 8N1, no flow control. Using pyserial's miniterm:

# on the PC
pip install pyserial
python3 -m serial.tools.miniterm /dev/ttyUSB0 1500000

minicom and PuTTY work too, at the same settings. To leave miniterm, press Ctrl+].

You should see the same login prompt you saw on the PicoCalc's screen, now in your PC's terminal.

Step 7 — Join Wi-Fi

Calculinux manages Wi-Fi with iwd. The easiest way is its text-mode picker: run uwific, highlight your network, press Enter and type the passphrase (Q quits). Or do the same from the command line:

# on the PicoCalc, as root
iwctl station wlan0 scan
iwctl station wlan0 get-networks
iwctl station wlan0 connect "<your SSID>"

It'll prompt for the passphrase. Check you're online:

ip addr show wlan0
ping -c 3 1.1.1.1

You should see an inet address on wlan0, and replies from the ping. iwd remembers the network, so this is a one-time step; to change networks later, run uwific again.

Step 8 — Copy the setup scripts to the device

You need this repository's scripts/ directory on the Lyra — its picocalc/ folder is the part the Lyra runs. Three ways to get it there, in order of ease:

• scp from your PC, once Wi-Fi is up. Find the Lyra's IP address with ip addr show wlan0 on the device, then from your PC:

# on the PC, from your MeshTerm checkout
scp -r scripts root@<lyra-ip>:/root/

If root is refused over SSH, copy as the pico user (password calc) instead, then move the directory as root on the device:

# on the PC
scp -r scripts pico@<lyra-ip>:/home/pico/
# on the PicoCalc, as root
mv /home/pico/scripts /root/

• The microSD card. Pull the card, copy scripts/ onto it from your PC's card reader, put it back.
• git clone on the device. Only once git is installed, and the setup script is what installs it — so this is a route for later updates, not the first copy.

scp is the recommended route.

Step 9 — Run calculinux-setup.sh

# on the PicoCalc, as root, with scripts/ copied over
cd scripts/picocalc
sh calculinux-setup.sh

It's idempotent — safe to re-run — and it checks before it acts. Two things it can't figure out on its own, both covered by environment variables read at the top of the script:

Knob	Default	Effect
DEPLOY_USER	meshterm	the login MeshTerm runs under
TIMEZONE	America/Toronto	any IANA zone
REPO_URL	the project's HTTPS URL	cloned when there's no deploy key
REPO_SSH	the project's SSH URL	cloned when there is one
KEY_PATH	/home/$DEPLOY_USER/.ssh/id_ed25519	a read-only GitHub deploy key, if you want SSH instead of HTTPS

You don't need to set any of these for a normal install — the defaults clone MeshTerm's public repository over plain HTTPS, which needs no credential at all.

What it does, one line per phase:

• opkg packages — installs python3-modules, python3-pip, git, kbd, because Calculinux ships a stripped Python missing pip, venv and several stdlib modules.
• Wi-Fi kick — installs a boot-time service that re-scans until the dongle joins the network iwd already knows, because on a cold boot the dongle's firmware finishes loading after iwd's first scan and the link would otherwise never come up.
• Time sync — installs a boot-time service that sets the clock over the network, since this board has no battery-backed real-time clock.
• Timezone — sets $TIMEZONE (Eastern by default).
• Deploy user — creates the meshterm login and puts it in the groups it needs.
• Clone — checks out MeshTerm to /home/meshterm/MeshTerm.
• venv and install — builds a Python virtual environment and pip install -e .s MeshTerm into it.
• Login PATH — puts that venv's bin on the meshterm user's PATH.
• Console font — builds and installs the console font MeshTerm's UI needs (braille charts, node glyphs, rounded corners).

This takes a few minutes on a good connection — most of it is pip install compiling things. It ends with done and tells you to log in as meshterm. That user has no password yet, so set one first:

# on the PicoCalc, as root
passwd meshterm

With no Wi-Fi dongle attached, the next boot takes about six minutes to get past the Wi-Fi kick, which keeps trying before it gives up. Nothing is broken. If the device is going to live offline, see Day-to-day for how to switch the kick off.

Step 10 — Log in as meshterm

Log out of root, and log in as meshterm with the password you just set. Try the app:

# on the PicoCalc, as meshterm
meshterm --mock

You should see MeshTerm's full-screen interface come up at 53 columns, with a simulated radio behind it, drawing braille charts and node glyphs cleanly — no empty tofu boxes. Along the bottom you should see the F-key lane: five labelled chips instead of the footer hint line a desktop terminal shows.

Have a look around. Esc backs out of any screen, and Quit on the main menu leaves the app.

Then look at the whole visual language on one card:

# on the PicoCalc, as meshterm
meshterm specimen

There are two console fonts available — a 6×12 one (53×26 rows) and a 6×8 one (53×40 rows, more rows but no Cyrillic glyphs). Try both from Preferences → Display → Console font — picking one previews it immediately, and the screen repaints at the new row count so you can see the choice before you keep it.

---

Phase 3 — Add the radio

This phase can wait. Everything above already gives you a working MeshTerm in --mock mode. Come back to this when you have the soldering iron out.

Step 11 — Install PlatformIO

On your PC:

# on the PC
pip install platformio

(or use the official installer script if you'd rather not touch your system Python). Confirm pio is on your PATH:

# on the PC
pio --version

The first firmware build downloads the nRF52 toolchain — several hundred megabytes — so do this somewhere with a decent connection.

Step 12 — Build the firmware

# on the PC (Git Bash or WSL on Windows)
cd scripts/picocalc/xiao-radio
sh build-firmware.sh

You should see it clone MeshCore, apply a patch, build, and finish with:

DONE.  Firmware: /path/to/scripts/picocalc/xiao-radio/meshcore-xiao-radio.uf2
Next: put the XIAO in bootloader (double-tap reset) and run:  python flash.py

Here's what it did, so you could do it by hand if you needed to:

1. Cloned MeshCore into scripts/picocalc/xiao-radio/_meshcore-build.
2. Checked out the pinned commit e9edfc8e on the dev branch — the commit this patch is known to apply cleanly to and build against.
3. Applied meshcore-uart1.patch.
4. Built the Xiao_nrf52_companion_radio_serial PlatformIO environment: pio run -e Xiao_nrf52_companion_radio_serial.
5. Converted the resulting .hex to a .uf2 with MeshCore's own converter, using the nRF52840 UF2 family id: python bin/uf2conv/uf2conv.py firmware.hex -c -f 0xADA52840 -o meshcore-xiao-radio.uf2.

What the patch changes, and why it is still needed

meshcore-uart1.patch touches two files, and both hunks are required:

• examples/companion_radio/main.cpp. MeshCore's companion-over-serial code declares HardwareSerial companion_serial(1) — a numbered constructor. On the Adafruit nRF52 core, HardwareSerial is an abstract base class with no numbered constructor at all, so this line simply doesn't compile for the XIAO nRF52840. The patch adds an #if defined(NRF52_PLATFORM) branch that binds companion_serial to Serial1 instead — the concrete UART object the nRF52 core always provides. Uart::setPins(rx, tx), called later in the same file, takes the same arguments either way, so nothing else needs to change.
• variants/xiao_nrf52/platformio.ini. This adds a new Xiao_nrf52_companion_radio_serial build environment that puts the companion serial link on pins D6 (TX) and D7 (RX). It also moves I²C off those same two pads, onto two internal pins, 16 and 17, that nothing in this build uses. This second change is the one that matters: the stock Xiao_nrf52 environment maps I²C onto D6/D7 by default, and both the board's begin() and the sensor code start the I²C bus on them automatically. Without the move, I²C seizes the UART pins at boot — the wiring is correct, the firmware builds and runs, and the serial link is still completely silent, because something else already owns the pins.

Both changes have been submitted upstream to MeshCore, but as of this writing they are not merged, and there's no sign that will happen soon — upstream dev still declares the bare HardwareSerial(1) with no nRF52 branch, and the XIAO's platformio.ini still has no _serial companion environment. Building with the patch is the normal route here, not a stopgap; when the patch does land, the git apply step (and the patch file itself) can be deleted.

Building by hand

If you want to track newer MeshCore instead of the pinned commit:

# on the PC
git clone https://github.com/meshcore-dev/MeshCore.git
cd MeshCore
git checkout dev                            # or MESHCORE_COMMIT=dev sh build-firmware.sh
git apply /path/to/scripts/picocalc/xiao-radio/meshcore-uart1.patch
pio run -e Xiao_nrf52_companion_radio_serial
python bin/uf2conv/uf2conv.py .pio/build/Xiao_nrf52_companion_radio_serial/firmware.hex \
    -c -f 0xADA52840 -o meshcore-xiao-radio.uf2

If git apply fails — upstream has moved and the patch context no longer lines up — the two hunks are small enough to make by hand:

1. In examples/companion_radio/main.cpp, find the line HardwareSerial companion_serial(1); and replace it with:

   #if defined(NRF52_PLATFORM)
     Uart& companion_serial = Serial1;
   #else
     HardwareSerial companion_serial(1);
   #endif
   

2. At the end of variants/xiao_nrf52/platformio.ini, add a new environment:

   [env:Xiao_nrf52_companion_radio_serial]
   extends = Xiao_nrf52
   board_build.ldscript = boards/nrf52840_s140_v7_extrafs.ld
   board_upload.maximum_size = 708608
   build_flags =
     ${Xiao_nrf52.build_flags}
     -I examples/companion_radio/ui-orig
     -D MAX_CONTACTS=350
     -D MAX_GROUP_CHANNELS=40
     -D OFFLINE_QUEUE_SIZE=256
     -D QSPIFLASH=1
     -D SERIAL_TX=D6
     -D SERIAL_RX=D7
     -D PIN_WIRE_SCL=16
     -D PIN_WIRE_SDA=17
   build_unflags =
     -D PIN_WIRE_SCL=D6
     -D PIN_WIRE_SDA=D7
   build_src_filter = ${Xiao_nrf52.build_src_filter}
     +<../examples/companion_radio/*.cpp>
     +<../examples/companion_radio/ui-orig/*.cpp>
   lib_deps =
     ${Xiao_nrf52.lib_deps}
     densaugeo/base64 @ ~1.4.0
   

Only the pinned commit (e9edfc8e) is known to build cleanly with this patch — a newer dev may need small further adjustments.

Step 13 — Flash the XIAO

Plug the XIAO's own USB-C port into your PC — it doesn't matter yet whether it's also wired to the Lyra. Then:

# on the PC
python flash.py

It first tries a 1200-baud "touch" over USB serial to reset the XIAO into its bootloader — this only ever targets Seeed's own USB vendor id, so it won't disturb another nRF52840 board on the same bench. If that doesn't take, double-tap the XIAO's reset button and run it again.

Once it finds the bootloader, it checks two things before writing anything:

• INFO_UF2.TXT's Model field must say a XIAO — a drive letter isn't an identity, and another board could have inherited the letter your XIAO just gave up.
• SoftDevice must not be 6.1.1. This firmware links for SoftDevice S140 v7 (app at 0x27000); a S140 6.1.1 bootloader wants the app at 0x26000 and would flash successfully and then simply never boot.

--force overrides both checks, if you're certain. A clean flash ends with:

DONE. XIAO flashed and rebooting into the radio firmware.

If no UF2 drive ever appears, that's not necessarily wrong — some XIAO bootloaders expose only a serial port, no mass-storage drive at all. flash.py recognises this case and prints the fallback command instead of failing silently:

# on the PC, from your MeshCore checkout
pio run -e Xiao_nrf52_companion_radio_serial -t upload --upload-port <bootloader port>

That command 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 protocol now lives on D6/D7, not on USB. That silence is correct; it doesn't mean the flash failed.

Step 14 — Wire the radio

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-shaped, but each pad's function is Luckfox's own RK3506 mapping: GP4 is gpio0-0 and GP5 is gpio0-1. Don't reach for a Pico pinout for anything else on this header. Every signal here is 3.3 V, and there is no 5 V rail on this board — power the XIAO from 3V3 only.

With the PicoCalc powered off and the back of the shell removed, solder the four wires between the XIAO's pads and the Lyra's header pins as above. The Lyra can stay seated in its socket: the tops of its header pins are reachable from inside the case, so solder to those. Keep the iron on each pin only as long as it takes, and don't press down on the board. Attach the LoRa antenna to the Wio-SX1262's u.FL connector before you power anything back on — running the radio without an antenna attached can damage it. Wrap the XIAO + Wio-SX1262 stack in Kapton tape so no pad can touch the Lyra, the mainboard or a battery, then tuck it into the shell wherever it fits without straining the wires; a strip of foam tape holds it in place against the inside of the case.

Step 15 — Set up the Lyra

With the wiring done and the shell closed back up, copy scripts/ to the device if you haven't already (Step 8), then:

# on the PicoCalc, as root
sh scripts/picocalc/xiao-radio/lyra-setup.sh          # MT_USER=meshterm by default

It does three idempotent things:

1. Installs uart1-mux.py as /usr/local/bin/uart1-radio-mux.py, run by a oneshot uart1-radio-mux.service on every boot. This is the part that actually makes /dev/ttyS1 reach the header pins — Calculinux enables the UART1 controller but never wires it to a physical pad on its own, and the RK3506's flexible pin matrix needs a direct register poke to route it onto GP4/GP5 instead.
2. Adds $MT_USER to the dialout group, so it can open the serial port. This needs a fresh login before it takes effect.
3. Writes a MeshTerm profile, only if none exists yet, at /home/$MT_USER/.meshterm/config.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 already exists, it prints those lines instead of touching your file — paste them in yourself.

Step 16 — Run it

Log out and back in as meshterm (so the dialout group membership takes effect), then:

# on the PicoCalc, as meshterm
meshterm

Because default_profile is set, a bare meshterm connects straight to the radio. You should see your node come up under whatever name the firmware advertises — both the device page and the dashboard header show it.

If you want to prove the wiring itself before suspecting anything else, there's a deeper check: open /dev/ttyS1 at 115200 as root and send a raw APP_START frame (3c 0e 00 01, seven zero bytes, then a name) — a live radio answers with a framed 05, SELF_INFO. The command byte and the reply code are the companion protocol's; the </> and little-endian-length framing around them come from the firmware and are worth confirming against it. It's a lower-level check than running MeshTerm and mostly useful for isolating a wiring problem.

---

Day-to-day

Charging. Only through the mainboard's USB-C port on the side of the case. ⚠ Never through the Lyra's own USB-C at the back — see Three ways to break it.

Powering off. Shut down cleanly rather than pulling the batteries:

# on the PicoCalc
sudo poweroff

Updating MeshTerm. Either re-run the setup script from root (it pulls the repository, reinstalls, and rebuilds the console font):

# on the PicoCalc, as root
sh calculinux-setup.sh

or, as the meshterm user, do just the update:

# on the PicoCalc, as meshterm
cd ~/MeshTerm && git pull && .venv/bin/pip install -e .

If an update adds new glyphs to the console font, rebuild it on its own afterwards:

# on the PicoCalc, as root
sh calculinux-console-font-6x12.sh

Changing Wi-Fi. Run uwific as root, as in Step 7. The boot-time kick picks up the new network on its own; it only needs iwd to know it.

The six-minute boot without a dongle. If the device is going to run permanently offline, the Wi-Fi kick is wasted time on every boot. Disable it:

# on the PicoCalc, as root
systemctl disable --now wifi-kick.service

The console font restores itself. MeshTerm saves whatever font the console was using before it starts, and puts it back when it exits — on a normal quit and on a crash alike. You don't need to do anything to keep the shell's own font intact.

---

Troubleshooting

Symptom	Check
Nothing on the PicoCalc's screen at all	Is the SD card in the Lyra's own slot, not the PicoCalc's front slot? Is a "Lyra B" (SPI NAND) erased? Is it the 128 MB RAM, Pico-form-factor variant — other RAM sizes have incompatible pinouts?
Wi-Fi never comes up	Is the dongle one of the tested chipsets (RTL8192CU / R8712U / RTL8188EU)? Remember the Lyra's USB port is 3.3 V — a 5 V dongle won't work. Give it the full six minutes on a cold boot before assuming it's stuck.
pip install fails with ENOSPC	/tmp is a small RAM disk. calculinux-setup.sh already sets TMPDIR=$HOME/tmp for its own install; if you're running pip by hand, do the same.
meshterm: command not found after setup	Log out and back in — the PATH line is added to ~/.profile, which only takes effect on a fresh login shell.
Tofu boxes instead of braille charts or node glyphs	The console font script hasn't run, or didn't persist. Re-run sh calculinux-console-font-6x12.sh, and check /etc/vconsole.conf has a FONT= line.
meshterm can't open /dev/ttyS1	Is the meshterm user in dialout (groups)? Group changes need a fresh login to take effect.
Port opens but the radio never answers	Re-flash with the _serial environment, not _ble or _usb — only it defines SERIAL_RX/SERIAL_TX. The XIAO's USB serial should be silent once it's running the radio firmware; that's expected, not a fault.
Still silent with wiring confirmed	Confirm the firmware actually carries the I²C remap (PIN_WIRE_SCL=16, PIN_WIRE_SDA=17) — a build without the patch's second hunk looks identical until you check this.
Flashed fine, XIAO never comes back	Wrong board, or the wrong SoftDevice — INFO_UF2.TXT must report a XIAO and S140 v7, not 6.1.1. flash.py refuses to flash either mismatch without --force.
flash.py finds no UF2 drive	Expected on a CDC-only bootloader — use the pio … -t upload --upload-port command it prints instead.
Nothing on /dev/ttyS1 after a reboot	systemctl status uart1-radio-mux, then journalctl -b -u uart1-radio-mux — the pin-mux poke has to run every boot, and a failed oneshot says why.

---

What has been tested

This whole path — from a stock PicoCalc kit through a running radio — has been exercised on one maintainer's bench: one Luckfox Lyra, one PicoCalc, one XIAO + Wio-SX1262 pair. It works. Some of it is also checked in code: a test parses the font script and pins it to MeshTerm's glyph inventory, the profile keys the scripts write are tested, the pinned MeshCore commit exists, the patch's two hunks are still needed on dev, and the nRF52840 UF2 family id and both XIAO bootloader ids match Adafruit's board files.

The rest is one bench's findings, 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 — was 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 runs at every boot.
• The header pin numbers 6, 7, 8 and 36 for GP4, GP5, GND and 3V3. The Pico-side numbering is right; the carrier's wiring is a bench observation.
• The MX1.25 socket's pin order. Taken from the wire colours of Luckfox's own cable, which is why Step 3 has you check pin 1 with a meter.
• The 5 V path through the Lyra's USB-C. The mechanism is read off the mainboard schematic and two forum measurements on the Pico; nobody has measured it with a Lyra. Treat the warning as the safe assumption it is.
• 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 dongle's cold-boot race with iwd, the opkg feed's occasional 404, that the stock Terminus console font is installed, and that kbd brings setvtrgb.
• That this board has no RTC. Only the script says so; the clock-sync phase follows.
• 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. Only the pinned commit is known to build.
• MeshCore's serial framing around the raw APP_START check in Step 16: the command byte and reply code are from the protocol documentation; the framing bytes are not.
• The framebuffer console's 512-glyph cap. Well known, taken as given, not re-measured.

If you build this and something disagrees with what's written here, that's worth reporting — a second board is the only way to learn which parts of this were about the hardware and which were about the one unit it was built on.