The handhelds are named for their variant: picocalc-lyra and cardputer-zero

M5Stack makes three Cardputers and only the Zero runs Linux; the PicoCalc
takes several cores and only the Luckfox Lyra runs MeshTerm. So the bare
names were ambiguous, and every reference to the two devices now carries
the variant: the --platform values and MESHTERM_PLATFORM, the Platform
constants (PICOCALC_LYRA, CARDPUTER_ZERO), their lane decks and every
screen's picocalc_lyra_lane / cardputer_zero_lane, the font inventories,
the lane chips' theme styles, the scripts/ folders, the two chrome test
files, and the docs and CLAUDE.md that name them.

There is no alias: --platform picocalc is refused with the three real
choices listed, rather than falling back to the desktop layout. The
PicoCalc is auto-detected from its device tree, so it needs nothing.
What names hardware or a user's data keeps its name: the PicoCalc
keyboard's input-device name, its battery's sysfs supply, and the serial
profile the Lyra setup script writes. .gitignore follows the firmware's
folder, and the changelog keeps the words each release used.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5.5 committed 2026-10-04 11:52:41 -04:00
1 parent a4619aa17d
commit b6e7cd5c16
104 files changed
+587 -542

No files matched your search

+2 -2
View File
@@ -61,7 +61,7 @@ With no command, MeshTerm launches the interactive menu instead.
| `--json` | Print the answer as JSON instead of aligned text. |
| `--absolute` | Print times as ISO-8601 instants rather than relative ages, for this run. |
| `-q`, `--quiet` | Suppress console logging entirely (the log file still records). |
| `--platform NAME` | Force the UI flavour (`regular`\|`picocalc`) instead of detecting it. |
| `--platform NAME` | Force the UI flavour (`regular`\|`picocalc-lyra`\|`cardputer-zero`) instead of detecting it. |
**A global option may be typed anywhere** — before the command or after it. `meshterm
--json contacts` and `meshterm contacts --json` are the same run, because `-o json` goes
@@ -1730,7 +1730,7 @@ Print the visual-language specimen — every mark, icon, colour scale and fold o
**This is the one command that keeps its colour**, and it builds its own themed console to
do it. That is deliberate: the colour *is* the output. It is the font-and-palette
acceptance card on the PicoCalc console, and with `--platform picocalc` it previews that
acceptance card on the PicoCalc console, and with `--platform picocalc-lyra` it previews that
flavour from a desktop. A monochrome specimen would test nothing.
It is also the one command that **refuses `--json`**, as a usage error (exit `2`). There is
+24 -20
View File
@@ -26,8 +26,8 @@ script before you run it; most run as root and change the machine they run on.
## The scripts
[`scripts/`](../../scripts/) holds the device-side helpers, one folder per manual:
[`picocalc/`](../../scripts/picocalc/) for the PicoCalc — bringing up Calculinux on the Lyra,
building its console font, and (under [`xiao-radio/`](../../scripts/picocalc/xiao-radio/))
[`picocalc-lyra/`](../../scripts/picocalc-lyra/) for the PicoCalc — bringing up Calculinux on the Lyra,
building its console font, and (under [`xiao-radio/`](../../scripts/picocalc-lyra/xiao-radio/))
giving it a MeshCore radio over UART — and [`uconsole/`](../../scripts/uconsole/) for the
always-on bridge that fronts the uConsole's SPI-attached LoRa chip as a companion (MeshTerm
can also drive that chip directly, with no script at all — the uConsole manual covers
@@ -38,36 +38,40 @@ directly, or a pump in front of it, never both.
| File | Runs on | What it does |
| --- | --- | --- |
| [`picocalc/calculinux-setup.sh`](../../scripts/picocalc/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. |
| [`picocalc/calculinux-console-font-6x12.sh`](../../scripts/picocalc/calculinux-console-font-6x12.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. Calls the 6×8 build below when it sits alongside. Run it alone after a MeshTerm update, from the pulled checkout (`/home/meshterm/MeshTerm/scripts/picocalc/`) rather than the copy made at install time. |
| [`picocalc/calculinux-console-font-6x8.sh`](../../scripts/picocalc/calculinux-console-font-6x8.sh) | the Lyra (root) | The shorter-cell companion font, **meshterm8** (6×8 → 53×40), for anyone who wants more rows than the 6×12 default gives. Its base bitmap is the kernel's `font_6x8`, so this one file and the PSF it builds are **GPL-2.0-only** ([`LICENSE.GPL-2.0`](../../scripts/picocalc/LICENSE.GPL-2.0) sits beside it); it reads the donor/alias/keeper tables out of the script above rather than keeping a second copy. Pick between the two fonts from MeshTerm's Preferences page. |
| [`picocalc/calculinux-wifi-set.sh`](../../scripts/picocalc/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. |
| [`picocalc/calculinux-radio-bridge.sh`](../../scripts/picocalc/calculinux-radio-bridge.sh) | the Lyra (root) | **Unfinished, unsupported.** An early UART-to-TCP pump: it serves `/dev/ttyS1` on TCP port 5000 and writes a `radio` TCP profile. It does not route UART1 to the header pads. Superseded by `xiao-radio/lyra-setup.sh`, which does the routing and points MeshTerm at the serial port directly. |
| [`picocalc/xiao-radio/`](../../scripts/picocalc/xiao-radio/) | see below | Everything for the XIAO nRF52840 + Wio-SX1262 radio wired to the Lyra's UART1; its [bench card](../../scripts/picocalc/xiao-radio/README.md) has the wiring table. The firmware is MeshCore, MIT-licensed — [`LICENSE.MeshCore`](../../scripts/picocalc/xiao-radio/LICENSE.MeshCore) sits beside the patch. |
| [`xiao-radio/build-firmware.sh`](../../scripts/picocalc/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`](../../scripts/picocalc/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`](../../scripts/picocalc/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`](../../scripts/picocalc/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`](../../scripts/picocalc/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. |
| [`picocalc-lyra/calculinux-setup.sh`](../../scripts/picocalc-lyra/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. |
| [`picocalc-lyra/calculinux-console-font-6x12.sh`](../../scripts/picocalc-lyra/calculinux-console-font-6x12.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. Calls the 6×8 build below when it sits alongside. Run it alone after a MeshTerm update, from the pulled checkout (`/home/meshterm/MeshTerm/scripts/picocalc-lyra/`) rather than the copy made at install time. |
| [`picocalc-lyra/calculinux-console-font-6x8.sh`](../../scripts/picocalc-lyra/calculinux-console-font-6x8.sh) | the Lyra (root) | The shorter-cell companion font, **meshterm8** (6×8 → 53×40), for anyone who wants more rows than the 6×12 default gives. Its base bitmap is the kernel's `font_6x8`, so this one file and the PSF it builds are **GPL-2.0-only** ([`LICENSE.GPL-2.0`](../../scripts/picocalc-lyra/LICENSE.GPL-2.0) sits beside it); it reads the donor/alias/keeper tables out of the script above rather than keeping a second copy. Pick between the two fonts from MeshTerm's Preferences page. |
| [`picocalc-lyra/calculinux-wifi-set.sh`](../../scripts/picocalc-lyra/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. |
| [`picocalc-lyra/calculinux-radio-bridge.sh`](../../scripts/picocalc-lyra/calculinux-radio-bridge.sh) | the Lyra (root) | **Unfinished, unsupported.** An early UART-to-TCP pump: it serves `/dev/ttyS1` on TCP port 5000 and writes a `radio` TCP profile. It does not route UART1 to the header pads. Superseded by `xiao-radio/lyra-setup.sh`, which does the routing and points MeshTerm at the serial port directly. |
| [`picocalc-lyra/xiao-radio/`](../../scripts/picocalc-lyra/xiao-radio/) | see below | Everything for the XIAO nRF52840 + Wio-SX1262 radio wired to the Lyra's UART1; its [bench card](../../scripts/picocalc-lyra/xiao-radio/README.md) has the wiring table. The firmware is MeshCore, MIT-licensed — [`LICENSE.MeshCore`](../../scripts/picocalc-lyra/xiao-radio/LICENSE.MeshCore) sits beside the patch. |
| [`xiao-radio/build-firmware.sh`](../../scripts/picocalc-lyra/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`](../../scripts/picocalc-lyra/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`](../../scripts/picocalc-lyra/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`](../../scripts/picocalc-lyra/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`](../../scripts/picocalc-lyra/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. |
| [`uconsole/meshterm-spi-bridge`](../../scripts/uconsole/meshterm-spi-bridge) | the radio host (your user) | The **always-on** option: 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`, so the node stays on the mesh while MeshTerm is closed. Setup menu, preflight, optional `systemd --user` service. Runs on `openhop_core` (preferred) or its predecessor `pymc_core`; see the manual for the venv it wants on a bookworm uConsole. Most people should reach for `meshterm --spi` instead — no script, no service, MeshTerm drives the chip itself while it runs. |
## The regular and picocalc platforms
## The platforms
MeshTerm resolves one frozen **platform** 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 a framebuffer console: 53 columns, no
a footer hint line. The **picocalc-lyra** platform is a framebuffer console: 53 columns, no
emoji, an F-key lane instead of a hint line, and sixteen colour slots rather than a colour
space. Nothing loses its colour there: the node hue and the recency heat gradient
quantise to those slots instead. It is detected from the device tree on the Lyra, and
`--platform picocalc` or `MESHTERM_PLATFORM=picocalc` forces it anywhere, which is how you
preview the handheld layout on a desktop:
`--platform picocalc-lyra` or `MESHTERM_PLATFORM=picocalc-lyra` forces it anywhere, which
is how you preview the handheld layout on a desktop:
```bash
meshterm --mock --platform picocalc # the whole app, simulated radio, handheld layout
meshterm specimen # the visual language on one card
meshterm platform # which platform this terminal resolved to
meshterm --mock --platform picocalc-lyra # the whole app, simulated radio, handheld layout
meshterm specimen # the visual language on one card
meshterm platform # which platform this terminal resolved to
```
The **cardputer-zero** platform is the Cardputer Zero's 53×14 screen, which MeshTerm draws
itself. It is [not supported yet](cardputer-zero.md), so it is never detected: only
`--platform cardputer-zero` chooses it.
What that platform needs from the console — a font with the glyphs the interface draws,
and the stock sixteen-slot palette — is installed by the PicoCalc manual's setup script;
the details are in that manual and in the scripts' own headers.
+1 -1
View File
@@ -68,7 +68,7 @@ You need a copy of MeshTerm's source code (see
the screen is drawn in:
```bash
python scripts/cardputer/fetch-terminus.py
python scripts/cardputer-zero/fetch-terminus.py
```
and start the simulator:
+9 -9
View File
@@ -422,7 +422,7 @@ the network, so this is a one-time step; to change networks later, run `uwific`
### Step 8 — Copy the setup scripts to the device
You need this repository's `scripts/` directory on the Lyra — its `picocalc/` folder is the
You need this repository's `scripts/` directory on the Lyra — its `picocalc-lyra/` folder is the
part the Lyra runs. Two ways to get it there, once Wi-Fi is up:
- **`scp` from your PC**. Find the Lyra's IP address with `ip addr show wlan0` on the
@@ -453,7 +453,7 @@ part the Lyra runs. Two ways to get it there, once Wi-Fi is up:
```bash
# on the PicoCalc, as root, with scripts/ copied over
cd scripts/picocalc
cd scripts/picocalc-lyra
sh calculinux-setup.sh
```
@@ -574,21 +574,21 @@ this somewhere with a decent connection.
```bash
# on the PC (Git Bash or WSL on Windows)
cd scripts/picocalc/xiao-radio
cd scripts/picocalc-lyra/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
DONE. Firmware: /path/to/scripts/picocalc-lyra/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](https://github.com/meshcore-dev/MeshCore) into
`scripts/picocalc/xiao-radio/_meshcore-build`.
`scripts/picocalc-lyra/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`.
@@ -635,7 +635,7 @@ If you want to track newer MeshCore instead of the pinned commit:
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
git apply /path/to/scripts/picocalc-lyra/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
@@ -766,7 +766,7 @@ haven't already (Step 8), then:
```bash
# on the PicoCalc, as root
sh scripts/picocalc/xiao-radio/lyra-setup.sh # MT_USER=meshterm by default
sh scripts/picocalc-lyra/xiao-radio/lyra-setup.sh # MT_USER=meshterm by default
```
It does three idempotent things:
@@ -840,7 +840,7 @@ re-run the setup script from root (it reinstalls and rebuilds the console font):
```bash
# on the PicoCalc, as root
su - meshterm -c 'git -C ~/MeshTerm pull'
sh /home/meshterm/MeshTerm/scripts/picocalc/calculinux-setup.sh
sh /home/meshterm/MeshTerm/scripts/picocalc-lyra/calculinux-setup.sh
```
or, as the `meshterm` user, do just the update:
@@ -854,7 +854,7 @@ If an update adds new glyphs to the console font, rebuild it on its own afterwar
```bash
# on the PicoCalc, as root
sh /home/meshterm/MeshTerm/scripts/picocalc/calculinux-console-font-6x12.sh
sh /home/meshterm/MeshTerm/scripts/picocalc-lyra/calculinux-console-font-6x12.sh
```
**Changing Wi-Fi.** Run `uwific` as root, as in [Step 7](#step-7--join-wi-fi). The boot-time