Jean-Pierre MartineauandClaude Opus 5
01ca242c98
The NODE lane suited the two classes that name a node and left every other one reading a dash. On this mesh that is half the traffic: the direct messages, requests, responses, returned paths, acks and traces that relay past us naming no origin. So the lane asks each class its own question instead, and the header says SUBJECT — the word that stays true down the whole column. An advert or a telemetry frame is still about its node. A channel text is about its channel, named by the key whose MAC confirms the frame — never by the fingerprint alone, which 256 buckets make no proof at all; a channel we hold no key for reads as that fingerprint and says so. A direct message, request, response, returned path or anonymous request is about the two nodes it travels between, drawn sender → recipient on the hop-sequence widget, so endpoints read exactly as route hops do: resolved names, key-derived hues, our own node white the moment a frame is addressed to us. Too wide, and the sender drops to its hash — the frame is addressed, so the addressee is the half worth the cells. An ack is about the message it answers, a trace about its tag. And an unsigned channel post is filed under its channel rather than the bare word "channel", which named nothing. Half of that was unreadable before because nobody had opened the frame. The companion hands every overheard packet to the library, which decodes the body for exactly two classes — advert and channel text — and leaves the rest as bytes. Those bytes are not opaque: MeshCore addresses a frame in the first few of them, and core/frames.py now reads them, class by class, against the layouts the protocol's own docs/payloads.md publishes. The trace tag is the little-endian uint32 the firmware writes, so it reads as the same number a trace reply reports; an ack's checksum keeps wire order, the form the companion reports its own delivery acks in. Two checks guard every decode, because a wrong slice yields not an error but a plausible-looking hash: the frame's payload version must be v1 (the header reserves two bits for a v2 that widens both hash and MAC), and the body must be long enough for the layout its class promises. Either failing yields nothing at all. The feed opens seeded from history, so any of this that lived only in a live event's raw payload would leave the opening screen blank — the same problem the channel-text crypto trio had. Same answer: three columns (dest/src/tag), written on capture and restored to the very keys the event used, so a replayed frame and a fresh one read identically all the way up. Older rows carry NULL until re-heard. The viewer gained the matching rows: to, from, tag, acks, and a channel for a datagram — whose body is not text, but whose MAC still names it. Verified against the MeshCore protocol documentation and firmware source, then corroborated on the air: every frame captured off the radio has a body length that decomposes exactly into its documented layout, an anonymous request's 51 bytes (1 + 32 + 2 + one AES block) included. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
15 KiB
15 KiB
MeshTerm
A full-screen terminal companion for MeshCore LoRa mesh devices — tune your radio, chat across the mesh, watch the network live, and keep a longitudinal record of everything you overhear, all from a connected serial, Bluetooth, or network (TCP) companion.
MeshTerm is interactive by default: a modern, keyboard-driven TUI built on
Rich and
prompt_toolkit. It is also
fully scriptable — every screen has a mirror meshterm subcommand — so the same
capabilities drive both an evening of exploring the mesh and a cron job. Every packet the
radio overhears is recorded to a local SQLite database, so the longer you run it, the more
your mesh's history is worth.
Why MeshTerm
- One tool, two faces. Launch
meshtermfor a full-screen menu; pass a subcommand for a scripted one-shot. The registry that builds the menu builds the CLI, so they never drift apart. - It remembers. A passive monitor logs every overheard advert and telemetry frame — SNR, RSSI, shared location — to SQLite from the moment the radio opens. Maps, contact lists, charts, and the Time Machine all read back that history.
- It measures. Live trace with per-hop reliability, a coarse→refine→verify TX-power sweep, and a walkable graph of how the mesh actually hangs together.
- It talks. Live channel and direct messaging, store-and-forward courier delivery for
contacts that aren't there yet, and shareable channels as QR codes and
meshcore://links. - It connects however your companion does. Serial (USB), Bluetooth LE, or TCP (a WiFi board or a network proxy) — the discoverable transports are auto-found and picked interactively, a network device is named by hand, and every kind reconnects live when a link drops. No radio? A built-in simulator covers development.
- It works offline. The street map caches OpenStreetMap tiles to disk and falls back to a blank grid when there's no network — it never needs the internet to run.
Install
git clone <your-fork-url> meshterm
cd meshterm
pip install -e ".[dev]"
Python 3.10+ is required (matching the meshcore library). The [dev] extra adds
pytest and ruff; drop it for a runtime-only install (pip install -e .).
python -m pytest -q # run the test suite
Quick start
# Interactive full-screen menu (auto-discovers serial + Bluetooth companions)
meshterm
# Connect over Bluetooth (address from `meshterm devices`)
meshterm --ble AA:BB:CC:DD:EE:FF info
# Connect over the network to a TCP companion (host[:port], port defaults to 5000)
meshterm --tcp 192.168.1.50 info
# No radio attached? Use the built-in simulator for development.
meshterm --mock
Features
MeshTerm's menu is organised into four sections. Every interactive screen is listed here with its scripted equivalent, where one exists.
🛰 Mesh — what's going on out there
| 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. | — |
| 🌍 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. | meshterm map (one-shot render) |
| 🌐 Mesh atlas | 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 atlas answers how it hangs together. | — |
| 🚨 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. | — |
| 📡 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 |
💬 Messaging
| 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 |
⚙ Device management
| Feature | What it does | Scripted |
|---|---|---|
| 📋 Device info | The connected companion's identity and full radio configuration at a glance. | meshterm info |
| 🔨 Device actions | Immediate 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. | config backup / restore / reboot / … |
| 🔧 Config | View and stage changes to every setting (name, radio, behaviour, experimental) for review before applying, with TOML backup/restore. | meshterm config / config set <key> <value> |
| 🗼 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 <node> <command…> |
🧰 Tools — measure and explore
| Feature | What it does | Scripted |
|---|---|---|
| 👥 Contacts | This node and its known contacts — a recency heat-map, overheard packet counts, and full public keys with the path-hash prefix highlighted. | meshterm contacts |
| 🧭 Trace | 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 … |
| ⚡ TX-power optimization | 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] |
| ⏳ 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 |
| 🔌 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 |
CLI cookbook
Every menu option is also a Typer subcommand — ideal for scripting, cron, and bots.
# 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"
# Sweep and apply a remote node's TX power
meshterm tx-optimize --path "Bravo-Repeater,Alice" --samples 6 --step 3 --apply
# Messaging: live chat in the menu, or scripted from the CLI
meshterm chat # interactive: pick a conversation, chat live
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
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 (before the subcommand): --profile/-p, --port, --ble, --ble-pin,
--tcp, --mock, --db, --json, --quiet/-q.
Configuration
MeshTerm runs with zero configuration — 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. Define a config file only to give your hardware stable
aliases or tune behaviour.
Copy config.example.toml to ~/.meshterm/config.toml:
default_profile = "s3"
trace_cooldown_s = 1.0
direct_message_soft_retries = 2 # auto-resend an unacked DM up to N extra times (0–2)
history_days = 365 # days of overheard-packet history to keep (0 = forever)
[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"
Timestamps are stored as UTC and rendered in your local time. History older than
history_days 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, config + 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.
Development
pip install -e ".[dev]"
python -m pytest -q # tests
ruff check . # lint
ruff format . # format
Screens are designed to stay readable at 72 columns.
Acknowledgements & attribution
MeshTerm stands on the MeshCore project — its firmware and the
meshcore Python companion library are what make talking to the radio possible.
Map data
The street map is rendered from © OpenStreetMap contributors data, served as vector tiles by OpenFreeMap. OpenStreetMap data is available under the Open Database License (ODbL). Tiles are decoded with a small built-in reader for the Mapbox Vector Tile format.
Open-source dependencies
MeshTerm is built with these libraries; each is used under its own license (see the respective project for the authoritative terms):
| Library | Role | License |
|---|---|---|
| meshcore | Companion-device protocol (serial / BLE) | MIT |
| pycryptodome | AES/HMAC for decrypting overheard channel packets | BSD-2-Clause / Public Domain |
| pyserial | Serial-port enumeration and I/O | BSD-3-Clause |
| bleak | Bluetooth LE scanning + connection | MIT |
| Typer | Scripted CLI (subcommands mirror the menu) | MIT |
| Rich | Console rendering | MIT |
| prompt_toolkit | Full-screen interactive TUI | BSD-3-Clause |
| Segno | Pure-Python QR codes (channel share links) | BSD-3-Clause |
| tomli / tomli-w | TOML config read/write | MIT |
License
Copyright © 2026 Jean-Pierre Martineau.