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 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Haiku 5.5 committed 2026-11-07 13:06:08 -05:00
1 parent 734e60ab37
commit e2146f9092
3 files changed
+111 -3

No files matched your search

+55 -2
View File
@@ -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",
+10 -1
View File
@@ -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),
)
+46
View File
@@ -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 ----------------------------------------------------