diff --git a/meshtools/cli.py b/meshtools/cli.py index 7bfe3ee..c49ee18 100644 --- a/meshtools/cli.py +++ b/meshtools/cli.py @@ -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, diff --git a/meshtools/context.py b/meshtools/context.py index 902a3dc..849b505 100644 --- a/meshtools/context.py +++ b/meshtools/context.py @@ -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 diff --git a/meshtools/core/admin_store.py b/meshtools/core/admin_store.py new file mode 100644 index 0000000..6533339 --- /dev/null +++ b/meshtools/core/admin_store.py @@ -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 (``/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) diff --git a/meshtools/core/config.py b/meshtools/core/config.py index ebc876a..8c47506 100644 --- a/meshtools/core/config.py +++ b/meshtools/core/config.py @@ -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)), ) diff --git a/meshtools/core/connection.py b/meshtools/core/connection.py index ae00993..faf712c 100644 --- a/meshtools/core/connection.py +++ b/meshtools/core/connection.py @@ -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. diff --git a/meshtools/core/models.py b/meshtools/core/models.py index 4b9e3f4..a7d7391 100644 --- a/meshtools/core/models.py +++ b/meshtools/core/models.py @@ -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) diff --git a/meshtools/persistence/repository.py b/meshtools/persistence/repository.py index 5aa8027..147f387 100644 --- a/meshtools/persistence/repository.py +++ b/meshtools/persistence/repository.py @@ -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(), ), ) diff --git a/meshtools/services/tx_optimizer.py b/meshtools/services/tx_optimizer.py index 1e2c0a8..45a80a1 100644 --- a/meshtools/services/tx_optimizer.py +++ b/meshtools/services/tx_optimizer.py @@ -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()), ) diff --git a/meshtools/tools/tx_optimize.py b/meshtools/tools/tx_optimize.py index e5822c2..44d5960 100644 --- a/meshtools/tools/tx_optimize.py +++ b/meshtools/tools/tx_optimize.py @@ -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." diff --git a/meshtools/ui/widgets.py b/meshtools/ui/widgets.py index 02a9f99..1a7133f 100644 --- a/meshtools/ui/widgets.py +++ b/meshtools/ui/widgets.py @@ -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), diff --git a/meshtools/viz/tx_plot.py b/meshtools/viz/tx_plot.py index 7dbe59d..49dae8c 100644 --- a/meshtools/viz/tx_plot.py +++ b/meshtools/viz/tx_plot.py @@ -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}
SNR %{y:+.1f} dB", ) ) - 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}
score %{y:.2f}", - ) - ) 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
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, diff --git a/tests/test_skeleton.py b/tests/test_skeleton.py index 1849dfe..64ff13c 100644 --- a/tests/test_skeleton.py +++ b/tests/test_skeleton.py @@ -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())