From 3f8c698625d686a99bd9348fdf91a091e321c4be Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Sun, 21 Jun 2026 14:45:03 -0400 Subject: [PATCH] Trace TX optimization round-trip; restore TX when no result Two correctness fixes for remote-admin TX optimization: 1. Reverse/round-trip measurement path. The optimizer traced a one-way path ending at the (possibly far) target and waited for the target itself to originate the trace reply, which never returns when the target is only reachable via other repeaters, so every trace timed out. Now we trace out to the target and back (the MeshCore A,B,A convention) so a reachable near node answers; the target only forwards. Its received SNR is read from its hop by hash (the round trip turn-around) rather than by position. 2. Restore original TX on no result. If not one trace gets through at any level there is no meaningful winner, so leave the node at its original power (applied=False) and warn, instead of writing a bogus value. Mock updated to model each hop SNR from the node that transmitted into it and to drop traces on the bottleneck hop. Added round-trip / target-hash tests. Co-Authored-By: Claude Opus 4.8 --- meshtools/core/connection.py | 27 ++++++---- meshtools/services/tx_optimizer.py | 85 +++++++++++++++++++++++------- meshtools/tools/tx_optimize.py | 26 ++++++--- tests/test_skeleton.py | 24 +++++++++ 4 files changed, 127 insertions(+), 35 deletions(-) diff --git a/meshtools/core/connection.py b/meshtools/core/connection.py index 287815f..a49b6a5 100644 --- a/meshtools/core/connection.py +++ b/meshtools/core/connection.py @@ -812,8 +812,8 @@ class MockDevice(Device): """Return the lookup key for a remote node (its public key, else key prefix).""" return (node.public_key or node.key_prefix or node.name).lower().removeprefix("0x") - def _remote_tx_for(self, hop_hex: str) -> int: - """Resolve the simulated remote TX power for a forced-path hop hash. + def _remote_tx_for(self, hop_hex: str) -> Optional[int]: + """Resolve the simulated remote TX power set on a forced-path hop, if any. The optimizer stores a node's power under its full public key; a trace addresses it by a shorter hash prefix, so match in either direction. @@ -822,13 +822,14 @@ class MockDevice(Device): hop_hex: The forced-path hop hash (hex). Returns: - The node's simulated TX power, or the default if none was set. + The node's simulated TX power, or ``None`` if we never set one (i.e. this + hop isn't a node the optimizer is tuning). """ h = hop_hex.lower() for key, tx in self._remote_tx.items(): if key.startswith(h) or h.startswith(key): return tx - return self._default_remote_tx + return None async def get_tuning(self) -> dict: # noqa: D102 - inherited docstring return dict(self._tuning) @@ -954,19 +955,23 @@ class MockDevice(Device): depth = len(forced) if forced else self._rng.randint(1, 3) hops: list[Hop] = [] for i in range(depth): - # The final forced hop is the target; the SNR it reports is the link from the - # *previous* (admin-tuned) node, so it tracks that node's remote TX power. - # All other hops follow the local TX-power model. - if forced is not None and i == depth - 1 and depth >= 2: - expected = self._expected_remote_snr(self._remote_tx_for(forced[i - 1])) + # Each hop's SNR reflects the node that transmitted *into* it (hop i-1). If + # that node is one the optimizer has tuned a remote TX on, model the link from + # its power — so the hop arriving at the target tracks the admin node we're + # tuning, wherever the target sits in a there-and-back path. Otherwise fall + # back to the local TX-power model. + prev_tx = self._remote_tx_for(forced[i - 1]) if forced is not None and i >= 1 else None + if prev_tx is not None: + expected = self._expected_remote_snr(prev_tx) else: expected = self._expected_snr(i) snr = expected + self._rng.gauss(0, 1.2) # measurement noise node = forced[i] if forced else f"hop{i}" hops.append(Hop(index=i, node=node, snr=round(snr, 1))) - # Very weak links occasionally drop entirely (judged on the repeater hops). - success = (hops[-1].snr if hops else -99) > -12 or self._rng.random() > 0.1 + # Very weak links occasionally drop the whole trace, judged on the bottleneck hop. + bottleneck = min((h.snr for h in hops), default=-99) + success = bottleneck > -12 or self._rng.random() > 0.1 # The trace reply returns to us: firmware appends the local device as a final # hash-less hop (``node=None``). Mirror that so the origin/destination framing diff --git a/meshtools/services/tx_optimizer.py b/meshtools/services/tx_optimizer.py index 45a80a1..5a36498 100644 --- a/meshtools/services/tx_optimizer.py +++ b/meshtools/services/tx_optimizer.py @@ -37,32 +37,46 @@ PersistLevel = Callable[[TxLevelResult], None] DEFAULT_SNR_TOLERANCE_DB = 1.0 -def trace_target_snr(trace: TraceResult) -> Optional[float]: - """Return the SNR the *target* received on a single trace. +def trace_target_snr(trace: TraceResult, target_hash: str) -> Optional[float]: + """Return the SNR the *target* received on a single (round-trip) trace. - The target is the last addressed hop in the forced path; firmware then appends the - reply returning to us as a final hash-less hop (``node is None``). So the target's - received SNR is the SNR of the last hop that still carries a node hash. + Because we trace out to the target and back (so a reachable node, not the far + target, answers), the target is no longer the last hop — it's the turn-around point. + We therefore locate it by matching its hash rather than by position. The matched + hop's SNR is the signal the target heard from the admin node just before it, which is + exactly the link being tuned. Args: trace: A single trace result. + target_hash: The target node's path hash (a leading slice of its public key). Returns: - The target's received SNR in dB, or ``None`` if the trace failed or had no - addressed hops. + The target's received SNR in dB, or ``None`` if the trace failed or the target + hop wasn't present in the reply. """ if not trace.success: return None - named = [hop for hop in trace.hops if hop.node is not None] - return named[-1].snr if named else None + needle = target_hash.lower().removeprefix("0x") + for hop in trace.hops: + if hop.node is None: + continue + node = hop.node.lower().removeprefix("0x") + # Match either way: the firmware may report hashes at a different width than the + # one we addressed the path with. + if node.startswith(needle) or needle.startswith(node): + return hop.snr + return None -def build_level(tx: int, target: str, traces: list[TraceResult]) -> TxLevelResult: +def build_level( + tx: int, target: str, target_hash: str, traces: list[TraceResult] +) -> TxLevelResult: """Aggregate the traces measured at one TX level into a :class:`TxLevelResult`. Args: tx: The TX power these traces were taken at. target: The target node (for the embedded :class:`TraceStats`). + target_hash: The target's path hash, used to find its hop in each trace. traces: Every trace run at this level. Returns: @@ -70,7 +84,7 @@ def build_level(tx: int, target: str, traces: list[TraceResult]) -> TxLevelResul traces, so a single outlier reading barely moves it. """ successes = [t for t in traces if t.success] - snrs = [snr for t in successes if (snr := trace_target_snr(t)) is not None] + snrs = [snr for t in successes if (snr := trace_target_snr(t, target_hash)) is not None] target_snr = statistics.median(snrs) if snrs else None return TxLevelResult( tx_power=tx, @@ -140,8 +154,9 @@ async def optimize_tx_power( device: The connected local device, used to trace and to drive the remote node. target: Node whose received SNR is being maximized (the last hop of ``path``). admin_node: The remote node whose TX power is tuned (the hop before ``target``). - path: The forced path to trace, as the comma-separated hash string - ``send_trace`` expects, ending at ``target``. + path: The one-way forced path out to ``target`` (comma-separated hashes, ending + at the target). It is traced as a there-and-back round trip internally so a + reachable node answers — the far target only has to forward the packet. tx_min: Lowest TX power to consider. tx_max: Highest TX power to consider. coarse_step: Step between coarse-sweep levels. @@ -167,6 +182,13 @@ async def optimize_tx_power( original_tx = await device.get_remote_tx_power(admin_node) + # Trace out to the target and back: the reply then originates at a node near us + # (the first hop), not the far target, which only has to forward the packet. The + # target's received SNR is read from its hop at the round trip's turn-around point. + outbound = [h for h in path.split(",") if h] + target_hash = outbound[-1] if outbound else path + trace_path = _round_trip_path(outbound) + # Accumulate raw traces per level so a verify pass can *add* samples to a level and # re-aggregate, rather than throwing away what we already measured. traces_by_tx: dict[int, list[TraceResult]] = {} @@ -184,12 +206,12 @@ async def optimize_tx_power( device, target, samples=samples_per_level, - path=path, + path=trace_path, cooldown_s=cooldown_s, persist=persist_trace, ) traces_by_tx.setdefault(tx, []).extend(batch) - level = build_level(tx, target, traces_by_tx[tx]) + level = build_level(tx, target, target_hash, traces_by_tx[tx]) levels[tx] = level if persist_level is not None: persist_level(level) @@ -218,10 +240,16 @@ async def optimize_tx_power( await measure_level(best.tx_power) best = select_best(list(levels.values()), snr_tolerance=snr_tolerance) - if apply or original_tx is None: + # "No result" = not one trace got through at any level (a meaningless winner). + # In that case, and when apply is off, leave the node at the power it started at. + got_result = best.successes > 0 + applied = apply and got_result + if applied: final_tx = best.tx_power + elif original_tx is not None: + final_tx = original_tx else: - final_tx = original_tx # apply off: leave the node as we found it + final_tx = best.tx_power # nothing to restore to; can't do better await device.set_remote_tx_power(admin_node, final_tx) except BaseException: # On any failure, try to leave the node at the power it started with. @@ -240,11 +268,32 @@ async def optimize_tx_power( best_tx=best.tx_power, best_snr=best.target_snr, best_success_rate=best.success_rate, - applied=apply, + applied=applied, levels=list(levels.values()), ) +def _round_trip_path(outbound: list[str]) -> str: + """Build a there-and-back trace path from a one-way path to the target. + + Tracing out to the target then back means the *final* hop is a node near us (the + first outbound hop), which can reliably answer; the far target only has to forward + the packet, never originate the reply. This mirrors the MeshCore ``A,B,A`` trace + convention. The target's own hop (the turn-around point) still records the SNR it + heard from the admin node, which is what we read. + + Args: + outbound: The one-way path hops, ending at the target. + + Returns: + The round-trip path as a comma-separated hash string (e.g. ``"3f,f2"`` becomes + ``"3f,f2,3f"``). A single-hop path is returned unchanged. + """ + if len(outbound) < 2: + return ",".join(outbound) + return ",".join(outbound + outbound[-2::-1]) + + def _coarse_levels(tx_min: int, tx_max: int, step: int) -> list[int]: """Build the coarse sweep grid, always including both endpoints. diff --git a/meshtools/tools/tx_optimize.py b/meshtools/tools/tx_optimize.py index 44d5960..aaf4d48 100644 --- a/meshtools/tools/tx_optimize.py +++ b/meshtools/tools/tx_optimize.py @@ -167,6 +167,9 @@ class TxOptimizeTool(Tool): persist_trace=lambda t: ctx.repo.record_trace(run_id, t), ) + # No trace got through at any TX level: nothing was tuned, the node was left at + # its original power. Usually a wrong/unreachable path rather than a weak link. + no_result = result.best_snr is None if result.applied: ctx.log.info("set TX power %s on %s", result.best_tx, admin_node.name) @@ -179,9 +182,22 @@ class TxOptimizeTool(Tool): path_out = render_tx_optimization(result, ctx.settings.output_dir) artifacts.append(str(path_out)) - applied_note = ( - f" [ok](set on {admin_node.name})[/ok]" if result.applied else "" - ) + if no_result: + restored = ( + f" Restored TX to {result.original_tx}." if result.original_tx is not None else "" + ) + message = ( + f"[warn]![/warn] no traces reached [brand]{result.target}[/brand] at any TX " + f"level — check the path ends at the target and is reachable.{restored}" + ) + else: + applied_note = f" [ok](set on {admin_node.name})[/ok]" if result.applied else "" + message = ( + f"[ok]✓[/ok] optimal TX for [brand]{admin_node.name}[/brand] → " + f"[brand]{result.target}[/brand] is [brand]{result.best_tx}[/brand]" + + applied_note + ) + return ToolResult( summary={ "target": result.target, @@ -194,9 +210,7 @@ class TxOptimizeTool(Tool): "applied": result.applied, "levels_measured": len(result.levels), }, - message=f"[ok]✓[/ok] optimal TX for [brand]{admin_node.name}[/brand] → " - f"[brand]{result.target}[/brand] is [brand]{result.best_tx}[/brand]" - + applied_note, + message=message, artifacts=artifacts, ) diff --git a/tests/test_skeleton.py b/tests/test_skeleton.py index 973b3a0..681ed61 100644 --- a/tests/test_skeleton.py +++ b/tests/test_skeleton.py @@ -338,6 +338,30 @@ def test_select_best_prefers_reliability_then_lowest_power() -> None: assert select_best([a, b], snr_tolerance=1.0).tx_power == 18 +def test_round_trip_path_mirrors_back_to_a_reachable_node() -> None: + """The trace path goes out to the target and back, so a near node answers.""" + from meshtools.services.tx_optimizer import _round_trip_path + + assert _round_trip_path(["3f", "f2"]) == "3f,f2,3f" + assert _round_trip_path(["3d", "3f", "f2"]) == "3d,3f,f2,3f,3d" + assert _round_trip_path(["f2"]) == "f2" # single hop: nothing to mirror + + +def test_trace_target_snr_matches_target_hop_not_position() -> None: + """The target's SNR is read from its hash, even when it's the turn-around hop.""" + from meshtools.core.models import Hop + from meshtools.services.tx_optimizer import trace_target_snr + + # Round trip 3f -> f2 -> 3f -> us: the f2 hop (index 1) is what we want, not the + # later 3f hop or the hash-less return hop. + trace = TraceResult( + target="f2", success=True, + hops=[Hop(0, "3f", 4.0), Hop(1, "f2", 7.5), Hop(2, "3f", 3.0), Hop(3, None, 4.0)], + ) + assert trace_target_snr(trace, "f2") == 7.5 + assert trace_target_snr(TraceResult(target="f2", success=False), "f2") is None + + def test_tx_plot_writes_html(tmp_path: Path) -> None: """The Plotly renderer produces a self-contained HTML file.""" import asyncio