From b4ea549fb07c0e93c3b54b27c8dbb9854b4b79d9 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Tue, 3 Nov 2026 01:41:06 -0500 Subject: [PATCH] The Clock drift histogram goes on top of the page "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 --- CLAUDE.md | 2 +- docs/guide/features.md | 2 +- meshterm/ui/clocks_screen.py | 37 +++++++++++++++++++----------------- tests/test_clocks.py | 15 +++++++++------ tests/test_managed_nodes.py | 2 +- 5 files changed, 32 insertions(+), 26 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 442659c..be8b53d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -74,7 +74,7 @@ them instead of hand-rolling: | Term | Meaning | |---|---| | node | any device on the mesh โ€” a radio broadcasting packets; roles: companion, repeater, room server, sensor. The umbrella term | -| managed node | a node whose admin password MeshTerm stores (`admin_store`) โ€” the user can log in to it without a prompt. Marked `๐Ÿ”‘` (`marks.MANAGED_ICON`, `*` on the PicoCalc) beside the type mark in the Contacts list, the admin picker, and the node page header; listed first on the Clock drift page. The menu section of the admin tools is **Managed nodes** (JP, 2026-11-03; it was "Other nodes") | +| managed node | a node whose admin password MeshTerm stores (`admin_store`) โ€” the user can log in to it without a prompt. Marked `๐Ÿ”‘` (`marks.MANAGED_ICON`, `*` on the PicoCalc) beside the type mark in the Contacts list, the admin picker, and the node page header; the first list on the Clock drift page, under its histogram. The menu section of the admin tools is **Managed nodes** (JP, 2026-11-03; it was "Other nodes") | | contact | a node your device knows: **discovered** (heard broadcasting, not yet added) or **added** (in the contact list, messageable). Every contact is a node; not every node is a contact | | heard | received from ("last heard", "first heard") โ€” never "seen" in UX text | | key | the full fixed-length value โ€” a node's public key, a channel secret | diff --git a/docs/guide/features.md b/docs/guide/features.md index 36083de..16db759 100644 --- a/docs/guide/features.md +++ b/docs/guide/features.md @@ -28,7 +28,7 @@ This page lists each interactive screen with its scripted equivalent, where one | **๐Ÿ“Š Dashboard** | The live overview of the mesh. It has a two-hour chart of the activity of all packets with a pulse line, the traffic counts of the session for each packet class, and window RF health next to the live numbers of the radio. The screen updates each second. | none | | **๐Ÿ“ฐ Live feed** | Each packet as it arrives, newest first. A row shows the time, the type of the packet (its parsed payload class), and what the packet is about. For an advert, that is the node. For a channel text, it is the channel. For a direct message or a request, it is sender โ†’ recipient. For a trace, it is the tag. The row also shows the reception quality and, for a scoped flood, the region of the flood. Press Enter to open a row in the packet viewer, with its route graph. | none | | **๐Ÿšจ Watchtower** | A passive watcher of the nodes that you star. It gives a silence alarm when a watched node goes quiet. It warns you when the SNR of a node gets worse, and it tells you when the node returns. It also tells you when a node is heard for the first time. It runs in the background during the whole session. Alerts that you did not acknowledge show as a badge in the header. | none | -| **๐Ÿ•’ Clock drift** | How far the clock of each node is from yours. A node with a wrong clock puts wrong times on what it sends, and only its owner can set it. The page starts with your managed nodes (the nodes whose admin password MeshTerm stores), each one always, because you can set these clocks yourself. Then a histogram of all the offsets, from the clocks behind yours, through the clocks in sync, to the clocks ahead. Then each other node whose clock is out of sync, the largest offset first. Press Enter to open the node page. In a chat, a message from a wrong clock shows the time when it arrived, with a `?` mark. | `meshterm clocks` | +| **๐Ÿ•’ Clock drift** | How far the clock of each node is from yours. A node with a wrong clock puts wrong times on what it sends, and only its owner can set it. The page starts with a histogram of all the offsets, from the clocks behind yours, through the clocks in sync, to the clocks ahead. Then it lists your managed nodes (the nodes whose admin password MeshTerm stores), each one always, because you can set these clocks yourself. Then each other node whose clock is out of sync, the largest offset first. Press Enter to open the node page. In a chat, a message from a wrong clock shows the time when it arrived, with a `?` mark. | `meshterm clocks` | | **โณ Time machine** | Everything that the recorder ever heard, as braille charts: reception volume, the median-SNR band, the rhythm of the hours of the day, packets and nodes for each day, and first-ever arrivals. You can switch the time window between 24h, 7d, 30d, and all time. On the PicoCalc, the windows stop at 30d. You can look at one node or at the whole mesh. | none | | **๐ŸŽง Monitor** | The app always records passively. On the command line, this command captures a window of a fixed length in the foreground. It shows each overheard packet as it arrives, and it gives a summary at the end. It transmits nothing. It only listens. | `meshterm monitor --seconds 60` | diff --git a/meshterm/ui/clocks_screen.py b/meshterm/ui/clocks_screen.py index 7097599..dbe70b8 100644 --- a/meshterm/ui/clocks_screen.py +++ b/meshterm/ui/clocks_screen.py @@ -4,20 +4,21 @@ The page reads the clock samples of the last ``clock_report_days`` (refer to :mod:`~meshterm.services.clock_offsets`) and shows them in these sections: -* **Managed nodes** (the nodes whose admin password MeshTerm stores) come first, each one - always, also when its clock is correct, because these are the clocks that the user can - set (JP, 2026-11-03). A managed node with no sample in the window shows its newest offset - from all the history, or ``no sample``. A repeater sends no message, so its adverts are - its only samples, and a new install has none yet. +* **All clocks** is on top (JP, 2026-11-03): a histogram of the offsets, in log steps on + two sides. The clocks behind ours are at the top, the clocks in sync in the centre, and + the clocks ahead at the bottom (JP, 2026-11-02). A clock can be wrong by seconds or by + years, so one linear axis cannot show the two. The centre row is as wide as the + ``clock_tolerance_s`` preference. Each bar is a + :func:`~meshterm.ui.braillechart.meter`, the only bar of the app. +* **Managed nodes** (the nodes whose admin password MeshTerm stores) are the first list, + each one always, also when its clock is correct, because these are the clocks that the + user can set (JP, 2026-11-03). A managed node with no sample in the window shows its + newest offset from all the history, or ``no sample``. A repeater sends no message, so + its adverts are its only samples, and a new install has none yet. * **Adverts refused**: the contacts whose adverts the device drops, because their clocks were once ahead (refer to :attr:`~meshterm.core.models.Contact.adverts_refused_until`), with the date until which it drops them. The node page of each one has the repair. -* **All clocks**: a histogram of the offsets, in log steps on two sides. The clocks behind - ours are at the top, the clocks in sync in the centre, and the clocks ahead at the - bottom (JP, 2026-11-02). A clock can be wrong by seconds or by years, so one linear axis - cannot show the two. The centre row is as wide as the ``clock_tolerance_s`` preference. - Each bar is a :func:`~meshterm.ui.braillechart.meter`, the only bar of the app. * **Out of sync**: each other node past the tolerance, the largest offset first. Enter opens the node page. * **Senders with no key**: the channel senders whose name resolves to no single key. Their @@ -352,6 +353,15 @@ def clock_drift_screen(rows: Sequence[ClockRow], *, tolerance_s: float) -> Selec def node_rows(group: Sequence[ClockRow]) -> list: return [Choice(lambda w, r=r: _row_text(r, tolerance_s, w), r.contact) for r in group] + # The histogram is on top: the shape of all the clocks, before the lists of single + # nodes (JP, 2026-11-03). + counted = histogram(rows, tolerance_s) + peak = max((count for _step, count in counted), default=0) or 1 + items.append(section_heading("All clocks")) + items.append(Separator(lambda _w: _histogram_header(peak))) + for step, count in counted: + items.append(Separator(lambda w, s=step, c=count: _bar_row(s, c, peak, w))) + managed = _by_size([r for r in rows if r.managed and r.contact is not None]) if managed: items.append(section_heading("Managed nodes")) @@ -369,13 +379,6 @@ def clock_drift_screen(rows: Sequence[ClockRow], *, tolerance_s: float) -> Selec items.append(Separator(_refused_header)) items += [Choice(lambda w, r=r: _refused_text(r, w), r.contact) for r in refused] - counted = histogram(rows, tolerance_s) - peak = max((count for _step, count in counted), default=0) or 1 - items.append(section_heading("All clocks")) - items.append(Separator(lambda _w: _histogram_header(peak))) - for step, count in counted: - items.append(Separator(lambda w, s=step, c=count: _bar_row(s, c, peak, w))) - others = _by_size([r for r in off if not r.managed and r.contact is not None]) items.append(section_heading("Out of sync")) if others: diff --git a/tests/test_clocks.py b/tests/test_clocks.py index 10de720..5078fef 100644 --- a/tests/test_clocks.py +++ b/tests/test_clocks.py @@ -93,10 +93,11 @@ def test_the_page_lists_managed_nodes_first_then_the_clocks_out_of_sync() -> Non def test_managed_nodes_come_first_with_a_header_and_no_sample_rows() -> None: - """The managed section is the first one, and a managed node with no sample is listed. + """The histogram is on top, the managed nodes are the first list, and each is listed. - Each table has a header line under its heading. An older offset of a managed node does - not count in the histogram or the title, because it is not from the window. + A managed node with no sample is listed too. Each table has a header line under its + heading. An older offset of a managed node does not count in the histogram or the + title, because it is not from the window. """ from meshterm.services.clock_offsets import ClockOffset @@ -108,12 +109,14 @@ def test_managed_nodes_come_first_with_a_header_and_no_sample_rows() -> None: screen = clock_drift_screen([stale, never, _row("Slow", -3 * 3600)], tolerance_s=TOLERANCE) assert screen.title == "Clock drift ยท 1 nodes ยท 1 out of sync" lines = plain("\n".join(screen.render_body(72))).splitlines() - assert lines[0].strip() == "โ”€โ”€ Managed nodes โ”€โ”€" - assert lines[1].split() == ["NAME", "OFFSET", "LAST"] + assert lines[0].strip() == "โ”€โ”€ All clocks โ”€โ”€" + assert lines[1].split() == ["OFFSET", "#"] + managed_at = next(i for i, line in enumerate(lines) if line.strip() == "โ”€โ”€ Managed nodes โ”€โ”€") + assert lines[managed_at + 1].split() == ["NAME", "OFFSET", "LAST"] assert any("New" in line and "no sample" in line for line in lines) assert any("Old" in line and "2h behind" in line and "4w" in line for line in lines) text = "\n".join(lines) - assert text.index("Managed nodes") < text.index("All clocks") < text.index("Out of sync") + assert text.index("All clocks") < text.index("Managed nodes") < text.index("Out of sync") counted = dict((b.label, n) for b, n in histogram([stale, never], TOLERANCE)) assert sum(counted.values()) == 0 diff --git a/tests/test_managed_nodes.py b/tests/test_managed_nodes.py index d78bb36..b1f304d 100644 --- a/tests/test_managed_nodes.py +++ b/tests/test_managed_nodes.py @@ -175,4 +175,4 @@ def test_the_page_lists_the_contacts_whose_adverts_are_refused() -> None: text = plain("\n".join(screen.render_body(72))) assert "Adverts refused" in text assert f"{until.astimezone():%Y-%m-%d}" in text - assert text.index("Adverts refused") < text.index("All clocks") + assert text.index("All clocks") < text.index("Adverts refused")