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