A companion, a room server, or a sensor does not relay a trace with the
firmware defaults (allowPacketForward in Mesh.cpp: client repeat is off,
and allowed only on 433.000, 869.495, and 918.000 MHz; disable_fwd is on).
A walk that turned at one of them never came home: the history held 36
companion traces and no reply from a real one.
The route to such a node is the same. Only the walk changes: it turns at
the last relay of the route, and the node is not in the spec. The route
out of a walk that comes home is still the full route to the node, so
the Device route row can offer it for DMs and admin.
- relays_traces() in models states the rule. render_forced_spec takes
relays=False, and forced_outbound reads the route back from a walk.
- services/trace_plan holds the route choice that the trace screen made
inline (radio route, outbound paths, best observed, last trace,
direct), so the CLI uses the same one.
- The trace screen names the relay where the walk turns, in a line under
the route. With no relay to turn at, Trace is dim. A neighbour that
does not relay gets "no relays" offered on the Device route row, with
the packets heard directly as its proof.
- The trace session turns a caller's spec (node page, Message paths) at
the last relay, so the callers do not need the rule. A sender that is
not a contact gets its type from its stored adverts.
- The composer and Explore paths turn the walk at the last hop.
- `meshterm trace -t NAME` with no --path walks the menu's route and says
on stderr where it turns. With no known relay, it is a usage error.
- The connection turns a device-routed trace at the last learned relay.
The simulator now stops a walk at a node that does not relay, as the
mesh does, and the tests that walked through Alice walk repeaters.
The picker keeps one list with no mark, sorted as before (JP's choice).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Enter on an arrival in the Message paths dialog (^P in a chat) opens a trace
of the route that the row draws, walked from our node:
- A received message is traced back to its sender: the relays in reverse,
out to the sender, and back on the mirror (Trace target).
- A sent direct message is traced out to its recipient on the relays in
order (Trace target).
- A sent channel message came back to our node, so its relays are the full
walk (Trace path).
- A sender with no key turns the trace at the first relay (Trace path).
- A direct-routed copy carries only the rest of its route, so it offers no
trace, and the hint does not show Enter there.
The trace screen opens idle and armed. Nothing transmits until the user
starts a trace. The dialog stays pushed under it as a hub, so Esc from the
trace comes back to the same dialog and highlight. In Trace target, a trace
that comes home lights the Device route row, so the route a message took can
become the radio's route to that contact.
A sender that is not a contact opens on its key, and open_trace takes a
label so that the screen shows its name instead of the hex.
Refs: #34
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Explore paths → Probe all walks each candidate once. When the user adopts a
candidate, that trace already measured exactly the adopted route, so the
screen now starts the route with it instead of with no traces. The Device
route row then offers a route that came home at once, with no second
transmission to prove it again.
The session keeps the probe traces by spec (seed_traces). Any later change to
a probed spec starts with them too, because they measured that route.
Refs: #34
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Trace target gets a Device route row after Explore paths, for a target that
the radio has as a contact. It says what the radio holds now, and Enter opens
the node page's Device route popup.
A trace that came home walked its route out and back, the best proof that
MeshTerm can have for a route. When its route out is not the radio's route,
the row turns green: "Use this route for DMs and admin — 4/5 came home…".
Nothing interrupts the session. The popup then shows the traced route with
its proof, and offers "Use the traced route" and, with a site, "Use and keep
it" before the usual rows. The popup changes no path of the trace screen, so
its traces and medians stay.
The gallery's Trace specimen draws the green row at both widths, and the
features guide says what it does.
Refs: #34
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Routes tab ends on a "Device route · …" row that says what the radio
holds now: none (it floods), or the hop count and how the radio got it
(learned, set by you, kept at a site). Enter opens one popup that turns its
page:
- The first page draws the route and the kept route (with why a kept route is
not in the radio: its first hop went silent), then the actions: Set the
route…, Keep this route (or Stop keeping it), Forget the route, Discover
routes…. With no site, Keep says that it needs one and opens Outbound paths.
- Set the route… turns to a picker: the suggested route first (an outbound
path, then the best way on), the routes heard, no relays, and Compose…, which
opens the path composer. A picked route replaces a kept route too.
- Discover routes… waits for the cooldown, sends one path discovery, and shows
the route each way. "Use this route" sets the route out.
After a change, the Routes tab is drawn again in place, with the highlight on
the row. Gallery specimens for both pages, and the glossary and features guide
name device, kept, and saved routes and path discovery.
Refs: #34
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The user names the ways out of their node, one or more hops long, in order.
Each site of this computer (Home, Foulab) has its own list, one site is
active, and a fixed device keeps its own list.
- Explore > Outbound paths: the sites with the active mark, the fixed
devices, and a staged editor for each list. Each path shows how well its
first hop hears us (out) and how well we hear it (in). Measure sends one
trace out along a path and back, after the cooldown.
- The path composer has an outbound mode, and puts the active paths first
while the insertion slot is at our node (trace target, trace path, the
TX sweep route).
- MeshTopology.outbound_scenarios: one route through each path. It scores
from the link after the path, lets the user's order win a near tie, and
skips a path whose first hop was silent for outbound_silent_hours. These
routes lead Explore paths, the node page's Routes tab, and the trace auto
route, ahead of a device route that starts on another hop.
- A first link out of our node is scored from what the far end measured,
when a trace gave such readings.
- The site suggestion: when the radio hears the first hop of another site
three times, the main menu asks to use that site and says what it heard.
"Never suggest" sets the new suggest_site preference off.
- CLI: meshterm outbound [show|sites|use|set|remove|fix|unfix], plain and
--json.
Refs: #35
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The reporter of #28 asked for a way to clear one or all of the stored admin
passwords. Del in the node picker forgets one. This adds the other: a
"Forget passwords" row in the Managed nodes section of the menu, behind the
red typed confirm (type FORGET), which names the nodes it will forget. It
also forgets the password of a node that is no longer a contact, which no
list shows. With nothing stored, it says so and asks nothing.
On the CLI it is `forget-admin-passwords --yes`: without --yes it is a usage
error, and with it the answer lists the nodes it forgot (NAME, LAST_LOGIN,
KEY). It exits 5 when nothing was stored, and works with no device.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The menu had no way to make MeshTerm forget an admin password (#28). Now Del on a
managed node in the node picker asks first (amber, Cancel or Forget), then forgets
the password. The list refreshes in place: the node leaves "Managed nodes" and the
highlight stays on it. The footer shows "Del forget" only on a managed row, and the
PicoCalc lane shows its Delete chip.
The first page of the TX optimize dialog has the same rows, so it takes the same
Del. A wizard page can now carry a Del key and an on_delete handler, and a turned
page brings its own Del key, so the second page shows none.
The feature guide also describes the new-password offer of the previous commit.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
"Sync their clocks…" now opens a dialog that lists every managed
repeater and room from the start: ○ waiting, a spinner with what it
waits for (the transmit cooldown, the login, the command), then ✓ with
the node's reply or a red ✗ with the reason. Long reasons wrap under
the name. Esc stops the run after the node in progress; the OK chip
closes the dialog once the run is done.
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
The bulk row now shows whenever the page has a managed repeater or room
server, and it syncs each one whatever its offset: a repeater with no
battery restarts from its build date at each power cycle, and the page
only learns that at its next advert. Managed companions still have no
clock sync command, so they are never included.
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
The Managed nodes section ends on "Sync their clocks…" when a managed
repeater or room server is out of sync or has no sample. One confirm,
then each node in turn: a cancellable transmit-cooldown wait, a quiet
login with its stored password, and "clock sync"; one summary names
each result. "Adverts refused" moves to the end of the page.
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
"All clocks" now opens the page, so the shape of every clock comes
before the lists of single nodes; Managed nodes is the first list under
it, then Adverts refused, Out of sync, and Senders with no key.
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
A room stamps posts with its own clock and sends only posts newer than
the companion's sync_since, so after its clock goes back (often a
reboot) it sends nothing new. When a room's newest stored post is later
than its clock now (from its clock offset), its node page shows
"posts blocked" and offers "Ask for all its posts again…". The repair
removes the room contact and adds the same raw record back, since the
firmware gives only a new contact a sync_since of zero, then logs in
with the stored password. Device.reset_room_sync tries the add twice and
says plainly if the room is left off the device.
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
A node whose admin password MeshTerm stores is now a "managed node": a
🔑 beside the type mark in the Contacts list, the admin picker (its
first section, renamed from "Remembered admins"), and the node page
header. The menu's "Other nodes" section is now "Managed nodes".
Contacts carry adverts_refused_until: the device's stored advert time
when it is in the future, so the firmware's replay check drops every
new advert. The node page shows it and offers "Accept its adverts
again…", which rewrites the device's own record with only last_advert
lowered (Device.accept_adverts_again). A managed repeater or room gets
"Sync its clock…". The Clock drift page lists refused contacts.
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Managed nodes are now the first section and are always listed: a node
with no sample in the window shows its newest offset from all history,
or "no sample". Each table has a header line under its section heading
(NAME / OFFSET / LAST, and OFFSET / # over the histogram, now under
"All clocks"). Older offsets do not count in the histogram or title.
The CLI lists each managed node too, with null fields when it has none.
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
A new Watch tool, "Clock drift" (meshterm clocks): a histogram of the
clock offsets in log steps on two sides, then the managed nodes, then
each other node out of sync, largest offset first; Enter opens the node
page. Channel senders with no key are listed by name. When most clocks
disagree with ours the same way, a note says our own clock may be wrong.
The CLI lists every sender with offset_s, samples, and flags. A new
clock_report_days preference sets the window. The demo world gets four
wrong clocks.
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Passwords, channel secrets, pairing PINs, and private keys reached the DEBUG log and
the runs table in plain text: every chat run stored its channel secret inside the
Conversation repr, and --password, --secret, channel links, and config set device_pin
were stored as typed. meshterm.core.secrets now hides each one as <secret> by its
shape (a secret-named key, record, set operation, or dataclass field; bytes; a Secret;
a remote `password`/`set guest.password` command; name=value in text), and by value
for each secret MeshTerm has read or sent. Both log handlers and the runs table go
through it, always. The remote CLI history keeps `password ` without its value. Schema
v20 hides the secrets that older versions stored.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Off by default. Each masked value keeps a tidbit (j*********u, DA:xx:xx:xx:7C:7C,
192.xxx.x.180, m******e.local), so two radios stay two radios. The log masks each
line as it is written; diagnostics take --anonymize/--no-anonymize, and the page
toggles with `a` (Shift+F3 on the PicoCalc). Refs #31.
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
MeshTerm already stores every channel packet it hears, including those
on channels the device doesn't have. A packet names its channel only by
a one-byte hash, but a public channel's key is derived from its name, so
a candidate name can be tested: derive the key and check the packet's
MAC with it, exactly as the firmware does before decoding. The guide
tries the device's channels, Public, every #name mentioned in a stored
message, and every known region. On one desktop history that names 25
public channels.
A guessed name has to match at least two messages before the guide
shows it. The check compares three bytes, and with thousands of names
against thousands of packets roughly one false match is expected. The
candidates are grouped by their hash byte, so each packet only checks
the ~1/256 that could match; the naive loop took 40 s, this takes 1 s
on 31,000 messages, in a worker thread under a busy card, and the result
is kept for the session while its inputs are unchanged.
"Channel guide…" is the first row of "Add a channel" on the Channels
page, and it stays there when every slot is full. Channels not on the
device come first, and Enter adds one to the next free slot. Channels
the device already has follow with a ✓ the highlight doesn't walk, and a
closing line counts the messages no name matched. Each row shows the
message count, the age of the last message and seven days of activity.
`channels guide` lists the same channels on the command line.
Refs: #25
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
A new device ships with Public and nothing else, so changing devices
meant adding every channel again by hand: each private key pasted, each
# name typed, each send scope and mute set again. The Channels page now
has an "Export and import" section. Export writes every channel to one
TOML file, in slot order, with its key, its send scope and its mute.
Import reads such a file and adds its channels to the device.
Import never removes a channel. The channels of the file go first, in
the file's order, and whatever else the device holds follows them. A
channel with no free slot is reported, not forced in. Before anything is
written, a dialog shows the plan (what is added into which slot, what
moves) and ends on "Nothing is removed from the device." The slots are
read again in full before the plan is made, because a probe cut short
makes an occupied slot look free.
The file uses the same [[channels]] table as config backup, so a config
backup imports too. A # channel carries no secret, since the device
derives its key from the name. A private channel carries its key, so the
file is written readable by its owner only, and the export says how many
private keys it holds.
On the command line, `channels export FILE` writes the file and prints
its path, and `channels import --file FILE [--dry-run]` prints the
device's layout after the import, one row per channel with add, move,
keep or skip. `channels import INDEX URL` still imports a single link.
Refs: #25
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The four user guides and the manuals for the PicoCalc, the uConsole, and
the Cardputer Zero. Procedures are numbered steps, with a WARNING or a
CAUTION before each step that has a risk. The step headings use a colon,
and each link to them changed with them. Quoted error messages are in
quotation marks, and the menu question is quoted as the app shows it.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Hold-to-quit was the Cardputer's alone. It is now MeshTerm's gesture
everywhere a key can be seen coming up, which a terminal never reports:
- The emulator's window, for either handheld, which reads its own keys
as the Cardputer's panel does.
- A terminal's Esc, where the keyboard can be asked whether it is still
down: GetAsyncKeyState on Windows, as the right-Ctrl rescue already
asks, and EVIOCGKEY on Linux wherever the keyboard's event device
opens (the PicoCalc, a uConsole, a user in `input`). It reads the key
state only, no events.
An Esc arriving while its key is still down is held back as a hold:
delivered as it comes up, a box after a second, gone at three. The
keyboard's repeats are part of the hold, a key typed during it goes in
behind the Esc, and on a VT stream the last repeat, which prompt_toolkit
can parse after the key is up, is dropped rather than going back a
screen behind a box the reader just let go of. On macOS and over SSH Esc
is unchanged.
SIGTERM is a quit for the interactive menu on every platform now, not
only under the Cardputer's launcher: a system shutting down gets the
same clean exit, terminal and console font restored.
EVIOCGKEY checked on the Cardputer's arm64 kernel; the Lyra was offline.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The radio on spidev1.0 was listed as a bare "SPI radio" and reported
"MeshTerm SPI node", because spidev1.0 alone could be any Pi. A
uConsole now proves itself by its own screen: ClockworkPi's uConsole
overlay declares the panel `cw,cwu50`, which no other machine carries
(the DevTerm's is cw,cwd686; the CM's model string and the AXP228 and
backlight are shared). Seen on JP's CM5 uConsole.
`BuiltinRadio` takes a device-tree `compatible` beside its marker path,
read once a run from /sys/firmware/devicetree/base. The named AIO comes
first in BUILTIN_RADIOS; without the panel, the unnamed entry still
lists spidev1.0 on the AIO's wiring as before.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
On a Cardputer Zero the device screen lists the Cap as "Cap LoRa-1262",
and --spi reaches it, with no profile: its wiring ships beside the
AIO's, listed when the board's own ext_5v_out switch says this is a
Cardputer Zero (spidev0.1 alone would claim every Pi with SPI on).
The Cap needs two things before the chip answers, and the wiring can
now say both. `leds` sets the switches the device tree hands to
gpio-leds — ext_5v_out powers the header, ext_usb_gpio_fun=0 keeps
the reset and interrupt pins on GPIO rather than USB — and puts them
back when the node ends, so the header is unpowered again after
MeshTerm quits. `pi4io_*` drives the Cap's PI4IOE5V6408 at 0x43, which
enables the RF path; a silent expander is reported as the Cap not
being attached.
Checked on the hardware: reset 26, busy 22, irq 23 on spidev0.1 (the
lines M5's factory test drives), the node comes up from a cold
header, and it hears the mesh at +12 dB.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Joining a room moves out of Chat into a Rooms page beside Channels. It
lists every room server the radio knows, joined ones first, with each
room's access, unread count, last post and last-heard time. Each room
has a page: join, log in again, change password, open the board, forget
it, or delete its stored posts. Chat now lists only joined rooms, the way
it lists only channels on a slot, and only a joined room raises the
unread badge. chat join becomes rooms join, alongside rooms list and
rooms forget.
"No reply" told the reader nothing, because a room is just as silent for
a wrong password as for a login that never reached it. Testing on
hardware showed the commonest cause is neither: a login sent along the
route the radio had learned met silence, and the same login by flood was
accepted in eleven seconds. A silent login is now explained from what is
known: how it went out, when the room was last heard, and whether this
password has worked before. It offers the one next step that evidence
points at:
- Try by flood, after a learned route met silence. The radio forgets
the route (local, nothing transmitted), then sends the login once.
- Try again…, after a flood met silence. The prompt reopens with the
password filled in, so Enter resends it and typing replaces it.
- Add it & try again, when the radio doesn't hold the room as a contact.
Every retry is a button press, and none is ever sent on its own. A
password over 15 bytes is refused at the prompt, since MeshCore sends
only the first 15.
On the board, a failed or unfinished login used to leave the compose
line taking posts the room would drop. It now opens only while we are in
and may post, and otherwise says why and what to press. Opening a joined
room that has gone quiet logs in in the background. ^L runs the
explained flow.
Underneath, the login exchange listens for the radio's own confirmation,
matched to the login by its expected ack. It records whether the login
went by flood or along a route, or the radio's reason for not sending it
at all. This also corrects the debug log: "send unacknowledged" read the
library's wait for the *answer* as the send. On hardware the radio
confirms in under 0.1 s. Device.reset_route is new. The simulator learns
routes, can be given a stale one, and refloods.
Refs: #24
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
chat join logs in to a room server and prints what it allowed: member,
admin or read-only. It uses --password, or the password MeshTerm
remembers for the room. A room says nothing to a wrong password, so a
join that hears nothing fails (exit 4) and names both possible reasons.
send --to a room posts to it, and its receipt says kind "room". A room's
history names each post's author where a direct transcript names the
peer, drawn the way a route draws a hop: "Alice (d4e5f6a7)", or the bare
hash when nothing names the key. The document carries the author on
every row, null outside a room, so history answers in one shape for
every kind of conversation; listen streams it too. chat list calls a
room a room.
The CLI manual, the features guide and the README describe rooms, and
CLAUDE.md adds room and post to the lexicon, 📌 to the icons, and ^L to
the chord list.
Refs: #24
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The September messages reached the device picker and the command line, but
three other places still lost them. The reconnect dialog retried every
failure in silence, so a device that came back and refused (its port taken
by the MeshCore app, a stale pairing) kept the spinner up forever; from the
second failure in a row it now shows the reason under the spinner, and goes
back to waiting if the device is unplugged again. A device named on the
command line skipped the picker, and a failed start was dropped unlogged; it
is now shown before the menu opens. And a failed open left the dead device
behind, so is_connected said yes and every later tool failed with "not
connected": it is dropped, and the next tool tries again and says why.
TCP failures are named one by one (host not found, nothing on the port, no
route, no answer, hung up) instead of all reading "no response from a
MeshCore companion". A failure MeshTerm has no name for is no longer called
"not a MeshCore device": it is said in its own words, its traceback is
logged once, and the dialog says where the log file is. The tool-failure
dialog stops reading an error's brackets as markup, which had silently
deleted "[org.bluez.Error.Failed]" from Linux Bluetooth errors.
docs/guide/connecting.md lists the TCP messages and where each message
appears.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
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>