Files
MeshTerm/meshtools/core/models.py
T
Jean-Pierre MartineauandClaude Opus 4.8 20c32f9642 Introduce an always-on event hub and broaden the device event surface
Decouple listening from consuming as the first step toward a full MeshCore
client. A new always-on EventHub owns the single device subscription and fans
typed MeshEvents out to any number of subscribers; passive-monitor history
logging becomes just one subscriber, so listening is now unconditional while the
on/off toggle controls only persistence.

- core/events.py: MeshEvent envelope + EventKind (OBSERVATION/MESSAGE/ACK)
- services/event_hub.py: subscribe/stream/wait_for fan-out, always-on pump
- connection.py: Device.subscribe_observations -> unified subscribe_events
  emitting observations, inbound messages, and acks; add message_from_event /
  ack_from_event mappers and a simulated message stream on MockDevice
- core/models.py: Message and Ack domain models
- monitor_service.py: slim to a hub subscriber (recording, not listening)
- context.py/menu.py: wire ctx.events into the session lifecycle
- config.py: connect_on_start setting (default on) to allow lazy connect
- Remove monitor --seconds / foreground capture and Device.listen; monitoring
  is passive/background only

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-05 21:20:24 -04:00

477 lines
18 KiB
Python

"""Domain models shared across services, tools, persistence, and visualizations.
These are plain dataclasses with no I/O dependencies so they can be constructed by the
real device, the simulator, or rehydrated from the database identically.
"""
from __future__ import annotations
import statistics
from collections import Counter
from dataclasses import dataclass, field
from datetime import datetime, timezone
from typing import Optional
#: Label used for our own (local) device when framing a trace path's endpoints.
LOCAL_DEVICE_LABEL = "us"
def utcnow() -> datetime:
"""Return a timezone-aware UTC timestamp.
Returns:
The current time in UTC.
"""
return datetime.now(timezone.utc)
@dataclass(slots=True)
class Contact:
"""A node known to the connected companion device.
Attributes:
name: Human-friendly name advertised by the node.
public_key: Full public key hex string, if known.
key_prefix: Short key prefix used to address the node.
last_seen: When the node was last heard, if known.
"""
name: str
public_key: str = ""
key_prefix: str = ""
last_seen: Optional[datetime] = None
@dataclass(slots=True)
class Observation:
"""A single over-the-air reception heard while passively monitoring the mesh.
Adverts, telemetry frames, and other packets the companion overhears are captured as
observations and logged longitudinally, so the mesh's behavior can be reviewed over
time rather than only at the instant a command runs.
Attributes:
node: Key prefix / hash identifying the transmitting node, if known.
name: Friendly name advertised by the node, if carried.
kind: Packet class, e.g. ``advert`` or ``telemetry``.
snr: Signal-to-noise ratio (dB) the companion measured, if reported.
rssi: Received signal strength (dBm), if reported.
lat: Advertised latitude (decimal degrees), when the node shares location.
lon: Advertised longitude (decimal degrees), when the node shares location.
observed_at: When the packet was heard.
raw: Optional raw event payload for debugging/replay.
"""
node: Optional[str]
name: Optional[str] = None
kind: str = "advert"
snr: Optional[float] = None
rssi: Optional[float] = None
lat: Optional[float] = None
lon: Optional[float] = None
observed_at: datetime = field(default_factory=utcnow)
raw: Optional[dict] = None
@dataclass(slots=True)
class Message:
"""An inbound text message the companion received (direct or on a channel).
Direct messages carry a :attr:`sender` key prefix; channel messages carry a
:attr:`channel` index instead. Both are surfaced by the always-on event hub as
:attr:`~meshtools.core.events.EventKind.MESSAGE` events, so client features (an inbox,
notifications) can react to them without polling.
Attributes:
text: The decoded message body.
sender: Key prefix of the sending contact (direct messages), if known.
channel: Channel index the message arrived on (channel messages), if applicable.
is_channel: Whether this is a channel message rather than a direct one.
sender_timestamp: The sender's own timestamp for the message, if carried.
snr: Signal-to-noise ratio (dB) of the reception, if reported.
received_at: When the companion delivered the message to us.
raw: Optional raw event payload for debugging/replay.
"""
text: str
sender: Optional[str] = None
channel: Optional[int] = None
is_channel: bool = False
sender_timestamp: Optional[datetime] = None
snr: Optional[float] = None
received_at: datetime = field(default_factory=utcnow)
raw: Optional[dict] = None
@dataclass(slots=True)
class Ack:
"""A delivery acknowledgement for a message the companion sent.
Attributes:
code: The ACK correlation code (hex), matching it to the sent message, if present.
received_at: When the acknowledgement arrived.
raw: Optional raw event payload for debugging/replay.
"""
code: Optional[str] = None
received_at: datetime = field(default_factory=utcnow)
raw: Optional[dict] = None
@dataclass(slots=True)
class HeardNode:
"""Aggregated reception statistics for one node across many observations.
Attributes:
node: Key prefix / hash of the node (``None`` only if never identified).
name: Most recent friendly name seen for the node, if any.
count: Number of observations aggregated.
median_snr: Median SNR (dB) across observations that reported one.
best_snr: Strongest SNR (dB) seen, if any.
last_rssi: Most recent RSSI (dBm), if any.
last_seen: Timestamp of the most recent observation.
lat: Most recent advertised latitude, if the node shared one.
lon: Most recent advertised longitude, if the node shared one.
"""
node: Optional[str]
name: Optional[str]
count: int
median_snr: Optional[float]
best_snr: Optional[float]
last_rssi: Optional[float]
last_seen: datetime
lat: Optional[float] = None
lon: Optional[float] = None
@property
def has_location(self) -> bool:
"""Whether this node reported a usable latitude/longitude."""
return self.lat is not None and self.lon is not None
@classmethod
def from_observations(
cls, node: Optional[str], observations: list["Observation"]
) -> "HeardNode":
"""Aggregate one node's observations into reception statistics.
Args:
node: The node identifier these observations belong to.
observations: The observations for ``node`` (must be non-empty).
Returns:
A :class:`HeardNode` summarizing them. The most recent observation supplies
the name, RSSI, and location; SNR is summarized robustly (median + best).
"""
ordered = sorted(observations, key=lambda o: o.observed_at)
latest = ordered[-1]
snrs = [o.snr for o in ordered if o.snr is not None]
located = next(
(o for o in reversed(ordered) if o.lat is not None and o.lon is not None), None
)
name = next((o.name for o in reversed(ordered) if o.name), None)
return cls(
node=node,
name=name,
count=len(ordered),
median_snr=statistics.median(snrs) if snrs else None,
best_snr=max(snrs) if snrs else None,
last_rssi=latest.rssi,
last_seen=latest.observed_at,
lat=located.lat if located else None,
lon=located.lon if located else None,
)
@dataclass(slots=True)
class Hop:
"""A single hop in a path trace.
Attributes:
index: Zero-based position of the hop along the path.
node: Identifier of the relaying node (name or key prefix), if resolved.
snr: Signal-to-noise ratio in dB recorded at this hop.
"""
index: int
node: Optional[str]
snr: float
@dataclass(slots=True)
class TraceResult:
"""The aggregated outcome of a single path trace to a target.
Attributes:
target: Name or key prefix of the trace destination.
success: Whether a trace reply was received before timeout.
hops: Per-hop SNR readings, ordered from source to destination.
round_trip_ms: Round-trip time of the trace in milliseconds, if measured.
tx_power: TX power level in effect when the trace ran, if known.
path_hash_bytes: Per-hop path-hash width (bytes) used by the trace command, so
node hashes can be displayed at the same width the command addressed them.
timestamp: When the trace completed.
raw: Optional raw event payload for debugging/replay.
"""
target: str
success: bool
hops: list[Hop] = field(default_factory=list)
round_trip_ms: Optional[float] = None
tx_power: Optional[int] = None
path_hash_bytes: Optional[int] = None
timestamp: datetime = field(default_factory=utcnow)
raw: Optional[dict] = None
@property
def hop_count(self) -> int:
"""Number of hops recorded in the trace."""
return len(self.hops)
@property
def min_snr(self) -> Optional[float]:
"""The bottleneck (weakest) SNR along the path, or ``None`` if no hops."""
if not self.hops:
return None
return min(h.snr for h in self.hops)
@property
def path_str(self) -> str:
"""A compact ``a -> b -> c`` rendering of the resolved path."""
if not self.hops:
return self.target
nodes = [h.node or f"hop{h.index}" for h in self.hops]
return " -> ".join(nodes)
def edges(self, device_label: str = LOCAL_DEVICE_LABEL) -> list["HopEdge"]:
"""Frame the per-hop SNR as directed ``origin -> destination`` edges.
Each hop's SNR is the signal measured arriving at that node, so an edge runs
from the previous node to this one. The first edge therefore originates at our
own device, and (because firmware records the reply returning to us as a final
hash-less hop) the last edge's destination is our device too.
Args:
device_label: Name to show for our own device at the path's endpoints.
Returns:
One :class:`HopEdge` per hop, in path order.
"""
edges: list[HopEdge] = []
origin = device_label
for hop in self.hops:
destination = hop.node or device_label
edges.append(HopEdge(index=hop.index, origin=origin, destination=destination, snr=hop.snr))
origin = destination
return edges
@dataclass(slots=True)
class HopEdge:
"""A directed link in a trace path: a hop framed as ``origin -> destination``.
Attributes:
index: Zero-based position of the hop along the path.
origin: Identifier of the transmitting node (our device for the first edge).
destination: Identifier of the receiving node (our device for the last edge).
snr: Signal-to-noise ratio in dB measured at ``destination``.
"""
index: int
origin: str
destination: str
snr: float
@dataclass(slots=True)
class HopAggregate:
"""Median SNR for one hop position aggregated across several traces.
``origin`` and ``destination`` hold raw node identifiers; ``None`` means our own
device, so the display label can be applied at render time.
Attributes:
index: Zero-based hop position along the path.
origin: Representative transmitting node at this position (``None`` = us).
destination: Representative receiving node at this position (``None`` = us).
median_snr: Median SNR in dB measured at ``destination`` across the samples.
samples: Number of traces that reported this hop.
"""
index: int
origin: Optional[str]
destination: Optional[str]
median_snr: float
samples: int
@dataclass(slots=True)
class TraceStats:
"""Robust statistics aggregated over several traces to the same target.
Robust (median-based) metrics are used throughout because mesh SNR readings are
noisy and prone to outliers.
Attributes:
target: The trace destination these statistics describe.
samples: Number of traces attempted.
successes: Number of traces that returned a reply.
median_min_snr: Median of each trace's bottleneck SNR, the headline metric.
median_rtt_ms: Median round-trip time, if measured.
tx_power: TX power level in effect for these samples, if fixed.
hop_snrs: Per-hop median SNR across the successful traces, in path order.
"""
target: str
samples: int
successes: int
median_min_snr: Optional[float]
median_rtt_ms: Optional[float]
tx_power: Optional[int] = None
hop_snrs: list[HopAggregate] = field(default_factory=list)
@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
@classmethod
def from_traces(cls, target: str, traces: list[TraceResult]) -> "TraceStats":
"""Aggregate a list of traces into robust statistics.
Args:
target: The trace destination.
traces: The individual trace results to aggregate.
Returns:
A :class:`TraceStats` summarizing the supplied traces.
"""
successes = [t for t in traces if t.success]
min_snrs = [t.min_snr for t in successes if t.min_snr is not None]
rtts = [t.round_trip_ms for t in successes if t.round_trip_ms is not None]
tx_powers = {t.tx_power for t in traces if t.tx_power is not None}
return cls(
target=target,
samples=len(traces),
successes=len(successes),
median_min_snr=statistics.median(min_snrs) if min_snrs else None,
median_rtt_ms=statistics.median(rtts) if rtts else None,
tx_power=next(iter(tx_powers)) if len(tx_powers) == 1 else None,
hop_snrs=cls._aggregate_hops(successes),
)
@staticmethod
def _aggregate_hops(successes: list["TraceResult"]) -> list[HopAggregate]:
"""Compute the median SNR per hop position across successful traces.
Hops are grouped by their path position; for each position the SNR median is
taken and the most common origin/destination nodes are used so the aggregate
path reads like a single representative trace. Node identities are kept raw
(``None`` = our device) so a display label can be applied later.
Args:
successes: The successful traces to aggregate.
Returns:
One :class:`HopAggregate` per hop position, ordered along the path.
"""
snrs_by_index: dict[int, list[float]] = {}
origins_by_index: dict[int, list[Optional[str]]] = {}
dests_by_index: dict[int, list[Optional[str]]] = {}
for trace in successes:
origin: Optional[str] = None # the first hop originates at our device
for hop in trace.hops:
snrs_by_index.setdefault(hop.index, []).append(hop.snr)
origins_by_index.setdefault(hop.index, []).append(origin)
dests_by_index.setdefault(hop.index, []).append(hop.node)
origin = hop.node
aggregates: list[HopAggregate] = []
for index in sorted(snrs_by_index):
snrs = snrs_by_index[index]
origin = Counter(origins_by_index[index]).most_common(1)[0][0]
destination = Counter(dests_by_index[index]).most_common(1)[0][0]
aggregates.append(
HopAggregate(
index=index,
origin=origin,
destination=destination,
median_snr=statistics.median(snrs),
samples=len(snrs),
)
)
return aggregates
@dataclass(slots=True)
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 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
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 remote-admin TX-power optimization run.
Attributes:
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_snr: Optional[float]
best_success_rate: float
applied: bool
levels: list[TxLevelResult] = field(default_factory=list)
@property
def best_level(self) -> Optional[TxLevelResult]:
"""The :class:`TxLevelResult` for ``best_tx``, if present."""
return next((lv for lv in self.levels if lv.tx_power == self.best_tx), None)
def sorted_by_tx(self) -> list[TxLevelResult]:
"""Return measured levels sorted ascending by TX power.
Returns:
The levels ordered by TX power, suitable for plotting.
"""
return sorted(self.levels, key=lambda lv: lv.tx_power)