Channel scopes, scoped packets and the default-scope fix are in the manual and changelog

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-09-24 21:37:38 -04:00
1 parent 169c3272c7
commit 62119e6e28
3 files changed
+57 -6

No files matched your search

+22
View File
@@ -30,9 +30,31 @@ one caveat SemVer makes for a leading zero: while the major version is still `0`
and saving — edits take effect at once and a reboot undoes whatever was not saved. A tree
too big for one reply is said to be cut, and the rest is recovered from the repeater's
own lists. On the command line, `meshterm regions NODE` asks the same question.
- **A channel can be kept to one region.** Give a channel a **Send scope** on its page, and
its messages are flooded into that region alone — only repeaters that carry it relay
them. The chat's title names the scope, and **^R** resends your last scoped message
unscoped when the region is getting it nowhere. A radio that can't send under the scope
refuses before anything goes out, rather than sending it everywhere. On the command line,
`channels scope INDEX [REGION]` reads or sets it, `channels list` gains a `SCOPE` column,
and `chat send --channel N --scope REGION` (or `--scope '*'` for unscoped) overrides it
for one message. Scoped sending needs firmware 1.10; `*` needs 1.16.
- **Packets say which region a flood was scoped to.** The packet viewer's route row, the
message paths title, and a new `SCOPE` lane in the live feed name the region a scoped
flood was sent into, or its code when no region known here matches it. `monitor` gains
the same `SCOPE` column and a `scope` field in `--json`. A scoped packet is kept with
what is needed to name its region later, so one heard today is named once a repeater or
a channel teaches the name. Packets recorded before this version have no scope.
- **A message you sent says what it was sent under.** Its message paths dialog names the
scope, and when nothing relayed it and no repeater known here carries that region, it
says so.
### Fixed
- **The default flood scope is stored the way the firmware and the MeshCore app store it.**
MeshTerm saved it as `#name` where they save `name`, refused a 30-character name the
firmware accepts, and mis-framed a name with an accent. Device config also now refuses
a name no repeater could list back (spaces, commas, a private `$` region).
- **The SPI bridge remembers its channels across restarts.** It kept them only in memory,
so after every reboot the Channels page came up empty while mute settings, which
MeshTerm keeps itself, survived. Update the service (menu option 2) to get the fix.
+31 -3
View File
@@ -105,6 +105,7 @@ of two directories from the same shell.
| `contacts.json`, `channels.json`, `settings.json` | Per-device caches of what the radio last told us, so a screen opens without a round-trip. |
| `adverts.json` | The weekly flood advert's clock: when it was switched on, and when each device's week began. |
| `mutes.json`, `watchtower.json`, `remote.json` | Muted channels; watched nodes and their alerts; per-node remote-admin cache and CLI history. |
| `regions.json` | The regions known by name — and which repeaters carry each — plus every channel's send scope and each repeater's last answer to "which regions do you carry?". What a scoped packet's region is named against. |
| `radio/<spidev>/` | An SPI radio's node, one folder per device node (`radio/spidev1.0/`): its identity key, settings, channels, and contacts, and its log, `node.log`. What firmware would keep in flash. |
| `tilecache/` | Downloaded basemap tiles. |
| `meshterm.log` | The log file. |
@@ -995,7 +996,7 @@ The live transcript is a menu screen; from the command line, pick a subcommand.
| Subcommand | What it does |
| --- | --- |
| `send TEXT --to NAME` | Send a direct message. |
| `send TEXT --channel N` | Broadcast on a channel slot. |
| `send TEXT --channel N [--scope REGION]` | Broadcast on a channel slot, under the channel's scope — or under `REGION` for this one message, `*` for unscoped. |
| `history [--to NAME \| --channel N] [--limit N]` | Print a conversation's stored transcript. Default limit 50. |
| `list` | Every channel and contact with its unread count and last message. |
| `listen [-s SECONDS] [--debug]` | Tail inbound messages live. `-s 0` (the default) runs until Ctrl-C. |
@@ -1061,6 +1062,23 @@ $ meshterm chat send "net in 5" --channel 0 --json
```
`kind` is `"direct"` \| `"channel"` and says which of `node` / `channel` is populated.
A channel send also carries `scope`, in the same shape `monitor` gives a received packet's:
`{"state":"scoped","region":"harbour","code":null}` for a region, `"unscoped"` for a plain
flood, and `null` where it isn't known (a direct message, or a channel with no scope of its
own whose device default couldn't be read). `code` is `null` on a send: the code is a hash
of the packet, and the radio builds the packet.
`--scope` applies to a channel send only. A direct message has no scope of its own to give
— the radio floods it under the device default like anything else — so `--scope` with
`--to` is a usage error (exit `2`), as is a name the firmware would refuse. A radio that
can't send under the scope (firmware older than 1.10, or `*` before 1.16 with a default
scope set) refuses before anything is transmitted, and that is a failure (exit `1`),
never a quiet unscoped send. Quote the `*` so the shell leaves it alone:
```console
$ meshterm chat send "all clear" --channel 0 --scope '*' --json
{"kind":"channel","node":null,"channel":{"slot":0,"name":"#0","public":true,"hash":null},"sent":true,"acked":null,"scope":{"state":"unscoped","region":null,"code":null}}
```
`acked` is `null` on a channel, not `false`: there is no acknowledgement to have, and that
is exactly what one absence token is for — it is also why the plain face prints nothing
there, having no way to say it.
@@ -1105,8 +1123,9 @@ Join on `hash`.
| `import INDEX URL` | Import a `meshcore://channel/add` link. |
| `share INDEX` | Print a slot's share link. |
| `clear INDEX --yes` | Clear a slot, removing the channel from the device. |
| `scope INDEX [REGION] [--clear]` | Show or set the region the channel's messages are flooded into. |
`list` prints `SLOT NAME TYPE HASH`, one record per configured slot, and returns `5` when
`list` prints `SLOT NAME TYPE HASH SCOPE`, one record per configured slot, and returns `5` when
the device has none. (The simulator these examples run against has none, so there is no
captured listing to show; each `--mock` invocation opens a fresh radio, and a slot written
by one run is not there for the next.)
@@ -1125,9 +1144,18 @@ that is actually the answer.)
`clear` is gated behind `--yes`, because a private channel's key is lost with the slot
unless it is saved elsewhere.
`scope` is MeshTerm's to keep, not the radio's: the firmware has no per-channel scope, so
MeshTerm sets the companion's scope around each message it sends on the channel. Setting
one therefore writes nothing to the device, and it follows the channel to any slot it moves
to. With no `REGION`, `scope` prints the channel's region alone, the way `config get` prints
one value — and a channel with none prints nothing and exits `5`. Setting (`scope 1
harbour`) or clearing (`scope 1 --clear`) prints nothing plain. Reading an empty slot exits
`5`, like `share`; writing to one is a usage error (exit `2`), since there is no channel to
scope. `SCOPE` in `list` is `-` for a channel that sends under the device default.
**`--json`.** `list` is an array whose rows are **flat** — this is the one listing whose
record *is* the shared shape rather than carrying one, so a row is
`{"slot":0,"name":"Public","type":"public","hash":"11"}`, with `type` the plain column's
`{"slot":0,"name":"Public","type":"public","hash":"11","scope":null}`, with `type` the plain column's
word rather than the `channel` shape's `public` boolean. Nesting a `channel` key under
every row would make `jq '.[].channel.name'` out of a listing whose every column is
already the channel.
+4 -3
View File
@@ -15,7 +15,7 @@ Every interactive screen is listed here with its scripted equivalent, where one
| 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` |
| **📻 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` |
@@ -24,7 +24,7 @@ Every interactive screen is listed here with its scripted equivalent, where one
| 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. | — |
| **📰 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 where the terminal is wide enough. 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 (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` |
@@ -52,7 +52,8 @@ Every interactive screen is listed here with its scripted equivalent, where one
| 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 <node> <command…>` |
| **🗼 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