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>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5.5 committed 2026-10-04 11:42:51 -04:00
1 parent 22398128f5
commit a4619aa17d
23 files changed
+273 -162

No files matched your search

+176
View File
@@ -0,0 +1,176 @@
# Configuring MeshTerm
Preferences, device profiles, and where everything is kept. You need none of it to run
MeshTerm: it discovers a companion, lets you pick one, and remembers the choice.
Two files, two jobs — and you need neither to run.
**Preferences** are how MeshTerm behaves: the pause it leaves between transmissions, how
hard it retries a message, how far back it keeps history, how a map frames itself. Every one has a built-in default, so change them only where you disagree — from
the **Preferences** page in the menu (grouped, staged, saved by one action at the bottom),
or from a shell:
```console
$ meshterm preferences show # every preference, its value, its default
$ meshterm preferences set history_days 90
$ meshterm preferences reset --yes # back to the built-in defaults
```
They are kept in `~/.meshterm/preferences.toml`, which lists only what you have changed;
delete a line and the default takes over again.
**Config** is where things live and which device to talk to. MeshTerm runs with none of it
— it discovers attached serial devices and nearby Bluetooth companions, lets you pick one,
and remembers the last good default. A network (TCP) companion isn't discoverable, so reach
it with `--tcp host:port`, a TCP profile, or the picker's "add a network device" prompt.
A LoRa radio on this machine's own SPI bus is listed on the picker when its device node
exists, or reached with `--spi`; see [the uConsole manual](../devices/uconsole.md).
Write a config file only to give your hardware stable aliases.
Copy [`config.example.toml`](../../config.example.toml) to `~/.meshterm/config.toml`:
```toml
# default_profile = "s3" # uncomment and name your own profile to make it the default
connect_on_start = true # false opens the radio link lazily instead of at launch
# db_path = "C:/Users/you/meshterm/meshterm.db" # the history lives elsewhere
[profiles.s3]
port = "COM5"
baudrate = 115200
description = "XIAO ESP32-S3 + Wio SX1262 serial companion"
# A Bluetooth LE companion: give it an `address` instead of a `port`.
[profiles.handheld]
address = "AA:BB:CC:DD:EE:FF"
# ble_pin = "123456" # only if your device requires a pairing PIN (not used on macOS)
description = "Pocket handheld over Bluetooth"
# A network (TCP) companion: give it a `host` (and optional `tcp_port`, default 5000).
[profiles.wifi]
host = "192.168.1.50"
description = "Basestation over Wi-Fi"
# A radio on this machine's own SPI bus (the uConsole AIO): MeshTerm runs its node.
# The pins default to the AIO v1's; a `spi` table states only what differs.
[profiles.aio]
transport = "spi"
# [profiles.aio.spi]
# en_pins = [27] # the AIO v2 powers its radio from pin 27
```
Both live in `~/.meshterm`, along with everything else MeshTerm remembers: the SQLite
history, the outbox, the contact and channel caches, stored admin passwords, and the log.
**`$MESHTERM_HOME` moves the whole directory**, which is the way to run a second radio —
or a `--mock` session — without touching the one you use every day. `--db` moves the
database alone; the rest stays where it was. A `--mock` run that names neither writes to
`meshterm-mock.db` beside the real history, so the simulator's invented nodes never enter
it. [`docs/cli.md`](../cli/README.md#where-meshterm-keeps-its-state)
lists every file.
Timestamps are stored as UTC and rendered in your local time. Heard packets older than the
`history_days` preference are deleted when monitoring starts: once in each menu session,
and at the start of each `meshterm monitor` run. Nothing else is pruned.
## Adding a radio on the SPI bus
Some boards put the LoRa chip straight on the computer's SPI bus, with no firmware in front
of it: the uConsole's AIO board, and LoRa HATs for the Raspberry Pi. MeshTerm drives these
itself — it runs the node while it is connected and lets go of the radio when it quits.
It needs Linux and the radio library; [the uConsole manual](../devices/uconsole.md#step-2--install-the-radio-library)
shows how to install that.
**An AIO v1 needs no configuration.** Its wiring is MeshTerm's default, so whenever
`/dev/spidev1.0` exists the device screen lists it as **SPI radio**, and `meshterm --spi`
reaches it. Any other board is added with a profile that states how it is wired.
**Why a profile, and not a prompt on the device screen.** A USB companion describes itself:
plug it in and there is nothing to ask. An SPI radio says nothing about how it is wired, and
the wiring is a dozen facts — the bus, the chip select, the reset, busy, and interrupt pins,
the antenna switch, the TCXO — any one of which, wrong, leaves a radio that comes up deaf
rather than failing. Those are facts to look up once and write down, not to type into a
dialog. And the radio doesn't come and go the way a cable does: it is soldered, stacked on
a header, or built into the case, so its description belongs somewhere as lasting as the
hardware is. A file you write once, and can read back when something is off, is that place.
### 1. Find your board's wiring
The easiest place to find it is the board's `meshtasticd` configuration, which most vendors
publish (usually a `config.yaml` or a `config.d/` fragment with a `Lora:` section). Its keys
map one to one:
| `meshtasticd` (`Lora:`) | MeshTerm (`[profiles.<name>.spi]`) |
| --- | --- |
| `spidev: spidev0.0` | `bus_id = 0` and `cs_id = 0` — the two numbers of `spidevB.C` |
| `CS: 21` | `cs_pin = 21` (only when the board drives chip select from a GPIO) |
| `Reset`, `Busy`, `IRQ` | `reset_pin`, `busy_pin`, `irq_pin` |
| `TXen`, `RXen` | `txen_pin`, `rxen_pin` |
| `DIO2_AS_RF_SWITCH: true` | `use_dio2_rf = true` |
| `DIO3_TCXO_VOLTAGE: true` | `use_dio3_tcxo = true` (1.8 V) |
| `gpiochip: 4` | usually nothing — see below; `gpio_chip = 4` to pin it |
`Module` must be `sx1262`; that is the chip MeshTerm's node drives. **Leave `gpio_chip` out**
unless you need to override it: a `meshtasticd` file pins a number because Meshtastic can't
look the chip up, but the number that carries a Raspberry Pi's 40-pin header differs
between a Pi 4/CM4 and a Pi 5/CM5 and has moved between kernel releases on the latter.
Left out, it defaults to `-1`, and MeshTerm finds the header's chip by its label
(`pinctrl-rp1`, `pinctrl-bcm2711`, `pinctrl-bcm2835`) — falling back to chip `0` on a board
whose chips carry none of them. `gpiodetect` lists every chip with its label. The
[uConsole guide](../devices/uconsole.md#which-gpio-chip) has the whole story.
**State every pin and both switches.** Where a `meshtasticd` file leaves a key out, it means
"none" or "off". Where the `spi` table leaves a key out, it means *the AIO's value* — IRQ on
26, DIO2 and DIO3 on — which is wrong for almost any other board, and a radio wired wrong
comes up deaf rather than failing.
### 2. Write the profile
In `~/.meshterm/config.toml`, give the radio a name and its wiring. The values below are an
illustration, not any particular board's — take yours from step 1:
```toml
[profiles.hat]
description = "SX1262 HAT on the Pi header"
[profiles.hat.spi]
bus_id = 0 # /dev/spidev0.0
cs_id = 0
reset_pin = 18
busy_pin = 20
irq_pin = 16
txen_pin = 6 # this HAT switches its antenna from a GPIO…
rxen_pin = -1
use_dio2_rf = false # …so DIO2 doesn't
use_dio3_tcxo = false # no TCXO on this board
```
A `spi` table is enough to make it an SPI profile; `transport = "spi"` says so outright and
is what an AIO profile with no table uses. Every key, with the AIO defaults, is in
[the uConsole manual's wiring table](../devices/uconsole.md#board-wiring). A key MeshTerm doesn't know,
or a value of the wrong type, stops it at startup with the profile named — a misspelt pin
is never quietly ignored.
### 3. Check it
```bash
meshterm -p hat info
```
The first run starts the node, which mints the radio's identity. If something is wrong, the
error says what to fix — a missing `/dev/spidev*` (enable SPI and reboot), a permission
problem (join the `spi` and `gpio` groups), a missing radio library, or another program
already holding the radio. A node that starts but never answers leaves its log in
`~/.meshterm/radio/spidev0.0/node.log`. Once it answers, the device screen lists the radio
under the profile's name.
### What the profile doesn't hold
- **Radio settings.** Frequency, bandwidth, spreading factor, coding rate, and TX power are
the node's own settings, saved by the node and changed on **Device config** like any
companion's. A new node starts on MeshCore's **US/Canada preset** (910.525 MHz, 62.5 kHz,
SF7, CR 4/5, 22 dBm): anywhere else, change it on Device config before you send anything.
- **The preamble.** The node follows MeshCore's own rule — 32 symbols up to SF8, 16 above —
and a receiver that expects anything else misses most of the mesh. `preamble_length` was
once a wiring key and is refused now; delete the line if an old profile has it.
- **Identity.** The node's key, contacts, and channels live in
`~/.meshterm/radio/<spidev>/`, filed by the device node rather than the profile, so
renaming a profile, or reaching the same radio from the device screen, keeps the same node.
+128
View File
@@ -0,0 +1,128 @@
# When a companion won't connect
MeshTerm talks to a MeshCore companion over USB, Bluetooth, or TCP, or runs the node itself
on a radio on the SPI bus. When a connection fails, MeshTerm says which step failed and what
to do about it, in the device picker and on the command line alike. This page collects those
messages, so you can look one up before you meet it, or search for the one you have.
Every failure is also written to the log file, `~/.meshterm/meshterm.log` (see
[Where MeshTerm keeps its state](../cli/README.md#where-meshterm-keeps-its-state)). Attach it to a
bug report. For more detail, set the **Log detail** preference to `DEBUG` (`meshterm
preferences set log_level DEBUG`) and run it again.
- [Bluetooth](#bluetooth)
- [Who does the pairing](#who-does-the-pairing)
- [Finding the PIN](#finding-the-pin)
- [What each message means](#what-each-bluetooth-message-means)
- [Forgetting a pairing](#forgetting-a-pairing)
- [USB](#usb)
- [TCP](#tcp)
- [A radio on the SPI bus](#a-radio-on-the-spi-bus)
---
## Bluetooth
**A companion takes one Bluetooth connection at a time.** If your phone's MeshCore app is
connected to it, MeshTerm cannot connect until the phone lets go, and the companion stops
advertising while it is connected, so MeshTerm cannot even see it. Disconnect the phone
first, or turn its Bluetooth off.
### Who does the pairing
A PIN-protected companion must be *paired* before it will talk: the computer and the
companion exchange keys once, using the six-digit PIN, and remember them. Who runs that
exchange depends on the system.
| System | Who pairs | What you do |
| --- | --- | --- |
| Windows | MeshTerm | Give the PIN when MeshTerm asks for it (the picker's PIN dialog, or `--ble-pin` on the command line). You do not need to pair in Settings first. |
| Linux | MeshTerm | The same. MeshTerm answers the pairing itself, so it works over SSH and on machines with no desktop, and you do not need `bluetoothctl` or the desktop's Bluetooth settings. |
| macOS | macOS | macOS shows its own dialog asking for the code; type the PIN there. `--ble-pin` has no effect on macOS. |
Once paired, the system remembers it, and later connections need no PIN.
**On macOS, the terminal needs Bluetooth permission.** macOS grants Bluetooth to the app
MeshTerm runs in (Terminal, iTerm2, Ghostty), not to MeshTerm itself. If no pairing dialog
appears, or no Bluetooth devices are listed, check System Settings > Privacy & Security >
Bluetooth. **Over SSH, macOS denies Bluetooth outright** and never asks, so run MeshTerm in
a terminal on the Mac itself.
### Finding the PIN
The PIN is shown on the companion's screen, or in the MeshCore app's settings for it. A
companion with no screen (a T1000-E, for instance) can tell you over USB instead:
```console
$ meshterm --port /dev/ttyACM0 config get device_pin
123456
```
`meshterm config set device_pin <PIN>` changes it, and so does the **Device PIN** row on
the menu's Device config page. A changed PIN makes every existing pairing with that
companion out of date. See [a stale pairing](#what-each-bluetooth-message-means) below.
### What each Bluetooth message means
In the device picker, a pairing problem opens the PIN dialog with a one-line reason under
the question. On the command line, it is the error message. Both come from the same
diagnosis.
| The message starts with… | What happened | What to do |
| --- | --- | --- |
| **couldn't open a Bluetooth link** | The companion was never reached. | Move closer, check it is powered on, and make sure no phone or other computer is connected to it. |
| **requires a Bluetooth pairing PIN** | The companion is PIN-protected and not paired with this computer. | Give the PIN: the picker asks for it; on the command line, add `--ble-pin <PIN>`. |
| **Windows has … paired** / **Linux has … paired, but the device refused that pairing** | Your computer remembers a pairing that the companion no longer accepts. It was reflashed, reset, or given a new PIN, or it was paired *without* a PIN back when it did not have one. | Give the PIN, and MeshTerm removes the old pairing and pairs again. Or [forget the pairing](#forgetting-a-pairing) yourself and reconnect. |
| **rejected the Bluetooth PIN** | The PIN was wrong. | Check the code on the device or in the MeshCore app, and try again. |
| **refused to pair** | The companion turned the pairing down. It is usually connected to a phone, or still holds an old pairing for this computer. | Disconnect it from anything else, or restart it, and try again. |
| **Windows couldn't pair** / **Linux couldn't pair** | The pairing failed for another reason, named in brackets. | Restart the companion, [forget the pairing](#forgetting-a-pairing), and try again. |
| **Windows couldn't reach** / **Linux couldn't reach … to pair it** | The system could not find the companion when it came to pair. | As for a link that never opened: range, power, or another connection. |
| **paired with …, but the device still refuses the connection** | Pairing succeeded, yet the companion still refuses. It is holding an old pairing for this computer. | Restart the companion, [forget the pairing](#forgetting-a-pairing), and try again. |
| **was not paired. macOS asks for the pairing code in its own dialog** | macOS had not finished pairing. | Type the PIN into the macOS dialog when it appears. If none appears, check the terminal's Bluetooth permission (above). |
| **connecting … took longer than** | The link, the pairing, or the service discovery stalled. | Move closer, restart the companion, and try again. |
| **connected …, but it didn't answer the identity query** | The link came up and the companion went quiet. | It may be busy with another app. Restart it and try again. |
| **connected …, but it never answered as a MeshCore companion** | Something answered, but not as a companion. | It may be running repeater or room server firmware, which has no companion interface. |
### Forgetting a pairing
MeshTerm fixes a stale pairing itself when you give it the PIN. To remove one by hand:
- **Windows:** Settings > Bluetooth & devices, open the companion, and choose *Remove device*.
- **Linux:** `bluetoothctl remove AA:BB:CC:DD:EE:FF`, with your companion's address.
- **macOS:** System Settings > Bluetooth, the companion's ⓘ button, then *Forget This Device*.
On Windows and Linux, MeshTerm's quit dialog also offers **Unpair & quit** while a paired
Bluetooth companion is connected. It forgets the pairing on the way out, so the next
connection asks for the PIN again.
---
## USB
| The message starts with… | What happened | What to do |
| --- | --- | --- |
| **no permission to open** | Your user may not open the port. On Linux, serial ports belong to a group, `dialout` on Ubuntu and Debian. | `sudo usermod -aG dialout $USER`, then log out and back in. The new group applies only to a new login. |
| **… is in use by another program** | Something else has the port open: the MeshCore app, a firmware flasher, or a serial monitor. On Windows this is reported as *Access is denied*. | Close the other program. On Linux, ModemManager probes new USB serial devices and can hold one: `sudo systemctl stop ModemManager`, and try again. |
| **… isn't there** | The port does not exist. The device was unplugged, or came back under another name (`/dev/ttyACM0` becoming `/dev/ttyACM1`, `COM5` becoming `COM6`). | `meshterm devices` lists what is attached now. |
| **no response from a MeshCore companion on …** | The port opened, but nothing answered as a companion. | It may not be a MeshCore companion (repeater firmware, or another device), or it is powered off or busy. On Linux, ModemManager may be probing it: `sudo systemctl stop ModemManager`, and try again. |
To stop ModemManager for good rather than for one boot, `sudo systemctl disable --now
ModemManager`, if nothing else on the machine needs it. Nothing does unless you have a
cellular modem.
---
## TCP
**no response from a MeshCore companion at HOST:PORT** means nothing answered there. Check
the host and the port (MeshTerm's default is `5000`), that the companion is powered on and
reachable on your network, and that no other client is already connected to it. Like
Bluetooth, a network companion serves one client at a time.
---
## A radio on the SPI bus
A radio MeshTerm drives itself (`--spi`) is not a companion. It has no pairing and no port,
and its failures are about the node MeshTerm starts. Its own guides cover them:
[the uConsole](../devices/uconsole.md) and [adding a radio on the SPI bus](configuration.md#adding-a-radio-on-the-spi-bus).
+72
View File
@@ -0,0 +1,72 @@
# What MeshTerm does
Every screen the menu offers, and the command that does the same job without it. This is
the catalogue; [the command line](../cli/README.md) is the manual for the scripted half of it.
MeshTerm's menu asks one question — *what would you like to do?* — and its six sections
answer it in two halves. The first three name a **doing**: Message, Watch, Explore. The
last three name **whose** a setting is: This node, the radio in your hand;
Other nodes, someone else's over the mesh; and This app, the program in front of you.
Every interactive screen is listed here with its scripted equivalent, where one exists.
## 💬 Message — the people on the other end
| Feature | What it does | Scripted |
| --- | --- | --- |
| **💬 Chat** | Live full-screen channel and direct messaging — a scrolling transcript with a pinned input line where sent and received messages stream together. Every message is logged; unread counts show in the menu header. | `meshterm chat send / history / list` |
| **📻 Channels** | Create, join, reorder, mute, and share mesh channels — with QR codes and `meshcore://` share links. Give a channel a **send scope** and its messages are flooded into one region, relayed only by the repeaters that carry it. | `meshterm channels list / add / join / import / share / clear / scope` |
| **📨 Courier** | Store-and-forward outbox for contacts that aren't reachable yet. Queue a message; it goes out (with ack tracking and polite exponential backoff) the moment the contact is next heard, or at a scheduled time. | `meshterm courier queue / list / send / cancel / clear` |
| **👥 Contacts** | This node and its known contacts — a recency heat-map, overheard packet counts, and full public keys with the path-hash prefix highlighted. The scripted listing is the contacts alone (this node is `meshterm info`'s answer, in far more detail). | `meshterm contacts` |
## 📊 Watch — what the mesh is doing, and what it did
| Feature | What it does | Scripted |
| --- | --- | --- |
| **📊 Dashboard** | The live mesh overview: a two-hour all-packet activity chart with a pulse line, session traffic tallies by packet class, and window RF health beside the radio's own live numbers. Repaints every second. | — |
| **📰 Live feed** | Every packet as it arrives, newest first: time, what the frame *is* (its parsed payload class), and what it is *about* — the node for an advert, the channel for a channel text, sender → recipient for a direct message or a request, the tag for a trace — with reception quality beside it, and the region a scoped flood was sent into. Enter opens any row in the packet viewer, route graph and all. | — |
| **🚨 Watchtower** | A passive sentinel over the nodes you star: silence alarms when a watched node goes quiet, SNR-sag warnings when reception degrades, recovery notes when it returns, and a heads-up when a node is heard for the first time. Runs in the background all session; unacked alerts show as a header badge. | — |
| **⏳ Time machine** | Everything the recorder ever heard, as braille charts: reception volume, the median-SNR band, hour-of-day rhythm, packets and nodes per day, and first-ever arrivals — over a switchable 24h / 7d / 30d / all-time window (on the PicoCalc the windows stop at 30d), per node or mesh-wide. | — |
| **🎧 Monitor** | Passive recording is always on in the app. On the CLI, capture a bounded foreground window, tailing each overheard packet and summarising when it ends. It transmits nothing — it only listens. | `meshterm monitor --seconds 60` |
## 🧭 Explore — where the nodes are and how they reach each other
| Feature | What it does | Scripted |
| --- | --- | --- |
| **🌍 Map** | Located nodes plotted over a real OpenStreetMap street basemap rendered as Unicode braille (streets, rivers, place names). Pannable and zoomable; repeaters highlighted and drawn on top. Falls back to a blank grid offline. | — (a map is a picture; `meshterm contacts` lists the same nodes) |
| **🌐 Mesh walk** | The mesh's *observed shape*, walked one node at a time: an evidence graph built from trace walks, firmware routes, overheard relay chains, and repeater neighbour tables. SNR-coloured braille edges, quality bars, Enter to walk, ⌫ to backtrack, type to find any node. The map answers *where*; the walk answers *how it hangs together*. | — |
| **🎯 Trace target** | A live trace screen: pick a target and watch each trace stream in hop by hop, with running per-hop medians and reliability. Compose or force a route through specific repeaters. A trace transmits **exactly once** (repeaters can blacklist nodes that burst) — sample more by running it again. | `meshterm trace --target …` |
| **👣 Trace path** | The other half of tracing: compose the whole circuit by hand — out and back whichever way you choose — and walk it. The path composer suggests each next hop from the links actually observed, strongest first, and can fetch a repeater's neighbour table over the mesh when you hold its admin password. | `meshterm trace-path --path …` |
| **🏆 Trophy case** | Every trace that comes home is scored, on seven boards: longest distance, farthest node, longest single leg, most nodes (with and without revisits), weakest surviving link, and biggest enclosed loop. Records are kept per hash width, and a record walk must be a *trail* — no link crossed twice the same way. | `meshterm records` |
## 🔧 This node — the radio in your hand
| Feature | What it does | Scripted |
| --- | --- | --- |
| **📋 Device info** | The connected companion's identity and full radio configuration at a glance. | `meshterm info` |
| **🔧 Device config** | Every setting the companion firmware exposes — name, radio, client repeat, auto-add, telemetry, custom variables — *staged* for review and applied in place, plus the operations on the box itself: clock sync, TOML backup/restore, the identity key, reboot, and factory reset, each acting the moment it's confirmed, with destructive ops gated. Laid out like Repeater admin, so the radio in your hand and one over the mesh are configured the same way. | `meshterm config` / `config set <key> <value>` / `config backup` / `config reboot` / … |
| **📡 Send advert** | Announce this node to the mesh — a zero-hop or flood advertisement, or share this node's contact card as a QR code. | `meshterm config advert` / `config share` |
| **🔌 Devices** | Not a menu screen. The companion is picked on the startup splash, which enumerates serial *and* Bluetooth LE companions (or auto-selects the only one present), adds a network (TCP) companion by host:port, and remembers the last good default. A dropped link is detected live and offers to reconnect. `meshterm devices` lists what discovery finds. | `meshterm devices` |
## 🗼 Other nodes — someone else's radio, over the mesh
| Feature | What it does | Scripted |
| --- | --- | --- |
| **🗼 Repeater admin** | Set up remote repeaters and room servers over the mesh: log in (remembered or prompted password), then a config-style editor speaking the node's text CLI — including repeater-only knobs (TX delay, airtime factor, advert intervals) — plus one-shot actions and a readline remote command line. A **Regions** page edits the repeater's region tree: which regions it relays floods for, whether it relays unscoped floods, its home and default scope. | `meshterm repeater-admin <node> <command…>` |
| **🔖 Regions** | Not a menu screen. A repeater's node page lists the regions it carries and asks it once, without logging in (it answers only a neighbour, or over a known route); the packet viewer, message paths and live feed name the region a flood was scoped to. | `meshterm regions <node>` |
| **📶 TX optimize** | Sweep a remote node's transmit power live — coarse, then refine, then verify — watch each level land, and decide whether to apply the winner. The scripted form applies the winner unless told not to. | `meshterm tx-optimize --path … [--no-apply]` |
## ⚙ This app — the program in front of you
The last of the three, and the one nothing on the mesh can answer. Preferences leads it because
it is the only row here that *changes* MeshTerm rather than describing it; the written
pages close it.
| Feature | What it does | Scripted |
| --- | --- | --- |
| **⚙ Preferences** | How MeshTerm behaves, in eight groups: Device, Sending, TX optimize, Watchtower, Map, History, Display, and Diagnostics. Grouped and staged, saved by one action at the bottom, and written to `preferences.toml` as only the values you changed. [Configuring MeshTerm](configuration.md) has the detail. | `meshterm preferences show / set / reset` |
| **🩺 Diagnostics** | Everything a bug report opens with, in one block: which build this is and how it was installed, the OS, the terminal and its size, the boot-time verdicts that show on no screen (icons, powerline, platform flavour, and why), the radio and its link, and how much history is stored. Nothing private — no keys, passwords, positions, or contact names; the mesh is described as per-table counts and the span they cover. `s` saves it beside the log for attaching. | `meshterm diagnostics [--out PATH]` |
| **📖 About MeshTerm** | What MeshTerm is, where it came from, and the terms it ships under — including the map and font credits and the licence URL. | `meshterm about` |
| **👤 About the author** | The person behind MeshTerm, on the mesh and off it. | `meshterm about-author` |
| **🔗 Join Discord** | The community server: one invite link, and a QR of it for a phone to read. | `meshterm discord` |
| **💰 Support MeshTerm** | What keeps MeshTerm going, and the ways — paid and unpaid — to help it along. | `meshterm support` |
+37
View File
@@ -0,0 +1,37 @@
# Terminals, icons, and the Windows console
Why MeshTerm looks right in some terminals and draws empty boxes in others, what it does
about it on Windows, and how to turn all of that off.
MeshTerm is drawn with emoji icons, braille charts, and powerline path chips. Whether you
see them is up to your *terminal*, not really your font: a modern terminal, asked for a
character its font doesn't have, quietly borrows it from another font on the machine.
That's why the app looks right in Windows Terminal, in VS Code's terminal, and on macOS
and Linux — usually with a font that contains almost none of it. The exception is macOS's
Terminal app, where the charts may draw misaligned: no Mac monospace font has braille, so
it is borrowed from a proportional one at the wrong width.
The classic Windows console — the black `cmd.exe` window a double-click opens on
Windows 10 — doesn't borrow. (Windows 11, 22H2 and later, opens Windows Terminal by
default instead.) It draws what its one font holds and empty boxes for everything else, and
no font fixes the icons there: the only two fonts on a Windows machine with emoji in them
are proportional, and a console won't take a proportional font.
So when MeshTerm lands in that console it just **moves to Windows Terminal** — it says
so, and opens there. Nothing is installed and nothing is changed; it's one window instead
of another, and it's the whole app exactly as the screenshots show it. Windows Terminal is
already on every Windows 11 machine and is a free install on Windows 10.
Where there's no Windows Terminal to move to, and the console's font can't already draw
the charts, MeshTerm offers the next best thing instead — the charts and marks, without
the icons. It ships
[Cascadia Mono PL](https://github.com/microsoft/cascadia-code), Microsoft's own console
font and one of the very few monospace faces that carries braille at all, and will install
it just for you: no administrator rights, nothing downloaded. If you already have a font
that can draw the charts (Cascadia, or another such as Iosevka), it offers to switch to
that one instead. Either way it asks first (`[y/N]`), and the answer defaults to no.
Preferences → Display → Console setup turns all of this off if you'd rather stay put.
Where MeshTerm keeps its state, and how to point a trial run somewhere else, is in
[Configuring MeshTerm](configuration.md).