Files
MeshTerm/scripts/README.md
T
Jean-Pierre MartineauandClaude Opus 5 5fbba275f6 The manuals describe what the code and scripts do today
Every manual was read against the code, the scripts and the upstream sources, and the
samples in docs/cli.md were recaptured under --mock where they had drifted.

The one a newcomer would hit first: config.example.toml set default_profile to a COM5
profile. Copied verbatim, as configuration.md says to, it broke every device command on a
machine with no COM5. default_profile is commented out now, so the copied file leaves
discovery working. default_tx_power goes from both, because nothing reads it.

docs/cli.md: config show has 22 settings and preferences show 21, not 20 and 8; monitor's
blocks have no blank line between them; the diagnostics sample is labelled as a real-radio
example with absolute instants and every table; an unknown key exits 1; devices, role and
records describe the values they really produce; no maintainer paths; and the "used to"
passages describe the present, since a first-time reader never saw the past.

picocalc.md: the Calculinux image carries a build stamp, so the gunzip and dd lines take
a wildcard; the front SD slot stays empty on first boot; masking wifi-kick is what stops
it, and time-sync is disabled with it; updates run the scripts from the pulled checkout
with TMPDIR set; the tested list names only what a test checks; git ships in the base
image; a bare meshterm shows the splash, and -p picocalc skips it.

uconsole.md: an AIO v2 needs MESHCORE_EN_PINS=27 whichever runtime is installed; the
bookworm paragraph states what upstream actually ships; the bridge shares the key but
keeps its own contacts and radio settings; the defaults are the US/Canada preset; Step 7
downloads what it installs; updating ends with a restart; no claim of test coverage the
suite does not have.

terminals.md, features.md, hardware.md, cookbook.md, configuration.md and the scripts
READMEs get the smaller corrections their audits found.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-21 11:28:24 -04:00

42 lines
2.0 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 SPI bridge service |
## 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.