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:
1 parent
a3ab95fd26
commit
c75a2eb2e3
12 files changed
+971
-198
No files matched your search
@@ -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,
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
@@ -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)),
|
||||
)
|
||||
@@ -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
@@ -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)
|
||||
|
||||
|
||||
@@ -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(),
|
||||
),
|
||||
)
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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())
|
||||
|
||||
Reference in new issue
Block a user