Jean-Pierre MartineauandClaude Opus 5.5
0d08e4bb5e
The XIAO stopped answering on 10-07 ("No response from meshcore
node" for many starts in a row). MeshCore's serial parser reads '<'
and a two-byte length, then waits for that many bytes with no time
limit, so one lost or damaged byte can make it swallow up to 65,535
bytes, and MeshTerm sends only 16 per start. Reproduced on the
PicoCalc: a half frame blocked two APP_STARTs until 600 filler bytes
arrived. meshcore-frame-timeout.patch drops a frame after 200 ms of
silence on the line (bytes queued while the loop was busy still
count), and build-firmware.sh applies it after meshcore-uart1.patch.
Upstream dev and main still have the old parser.
Flashing the XIAO with the new firmware, following the guide as
written, found these problems, now corrected:
- Step 11: `pip install platformio` failed (no pip outside a venv on
this PC), and it fails on externally managed Pythons or lands in an
active venv. The guide now uses the official installer only, and
build-firmware.sh and flash.py find pio in ~/.platformio/penv, so
nobody edits the PATH. uf2conv runs on PlatformIO's Python, because
a bare `python` is missing on many Linux systems.
- Step 12: the script's last line said to double-tap reset first;
flash.py touches the XIAO itself, and a wired XIAO's reset button is
inside the case.
- Step 13: this XIAO's bootloader has only a serial port, and flash.py
printed a pio command for the user to run "from your MeshCore
checkout", with pio not on the PATH. flash.py now does the serial
DFU upload itself (54 s here). Without pyserial, it runs itself
again with PlatformIO's Python instead of skipping the touch.
- A wired XIAO's USB power goes backward into the Lyra through the
3V3 wire (JP confirmed it on the bench). Step 13 now applies only
before wiring, and a new Day-to-day procedure updates the firmware
of a wired radio: poweroff, switch off, open, batteries out, flash.
After the flash, the radio kept its identity, MeshTerm's info command
connected, and an APP_START after a half frame and 0.5 s of silence
got its reply at once.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
MeshTerm documentation
This folder has everything that does not belong on the front page. The README is the front door. It says what MeshTerm is, how to install it, and how to start a first session. This folder has the other documents, in four parts:
| Folder | What is in it |
|---|---|
guide/ |
How to use MeshTerm: what each screen does, how to configure it, how to connect a companion, and terminals. |
cli/ |
The manual of the command line, and a cookbook of one-line commands. |
devices/ |
How to run MeshTerm on a handheld's own screen, with one manual for each device. |
development/ |
How the code is laid out, how we write, and a historical survey. |
Using MeshTerm
| Read | For |
|---|---|
| What MeshTerm does | Each screen that the menu has, in the same groups as the menu, with the command that does the same job without the menu. |
| Configuring MeshTerm | The difference between preferences and config, the device profiles, and all the files that MeshTerm keeps in ~/.meshterm. |
| When a companion does not connect | Bluetooth pairing on each system, how to find the PIN, and each connection error that MeshTerm reports, with the action to take. |
| Terminals, icons, and the Windows console | Why the icons and charts draw correctly on some terminals and not on others, and what MeshTerm does about it on Windows. |
The command line
| Read | For |
|---|---|
| The command line | The manual. Each subcommand and option, what each prints on the plain face and on the JSON face, the exit statuses, and recipes that use jq. |
| The CLI cookbook | Common one-line commands, in groups by task. Use it when you want the form of a command and not its specification. |
Running it on a handheld
Read these documents only if you want to run MeshTerm on a handheld's own screen. A MeshCore companion on USB, Bluetooth, or Wi-Fi does not need them.
| Read | For |
|---|---|
| MeshTerm on hardware | Start here. It says which of the manuals below is the correct one for you, and what the scripts on the device do. |
| MeshTerm on the PicoCalc | How to change a stock ClockworkPi PicoCalc into a Linux handheld that has a LoRa radio soldered inside: the shopping list, the change to a Luckfox Lyra core, Calculinux, and the radio. |
| MeshTerm on the uConsole | A uConsole (CM4 or CM5) with the hackergadgets AIO LoRa board. Its SX1262 is on the computer's own SPI bus. MeshTerm can control it directly with --spi. Or a small bridge can make it a companion for a node that is always on. |
| MeshTerm on the Cardputer Zero | ⚠️ Not supported yet. What exists for M5Stack's Linux Cardputer, and how to try it in the desktop emulator. |
Reading the code
| Read | For |
|---|---|
| How the code is laid out | The layers of the code, and where to put a new feature. |
| How we write | How we write: the ASD-STE100 rules and the glossary for docstrings, comments, and documents. |
| CLAUDE.md | The real style guide: the terms, the UX standards, and the building blocks that you can use again. It is written for AI assistants, and it has the house rules for everyone. |
| CONTRIBUTING.md | How to propose a change, the rules for the use of AI, the dev install, the three checks that a change must pass, and what happens to the licensing of your contribution. |
Historical record
This is a survey of the code. We keep it, because a project that writes down its own problems is easier to trust than a project that does not. But it is a snapshot of one date, not a list of tasks. Some of the problems that it describes are corrected now, and the survey does not say which.
| Read | For |
|---|---|
| UI consistency survey | Each other point of the CLAUDE.md UX standard. Six sweeps found nothing, and this is the useful result. |
Also here
screenshots/ has the captures that the README shows. It also has the captures from which
meshterm.net builds its landing page. Thus more than one place
refers to each file in this folder.