Packet viewer: show a trace's links, and say whose signal the reading is

A trace reports on the mesh as it crosses it — every node that forwards
one records the SNR it heard its predecessor at — so an overheard trace
arrives carrying a reading per hop travelled. Those are now a `links` row,
in walk order and coloured by quality like every other reception figure,
which for a walk out and back through a repeater reads as one strong
outbound leg and two weaker ones home.

The card's standing caveat also stopped being true. "Reception describes
the last relay, not the origin" is right for a relayed frame and wrong for
one that crossed nothing — those are only listed at all as of this
branch — where the reading *is* the origin's, and worth saying so: a frame
heard straight off its sender is the best evidence a link ever gives.
This commit is contained in:
Jean-Pierre Martineau committed 2026-08-22 14:03:23 -04:00
1 parent c246fb8080
commit 71f60c0eeb
2 files changed
+82 -3

No files matched your search

+37 -3
View File
@@ -95,7 +95,7 @@ _RAW_ROW_SKIP = frozenset({
"pkt_payload", "pkt_hash", "raw_hex", "payload", "payload_length", "recv_time",
"chan_hash", "cipher_mac", "crypted", "message", "msg_hash", "sender_timestamp",
"attempt", "txt_type",
"dest_hash", "src_hash", "src_key", "trace_tag", "ack_crc",
"dest_hash", "src_hash", "src_key", "trace_tag", "ack_crc", "trace_snrs",
"adv_key", "adv_name", "adv_type", "adv_lat", "adv_lon",
})
@@ -752,9 +752,17 @@ class PacketViewer(Screen):
if route:
rows.append(("route", Text(route.replace("_", " ").lower())))
rows.append(("via", self._via_path(entry)))
# Which node the SNR beside it actually measured. On a relayed frame that is the
# last repeater, and saying so stops the figure being read as the origin's signal;
# on one that crossed nothing it *is* the origin's, which is worth saying outright
# — a frame heard straight off its sender is the best evidence a link ever gives.
relayed = bool([hop for hop in (entry.path or "").split(",") if hop])
rows.append((
"", Text("reception describes the last relay, not the origin",
style="faint"),
"", Text(
"reception describes the last relay, not the origin" if relayed
else "reception describes the sender itself — nothing relayed it",
style="faint",
),
))
# A chain that names one hop twice reads as a mistake until it is explained; the graph
# below draws that hop twice too (see ``_graph_lines``), so the note covers both.
@@ -809,11 +817,37 @@ class PacketViewer(Screen):
rows.append(("from", self._endpoint(src)))
if raw.get("trace_tag"):
rows.append(("tag", Text(raw["trace_tag"], style="muted")))
readings = raw.get("trace_snrs")
if readings:
rows.append(("links", self._link_readings(readings)))
if raw.get("ack_crc"):
# An ack identifies the message it answers, by that message's own checksum.
rows.append(("acks", Text(raw["ack_crc"], style="muted")))
return rows
def _link_readings(self, readings: list[float]) -> Text:
"""How well each leg of a trace's walk was heard, in the order it walked them.
A trace is the one class that reports on the mesh as it crosses it: every node
that forwards it records the SNR it heard its predecessor at, so an overheard
trace carries a reading per hop travelled — and how many there are says how far
along its route the frame had got when we caught it. Read oldest hop first, the
same direction a path line runs, each coloured by :func:`~meshterm.ui.theme.
snr_style` like every other reception figure in the app.
Args:
readings: The per-hop SNRs in dB, in walk order.
Returns:
The readings as one separated line.
"""
line = Text()
for at, value in enumerate(readings):
if at:
line.append(SEP_COMPACT, style="muted")
line.append(f"{value:+.2f} dB", style=snr_style(value))
return line
def _endpoint(self, value: str) -> Text:
"""One end of an addressed frame: its resolved name, then the key it was named by.
+45
View File
@@ -369,3 +369,48 @@ def test_packet_viewer_reception_row_keeps_rssi_on_one_line() -> None:
# Where the cells are there, the roomy separator stays.
set_platform(REGULAR)
assert " · " in _plain(_viewer(entry).render_body(80))
def test_packet_viewer_shows_a_traces_per_hop_links() -> None:
"""A trace reports on the mesh as it crosses it, so the card shows every leg it heard.
One reading per hop travelled, in walk order — which for a walk out and back through
a repeater means the return legs read weaker than the outbound one.
"""
entry = PacketEntry(
when=utcnow(), kind="packet", path="",
raw={"payload_typename": "TRACE", "route_typename": "DIRECT",
"trace_tag": "52a37882", "trace_snrs": [13.25, -5.0, -4.25]},
)
body = _plain(_viewer(entry).render_body(80))
assert "🎯 TRACE" in body
assert "links" in body
for reading in ("+13.25 dB", "-5.00 dB", "-4.25 dB"):
assert reading in body, reading
assert "trace_snrs" not in body # folded into its own row, not dumped raw
def test_packet_viewer_omits_links_for_a_trace_nobody_relayed() -> None:
"""No hop has measured it yet, so there is no link row to draw — not an empty one."""
entry = PacketEntry(
when=utcnow(), kind="packet", path="",
raw={"payload_typename": "TRACE", "trace_tag": "52a37882", "trace_snrs": []},
)
assert "links" not in _plain(_viewer(entry).render_body(80))
def test_packet_viewer_says_whose_signal_the_reading_is() -> None:
"""The SNR beside a frame measures its last transmitter — which is not always a relay.
A relayed frame's reading belongs to the repeater that passed it on, and reading it as
the origin's would be wrong. One that crossed nothing was heard straight off its
sender, so the reading is exactly that link — the strongest evidence there is.
"""
def note(path: str) -> str:
entry = PacketEntry(when=utcnow(), kind="packet", path=path, snr=9.0,
raw={"payload_typename": "TRACE"})
return _plain(_viewer(entry).render_body(80))
assert "last relay, not the origin" in note("a1b2c3,d4e5f6")
assert "the sender itself" in note("")
assert "last relay" not in note("")