From e2146f9092097d467cc06bd112138cfa75eec869 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Sat, 7 Nov 2026 13:06:08 -0500 Subject: [PATCH] The topology keeps the direction of each SNR reading A link pooled the readings of its two directions, and received packets far outnumber trace first hops. Link.heard_at now keeps each reading under the node that measured it, and MeshTopology.readings(sender, receiver) gives one direction. A neighbour report is the repeater's own reading, so it goes in as the reverse pair. The pooled ranking does not change. Refs: #35 Co-Authored-By: Claude Haiku 5.5 --- meshterm/services/topology.py | 57 +++++++++++++++++++++++++++++++++-- meshterm/ui/path_composer.py | 11 ++++++- tests/test_topology.py | 46 ++++++++++++++++++++++++++++ 3 files changed, 111 insertions(+), 3 deletions(-) diff --git a/meshterm/services/topology.py b/meshterm/services/topology.py index 73958c2..697a40c 100644 --- a/meshterm/services/topology.py +++ b/meshterm/services/topology.py @@ -192,6 +192,12 @@ class Link: last_seen: The time when the link was most recently observed. sources: The evidence classes that observed it (``trace``, ``route``, ``packet``, ``neighbour``). + heard_at: The same SNR readings, divided by the endpoint that measured them. The + key is the id of the node that received. Its list holds what that node + measured on the packets from the other end. A radio link is not symmetric: + a repeater that we hear well can hear our node badly. ``snrs`` pools the two + directions for the ranking, and this field keeps them apart, so that a caller + can ask about one direction (refer to :meth:`MeshTopology.readings`). """ a: str @@ -200,12 +206,25 @@ class Link: snrs: list[float] = field(default_factory=list) last_seen: datetime | None = None sources: set[str] = field(default_factory=set) + heard_at: dict[str, list[float]] = field(default_factory=dict) @property def median_snr(self) -> float | None: """The median SNR (dB) of the readings of the link, or ``None`` if there are none.""" return statistics.median(self.snrs) if self.snrs else None + def heard_by(self, node: str) -> list[float]: + """The SNR readings that ``node`` measured on this link, from the other end. + + Args: + node: The id of one endpoint of the link. + + Returns: + The readings in dB, oldest first. The list is empty when ``node`` never + measured the other end, also when the other end measured ``node`` many times. + """ + return self.heard_at.get(node, []) + def strength(self, now: datetime | None = None) -> float: """Score the observed reliability of the link, for the ranking (higher is stronger). @@ -414,7 +433,10 @@ class MeshTopology: nodes: The walked sequence, with the endpoints, in order. snrs: Optional SNR readings for each link, aligned with the links (``snrs[i]`` is for the ``nodes[i] → nodes[i+1]`` link, measured at - arrival). + arrival). Thus ``nodes[i+1]`` measured it, and the reading goes into the + direction of the link that ends at that node (refer to + :attr:`Link.heard_at`). A caller with a reading that the *first* node of + a pair measured must give the pair in the reverse order. when: When the walk was observed (this sets the recency of each touched link). source: The evidence class tag (``trace``, ``route``, ``packet``, ``neighbour``). @@ -433,6 +455,7 @@ class MeshTopology: snr = snrs[i] if snrs and i < len(snrs) else None if snr is not None: link.snrs.append(snr) + link.heard_at.setdefault(b, []).append(snr) if when is not None and (link.last_seen is None or when > link.last_seen): link.last_seen = when @@ -692,6 +715,9 @@ class MeshTopology: if far == dst: # a src→dst link (src is a prefix of dst) becomes a self-loop continue new_key = (dst, far) if dst < far else (far, dst) + # The readings that src measured become the readings of dst, the node that + # src is. The readings that far measured keep their key. + heard = {(dst if node == src else node): snrs for node, snrs in link.heard_at.items()} existing = self._links.get(new_key) if existing is None: self._links[new_key] = Link( @@ -701,11 +727,14 @@ class MeshTopology: snrs=list(link.snrs), last_seen=link.last_seen, sources=set(link.sources), + heard_at={node: list(snrs) for node, snrs in heard.items()}, ) else: existing.samples += link.samples existing.snrs.extend(link.snrs) existing.sources |= link.sources + for node, snrs in heard.items(): + existing.heard_at.setdefault(node, []).extend(snrs) if link.last_seen is not None and ( existing.last_seen is None or link.last_seen > existing.last_seen ): @@ -734,6 +763,28 @@ class MeshTopology: """The evidence for the undirected link between ``a`` and ``b``, if there is any.""" return self._links.get((a, b) if a < b else (b, a)) + def readings(self, sender: str, receiver: str) -> list[float]: + """The SNR readings of one direction of a link: what ``receiver`` measured from ``sender``. + + The ranking pools the two directions of a link (refer to :class:`Link`). This + method keeps them apart. For the link from our node to a repeater, ``readings(us, + repeater)`` is how well the repeater hears our node. Only a trace gives these + readings, because the first hop of a trace reports the SNR at which it received + our packet. ``readings(repeater, us)`` is how well our node hears the repeater: + each packet that the repeater relayed to us, and the last hop of each trace that + came home through it. + + Args: + sender: The canonical id of the node that transmitted. + receiver: The canonical id of the node that measured. + + Returns: + The readings in dB. The list is empty when there is no link, or when no + reading in that direction exists. + """ + link = self.link(sender, receiver) + return list(link.heard_by(receiver)) if link is not None else [] + def next_hops(self, tail: str, *, exclude: frozenset[str] = frozenset()) -> list[HopSuggestion]: """Suggest the nodes that ``tail`` can reach, with the strongest observed link first. @@ -1084,8 +1135,10 @@ def build_topology( topo.add_walk(nodes, snrs=snrs, when=packet.when, source="packet") for reported in neighbour_links: + # The repeater measured the SNR when it received from its neighbour. add_walk + # gives a reading to the second node of a pair, so the neighbour goes first. topo.add_walk( - [topo.canonical(reported.repeater), topo.canonical(reported.neighbour)], + [topo.canonical(reported.neighbour), topo.canonical(reported.repeater)], snrs=[reported.snr], when=reported.when, source="neighbour", diff --git a/meshterm/ui/path_composer.py b/meshterm/ui/path_composer.py index a18626d..aaced86 100644 --- a/meshterm/ui/path_composer.py +++ b/meshterm/ui/path_composer.py @@ -370,7 +370,15 @@ class PathComposerScreen(Screen): """ node = one.node if len(one.node) >= len(other.node) else other.node stamps = [link.last_seen for link in (one.link, other.link) if link.last_seen is not None] - ends = sorted((self._anchor(), node)) + anchor = self._anchor() + ends = sorted((anchor, node)) + # Each reading keeps its direction. A reading that an alias of the suggested node + # measured is the node's own. Each other reading is the anchor's. + heard: dict[str, list[float]] = {} + for link in (one.link, other.link): + for end, snrs in link.heard_at.items(): + key = node if self._same_node(end, node) else anchor + heard.setdefault(key, []).extend(snrs) return HopSuggestion( node=node, link=Link( @@ -380,6 +388,7 @@ class PathComposerScreen(Screen): snrs=[*one.link.snrs, *other.link.snrs], last_seen=max(stamps) if stamps else None, sources=one.link.sources | other.link.sources, + heard_at=heard, ), strength=max(one.strength, other.strength), ) diff --git a/tests/test_topology.py b/tests/test_topology.py index cdb8278..d4083a9 100644 --- a/tests/test_topology.py +++ b/tests/test_topology.py @@ -201,6 +201,52 @@ def test_neighbour_reports_feed_the_graph_as_fetched_evidence() -> None: assert "f2c24f54551e" in suggested and "beefbeef" in suggested +# --- the direction of a reading ----------------------------------------------------- + + +def test_trace_readings_keep_the_direction_that_measured_them() -> None: + """Each hop of a trace measured the packet from the hop before it. The link keeps that.""" + topo = _topo(trace_paths=[_traced(("3d", 12.5), ("f2", -5.5), ("3d", -6.5), (None, 11.75))]) + us, hub, far = topo.self_id, "3d63c6429436", "f2c24f54551e" + assert topo.readings(us, hub) == [12.5] # the hub heard our node + assert topo.readings(hub, us) == [11.75] # our node heard the hub + assert topo.readings(hub, far) == [-5.5] + assert topo.readings(far, hub) == [-6.5] + assert sorted(topo.link(us, hub).snrs) == [11.75, 12.5] # the pool is unchanged + + +def test_packet_readings_are_what_our_node_heard() -> None: + """A received packet is a reading of the last relay toward our node, never the reverse.""" + packet = PacketPath(when=utcnow(), origin="27d4396a2967", snr=8.0, hops=["3d63c6429436"]) + topo = _topo(packet_paths=[packet]) + assert topo.readings("3d63c6429436", topo.self_id) == [8.0] + assert topo.readings(topo.self_id, "3d63c6429436") == [] + assert topo.readings(topo.self_id, "f2c24f54551e") == [] # no link at all + + +def test_neighbour_report_readings_are_what_the_repeater_heard() -> None: + """A neighbour table holds the SNR that the repeater measured from each neighbour.""" + reported = [NeighbourLink(when=utcnow(), repeater="3d63c6429436", neighbour="f2c2", snr=7.0)] + topo = _topo(neighbour_links=reported) + assert topo.readings("f2c24f54551e", "3d63c6429436") == [7.0] + assert topo.readings("3d63c6429436", "f2c24f54551e") == [] + + +def test_coalesce_keeps_the_direction_of_the_readings_of_a_stub() -> None: + """When a bare hop folds into its wide id, its readings keep the end that measured them.""" + twin = Contact(name="Twin", public_key="27e4" + "0" * 60) + walks = [ + _traced(("27", 5.0), ("f2", -3.0), ("27", -3.5), (None, 6.0)), + _traced(("27d4", 7.0), ("f2", -4.0), ("27d4", -4.5), (None, 8.0)), + ] + topo = _topo(trace_paths=walks, contacts=[REPEATER, FAR, LEAF, twin]) + us, leaf, far = topo.self_id, "27d4396a2967", "f2c24f54551e" + assert sorted(topo.readings(us, leaf)) == [5.0, 7.0] + assert sorted(topo.readings(leaf, us)) == [6.0, 8.0] + assert sorted(topo.readings(leaf, far)) == [-4.0, -3.0] + assert sorted(topo.readings(far, leaf)) == [-4.5, -3.5] + + # --- suggestions and scenarios ----------------------------------------------------