Replace local TX optimizer with remote-admin, path-based tuning

Tune the TX power of a remote node we have admin rights on (the hop before
a chosen target) to maximize the SNR the target receives from it, instead of
tuning the local device against a path bottleneck.

- Device gains admin_login / get_remote_tx_power / set_remote_tx_power
  (MeshCoreDevice via send_login_sync + `set tx <dbm>` send_cmd; MockDevice
  models target SNR as an inverted-U in the admin node's TX with a reliability
  dropoff at the band edges).
- tx_optimizer: forced-path sweep with a lexicographic objective (reliability
  first, then SNR), median-based levels, coarse+refine search, and a verify
  pass; near-SNR ties break toward lower power. Outlier-robust by construction.
- AdminStore remembers per-node admin passwords in <config_dir>/admin.json
  (owner-only perms), cleared automatically when a login is rejected.
- Configurable 12-28 dBi default range (tx_opt_min/tx_opt_max).
- tx-optimize tool: path/password prompts, live progress, persistence, applies
  the winner on finish, and renders an interactive HTML chart.
- Rewrote TX result models, widgets, plot, repository.record_tx_sample, and the
  TX tests for the new flow.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 4.8 committed 2026-06-21 13:58:15 -04:00
1 parent a3ab95fd26
commit c75a2eb2e3
12 files changed
+971 -198

No files matched your search

+2
View File
@@ -16,6 +16,7 @@ from typing import Optional
import typer
from .context import AppContext
from .core.admin_store import AdminStore
from .core.config import Settings
from .core.connection import DeviceCommandError
from .core.device_config import DeviceConfigError
@@ -75,6 +76,7 @@ def main_callback(
settings=settings,
repo=Repository(settings.db_path),
device_store=DeviceStore(settings.config_dir / "devices.json"),
admin_store=AdminStore(settings.config_dir / "admin.json"),
profile=settings.resolve_profile(profile),
mock=mock,
port_override=port,
+3
View File
@@ -12,6 +12,7 @@ from typing import Optional
from rich.console import Console
from .core.admin_store import AdminStore
from .core.config import DeviceProfile, Settings
from .core.connection import Device, make_device
from .core.device_store import DeviceStore
@@ -31,6 +32,7 @@ class AppContext:
repo: Database repository.
profile: Active device profile, if one was resolved.
device_store: Store for the remembered "last known good" device.
admin_store: Store for remembered remote-node admin passwords.
mock: Whether the simulator device is in use.
port_override: Explicit serial port (from ``--port`` or the interactive picker),
overriding the profile.
@@ -45,6 +47,7 @@ class AppContext:
settings: Settings
repo: Repository
device_store: DeviceStore
admin_store: AdminStore
profile: Optional[DeviceProfile] = None
mock: bool = False
port_override: Optional[str] = None
+127
View File
@@ -0,0 +1,127 @@
"""Persistence for remembered remote-node admin passwords.
The remote-admin optimizer logs in to a repeater to tune its TX power; storing the
password means the user isn't prompted on every run. Like the remembered device
(:mod:`meshtools.core.device_store`), this lives in a small JSON file in the config
directory (``<config_dir>/admin.json``) rather than the per-invocation SQLite database,
because admin credentials are global machine state.
Passwords are stored in plaintext, so the file is written with owner-only permissions
where the platform supports it. This is a local operator tool tuning their own mesh, not
a multi-user secret store; treat the file accordingly.
"""
from __future__ import annotations
import json
import os
import stat
from dataclasses import dataclass
from pathlib import Path
from typing import Optional
from .models import Contact, utcnow
def admin_key(node: Contact) -> str:
"""Return the lookup key for a node's stored password.
Prefers the full public key (stable and unambiguous); falls back to the key prefix
and finally the name so a contact without a key can still be remembered.
Args:
node: The contact to key on.
Returns:
A normalized, lowercased identifier.
"""
key = node.public_key or node.key_prefix or node.name
return key.lower().removeprefix("0x")
@dataclass(slots=True)
class AdminCredential:
"""A remembered admin password for one remote node.
Attributes:
key: The :func:`admin_key` the password is stored under.
password: The node's admin password (plaintext).
label: A friendly node name for display.
last_used: ISO-8601 timestamp of the last successful login.
"""
key: str
password: str
label: str
last_used: str
class AdminStore:
"""Reads and writes remembered remote-node admin passwords."""
def __init__(self, path: Path) -> None:
"""Open the store against a JSON file location.
Args:
path: Path to the JSON state file (created lazily on first write).
"""
self._path = path
def _load_all(self) -> dict[str, dict]:
"""Return the raw key -> record mapping, or empty on missing/corrupt file."""
try:
data = json.loads(self._path.read_text(encoding="utf-8"))
except (OSError, ValueError):
return {}
return data if isinstance(data, dict) else {}
def get(self, node: Contact) -> Optional[str]:
"""Return the remembered password for ``node``, or ``None`` if not stored.
Args:
node: The contact to look up.
Returns:
The stored password, or ``None``.
"""
record = self._load_all().get(admin_key(node))
if isinstance(record, dict):
password = record.get("password")
return str(password) if password is not None else None
return None
def remember(self, node: Contact, password: str) -> None:
"""Store (or update) the admin password for ``node``.
Args:
node: The contact the password belongs to.
password: The admin password to remember.
"""
records = self._load_all()
records[admin_key(node)] = {
"password": password,
"label": node.name,
"last_used": utcnow().isoformat(),
}
self._write(records)
def forget(self, node: Contact) -> None:
"""Remove any remembered password for ``node`` (e.g. after it stops working).
Args:
node: The contact to forget.
"""
records = self._load_all()
if records.pop(admin_key(node), None) is not None:
self._write(records)
def _write(self, records: dict[str, dict]) -> None:
"""Persist ``records`` atomically with owner-only permissions where supported."""
self._path.parent.mkdir(parents=True, exist_ok=True)
tmp = self._path.with_suffix(self._path.suffix + ".tmp")
tmp.write_text(json.dumps(records, indent=2), encoding="utf-8")
try: # best-effort: not all platforms/filesystems honor chmod
os.chmod(tmp, stat.S_IRUSR | stat.S_IWUSR)
except OSError: # pragma: no cover - platform-dependent
pass
tmp.replace(self._path)
+6
View File
@@ -64,6 +64,8 @@ class Settings:
default_profile: Profile used when ``--profile`` is omitted.
profiles: Mapping of profile name to :class:`DeviceProfile`.
trace_cooldown_s: Minimum delay between transmit bursts (duty-cycle safety).
tx_opt_min: Lowest TX power explored by the remote-admin optimizer (dBm).
tx_opt_max: Highest TX power explored by the remote-admin optimizer (dBm).
"""
config_dir: Path = field(default_factory=default_config_dir)
@@ -72,6 +74,8 @@ class Settings:
default_profile: Optional[str] = None
profiles: dict[str, DeviceProfile] = field(default_factory=dict)
trace_cooldown_s: float = 1.0
tx_opt_min: int = 12
tx_opt_max: int = 28
def __post_init__(self) -> None:
"""Derive dependent paths that were not explicitly provided."""
@@ -130,4 +134,6 @@ class Settings:
default_profile=data.get("default_profile"),
profiles=profiles,
trace_cooldown_s=float(data.get("trace_cooldown_s", 1.0)),
tx_opt_min=int(data.get("tx_opt_min", 12)),
tx_opt_max=int(data.get("tx_opt_max", 28)),
)
+253 -7
View File
@@ -23,6 +23,13 @@ from .models import Contact, Hop, TraceResult, utcnow
TX_POWER_MIN = 1
TX_POWER_MAX = 22
#: Default range explored when tuning a *remote* repeater's transmit power. Remote nodes
#: (e.g. high-gain repeaters) typically run hotter than the local companion, so this band
#: differs from the local ``TX_POWER_MIN``/``TX_POWER_MAX`` clamp. Both bounds are
#: user-configurable (see :class:`~meshtools.core.config.Settings`).
REMOTE_TX_MIN = 12
REMOTE_TX_MAX = 28
class DeviceCommandError(RuntimeError):
"""A device command failed in a recoverable, user-facing way.
@@ -76,6 +83,44 @@ class Device(ABC):
value: TX power level, clamped by the caller to the device's valid range.
"""
# -- remote administration (tuning a node we have admin rights on) -----------
@abstractmethod
async def admin_login(self, node: Contact, password: str) -> bool:
"""Authenticate as administrator on a remote node.
Args:
node: The contact to log in to. Its ``public_key`` addresses the node.
password: The node's admin password.
Returns:
``True`` if the node accepted the login, ``False`` otherwise (e.g. a wrong
password or no response).
"""
@abstractmethod
async def get_remote_tx_power(self, node: Contact) -> Optional[int]:
"""Read a remote (admin) node's current transmit power.
Args:
node: The contact to query (must already be logged in).
Returns:
The node's TX power in dBm, or ``None`` if it could not be read.
"""
@abstractmethod
async def set_remote_tx_power(self, node: Contact, value: int) -> None:
"""Set a remote (admin) node's transmit power.
Args:
node: The contact to adjust (must already be logged in).
value: TX power in dBm.
Raises:
DeviceCommandError: If the node rejected the command.
"""
@abstractmethod
async def run_trace(
self,
@@ -339,6 +384,86 @@ class MeshCoreDevice(Device):
mc = self._require()
await mc.commands.set_tx_power(value)
@staticmethod
def _node_pubkey(node: Contact) -> str:
"""Return a contact's full public key for remote addressing.
Args:
node: The contact to address.
Returns:
The lowercased hex public key (``0x`` stripped).
Raises:
DeviceCommandError: If the contact carries no public key, so it cannot be
addressed for login/admin commands.
"""
pub = (node.public_key or "").lower().removeprefix("0x")
if not pub:
raise DeviceCommandError(
f"contact {node.name!r} has no public key on this device, so it can't be "
"logged in to for admin commands. Receive an advert from it first."
)
return pub
async def admin_login(self, node: Contact, password: str) -> bool: # noqa: D102
from meshcore import EventType
mc = self._require()
pub = self._node_pubkey(node)
event = await mc.commands.send_login_sync(pub, password)
# ``send_login_sync`` returns the LOGIN_SUCCESS event, or ``None``/an ERROR or
# LOGIN_FAILED event when the node refused (typically a wrong password).
if event is None:
return False
etype = getattr(event, "type", None)
if etype in (EventType.ERROR, EventType.LOGIN_FAILED):
return False
return True
async def _send_admin_cmd(self, node: Contact, cmd: str, *, timeout: float = 8.0):
"""Send a CLI command to a logged-in remote node and await its reply.
The companion acknowledges the send immediately (``MSG_SENT``); the node's
textual reply arrives later as a ``CONTACT_MSG_RECV`` event. We return that
reply text (or ``None`` if none arrived before ``timeout``).
Args:
node: The remote contact (must already be logged in).
cmd: The repeater CLI command, e.g. ``"set tx 20"``.
timeout: Seconds to wait for the node's reply.
Returns:
The reply text, or ``None`` if the node did not answer in time.
Raises:
DeviceCommandError: If the companion rejected the send outright.
"""
from meshcore import EventType
mc = self._require()
pub = self._node_pubkey(node)
sent = await mc.commands.send_cmd(pub, cmd)
if sent is not None and getattr(sent, "is_error", lambda: False)():
raise DeviceCommandError(
f"failed to send admin command {cmd!r} to {node.name!r}: "
f"{getattr(sent, 'payload', {})}"
)
reply = await mc.wait_for_event(EventType.CONTACT_MSG_RECV, timeout=timeout)
if reply is None:
return None
payload = getattr(reply, "payload", {}) or {}
return str(payload.get("text", payload.get("msg", "")))
async def get_remote_tx_power(self, node: Contact) -> Optional[int]: # noqa: D102
reply = await self._send_admin_cmd(node, "get tx")
return _parse_tx_reply(reply)
async def set_remote_tx_power(self, node: Contact, value: int) -> None: # noqa: D102
# The reply ("ok"/echoed value) is best-effort confirmation; absence isn't fatal
# since some firmware answers tersely or drops the ack under duty-cycle limits.
await self._send_admin_cmd(node, f"set tx {value}")
async def run_trace( # noqa: D102 - inherited docstring
self,
target: str,
@@ -580,23 +705,40 @@ class MockDevice(Device):
optimal_tx: The TX power at which the simulated link peaks.
"""
def __init__(self, seed: int = 1234, optimal_tx: int = 14) -> None:
def __init__(
self,
seed: int = 1234,
optimal_tx: int = 14,
optimal_remote_tx: int = 20,
admin_password: str = "admin",
) -> None:
"""Initialize the simulator.
Args:
seed: RNG seed for reproducible measurement noise.
optimal_tx: TX power level at which simulated SNR is maximized.
optimal_tx: Local TX power at which the simulated *bottleneck* SNR peaks.
optimal_remote_tx: Remote-node TX power at which the simulated SNR *at the
target* peaks (what the remote-admin optimizer converges on).
admin_password: Password the simulated remote nodes accept for admin login.
"""
self.optimal_tx = optimal_tx
self.optimal_remote_tx = optimal_remote_tx
self._admin_password = admin_password
self._rng = random.Random(seed)
self._tx_power = 20
self._connected = False
self._contacts = [
Contact(name="Yagi-Repeater", key_prefix="a1b2c3d4"),
Contact(name="Local-Repeater", key_prefix="b2c3d4e5"),
Contact(name="Observer-Bot", key_prefix="c3d4e5f6"),
Contact(name="Alice", key_prefix="d4e5f6a7"),
Contact(name="Yagi-Repeater", public_key=_mock_pub("a1b2c3d4"), key_prefix="a1b2c3d4"),
Contact(name="Local-Repeater", public_key=_mock_pub("b2c3d4e5"), key_prefix="b2c3d4e5"),
Contact(name="Observer-Bot", public_key=_mock_pub("c3d4e5f6"), key_prefix="c3d4e5f6"),
Contact(name="Alice", public_key=_mock_pub("d4e5f6a7"), key_prefix="d4e5f6a7"),
]
# Remote-admin simulation: which nodes we're "logged in" to, and each tuned
# node's transmit power keyed by full public key. ``_default_remote_tx`` is the
# assumed power before the optimizer first writes one.
self._admin_sessions: set[str] = set()
self._remote_tx: dict[str, int] = {}
self._default_remote_tx = 20
# Mutable configuration state, keyed exactly like the real SELF_INFO payload so the
# settings registry behaves identically on the simulator and on hardware.
self._info: dict = {
@@ -644,6 +786,50 @@ class MockDevice(Device):
async def set_tx_power(self, value: int) -> None: # noqa: D102 - inherited docstring
self._tx_power = value
async def admin_login(self, node: Contact, password: str) -> bool: # noqa: D102
await asyncio.sleep(0)
if password != self._admin_password:
return False
self._admin_sessions.add(self._mock_key(node))
return True
async def get_remote_tx_power(self, node: Contact) -> Optional[int]: # noqa: D102
key = self._mock_key(node)
if key not in self._admin_sessions:
return None
return self._remote_tx.get(key, self._default_remote_tx)
async def set_remote_tx_power(self, node: Contact, value: int) -> None: # noqa: D102
key = self._mock_key(node)
if key not in self._admin_sessions:
raise DeviceCommandError(
f"not logged in to {node.name!r}; call admin_login first."
)
self._remote_tx[key] = value
@staticmethod
def _mock_key(node: Contact) -> str:
"""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.
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.
Args:
hop_hex: The forced-path hop hash (hex).
Returns:
The node's simulated TX power, or the default if none was set.
"""
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
async def get_tuning(self) -> dict: # noqa: D102 - inherited docstring
return dict(self._tuning)
@@ -733,6 +919,27 @@ class MockDevice(Device):
peak = 8.0 - 10.0 * (offset**2)
return peak - 2.5 * hop_index
def _expected_remote_snr(self, remote_tx: int) -> float:
"""Model the SNR the target receives from the admin node it sits behind.
An inverted-U in the admin node's TX power: too low and the target barely hears
it, too high and the target's front end saturates. The peak sits at
``optimal_remote_tx`` so the remote-admin optimizer has a unimodal-with-noise
curve to converge on.
Args:
remote_tx: The admin node's transmit power.
Returns:
The noise-free expected SNR in dB at the target.
"""
# Curvature is steep enough that the band edges fall below the ~-12 dB drop
# threshold, so traces start failing there — giving the optimizer a real
# reliability gradient (not just an SNR one) to honor reliability-first.
span = (REMOTE_TX_MAX - REMOTE_TX_MIN) / 2
offset = (remote_tx - self.optimal_remote_tx) / span
return 9.0 - 24.0 * (offset**2)
async def run_trace( # noqa: D102 - inherited docstring
self,
target: str,
@@ -747,7 +954,13 @@ class MockDevice(Device):
depth = len(forced) if forced else self._rng.randint(1, 3)
hops: list[Hop] = []
for i in range(depth):
expected = self._expected_snr(i)
# 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]))
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)))
@@ -792,6 +1005,39 @@ def parse_trace_hops(payload: dict) -> list[Hop]:
return hops
def _mock_pub(prefix: str) -> str:
"""Build a 32-byte mock public key from a short hex prefix (simulator only).
Args:
prefix: Leading hex digits identifying the node.
Returns:
A 64-hex-character (32-byte) key beginning with ``prefix``.
"""
return prefix + "0" * (64 - len(prefix))
def _parse_tx_reply(reply: Optional[str]) -> Optional[int]:
"""Extract a TX-power integer from a repeater's ``get tx`` reply text.
Repeater firmware answers tersely and inconsistently across versions (e.g.
``"tx: 20"``, ``"TX power = 20 dBm"``, or just ``"20"``), so pull the first signed
integer out of the reply rather than matching a fixed format.
Args:
reply: The node's reply text, or ``None`` if it did not answer.
Returns:
The parsed TX power, or ``None`` if the reply was empty or carried no number.
"""
if not reply:
return None
import re
match = re.search(r"-?\d+", reply)
return int(match.group()) if match else None
def clamp_tx_power(value: int) -> int:
"""Clamp a TX power value to the supported range.
+35 -11
View File
@@ -266,34 +266,58 @@ class TraceStats:
class TxLevelResult:
"""Robust measurement of one TX power level during an optimization sweep.
The headline metric is ``target_snr`` — the SNR the *target* node reports receiving
from the admin-tuned node just ahead of it — since that single link is what the
remote-admin optimizer is tuning. ``success_rate`` is the primary objective
(reliability first), with ``target_snr`` the tie-breaker.
Attributes:
tx_power: The transmit power level tested.
stats: Aggregated trace statistics at this level.
score: Scalar objective value (higher is better) combining SNR and reliability.
tx_power: The transmit power level tested on the admin node.
samples: Number of traces run at this level.
successes: Number of traces that returned a reply.
target_snr: Median SNR (dB) received at the target across successful traces,
or ``None`` if every trace at this level failed.
score: Scalar objective for display/plotting (the median target SNR, or
negative infinity when nothing got through).
stats: Aggregated trace statistics at this level (full path, for display).
"""
tx_power: int
stats: TraceStats
samples: int
successes: int
target_snr: Optional[float]
score: float
stats: TraceStats
@property
def success_rate(self) -> float:
"""Fraction of traces that returned a reply, in the range ``[0, 1]``."""
return self.successes / self.samples if self.samples else 0.0
@dataclass(slots=True)
class TxOptResult:
"""The outcome of a TX-power optimization run.
"""The outcome of a remote-admin TX-power optimization run.
Attributes:
target: Node the optimization was tuned against.
original_tx: TX power in effect before the sweep (restored afterward).
best_tx: TX power with the highest score.
best_score: The winning score.
applied: Whether ``best_tx`` was written back to the device.
target: Node the SNR was measured at.
admin_node: Label of the node whose TX power was tuned (the hop before target).
path: The forced path the traces walked (comma-separated hashes).
original_tx: The admin node's TX power before the sweep, if it could be read.
best_tx: The chosen optimal TX power.
best_snr: Median target SNR (dB) at ``best_tx``.
best_success_rate: Trace success rate at ``best_tx``.
applied: Whether ``best_tx`` was written to the admin node.
levels: Every level measured, in the order tested.
"""
target: str
admin_node: str
path: str
original_tx: Optional[int]
best_tx: int
best_score: float
best_snr: Optional[float]
best_success_rate: float
applied: bool
levels: list[TxLevelResult] = field(default_factory=list)
+12 -9
View File
@@ -14,7 +14,7 @@ from typing import Any, Optional
from datetime import datetime
from ..core.models import Hop, TraceResult, TraceStats, utcnow
from ..core.models import Hop, TraceResult, TxLevelResult, utcnow
from . import db
@@ -207,12 +207,15 @@ class Repository:
timestamp=datetime.fromisoformat(row["created_at"]),
)
def record_tx_sample(self, run_id: int, stats: TraceStats) -> None:
"""Persist one robust TX-power sample from an optimization sweep.
def record_tx_sample(self, run_id: int, level: TxLevelResult) -> None:
"""Persist one robust TX-power level from an optimization sweep.
The ``median_min_snr`` column stores this optimizer's headline metric — the
median SNR measured *at the target* — rather than a path bottleneck.
Args:
run_id: The owning run.
stats: Aggregated trace statistics for a single TX power level.
level: Aggregated result for a single TX power level.
"""
self._conn.execute(
"INSERT INTO tx_samples "
@@ -220,11 +223,11 @@ class Repository:
"VALUES (?, ?, ?, ?, ?, ?, ?)",
(
run_id,
stats.target,
stats.tx_power,
stats.median_min_snr,
stats.success_rate,
stats.samples,
level.stats.target,
level.tx_power,
level.target_snr,
level.success_rate,
level.samples,
utcnow().isoformat(),
),
)
+164 -59
View File
@@ -1,113 +1,198 @@
"""TX-power optimization.
"""Remote-admin TX-power optimization.
The transmit-power response is non-monotonic: too low and the signal sits in the noise
floor, too high and the receiver saturates. The optimum is therefore an interior peak,
and trace measurements are noisy, so this module uses a robust two-phase search:
This tunes the transmit power of a *remote* node we have admin rights on — the node
sitting one hop before a chosen target — to maximize the signal the **target** receives
from it. We force a path (exactly like the trace tool), so every measurement exercises the
same admin-node→target link, and read the SNR the target reports at the end of that path.
1. A **coarse sweep** across the TX range at a fixed step, taking several traces per
level and scoring each level by a reliability-weighted median bottleneck SNR.
2. A **local refine** that fills in every integer level around the coarse winner, so the
reported optimum is exact within the bracket without paying for a full fine sweep.
Radio links are noisy and the real-world response is non-monotonic (too little power and
the target can't hear it; too much and its front end saturates), so the search is robust
by design:
The device's original TX power is always restored when the sweep finishes; writing the
winner back is the caller's decision.
1. A **coarse sweep** across the TX range, running several traces per level and scoring
each level by its trace success rate first and a *median* target SNR second.
2. A **local refine** filling in integer levels around the coarse winner.
3. A **verify** pass that re-measures the leading candidate with extra samples so a single
lucky (or unlucky) reading can't decide the optimum.
Selection is lexicographic — **reliability first, then SNR** — and on a near-tie in SNR it
prefers the *lower* TX power, since cranking power for a fraction of a dB only adds
interference and burns duty cycle. The chosen optimum is written back to the admin node
when ``apply`` is set (the whole point of the run is to leave it tuned).
"""
from __future__ import annotations
import statistics
from typing import Callable, Optional
from ..core.connection import Device, clamp_tx_power
from ..core.models import TraceStats, TxLevelResult, TxOptResult
from ..core.connection import REMOTE_TX_MAX, REMOTE_TX_MIN, Device
from ..core.models import Contact, TraceResult, TraceStats, TxLevelResult, TxOptResult
from . import trace_runner
#: How many dB of SNR a fully-unreliable link is penalized, blending reliability into
#: the scalar objective so a strong-but-flaky level cannot beat a solid one.
RELIABILITY_PENALTY_DB = 10.0
LevelCallback = Callable[[int, int, TxLevelResult], None]
PersistLevel = Callable[[TraceStats], None]
PersistLevel = Callable[[TxLevelResult], None]
#: On a near-tie in target SNR (within this many dB of the best), the lower TX power wins.
DEFAULT_SNR_TOLERANCE_DB = 1.0
def score_level(stats: TraceStats) -> float:
"""Score a measured TX level; higher is better.
def trace_target_snr(trace: TraceResult) -> Optional[float]:
"""Return the SNR the *target* received on a single trace.
Combines the robust bottleneck SNR with the success rate so an intermittently
failing level cannot outrank a reliable one.
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.
Args:
stats: Aggregated trace statistics for the level.
trace: A single trace result.
Returns:
The scalar objective value, or negative infinity if nothing got through.
The target's received SNR in dB, or ``None`` if the trace failed or had no
addressed hops.
"""
if stats.successes == 0 or stats.median_min_snr is None:
return float("-inf")
return stats.median_min_snr - (1.0 - stats.success_rate) * RELIABILITY_PENALTY_DB
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
def build_level(tx: int, target: 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`).
traces: Every trace run at this level.
Returns:
The level's robust aggregate. ``target_snr`` is the median across successful
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]
target_snr = statistics.median(snrs) if snrs else None
return TxLevelResult(
tx_power=tx,
samples=len(traces),
successes=len(successes),
target_snr=target_snr,
score=target_snr if target_snr is not None else float("-inf"),
stats=TraceStats.from_traces(target, traces),
)
def select_best(
levels: list[TxLevelResult], *, snr_tolerance: float = DEFAULT_SNR_TOLERANCE_DB
) -> TxLevelResult:
"""Pick the optimal level: reliability first, then SNR, then the lowest TX.
Among the levels with the highest trace success rate, take those whose median target
SNR is within ``snr_tolerance`` of the best, and return the one using the least
power. The tolerance band is what makes the choice robust to measurement noise: a
fractionally-higher SNR from a hotter level doesn't win if a cooler one is within
spitting distance.
Args:
levels: The measured levels (must be non-empty).
snr_tolerance: dB band within which SNRs are treated as tied.
Returns:
The chosen :class:`TxLevelResult`.
"""
best_rate = max(lv.success_rate for lv in levels)
contenders = [lv for lv in levels if lv.success_rate >= best_rate - 1e-9]
best_snr = max(_snr_or_floor(lv) for lv in contenders)
near = [lv for lv in contenders if _snr_or_floor(lv) >= best_snr - snr_tolerance]
return min(near, key=lambda lv: lv.tx_power)
def _snr_or_floor(level: TxLevelResult) -> float:
"""Return a level's target SNR, or negative infinity if it never got through."""
return level.target_snr if level.target_snr is not None else float("-inf")
async def optimize_tx_power(
device: Device,
target: str,
admin_node: Contact,
path: str,
*,
tx_min: int = 1,
tx_max: int = 22,
tx_min: int = REMOTE_TX_MIN,
tx_max: int = REMOTE_TX_MAX,
coarse_step: int = 3,
samples_per_level: int = 5,
samples_per_level: int = 3,
refine: bool = True,
verify: bool = True,
apply: bool = True,
cooldown_s: float = 1.0,
snr_tolerance: float = DEFAULT_SNR_TOLERANCE_DB,
on_level: Optional[LevelCallback] = None,
persist_level: Optional[PersistLevel] = None,
persist_trace: Optional[Callable] = None,
) -> TxOptResult:
"""Search for the TX power that maximizes the reliability-weighted SNR to ``target``.
"""Tune ``admin_node``'s TX power for the best signal at ``target``.
The caller must already be logged in to ``admin_node`` (see
:meth:`~meshtools.core.connection.Device.admin_login`).
Args:
device: Connected device to tune.
target: Destination node name or key prefix.
tx_min: Lowest TX power to consider (clamped to the device range).
tx_max: Highest TX power to consider (clamped to the device range).
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``.
tx_min: Lowest TX power to consider.
tx_max: Highest TX power to consider.
coarse_step: Step between coarse-sweep levels.
samples_per_level: Traces averaged at each level.
samples_per_level: Traces averaged at each level (and added again on verify).
refine: Whether to fill in integer levels around the coarse winner.
verify: Whether to re-measure the leading candidate to reject an outlier.
apply: Leave the winning TX power on the node when done (otherwise restore the
power it had before the sweep, if that could be read).
cooldown_s: Delay between individual traces (duty-cycle safety).
snr_tolerance: dB band for the lower-power tie-break (see :func:`select_best`).
on_level: Optional progress callback ``(completed, total, level_result)``.
persist_level: Optional callback to store each level's aggregated stats.
persist_level: Optional callback to store each level's aggregated result.
persist_trace: Optional callback to store each individual trace.
Returns:
A :class:`TxOptResult`. The device is left at its original TX power.
A :class:`TxOptResult`.
Raises:
ValueError: If the resolved TX range is empty.
"""
tx_min = clamp_tx_power(tx_min)
tx_max = clamp_tx_power(tx_max)
if tx_min > tx_max:
raise ValueError(f"Empty TX range: {tx_min}..{tx_max}")
original_tx = await device.get_tx_power()
measured: dict[int, TxLevelResult] = {}
original_tx = await device.get_remote_tx_power(admin_node)
# 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]] = {}
levels: dict[int, TxLevelResult] = {}
# Phase 1 + 2 share this planner so progress totals stay accurate.
coarse = _coarse_levels(tx_min, tx_max, coarse_step)
total_estimate = len(coarse) + (2 * coarse_step if refine else 0)
total_estimate = len(coarse) + (2 * coarse_step if refine else 0) + (1 if verify else 0)
completed = 0
async def measure_level(tx: int) -> TxLevelResult:
"""Run a batch of traces at ``tx`` (accumulating) and refresh its aggregate."""
nonlocal completed
await device.set_tx_power(tx)
stats = await trace_runner.measure(
await device.set_remote_tx_power(admin_node, tx)
batch = await trace_runner.run_traces(
device,
target,
samples=samples_per_level,
path=path,
cooldown_s=cooldown_s,
persist=persist_trace,
)
level = TxLevelResult(tx_power=tx, stats=stats, score=score_level(stats))
measured[tx] = level
traces_by_tx.setdefault(tx, []).extend(batch)
level = build_level(tx, target, traces_by_tx[tx])
levels[tx] = level
if persist_level is not None:
persist_level(stats)
persist_level(level)
completed += 1
if on_level is not None:
on_level(completed, max(total_estimate, completed), level)
@@ -117,26 +202,46 @@ async def optimize_tx_power(
for tx in coarse:
await measure_level(tx)
best_tx = max(measured, key=lambda t: measured[t].score)
best = select_best(list(levels.values()), snr_tolerance=snr_tolerance)
if refine:
lo = clamp_tx_power(best_tx - coarse_step + 1)
hi = clamp_tx_power(best_tx + coarse_step - 1)
lo = max(tx_min, best.tx_power - coarse_step + 1)
hi = min(tx_max, best.tx_power + coarse_step - 1)
for tx in range(lo, hi + 1):
if tx not in measured:
if tx not in levels:
await measure_level(tx)
best_tx = max(measured, key=lambda t: measured[t].score)
finally:
best = select_best(list(levels.values()), snr_tolerance=snr_tolerance)
if verify:
# Re-measure the leader with extra samples; if it was an outlier the larger
# sample will pull it back and a steadier neighbor can take over.
await measure_level(best.tx_power)
best = select_best(list(levels.values()), snr_tolerance=snr_tolerance)
if apply or original_tx is None:
final_tx = best.tx_power
else:
final_tx = original_tx # apply off: leave the node as we found it
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.
if original_tx is not None:
await device.set_tx_power(original_tx)
try:
await device.set_remote_tx_power(admin_node, original_tx)
except Exception: # noqa: BLE001 - best-effort restore; don't mask the cause
pass
raise
return TxOptResult(
target=target,
admin_node=admin_node.name,
path=path,
original_tx=original_tx,
best_tx=best_tx,
best_score=measured[best_tx].score,
applied=False,
levels=list(measured.values()),
best_tx=best.tx_power,
best_snr=best.target_snr,
best_success_rate=best.success_rate,
applied=apply,
levels=list(levels.values()),
)
+252 -68
View File
@@ -1,8 +1,10 @@
"""The ``tx-optimize`` tool: sweep transmit power and converge on the best setting.
"""The ``tx-optimize`` tool: tune a remote node's TX power for the best signal at a target.
Wraps :func:`meshtools.services.tx_optimizer.optimize_tx_power` with interactive prompts,
a live progress bar, persistence of every level, an interactive HTML chart, and an opt-in
apply step (changing the radio's TX power is a hardware change, so it is never implicit).
You force a path (just like ``trace``) ending at the **target** node where SNR is
measured. The node one hop *before* the target — one you hold admin rights on — is the
node whose transmit power gets swept and tuned. Admin passwords are remembered between
runs, progress streams live like a trace, and the winning power is written back to the
node when the sweep finishes.
"""
from __future__ import annotations
@@ -13,24 +15,29 @@ import questionary
import typer
from ..context import AppContext
from ..core.connection import TX_POWER_MAX, TX_POWER_MIN
from ..services import tx_optimizer
from ..core.connection import DeviceCommandError
from ..core.models import Contact
from ..services import trace_runner, tx_optimizer
from ..ui.widgets import make_progress, tx_opt_summary, tx_opt_table
from ..viz.tx_plot import render_tx_optimization
from .base import Tool, ToolResult, register
#: Trace count per TX level — kept to single digits so the radio's duty cycle stays sane
#: and the per-level sweep finishes in reasonable time.
MAX_SAMPLES = 9
@register
class TxOptimizeTool(Tool):
"""Find the transmit power with the strongest, most reliable signal to a target."""
"""Tune a remote node's TX power for the strongest, most reliable signal at a target."""
name = "tx-optimize"
help = "Sweep TX power and converge on the value with the best signal."
help = "Tune a remote node's TX power for the best signal at a target along a path."
category = "Optimization"
order = 10
async def prompt_params(self, ctx: AppContext) -> Optional[dict[str, Any]]:
"""Interactively gather target, range, sampling, and apply choices.
"""Interactively gather the path, sampling, range, and apply choices.
Args:
ctx: Shared application context.
@@ -41,89 +48,127 @@ class TxOptimizeTool(Tool):
device = await ctx.device()
contacts = await device.get_contacts()
choices = [c.name for c in contacts]
prompt = "Target node to optimize against:"
# ``autocomplete`` requires a non-empty choice list; with no known contacts fall
# back to a free-text entry so the user can still type a name or key prefix.
path_prompt = (
"Path to the target (comma-separated contacts/hex, ending at the target;\n"
"the node just before the target is the one we'll tune):"
)
validate_path = lambda v: _validate_link_path(v, contacts) # noqa: E731
if choices:
target = await questionary.autocomplete(
prompt, choices=choices, ignore_case=True
path_spec = await questionary.autocomplete(
path_prompt, choices=choices, ignore_case=True, validate=validate_path
).ask_async()
else:
target = await questionary.text(prompt).ask_async()
if not target:
path_spec = await questionary.text(path_prompt, validate=validate_path).ask_async()
if not path_spec:
return None
samples = await questionary.text(
"Traces per TX level:", default="5", validate=_positive_int
f"Traces per TX level? (1-{MAX_SAMPLES})", default="3", validate=_is_valid_sample_count
).ask_async()
if samples is None:
return None
tx_min = await questionary.text(
"Lowest TX power to try:", default=str(ctx.settings.tx_opt_min), validate=_is_int
).ask_async()
if tx_min is None:
return None
tx_max = await questionary.text(
"Highest TX power to try:", default=str(ctx.settings.tx_opt_max), validate=_is_int
).ask_async()
if tx_max is None:
return None
step = await questionary.text(
"Coarse step:", default="3", validate=_positive_int
"Coarse step:", default="3", validate=_is_valid_sample_count
).ask_async()
if step is None:
return None
refine = await questionary.confirm(
"Refine around the best level?", default=True
).ask_async()
apply = await questionary.confirm(
"Apply the winning TX power to the device afterward?", default=False
"Set the winning TX power on the node afterward?", default=True
).ask_async()
if apply is None:
return None
return {
"target": target.strip(),
"path": path_spec.strip(),
"samples": int(samples),
"tx_min": int(tx_min),
"tx_max": int(tx_max),
"step": int(step),
"refine": bool(refine),
"apply": bool(apply),
"tx_min": TX_POWER_MIN,
"tx_max": TX_POWER_MAX,
"viz": True,
}
async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult:
"""Run the sweep, persist levels, render results, and optionally apply the winner.
"""Resolve the link, log in, sweep TX power, render results, and apply the winner.
Args:
ctx: Shared application context.
params: ``target``, ``samples``, ``step``, ``refine``, ``apply``,
``tx_min``, ``tx_max``, ``viz``, and the injected ``_run_id``.
params: ``path``, ``samples``, ``tx_min``, ``tx_max``, ``step``, ``apply``,
optional ``password``/``viz``, and the injected ``_run_id``.
Returns:
A :class:`ToolResult` with the optimum and the chart path.
A :class:`ToolResult` with the optimum and any chart path.
"""
target = params["target"]
run_id = params["_run_id"]
device = await ctx.device()
contacts = await device.get_contacts()
# Resolve the forced path to hashes, then pull out the target (last hop) and the
# admin node we tune (the hop before it).
path = trace_runner.parse_trace_path(params["path"], contacts)
admin_node, target_label = _resolve_link(path, contacts)
samples = max(1, min(MAX_SAMPLES, int(params.get("samples", 3))))
if int(params.get("samples", 3)) > MAX_SAMPLES:
ctx.console.print(f"[warn]capping at {MAX_SAMPLES} traces per level[/warn]")
password = await self._resolve_password(ctx, admin_node, params)
ctx.console.print(
f"[dim]logging in to[/dim] [brand]{admin_node.name}[/brand][dim]…[/dim]"
)
if not await device.admin_login(admin_node, password):
ctx.admin_store.forget(admin_node) # bad password: don't keep reusing it
raise DeviceCommandError(
f"admin login to {admin_node.name!r} failed (wrong password?). "
"The saved password was cleared; re-run to enter a new one."
)
ctx.admin_store.remember(admin_node, password)
ctx.console.print(
f"[dim]tuning[/dim] [brand]{admin_node.name}[/brand] "
f"[dim]→ target[/dim] [brand]{target_label}[/brand] "
f"[dim]via[/dim] [muted]{path}[/muted]"
)
with make_progress(ctx.console) as progress:
task = progress.add_task(f"optimizing TX -> {target}", total=None)
task = progress.add_task(f"optimizing TX -> {target_label}", total=None)
def on_level(done: int, total: int, level) -> None: # noqa: ANN001
progress.update(
task, total=total, completed=done,
description=f"TX {level.tx_power:>2} "
f"SNR {_fmt_snr(level.stats.median_min_snr)}",
f"SNR {_fmt_snr(level.target_snr)} {level.success_rate:.0%}",
)
result = await tx_optimizer.optimize_tx_power(
device,
target,
tx_min=int(params.get("tx_min", TX_POWER_MIN)),
tx_max=int(params.get("tx_max", TX_POWER_MAX)),
target_label,
admin_node,
path,
tx_min=int(params.get("tx_min", ctx.settings.tx_opt_min)),
tx_max=int(params.get("tx_max", ctx.settings.tx_opt_max)),
coarse_step=int(params.get("step", 3)),
samples_per_level=int(params.get("samples", 5)),
refine=bool(params.get("refine", True)),
samples_per_level=samples,
apply=bool(params.get("apply", True)),
cooldown_s=ctx.settings.trace_cooldown_s,
on_level=on_level,
persist_level=lambda stats: ctx.repo.record_tx_sample(run_id, stats),
persist_level=lambda lv: ctx.repo.record_tx_sample(run_id, lv),
persist_trace=lambda t: ctx.repo.record_trace(run_id, t),
)
if params.get("apply"):
await device.set_tx_power(result.best_tx)
result.applied = True
ctx.log.info("applied TX power %s to device", result.best_tx)
if result.applied:
ctx.log.info("set TX power %s on %s", result.best_tx, admin_node.name)
ctx.console.print(tx_opt_table(result))
ctx.console.print(tx_opt_summary(result))
@@ -131,24 +176,61 @@ class TxOptimizeTool(Tool):
artifacts: list[str] = []
if params.get("viz", True):
assert ctx.settings.output_dir is not None
path = render_tx_optimization(result, ctx.settings.output_dir)
artifacts.append(str(path))
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 ""
)
return ToolResult(
summary={
"target": target,
"target": result.target,
"admin_node": result.admin_node,
"path": result.path,
"best_tx": result.best_tx,
"best_score": round(result.best_score, 3),
"best_snr": result.best_snr,
"best_success_rate": round(result.best_success_rate, 3),
"original_tx": result.original_tx,
"applied": result.applied,
"levels_measured": len(result.levels),
},
message=f"[ok]✓[/ok] optimum TX for [brand]{target}[/brand] is "
f"[brand]{result.best_tx}[/brand]"
+ (" [ok](applied)[/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,
artifacts=artifacts,
)
async def _resolve_password(
self, ctx: AppContext, admin_node: Contact, params: dict[str, Any]
) -> str:
"""Find the admin password: explicit flag, remembered, or an interactive prompt.
Args:
ctx: Shared application context.
admin_node: The node we're about to log in to.
params: Tool params (may carry an explicit ``password``).
Returns:
The password to log in with.
Raises:
DeviceCommandError: If no password is available and we can't prompt (JSON mode).
"""
password = params.get("password") or ctx.admin_store.get(admin_node)
if password:
return str(password)
if ctx.json_output:
raise DeviceCommandError(
f"no admin password for {admin_node.name!r}; pass --password or run once "
"interactively to store it."
)
entered = await questionary.password(
f"Admin password for {admin_node.name}:"
).ask_async()
if not entered:
raise DeviceCommandError("an admin password is required to tune a remote node.")
return entered
def register_cli(self, app: typer.Typer) -> None:
"""Register the ``tx-optimize`` subcommand.
@@ -159,36 +241,138 @@ class TxOptimizeTool(Tool):
@app.command(name=self.name, help=self.help)
def _tx_optimize(
target: str = typer.Option(..., "--target", "-t", help="Target node."),
samples: int = typer.Option(5, "--samples", "-n", help="Traces per level."),
path: str = typer.Option(
..., "--path", "-p",
help="Forced path ending at the target (e.g. 'Repeater,Target' or '3d,f2').",
),
samples: int = typer.Option(3, "--samples", "-n", help="Traces per TX level."),
step: int = typer.Option(3, "--step", help="Coarse sweep step."),
tx_min: int = typer.Option(TX_POWER_MIN, "--min", help="Lowest TX power."),
tx_max: int = typer.Option(TX_POWER_MAX, "--max", help="Highest TX power."),
refine: bool = typer.Option(True, "--refine/--no-refine", help="Local refine."),
apply: bool = typer.Option(False, "--apply", help="Write the winner to device."),
tx_min: Optional[int] = typer.Option(None, "--min", help="Lowest TX power."),
tx_max: Optional[int] = typer.Option(None, "--max", help="Highest TX power."),
password: Optional[str] = typer.Option(
None, "--password", help="Admin password (else remembered/prompted)."
),
apply: bool = typer.Option(True, "--apply/--no-apply", help="Set the winner."),
viz: bool = typer.Option(True, "--viz/--no-viz", help="Generate HTML chart."),
) -> None:
run_tool_command(
self,
{
"target": target, "samples": samples, "step": step,
"tx_min": tx_min, "tx_max": tx_max, "refine": refine,
"apply": apply, "viz": viz,
},
)
tool_params: dict[str, Any] = {
"path": path, "samples": samples, "step": step,
"apply": apply, "viz": viz,
}
if tx_min is not None:
tool_params["tx_min"] = tx_min
if tx_max is not None:
tool_params["tx_max"] = tx_max
if password is not None:
tool_params["password"] = password
run_tool_command(self, tool_params)
def _positive_int(value: str) -> bool | str:
"""Validate a positive-integer questionary answer.
def _resolve_link(path: str, contacts: list[Contact]) -> tuple[Contact, str]:
"""Split a forced path into the admin node we tune and the target's display label.
Args:
path: The comma-separated hash path (output of ``parse_trace_path``).
contacts: Known contacts, used to map hashes back to names/keys.
Returns:
``(admin_node, target_label)`` — the second-to-last hop as a full
:class:`Contact` (needed for login), and a friendly name for the last hop.
Raises:
DeviceCommandError: If the path has fewer than two hops, or the admin hop can't
be matched to a known contact carrying a public key.
"""
hops = [h for h in path.split(",") if h]
if len(hops) < 2:
raise DeviceCommandError(
"the path needs at least two hops: the node to tune and the target after it "
"(e.g. 'AdminNode,Target')."
)
admin = _contact_for_hash(hops[-2], contacts)
if admin is None or not (admin.public_key or "").strip():
raise DeviceCommandError(
f"the node before the target ({hops[-2]}) isn't a known contact with a public "
"key, so we can't log in to tune it. Receive an advert from it first."
)
target = _contact_for_hash(hops[-1], contacts)
return admin, (target.name if target else hops[-1])
def _contact_for_hash(hash_hex: str, contacts: list[Contact]) -> Optional[Contact]:
"""Return the contact whose key matches a path-hop hash, if any.
Args:
hash_hex: A path hop hash (a leading slice of the node's public key).
contacts: Known contacts to match against.
Returns:
The matching :class:`Contact`, or ``None``.
"""
needle = hash_hex.lower().removeprefix("0x")
for c in contacts:
pub = (c.public_key or "").lower().removeprefix("0x")
prefix = (c.key_prefix or "").lower().removeprefix("0x")
if pub.startswith(needle):
return c
if prefix and (prefix.startswith(needle) or needle.startswith(prefix)):
return c
return None
def _validate_link_path(value: str, contacts: list[Contact]) -> bool | str:
"""Validate the interactive path entry: parseable and at least two hops.
Args:
value: The raw comma-separated path entry.
contacts: Known contacts used to resolve names.
Returns:
``True`` if valid, otherwise an error message string.
"""
if not value.strip():
return "Enter a path ending at the target node."
try:
path = trace_runner.parse_trace_path(value, contacts)
except ValueError as exc:
return str(exc)
if len([h for h in path.split(",") if h]) < 2:
return "Need at least two hops: the node to tune, then the target."
return True
def _is_valid_sample_count(value: str) -> bool | str:
"""Validate a positive count in ``1..MAX_SAMPLES`` for a questionary text answer.
Args:
value: Raw input.
Returns:
``True`` if valid, else an error message.
``True`` if valid, otherwise an error message string.
"""
try:
return int(value) > 0 or "Enter a number greater than zero."
count = int(value)
except ValueError:
return "Enter a whole number."
if count < 1:
return "Enter a number greater than zero."
if count > MAX_SAMPLES:
return f"Maximum {MAX_SAMPLES}."
return True
def _is_int(value: str) -> bool | str:
"""Validate that a questionary answer is a whole number.
Args:
value: Raw input.
Returns:
``True`` if valid, otherwise an error message string.
"""
try:
int(value)
return True
except ValueError:
return "Enter a whole number."
+24 -11
View File
@@ -458,23 +458,30 @@ def tx_opt_table(result: TxOptResult) -> Table:
result: The optimization result to display.
Returns:
A Rich :class:`Table` of TX level, SNR, success rate, and score.
A Rich :class:`Table` of TX level, target SNR, success rate, and sample count.
"""
table = Table(title=f"TX sweep -> {result.target}", border_style="muted", expand=False)
table = Table(
title=f"TX sweep · {result.admin_node} -> {result.target}",
border_style="muted",
expand=False,
)
table.add_column("TX", justify="right")
table.add_column("median min SNR", justify="right")
table.add_column("target SNR", justify="right")
table.add_column("success", justify="right")
table.add_column("score", justify="right")
table.add_column("traces", justify="right")
for lv in result.sorted_by_tx():
is_best = lv.tx_power == result.best_tx
marker = "[ok]★[/ok] " if is_best else " "
snr = lv.stats.median_min_snr
snr = lv.target_snr
snr_cell = Text(f"{snr:+.1f}", style=snr_style(snr)) if snr is not None else Text("—")
score_txt = f"{lv.score:.2f}" if lv.score != float("-inf") else "—"
# Highlight anything short of a perfect success rate — reliability comes first.
rate = lv.success_rate
rate_style = "ok" if rate >= 1.0 else ("warn" if rate > 0 else "err")
rate_cell = Text(f"{rate:.0%}", style=rate_style)
tx_cell = f"{marker}{lv.tx_power}"
row_style = "ok" if is_best else None
table.add_row(
tx_cell, snr_cell, f"{lv.stats.success_rate:.0%}", score_txt, style=row_style
tx_cell, snr_cell, rate_cell, f"{lv.successes}/{lv.samples}", style=row_style
)
return table
@@ -488,13 +495,19 @@ def tx_opt_summary(result: TxOptResult) -> Panel:
Returns:
A Rich :class:`Panel` stating the chosen optimum and whether it was applied.
"""
best = result.best_level
snr = best.stats.median_min_snr if best else None
snr = result.best_snr
snr_text = Text(f"{snr:+.1f} dB", style=snr_style(snr)) if snr is not None else Text("n/a")
applied = "[ok]applied to device[/ok]" if result.applied else "[muted]not applied[/muted]"
applied = (
f"[ok]applied to {result.admin_node}[/ok]"
if result.applied
else "[muted]not applied[/muted]"
)
body = Text.assemble(
("tuning node ", "muted"), (f"{result.admin_node}\n", "brand"),
("target ", "muted"), (f"{result.target}\n", "brand"),
("optimal TX ", "muted"), (f"{result.best_tx}", "brand"), ("\n", ""),
("at SNR ", "muted"), snr_text, ("\n", ""),
("target SNR ", "muted"), snr_text, ("\n", ""),
("reliability ", "muted"), (f"{result.best_success_rate:.0%}\n", ""),
("previous TX ", "muted"),
(f"{result.original_tx if result.original_tx is not None else '?'}\n", ""),
("status ", "muted"), Text.from_markup(applied),
+12 -22
View File
@@ -1,12 +1,11 @@
"""Plotly renderer for TX-power optimization sweeps.
"""Plotly renderer for remote-admin TX-power optimization sweeps.
Produces a self-contained, interactive HTML chart: reliability-weighted score and median
bottleneck SNR versus TX power, with the chosen optimum marked.
Produces a self-contained, interactive HTML chart: median SNR measured *at the target*
and trace success rate versus the admin node's TX power, with the chosen optimum marked.
"""
from __future__ import annotations
import math
from datetime import datetime
from pathlib import Path
@@ -16,7 +15,6 @@ from ..core.models import TxOptResult
_TEMPLATE = "plotly_dark"
_BRAND = "#5eead4"
_ACCENT = "#818cf8"
_MUTED = "#94a3b8"
@@ -32,25 +30,18 @@ def render_tx_optimization(result: TxOptResult, output_dir: Path) -> Path:
"""
levels = result.sorted_by_tx()
tx = [lv.tx_power for lv in levels]
snr = [lv.stats.median_min_snr for lv in levels]
score = [lv.score if math.isfinite(lv.score) else None for lv in levels]
success = [lv.stats.success_rate * 100 for lv in levels]
snr = [lv.target_snr for lv in levels]
success = [lv.success_rate * 100 for lv in levels]
fig = go.Figure()
fig.add_trace(
go.Scatter(
x=tx, y=snr, name="median min SNR (dB)", mode="lines+markers",
x=tx, y=snr, name="target SNR (dB)", mode="lines+markers",
line=dict(color=_BRAND, width=3), marker=dict(size=8),
connectgaps=False,
hovertemplate="TX %{x}<br>SNR %{y:+.1f} dB<extra></extra>",
)
)
fig.add_trace(
go.Scatter(
x=tx, y=score, name="score", mode="lines+markers",
line=dict(color=_ACCENT, width=2, dash="dot"), marker=dict(size=6),
hovertemplate="TX %{x}<br>score %{y:.2f}<extra></extra>",
)
)
fig.add_trace(
go.Bar(
x=tx, y=success, name="success rate (%)", yaxis="y2",
@@ -59,12 +50,11 @@ def render_tx_optimization(result: TxOptResult, output_dir: Path) -> Path:
)
)
best = result.best_level
if best is not None and best.stats.median_min_snr is not None:
if result.best_snr is not None:
fig.add_vline(x=result.best_tx, line=dict(color="#4ade80", width=2, dash="dash"))
fig.add_trace(
go.Scatter(
x=[result.best_tx], y=[best.stats.median_min_snr],
x=[result.best_tx], y=[result.best_snr],
name=f"optimum (TX {result.best_tx})", mode="markers",
marker=dict(color="#4ade80", size=16, symbol="star"),
hovertemplate=f"optimum<br>TX {result.best_tx}"
@@ -75,12 +65,12 @@ def render_tx_optimization(result: TxOptResult, output_dir: Path) -> Path:
fig.update_layout(
template=_TEMPLATE,
title=dict(
text=f"TX-power optimization — {result.target}"
text=f"TX-power optimization — {result.admin_node} → {result.target}"
f" · optimum TX {result.best_tx}",
font=dict(color=_BRAND),
),
xaxis=dict(title="TX power", dtick=1),
yaxis=dict(title="SNR (dB) / score"),
xaxis=dict(title="admin-node TX power", dtick=1),
yaxis=dict(title="target SNR (dB)"),
yaxis2=dict(
title="success rate (%)", overlaying="y", side="right",
range=[0, 105], showgrid=False,
+81 -11
View File
@@ -251,21 +251,91 @@ async def test_mock_device_trace_is_unimodal_in_tx() -> None:
assert peak > high
async def _setup_link(optimal_remote_tx: int = 20):
"""Return a connected mock plus the (admin, target) contacts and forced path.
The path runs admin → target, so the optimizer tunes the admin node and reads the
SNR the target receives from it.
"""
device = MockDevice(optimal_remote_tx=optimal_remote_tx)
await device.connect()
contacts = await device.get_contacts()
admin = next(c for c in contacts if c.name == "Yagi-Repeater")
target = next(c for c in contacts if c.name == "Alice")
path = trace_runner.parse_trace_path(f"{admin.name},{target.name}", contacts)
assert await device.admin_login(admin, "admin")
return device, admin, target, path
async def test_admin_login_rejects_wrong_password() -> None:
"""A wrong admin password is refused, and the node stays un-tunable."""
device = MockDevice(admin_password="secret")
await device.connect()
admin = (await device.get_contacts())[0]
assert await device.admin_login(admin, "nope") is False
with pytest.raises(Exception):
await device.set_remote_tx_power(admin, 18) # not logged in
assert await device.admin_login(admin, "secret") is True
await device.set_remote_tx_power(admin, 18) # now allowed
assert await device.get_remote_tx_power(admin) == 18
async def test_tx_optimizer_finds_simulator_peak(tmp_path: Path) -> None:
"""The optimizer converges near the simulator's known optimal TX power."""
"""The optimizer converges near the simulated remote optimum and applies it."""
from meshtools.services import tx_optimizer
device = MockDevice(optimal_tx=14)
await device.connect()
await device.set_tx_power(20)
device, admin, target, path = await _setup_link(optimal_remote_tx=20)
result = await tx_optimizer.optimize_tx_power(
device, "Alice", samples_per_level=12, coarse_step=3, cooldown_s=0
device, target.name, admin, path,
samples_per_level=8, coarse_step=3, cooldown_s=0,
)
assert abs(result.best_tx - 14) <= 2 # within a step of the true peak
assert result.original_tx == 20
assert await device.get_tx_power() == 20 # original restored, not the winner
assert abs(result.best_tx - 20) <= 3 # near the true remote peak
assert result.best_success_rate == 1.0 # reliability-first: the winner never drops
assert result.applied
assert await device.get_remote_tx_power(admin) == result.best_tx # left tuned
assert result.admin_node == "Yagi-Repeater"
async def test_tx_optimizer_no_apply_restores_original(tmp_path: Path) -> None:
"""With apply off, the node is left at the power it started with."""
from meshtools.services import tx_optimizer
device, admin, target, path = await _setup_link()
await device.set_remote_tx_power(admin, 15) # a known starting power
result = await tx_optimizer.optimize_tx_power(
device, target.name, admin, path,
samples_per_level=4, coarse_step=4, refine=False, verify=False,
apply=False, cooldown_s=0,
)
assert result.original_tx == 15
assert not result.applied
assert await device.get_remote_tx_power(admin) == 15 # restored, not the winner
def test_select_best_prefers_reliability_then_lowest_power() -> None:
"""A 100%-reliable level beats a flakier higher-SNR one; ties go to lower TX."""
from meshtools.core.models import TraceStats, TxLevelResult
from meshtools.services.tx_optimizer import select_best
def level(tx: int, snr: float, successes: int, samples: int = 5) -> TxLevelResult:
return TxLevelResult(
tx_power=tx, samples=samples, successes=successes, target_snr=snr,
score=snr, stats=TraceStats(target="t", samples=samples, successes=successes,
median_min_snr=snr, median_rtt_ms=None),
)
# A flaky level with a great SNR must not beat a perfectly reliable one.
flaky = level(26, snr=12.0, successes=3)
solid = level(20, snr=7.0, successes=5)
assert select_best([flaky, solid]).tx_power == 20
# Among reliable levels with SNR within tolerance, the lowest TX wins.
a = level(18, snr=7.4, successes=5)
b = level(22, snr=8.0, successes=5)
assert select_best([a, b], snr_tolerance=1.0).tx_power == 18
def test_tx_plot_writes_html(tmp_path: Path) -> None:
@@ -276,10 +346,10 @@ def test_tx_plot_writes_html(tmp_path: Path) -> None:
from meshtools.viz.tx_plot import render_tx_optimization
async def _build():
device = MockDevice(optimal_tx=14)
await device.connect()
device, admin, target, path = await _setup_link()
return await tx_optimizer.optimize_tx_power(
device, "Alice", samples_per_level=4, coarse_step=4, refine=False, cooldown_s=0
device, target.name, admin, path,
samples_per_level=4, coarse_step=4, refine=False, verify=False, cooldown_s=0,
)
result = asyncio.run(_build())