From 55797a5bc6f867b568de3d7d96a5784a1079db7f Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Sat, 19 Sep 2026 21:32:57 -0400 Subject: [PATCH] The README is a front door, and the manuals moved behind it It had grown to 580 lines, and most of what a newcomer scrolled past was reference material: the five feature tables, the CLI cookbook with both output faces and the exit statuses, the configuration reference, and the package layout. None of that is what somebody reads while deciding whether to install this. It is 375 lines now and it does onboarding and install -- what MeshTerm is, the screenshots, how to get it running, a quick start, and how the project is run. The rest moved under docs/ behind a new docs/README.md index, which GitHub renders when you browse to the folder. The index also lists the two code surveys, which the README's own table never did. The prose moved by extracting line ranges rather than retyping, so anything that did not need rewording is byte-identical. All 255 relative links across the 13 markdown files resolve, anchors included. Two changes are not relocations. "## Development" is deleted rather than moved, because CONTRIBUTING.md already carried every command in it plus the blame-ignore config and the 72-column gallery gate. And the Windows console section is summarised in Install with the full explanation in docs/terminals.md, since a Windows user meeting empty boxes cannot afford to miss it. Licensing stays where it was. Acknowledgements, the map and font credits, the dependency table and the licence are all still in the README, which is where a redistributor looks and where SignPath Foundation will look for its credit. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 300 +++++++----------------------------------- docs/README.md | 52 ++++++++ docs/architecture.md | 23 ++++ docs/configuration.md | 61 +++++++++ docs/cookbook.md | 106 +++++++++++++++ docs/features.md | 54 ++++++++ docs/terminals.md | 32 +++++ 7 files changed, 376 insertions(+), 252 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/architecture.md create mode 100644 docs/configuration.md create mode 100644 docs/cookbook.md create mode 100644 docs/features.md create mode 100644 docs/terminals.md diff --git a/README.md b/README.md index 5851a2f..7e6aae1 100644 --- a/README.md +++ b/README.md @@ -123,32 +123,22 @@ Whichever you took, you now have a file called `meshterm` — put it somewhere o > Each release page also carries these commands written out for **that exact version**, > next to its own downloads. -### A word about terminals, on Windows +### If your terminal draws empty boxes -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. +MeshTerm is drawn with emoji icons, braille charts and powerline path chips, and whether +you see them is up to your *terminal* rather than your font. Windows Terminal, VS Code's +terminal, and anything modern on macOS and Linux all draw them correctly. The classic Windows console — the black `cmd.exe` window you get from a double-click — -doesn't borrow. 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, 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 Cascadia -it simply switches to it. +does not. So when MeshTerm lands there it **moves to Windows Terminal**, says so, and +opens there; nothing is installed and nothing is changed. Where there's no Windows +Terminal to move to, it offers the charts and marks without the icons instead, and will +install Microsoft's [Cascadia Mono PL](https://github.com/microsoft/cascadia-code) just +for you — no administrator rights, nothing downloaded. Preferences → Display → Console setup turns all of this off if you'd rather stay put. +[Terminals, icons, and the Windows console](docs/terminals.md) explains why any of it is +necessary. > **Trying a build without touching your real data.** MeshTerm keeps everything in > `~/.meshterm` — your history database, contacts, channel keys — and *every* copy of @@ -194,12 +184,17 @@ Setting up for development instead? That's in [CONTRIBUTING.md](CONTRIBUTING.md) ## Documentation +**[The documentation index](docs/README.md)** lists everything, including the two code +surveys kept as a historical record. The short version: + | Read | For | | --- | --- | | **[The command line](docs/cli.md)** | Every subcommand and option, what each prints on the plain and JSON faces, the exit statuses, recipes. | -| **[MeshTerm on the PicoCalc](docs/picocalc.md)** | Building the handheld from a stock PicoCalc: the shopping list, swapping in the Lyra, installing Calculinux and MeshTerm, the soldered LoRa radio. | -| **[MeshTerm on the uConsole](docs/uconsole.md)** | A uConsole with the AIO LoRa board: installing the bridge that fronts its SPI radio as a companion, and connecting to it. | -| [MeshTerm on hardware](docs/hardware.md) | Which of the two manuals is yours, and the two platform flavours MeshTerm draws in. | +| **[What MeshTerm does](docs/features.md)** | Every screen the menu offers, and the command that does the same job without it. | +| [The CLI cookbook](docs/cookbook.md) | Common one-liners, by the thing you're trying to do. | +| [Configuring MeshTerm](docs/configuration.md) | Preferences, device profiles, and everything kept under `~/.meshterm`. | +| [MeshTerm on hardware](docs/hardware.md) | Which handheld manual is yours — the [PicoCalc](docs/picocalc.md) build, or the [uConsole](docs/uconsole.md) bridge. | +| [How the code is laid out](docs/architecture.md) | The layering, and where a new feature goes. | | [CONTRIBUTING.md](CONTRIBUTING.md) | The development setup and the house rules. | | [CHANGELOG.md](CHANGELOG.md) | What changed, newest first. | @@ -232,233 +227,47 @@ connects a uConsole's SPI LoRa board through a small bridge. The device-side scr manuals run are in [`scripts/`](scripts/); not sure which manual is yours? [`docs/hardware.md`](docs/hardware.md) says. -## Features +## What it does -MeshTerm's menu answers one question — *what would you like to do?* — so its five -sections are named for the doing, not the subject. Every interactive screen is listed -here with its scripted equivalent, where one exists. +The menu answers one question — *what would you like to do?* — so its five sections are +named for the doing, not the subject. **Message** is chat, channels, the courier outbox +and contacts. **Watch** is the dashboard, the live feed, the watchtower and the time +machine. **Explore** is the map, the mesh walk, tracing and the trophy case. **This +node** configures the radio in your hand; **Other nodes** administers someone else's +over the mesh. -### 💬 Message — the people on the other end +Nearly every one of them has a mirror `meshterm` subcommand — the same registry builds +the menu and the CLI, so they can't drift apart. The live pictures stay in the menu, +where their meaning is. -| 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. | `meshterm channels list / add / join / import / share / clear` | -| **📨 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` | +**[What MeshTerm does](docs/features.md)** is the full catalogue: every screen, what it +does, and its scripted equivalent where one exists. -### 📊 Watch — what the mesh is doing, and what it did +## Scripting it -| 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. 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 never-before-seen node appears. 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, 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 ` / `config backup` / `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` | -| **🔌 Device discovery** | Enumerate serial *and* Bluetooth LE companions, pick one interactively (or auto-select the only one present), add a network (TCP) companion by host:port, and remember the last good default. A dropped link is detected live and offers to reconnect. | `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. | `meshterm repeater-admin ` | -| **📶 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. | `meshterm tx-optimize --path … [--apply]` | - -## CLI cookbook - -Nearly every menu option is also a subcommand — ideal for scripting, cron, and bots. The -live pictures stay in the menu, where their meaning is (the map, dashboard, live feed, -watchtower and mesh walk); everything else has a command, and every command speaks -`--json`. **[`docs/cli.md`](docs/cli.md) is the full manual**: every command and option, -what each one prints on both faces, and the exit statuses. A taste: +Every command speaks `--json`, and the global options — `--profile/-p`, `--port`, +`--ble`, `--tcp`, `--mock`, `--db`, `--json`, `--quiet/-q` — may be typed before or +after the subcommand. ```bash -# Trace — a trace transmits exactly once; run it again to sample more. +# Every repeater's public key, for a script +meshterm contacts --json | jq -r '.[] | select(.node.type == "repeater") | .node.key' + +# A trace transmits exactly once; run it again to sample more meshterm trace --target Alice --profile yagi -# Force a route through specific repeaters (MeshCore-app style): comma-separated -# contact names and/or hex key prefixes, mixed freely. Blank lets the device route. -meshterm trace --target Alice --path "3d,f2,3d" -meshterm trace --target Alice --path "3d,Bravo-Repeater,f2" - -# Walk a composed circuit with no target at all — out and back your own way -meshterm trace-path --path "3d,f2,3d" - -# Sweep and apply a remote node's TX power -meshterm tx-optimize --path "Bravo-Repeater,Alice" --samples 6 --step 3 --apply - -# Messaging: the live transcript is a menu screen; the CLI takes a subcommand -meshterm chat send --to Alice "on my way" # direct message -meshterm chat send --channel 0 "net in 5" # channel broadcast -meshterm chat history --to Alice -meshterm chat list - -# Store-and-forward: queue for a contact that's offline right now +# Messaging, and store-and-forward for a contact who isn't there yet +meshterm chat send --channel 0 "net in 5" meshterm courier queue Alice "ping me when you're back" --at 18:30 -meshterm courier list # the outbox — waiting and finished -meshterm courier send 3 # force one delivery attempt now -# Remote repeater admin (one transmission per invocation) -meshterm repeater-admin Bravo-Repeater "get name" - -# Device configuration: view, set, back up, restore -meshterm config # show all current settings, one `key value` per line -meshterm config get name # just the value, ready for $(...) -meshterm config set radio_sf 9 # change one setting -meshterm config backup node.toml # archive every setting to TOML -meshterm config restore node.toml --dry-run -meshterm config advert-cadence 2 # auto-advert to neighbours every 2 h (0 = off) -meshterm config advert-cadence 24 --flood # flood the wider mesh daily - -# Passive capture window (records to history; transmits nothing) +# The radio's own settings, and a passive capture window +meshterm config set radio_sf 9 meshterm monitor --seconds 60 ``` -Global options — `--profile/-p`, `--port`, `--ble`, `--ble-pin`, `--tcp`, `--mock`, -`--db`, `--json`, `--absolute`, `--quiet/-q` — may be typed **before or after** the -subcommand: `meshterm contacts --json` and `meshterm --json contacts` are the same run. - -### Two output faces - -*(The short version — [`docs/cli.md`](docs/cli.md) has the whole of it.)* - -The **plain face** is for a person at a prompt. It prints like a standard Unix utility — -no colour, no borders, one record per line, nothing wrapped — and it is allowed to be -comfortable about it: listings are `ps`-style aligned records with **bare names** -(alignment is the delimiter), times are **relative ages** (`now`, `5m`, `never`), and a -route is drawn with arrows — `MockCompanion (00) → Yagi-Repeater (a1) → Alice (d4)`. -`--absolute` swaps every age back for an ISO-8601 instant. A *path*, the spec `--path` -takes back, stays comma-separated hex. `-` is the one token for absent. Errors, -acknowledgements and progress all go to stderr, so a redirect catches only the answer. - -The **JSON face** is the machine contract, and `--json` works on **every** command: - -```console -$ meshterm contacts --json | jq -r '.[] | select(.node.type == "repeater") | .node.key' -b2c3d4e500000000000000000000000000000000000000000000000000000000 -a1b2c3d400000000000000000000000000000000000000000000000000000000 -``` - -No envelope — an array for a listing, an object for a set of facts. One compact line; -`monitor` and `chat listen` stream one document per record. Values are typed, absent is -`null` and never an omitted key, and timestamps are always UTC to the second regardless of -`--absolute`. `--json` changes the rendering, never the report: same records, same exit -status. - -Anything structural should go through `--json` and `jq`. The plain face is for looking at. - -### Exit status - -`0` success · `1` failure · `2` usage error · `3` no device found (nothing was -transmitted) · `4` the device was reached but the operation failed · `5` nothing to -report. The table with its full wording is printed under `meshterm --help` and explained -in [`docs/cli.md`](docs/cli.md#exit-status). - -`5` is the one worth knowing about: it lets a script tell "found nothing" from "worked" -without counting output lines. - -```bash -if meshterm contacts > contacts.txt; then - echo "$(wc -l < contacts.txt) contacts" -elif [ $? -eq 5 ]; then - echo "no contacts yet" -fi -``` - -## Configuration - -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. -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" -connect_on_start = true # false opens the radio link lazily instead of at launch - -[profiles.s3] -port = "COM5" -baudrate = 115200 -default_tx_power = 20 -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 -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 WiFi" -``` - -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. [`docs/cli.md`](docs/cli.md#where-meshterm-keeps-its-state) -lists every file. - -Timestamps are stored as UTC and rendered in your local time. History older than the -`history_days` preference is pruned once at session start. - -## Architecture - -MeshTerm is layered so a new feature is one file in `meshterm/tools/`: - -``` -cli.py Typer app; no subcommand -> interactive menu -context.py AppContext (console, config, repository, device) dependency container -core/ Domain: models, preferences + device profiles, connection abstraction (+ mock) -tools/ Pluggable "menu options"; each self-registers and gets logging for free -services/ Background algorithms (monitor, trace, tx search, courier, watchtower) — no UI -persistence/ SQLite schema, repository, structured logging -ui/ Rich theme/widgets + the full-screen TUI (screens, dialogs, map, chat) -``` - -Adding a feature means subclassing `Tool`, decorating it with `@register`, and -implementing `run()`. The same registry builds both the CLI and the menu, and the base -class wraps every execution in a logged `runs` row automatically. +**[The command line](docs/cli.md)** is the manual — every command and option, what each +prints on both faces, and the exit statuses. +**[The CLI cookbook](docs/cookbook.md)** has more one-liners like these. ## How this project is run @@ -495,19 +304,6 @@ Also here: [CONTRIBUTING.md](CONTRIBUTING.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) · [CHANGELOG.md](CHANGELOG.md) -## Development - -```bash -pip install -e ".[dev]" -python -m pytest -q # tests -ruff check . # lint -ruff format . # format -``` - -Screens are designed to stay readable at **72 columns**. - -Want to send a pull request? See [CONTRIBUTING.md](CONTRIBUTING.md) first. - ## Acknowledgements & attribution MeshTerm stands on the [MeshCore](https://meshcore.io/) project — its firmware and the @@ -534,7 +330,7 @@ short form throughout. The About page inside the app spells out the licence URL. MeshTerm ships **Cascadia Mono PL**, © 2019–present Microsoft Corporation, redistributed unmodified under the [SIL Open Font License 1.1](meshterm/assets/fonts/CascadiaMono-OFL.txt). It's offered to Windows users whose console can't draw the charts — see -[A word about terminals, on Windows](#a-word-about-terminals-on-windows). Microsoft doesn't endorse MeshTerm; the font is +[Terminals, icons, and the Windows console](docs/terminals.md). Microsoft doesn't endorse MeshTerm; the font is simply the right tool, being one of the very few monospace faces that carries the braille block the timelines are drawn from. @@ -577,4 +373,4 @@ license. Each standalone build carries `LICENSE`, `NOTICE` and a generated `THIRD-PARTY-NOTICES.txt` (every dependency's own license text) inside the archive, and the same three files sit beside the downloads on the [releases page](https://github.com/jpmartineau/MeshTerm/releases) -so you don't have to extract one just to read them. +so you don't have to extract one just to read them. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..88597e6 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,52 @@ +# MeshTerm documentation + +Everything that didn't belong on the front page. The [README](../README.md) is the front +door — what MeshTerm is, how to install it, and enough to get a first session running. +This folder is the rest. + +## Using MeshTerm + +| Read | For | +| --- | --- | +| **[What MeshTerm does](features.md)** | Every screen the menu offers, grouped the way the menu groups them, with the command that does the same job without it. | +| **[The command line](cli.md)** | The manual. Every subcommand and option, what each prints on the plain and JSON faces, the exit statuses, and recipes built on `jq`. | +| [The CLI cookbook](cookbook.md) | Common one-liners by task, for when you want the shape of a command rather than its specification. | +| [Configuring MeshTerm](configuration.md) | Preferences versus config, device profiles, and everything kept under `~/.meshterm`. | +| [Terminals, icons, and the Windows console](terminals.md) | Why the icons and charts draw on some terminals and not others, and what MeshTerm does about it on Windows. | + +## Putting it on hardware + +Only if you want MeshTerm running on a handheld's own screen. A MeshCore companion on +USB, Bluetooth or Wi-Fi needs none of this. + +| Read | For | +| --- | --- | +| **[MeshTerm on hardware](hardware.md)** | Start here — which of the two manuals below is yours, and what the device-side scripts do. | +| [MeshTerm on the PicoCalc](picocalc.md) | A stock ClockworkPi PicoCalc to a Linux handheld with a LoRa radio soldered inside: the shopping list, the Lyra swap, Calculinux, and the radio. | +| [MeshTerm on the uConsole](uconsole.md) | A uConsole with the hackergadgets AIO LoRa board, whose SX1262 sits on the host's own SPI bus, fronted as a companion by a small bridge. | + +## Reading the code + +| Read | For | +| --- | --- | +| [How the code is laid out](architecture.md) | The layering, and where a new feature goes. | +| [CLAUDE.md](../CLAUDE.md) | The actual style guide — terminology, UX standards, and the reusable building blocks. Written for AI assistants, and the house rules for everyone. | +| [CONTRIBUTING.md](../CONTRIBUTING.md) | The dev install, the three gates a change has to pass, and what happens to your contribution's licensing. | + +## Historical record + +Two surveys of the code, written the same day against the same commit. They are kept +because a project that writes down its own problems is easier to trust than one that +doesn't — but they are **snapshots of a date, not to-do lists**. Some of what they +describe has been fixed since, and each says so where it has. + +| Read | For | +| --- | --- | +| [Navigation survey](survey-navigation.md) | Every exception to "Esc pops the stack", catalogued. | +| [UI consistency survey](survey-ui-consistency.md) | Everything else in the CLAUDE.md UX standard — six sweeps found nothing, which is the useful part. | + +## Also here + +`screenshots/` holds the captures the README shows and the ones +[meshterm.net](https://meshterm.net) builds its landing page from, so a file in there is +referenced from more than one place. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..6e2c8a2 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,23 @@ +# How the code is laid out + +A map of the package for anyone reading it for the first time. The house rules that +govern what goes where are in [CLAUDE.md](../CLAUDE.md), which is the real style guide; +[CONTRIBUTING.md](../CONTRIBUTING.md) has the dev install and the gates a change has to +pass. + +MeshTerm is layered so a new feature is one file in `meshterm/tools/`: + +``` +cli.py Typer app; no subcommand -> interactive menu +context.py AppContext (console, config, repository, device) dependency container +core/ Domain: models, preferences + device profiles, connection abstraction (+ mock) +tools/ Pluggable "menu options"; each self-registers and gets logging for free +services/ Background algorithms (monitor, trace, tx search, courier, watchtower) — no UI +persistence/ SQLite schema, repository, structured logging +ui/ Rich theme/widgets + the full-screen TUI (screens, dialogs, map, chat) +``` + +Adding a feature means subclassing `Tool`, decorating it with `@register`, and +implementing `run()`. The same registry builds both the CLI and the menu, and the base +class wraps every execution in a logged `runs` row automatically. + diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..a4d6cb4 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,61 @@ +# 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. +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" +connect_on_start = true # false opens the radio link lazily instead of at launch + +[profiles.s3] +port = "COM5" +baudrate = 115200 +default_tx_power = 20 +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 +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 WiFi" +``` + +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. [`docs/cli.md`](cli.md#where-meshterm-keeps-its-state) +lists every file. + +Timestamps are stored as UTC and rendered in your local time. History older than the +`history_days` preference is pruned once at session start. + diff --git a/docs/cookbook.md b/docs/cookbook.md new file mode 100644 index 0000000..c289dd9 --- /dev/null +++ b/docs/cookbook.md @@ -0,0 +1,106 @@ +# The CLI cookbook + +Common one-liners, by the thing you are trying to do. [The command line](cli.md) is the +full manual — every command, every option, both output faces, the exit statuses — and its +own [Recipes](cli.md#recipes) section goes further than this one, into `jq` pipelines and +shell loops. + +Nearly every menu option is also a subcommand — ideal for scripting, cron, and bots. The +live pictures stay in the menu, where their meaning is (the map, dashboard, live feed, +watchtower and mesh walk); everything else has a command, and every command speaks +`--json`. **[`docs/cli.md`](cli.md) is the full manual**: every command and option, +what each one prints on both faces, and the exit statuses. A taste: + +```bash +# Trace — a trace transmits exactly once; run it again to sample more. +meshterm trace --target Alice --profile yagi + +# Force a route through specific repeaters (MeshCore-app style): comma-separated +# contact names and/or hex key prefixes, mixed freely. Blank lets the device route. +meshterm trace --target Alice --path "3d,f2,3d" +meshterm trace --target Alice --path "3d,Bravo-Repeater,f2" + +# Walk a composed circuit with no target at all — out and back your own way +meshterm trace-path --path "3d,f2,3d" + +# Sweep and apply a remote node's TX power +meshterm tx-optimize --path "Bravo-Repeater,Alice" --samples 6 --step 3 --apply + +# Messaging: the live transcript is a menu screen; the CLI takes a subcommand +meshterm chat send --to Alice "on my way" # direct message +meshterm chat send --channel 0 "net in 5" # channel broadcast +meshterm chat history --to Alice +meshterm chat list + +# Store-and-forward: queue for a contact that's offline right now +meshterm courier queue Alice "ping me when you're back" --at 18:30 +meshterm courier list # the outbox — waiting and finished +meshterm courier send 3 # force one delivery attempt now + +# Remote repeater admin (one transmission per invocation) +meshterm repeater-admin Bravo-Repeater "get name" + +# Device configuration: view, set, back up, restore +meshterm config # show all current settings, one `key value` per line +meshterm config get name # just the value, ready for $(...) +meshterm config set radio_sf 9 # change one setting +meshterm config backup node.toml # archive every setting to TOML +meshterm config restore node.toml --dry-run +meshterm config advert-cadence 2 # auto-advert to neighbours every 2 h (0 = off) +meshterm config advert-cadence 24 --flood # flood the wider mesh daily + +# Passive capture window (records to history; transmits nothing) +meshterm monitor --seconds 60 +``` + +Global options — `--profile/-p`, `--port`, `--ble`, `--ble-pin`, `--tcp`, `--mock`, +`--db`, `--json`, `--absolute`, `--quiet/-q` — may be typed **before or after** the +subcommand: `meshterm contacts --json` and `meshterm --json contacts` are the same run. + +## Two output faces + +*(The short version — [`docs/cli.md`](cli.md) has the whole of it.)* + +The **plain face** is for a person at a prompt. It prints like a standard Unix utility — +no colour, no borders, one record per line, nothing wrapped — and it is allowed to be +comfortable about it: listings are `ps`-style aligned records with **bare names** +(alignment is the delimiter), times are **relative ages** (`now`, `5m`, `never`), and a +route is drawn with arrows — `MockCompanion (00) → Yagi-Repeater (a1) → Alice (d4)`. +`--absolute` swaps every age back for an ISO-8601 instant. A *path*, the spec `--path` +takes back, stays comma-separated hex. `-` is the one token for absent. Errors, +acknowledgements and progress all go to stderr, so a redirect catches only the answer. + +The **JSON face** is the machine contract, and `--json` works on **every** command: + +```console +$ meshterm contacts --json | jq -r '.[] | select(.node.type == "repeater") | .node.key' +b2c3d4e500000000000000000000000000000000000000000000000000000000 +a1b2c3d400000000000000000000000000000000000000000000000000000000 +``` + +No envelope — an array for a listing, an object for a set of facts. One compact line; +`monitor` and `chat listen` stream one document per record. Values are typed, absent is +`null` and never an omitted key, and timestamps are always UTC to the second regardless of +`--absolute`. `--json` changes the rendering, never the report: same records, same exit +status. + +Anything structural should go through `--json` and `jq`. The plain face is for looking at. + +## Exit status + +`0` success · `1` failure · `2` usage error · `3` no device found (nothing was +transmitted) · `4` the device was reached but the operation failed · `5` nothing to +report. The table with its full wording is printed under `meshterm --help` and explained +in [`docs/cli.md`](cli.md#exit-status). + +`5` is the one worth knowing about: it lets a script tell "found nothing" from "worked" +without counting output lines. + +```bash +if meshterm contacts > contacts.txt; then + echo "$(wc -l < contacts.txt) contacts" +elif [ $? -eq 5 ]; then + echo "no contacts yet" +fi +``` + diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 0000000..a008732 --- /dev/null +++ b/docs/features.md @@ -0,0 +1,54 @@ +# 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.md) is the manual for the scripted half of it. + +MeshTerm's menu answers one question — *what would you like to do?* — so its five +sections are named for the doing, not the subject. 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. | `meshterm channels list / add / join / import / share / clear` | +| **📨 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. 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 never-before-seen node appears. 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, 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 ` / `config backup` / `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` | +| **🔌 Device discovery** | Enumerate serial *and* Bluetooth LE companions, pick one interactively (or auto-select the only one present), add a network (TCP) companion by host:port, and remember the last good default. A dropped link is detected live and offers to reconnect. | `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. | `meshterm repeater-admin ` | +| **📶 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. | `meshterm tx-optimize --path … [--apply]` | + diff --git a/docs/terminals.md b/docs/terminals.md new file mode 100644 index 0000000..86850a4 --- /dev/null +++ b/docs/terminals.md @@ -0,0 +1,32 @@ +# 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 classic Windows console — the black `cmd.exe` window you get from a double-click — +doesn't borrow. 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, 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 Cascadia +it simply switches to it. + +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).