Files
MeshTerm/scripts/README.md
T
Jean-Pierre MartineauandClaude Opus 5.5 a4619aa17d The docs are in folders, and the Cardputer Zero has a page
docs/ was one flat folder: the user guides, the CLI manual, the device
manuals, the code notes and an old survey side by side. It is now
guide/ (features, configuration, connecting, terminals), cli/ (the
manual as its README, the cookbook), devices/ (which manual is yours
as its README, then one per device) and development/ (architecture,
the survey); screenshots/ stays put. The index follows the folders.

The device manuals are named for the device they are about: the
PicoCalc's is picocalc-lyra.md, since MeshTerm runs on the PicoCalc's
Luckfox Lyra core and on none of the others, and the uConsole's stays
uconsole.md, since its CM4 and CM5 run it alike. A new cardputer-zero.md
opens on a warning that the device is not supported yet, says what has
been built and tested only in the simulator, and how to try it there.

Every relative link was resolved from where it was written and rewritten
from where it now lives, and the repo-root spellings in code, config and
the release skill moved with them; the changelog's GitHub URLs too.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-04 11:42:51 -04:00

43 lines
2.3 KiB
Markdown

# scripts/
Repo-side tools. None of these ship in the wheel.
| Script | What it is for |
|---|---|
| `basemap-doctor.py` | Why a user's map has no basemap — certificates, DNS, proxy, or colour depth |
| `picocalc/` | Calculinux device setup: console font, palette, Wi-Fi; `xiao-radio/` is the XIAO radio kit (firmware build, flashing, UART setup) |
| `uconsole/` | The uConsole's always-on SPI bridge service (MeshTerm can also drive that radio directly, with no script at all — see `docs/devices/uconsole.md`) |
| `cardputer/` | The Cardputer Zero's console host: `fetch-terminus.py` installs the 12-pixel Terminus fonts it draws in (OFL, so never shipped with MeshTerm) |
## basemap-doctor.py
The map is the only networked part of MeshTerm, and every fetch failure on that path is
logged at DEBUG while `log_level` defaults to WARNING — so a reader whose tiles never
arrive sees a blank ground and no explanation. This prints the explanation and the fix.
Send a user this, to run **on the machine with the problem**:
```bash
curl -fsSL https://raw.githubusercontent.com/jpmartineau/MeshTerm/main/scripts/basemap-doctor.py -o /tmp/basemap-doctor.py
python3 /tmp/basemap-doctor.py
```
Any `python3` will do: if that one has no MeshTerm, the script reads the interpreter out
of the installed `meshterm` command's shebang and hands itself over, so the answer always
comes from **the app's own Python** — a Mac routinely has three and only that one has the
trust store that matters. Save it to a file as above rather than piping into `python3 -`:
with no file on disk there is nothing to hand over.
Have them paste the whole output back. It names the interpreter, the certificate store,
the tile source, the cached-tile count, `COLORTERM`, and then one verdict:
- **curl reached it, Python did not** — the Python's certificate store is empty. A
python.org install on macOS ships that way until `Install Certificates.command` is run.
- **neither reached it** — the network path: a firewall, a proxy, a DNS filter, or an
outage. Nothing to fix in MeshTerm.
- **both reached it** — tiles are fine and the complaint is colour: an unset `COLORTERM`
means 256 colours, where the basemap's greens and blues collide. Terminal.app cannot do
24-bit colour at all.
Exit status is 0 when tiles arrive and 1 when they do not, so it can be scripted.