diff --git a/docs/guide/features.md b/docs/guide/features.md index 58cb306..8fd663a 100644 --- a/docs/guide/features.md +++ b/docs/guide/features.md @@ -38,7 +38,7 @@ This page lists each interactive screen with its scripted equivalent, where one | --- | --- | --- | | **๐ŸŒ Map** | The nodes that have a position, plotted on a real OpenStreetMap street map. The map is drawn as Unicode braille (streets, rivers, and place names). You can pan and zoom. Repeaters are highlighted and drawn on top. When you are offline, the map shows a blank grid. | none (a map is a picture, but `meshterm contacts` lists the same nodes) | | **๐ŸŒ Mesh walk** | The observed shape of the mesh, which you walk one node at a time. It is a graph of evidence from trace walks, firmware routes, overheard relay chains, and the neighbour tables of repeaters. It has braille edges that are coloured by SNR, and quality bars. Press Enter to walk to a node. Press โŒซ to go back. Type to find any node. The map shows where the nodes are. The walk shows how the nodes connect. | none | -| **๐ŸŽฏ Trace target** | A live trace screen. Select a target, and each trace streams in, hop by hop. The screen shows the running median and the reliability of each hop. You can compose a route through specific repeaters, or force one. A trace transmits **exactly once**, because repeaters can blacklist nodes that send bursts. To get more samples, run the trace again. A trace that came home proves its route out and back. Thus, when the radio uses another route to the target, the Device route row turns green and offers the traced route for direct messages and admin. | `meshterm trace --target โ€ฆ` | +| **๐ŸŽฏ Trace target** | A live trace screen. Select a target, and each trace streams in, hop by hop. The screen shows the running median and the reliability of each hop. You can compose a route through specific repeaters, or force one. A trace transmits **exactly once**, because repeaters can blacklist nodes that send bursts. To get more samples, run the trace again. A trace that came home proves its route out and back. Thus, when the radio uses another route to the target, the Device route row turns green and offers the traced route for direct messages and admin. A route that Explore paths measured with a probe counts too: when you adopt it, the row offers it at once, with no second transmission. | `meshterm trace --target โ€ฆ` | | **๐Ÿ‘ฃ Trace path** | The other half of tracing. You compose the whole circuit by hand, out and back, by the way that you choose. Then you walk it. The path composer suggests each next hop from the links that MeshTerm observed, strongest first. If you have the admin password of a repeater, the composer can also get the neighbour table of that repeater over the mesh. | `meshterm trace-path --path โ€ฆ` | | **๐Ÿงญ Outbound paths** | The ways out of your node that you trust, in your order. A radio link is not the same in the two directions: a repeater that your node hears well can hear your node badly, and most of what MeshTerm knows comes from what your node hears. Thus you name the way out, one or more hops long. Each site where you take the computer (Home, Work) has its own list, and one site is active. A companion that never moves can keep its own list. The trace features then start their suggested routes on your paths. Each path shows how well its first hop hears you (`out`) and how well you hear it (`in`). Measure sends one trace out along a path and back. When your radio hears the way out of another site, the menu asks if you want to use that site. | `meshterm outbound โ€ฆ` | | **๐Ÿงญ Device route** | The route that your radio holds for each contact, on the Routes tab of the node page. The radio keeps one route for each contact and replaces it with each new one that it learns, good or bad. A route that stopped to work loses each message on it, with no error. Here you see the route and how the radio got it. You can set it (your suggested route comes first), forget it so that the next message floods, or keep it: MeshTerm then writes it back each time that the radio replaces it. A kept route belongs to the site where you are. When you change site, MeshTerm saves the routes that the radio learned at the old site, and writes them back when you return. Discover routes sends one request and shows the route in each direction. When a direct message or an admin login gets no answer on a route, its retry can go by flood. | `meshterm route โ€ฆ` | diff --git a/meshterm/ui/trace_screen.py b/meshterm/ui/trace_screen.py index 16d5b1b..7673cf0 100644 --- a/meshterm/ui/trace_screen.py +++ b/meshterm/ui/trace_screen.py @@ -52,7 +52,9 @@ it to. An action list controls the screen: โ†‘/โ†“ select a row, and Enter runs route out and back. Thus, when the route out of such a trace is not the radio's route, the row turns green and offers it: ``Use this route for DMs and admin``. The popup then has *Use the traced route* and *Use and keep it* first. Nothing interrupts the session: - only the row changes. + only the row changes. A route that *Probe all* measured is already proved: when the user + adopts it, the probe traces become the first traces of the screen, so the row offers the + route at once, with no second transmission. * **Path width** opens a small dialog, where the user selects the path-hash width for each hop: 1, 2, or 4 bytes. A forced hop is addressed by this number of bytes from the start of its key. The first value is the routing width of the device. When the @@ -502,6 +504,7 @@ class TraceScreen(Screen): open_trophy_case: Callable[[], Awaitable[None]] | None = None, route_row: RouteRow | None = None, prove: Callable[[list[TraceResult]], ProvenRoute | None] | None = None, + seed_traces: Callable[[str], list[TraceResult]] | None = None, ) -> None: """Create the screen (nothing transmits until the user runs Trace). @@ -563,6 +566,9 @@ class TraceScreen(Screen): has), or ``None`` for no row. prove: Finds the route out that the traces of the screen came home on, for the Device route row. ``None`` offers no traced route. + seed_traces: Gives the traces that this session already walked on a spec (the + traces of a probe). When the screen adopts that spec, they become its + first traces. ``None`` starts each adopted path with no traces. """ super().__init__() self.title = f"Trace โ€” {target}" if mode == "target" else "Trace path" @@ -588,6 +594,7 @@ class TraceScreen(Screen): self._open_trophy_case = open_trophy_case self._route_row = route_row if mode == "target" else None self._prove = prove + self._seed_traces = seed_traces #: The trophy case disciplines that the current run placed in. The key is the #: title of the discipline, so that a run with more than one sample that #: improves keeps only its latest ``"Title โ€” score"`` label for each board. @@ -982,9 +989,13 @@ class TraceScreen(Screen): if spec is not None and spec.strip() != self._path_spec: # A different spec is a different measurement. The aggregates, the # medians for each hop, and the log all belong to the old route. - # Thus the session starts again, as clean as a new screen. + # Thus the session starts again, as clean as a new screen. Only the + # traces that this session already walked on the new spec (a probe) + # stay, because they measured exactly this route. self._path_spec = spec.strip() self._traces.clear() + if self._seed_traces is not None: + self._traces.extend(self._seed_traces(self._path_spec)) self._traces_rev += 1 self._status = "" finally: @@ -2307,6 +2318,10 @@ async def _open_session(ctx: AppContext, target: str | None, *, initial_spec: st text.append(f" ({outcome.candidate.label})", style="faint") return text + #: The traces that each probe walked, by spec, for the screen to start an adopted route + #: with (refer to the seed_traces argument of TraceScreen). + probe_traces: dict[str, list[TraceResult]] = {} + async def run_probe( candidates: list[ProbeCandidate], ) -> list[ProbeOutcome] | None: @@ -2331,6 +2346,9 @@ async def _open_session(ctx: AppContext, target: str | None, *, initial_spec: st dialog.status = f"path 1/{len(candidates)} ยท one trace each" def on_result(index: int, done: int, result: TraceResult) -> None: + # Keep the trace for its spec. When the user adopts that route, the screen + # starts with it (refer to seed_traces), and needs no second transmission. + probe_traces.setdefault(candidates[index].spec.strip(), []).append(result) dialog.status = f"path {index + 1}/{len(candidates)} ยท one trace each" dialog.last = result session.invalidate() @@ -2704,6 +2722,7 @@ async def _open_session(ctx: AppContext, target: str | None, *, initial_spec: st open_trophy_case=_trophy_case_opener(ctx), route_row=route_row, prove=prove, + seed_traces=lambda spec: list(probe_traces.get(spec, [])), ) try: await session.run_screen(screen) diff --git a/tests/test_device_route_screen.py b/tests/test_device_route_screen.py index 1e100f3..2b7b127 100644 --- a/tests/test_device_route_screen.py +++ b/tests/test_device_route_screen.py @@ -292,3 +292,54 @@ async def test_trace_target_has_the_row_and_hands_it_the_traced_route() -> None: await asyncio.sleep(0) assert opened == [ProvenRoute(("27d4",), 1, 1, 2.0)] assert len(screen._traces) == 1 # the popup changes no path of the screen + + +async def test_an_adopted_probe_route_starts_with_its_probe_traces() -> None: + """Adopting a probed route keeps its probe trace, so the row offers it at once.""" + import asyncio + + from meshterm.ui.device_route_screen import ProvenRoute + from meshterm.ui.trace_screen import TraceScreen + from tests.test_live_screens import _FakeSession, _trace + + probed = _trace(4.0, 1.0) + adopted = "3d63,f2c2,3d63" + + async def flow(current): # noqa: ANN001, ANN202 + return current + + async def explore(current): # noqa: ANN001, ANN202 + return adopted + + async def trace(spec, on_trace): # noqa: ANN001, ANN202 + raise AssertionError("an adopted probe route needs no new trace") + + def prove(traces: list) -> ProvenRoute | None: + home = [t for t in traces if t.success] + return ProvenRoute(("3d63",), len(home), len(traces)) if home else None + + screen = TraceScreen( + "Alice", + device_label="Us", + device_hash="aabb" + "00" * 30, + resolve=lambda label: label, + session=_FakeSession(), + trace=trace, + compose_path=flow, + explore=explore, + pick_width=flow, + pick_samples=flow, + width_bytes=lambda: 2, + sample_count=lambda: 1, + pace_s=0.0, + route_row=_row(None), + prove=prove, + seed_traces=lambda spec: [probed] if spec == adopted else [], + ) + screen._index = screen._actions.index("explore") + screen.handle("enter") + await asyncio.sleep(0) + await asyncio.sleep(0) + assert screen._traces == [probed] + assert screen.proven() == ProvenRoute(("3d63",), 1, 1) + assert screen._actions[screen._index] == "trace" # the highlight moved, as after Explore