meshcorectl 0.1.0__py3-none-any.whl

meshcorectl/commands/scan.py

@@ -0,0 +1,76 @@
+"""`meshcorectl scan` -- non-interactive discovery of BLE/serial candidates.
+
+A plain read-only listing: pick an address/port from the output and pass it
+to `meshcorectl config set-context`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+import serial.tools.list_ports
+from bleak import BleakScanner
+from bleak.exc import BleakError
+
+from ..output import output_option, render, resolve_output
+
+
+@click.command(name="scan")
+@click.option("--ble/--no-ble", "include_ble", default=True, help="Include BLE devices.")
+@click.option(
+    "--serial/--no-serial", "include_serial", default=True, help="Include serial ports."
+)
+@click.option(
+    "--timeout",
+    "timeout",
+    type=float,
+    default=2.0,
+    show_default=True,
+    metavar="SECONDS",
+    help="BLE scan duration.",
+)
+@output_option
+@click.pass_obj
+def scan_command(
+    state: Any,
+    include_ble: bool,
+    include_serial: bool,
+    timeout: float,
+    output_override: str | None,
+) -> None:
+    """List discoverable BLE and serial candidates."""
+    rows = state.run_async(_scan(include_ble, include_serial, timeout))
+    if not rows:
+        click.echo("No candidates found.", err=True)
+        return
+    click.echo(render(rows, resolve_output(state.output, output_override), kind="scan-result"))
+
+
+async def _scan(include_ble: bool, include_serial: bool, timeout: float) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    if include_ble:
+        rows.extend(await scan_ble(timeout))
+    if include_serial:
+        rows.extend(scan_serial())
+    return rows
+
+
+async def scan_ble(timeout: float) -> list[dict[str, Any]]:
+    try:
+        devices = await BleakScanner.discover(timeout=timeout)
+    except BleakError as exc:
+        click.echo(f"BLE scan unavailable: {exc}", err=True)
+        return []
+    return [
+        {"kind": "ble", "address": device.address, "name": device.name}
+        for device in devices
+        if device.name and device.name.startswith("MeshCore-")
+    ]
+
+
+def scan_serial() -> list[dict[str, Any]]:
+    return [
+        {"kind": "serial", "address": port.device, "name": port.description}
+        for port in serial.tools.list_ports.comports()
+    ]

meshcorectl/commands/send.py

@@ -0,0 +1,124 @@
+"""`meshcorectl send` -- send a message to a contact/channel."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from ..connect import MeshCoreConnection
+from ..mesh_data import (
+    AmbiguousMatchError,
+    fetch_channels,
+    fetch_contacts,
+    find_channel,
+    find_contact,
+)
+from ..mesh_data import send_channel_message as send_channel_message_data
+from ..mesh_data import send_message as send_message_data
+from ..selectors import SelectorError, filter_contacts
+
+
+@click.group(name="send")
+def send_group() -> None:
+    """Send a message to a contact or a channel."""
+
+
+@send_group.command("message", context_settings={"ignore_unknown_options": True})
+@click.argument("args", nargs=-1, type=click.UNPROCESSED, metavar="[CONTACT] TEXT")
+@click.option(
+    "-l",
+    "--selector",
+    "selector_text",
+    default=None,
+    metavar="SELECTOR",
+    help="Send to every contact matching this filter instead of one by name.",
+)
+@click.option(
+    "--wait-ack",
+    is_flag=True,
+    help="Wait for delivery confirmation, retrying (and flooding) automatically.",
+)
+@click.option("--dry-run", is_flag=True, help="Show what would be sent without sending it.")
+@click.pass_obj
+def send_message(
+    state: Any,
+    args: tuple[str, ...],
+    selector_text: str | None,
+    wait_ack: bool,
+    dry_run: bool,
+) -> None:
+    """Send TEXT to CONTACT, or to every contact matching -l/--selector.
+
+    CONTACT and TEXT come out of a single catch-all argument, not two
+    separate Click arguments: an optional leading CONTACT ahead of a
+    required TEXT has the same Click positional-filling ambiguity `exec`'s
+    docstring explains, so it's resolved the same way here. An unquoted
+    multi-word message is joined back together with spaces.
+    """
+    tokens = list(args)
+    if selector_text is None:
+        if len(tokens) < 2:
+            raise click.ClickException(
+                "pass CONTACT and TEXT, or -l/--selector and TEXT (see --help)"
+            )
+        name: str | None = tokens[0]
+        text = " ".join(tokens[1:])
+    else:
+        if not tokens:
+            raise click.ClickException(
+                "pass CONTACT and TEXT, or -l/--selector and TEXT (see --help)"
+            )
+        name = None
+        text = " ".join(tokens)
+
+    async def run(connection: MeshCoreConnection) -> None:
+        contacts = await fetch_contacts(connection)
+        if name is not None:
+            try:
+                contact = find_contact(contacts, name)
+            except AmbiguousMatchError as exc:
+                raise click.ClickException(str(exc)) from exc
+            if contact is None:
+                raise click.ClickException(f"no contact matching {name!r}")
+            targets = [contact]
+        else:
+            try:
+                targets = filter_contacts(contacts, selector_text)
+            except SelectorError as exc:
+                raise click.ClickException(str(exc)) from exc
+            if not targets:
+                click.echo("No contacts matched.", err=True)
+                return
+
+        for target in targets:
+            if dry_run:
+                click.echo(f"would send to {target['name']!r}: {text!r} (dry run)")
+                continue
+            result = await send_message_data(connection, target, text, wait_ack=wait_ack)
+            status = "acked" if result.get("acked") else "sent"
+            click.echo(f"{status}: {target['name']!r}")
+
+    state.call(run)
+
+
+@send_group.command("channel")
+@click.argument("index_or_name", metavar="CHANNEL")
+@click.argument("text")
+@click.option("--dry-run", is_flag=True, help="Show what would be sent without sending it.")
+@click.pass_obj
+def send_channel(state: Any, index_or_name: str, text: str, dry_run: bool) -> None:
+    """Send TEXT to CHANNEL (by index or name)."""
+
+    async def run(connection: MeshCoreConnection) -> None:
+        channels = await fetch_channels(connection)
+        channel = find_channel(channels, index_or_name)
+        if channel is None:
+            raise click.ClickException(f"no channel matching {index_or_name!r}")
+        if dry_run:
+            click.echo(f"would send to channel {channel['name']!r}: {text!r} (dry run)")
+            return
+        await send_channel_message_data(connection, channel, text)
+        click.echo(f"sent: {channel['name']!r}")
+
+    state.call(run)

meshcorectl/commands/set_.py

@@ -0,0 +1,73 @@
+"""`meshcorectl set device` -- set a device parameter."""
+
+from __future__ import annotations
+
+import inspect
+import textwrap
+from typing import Any
+
+import click
+
+from ..connect import MeshCoreConnection
+from ..mesh_data import DEVICE_PARAMS, set_device_param
+from ..output import output_option, render_result, resolve_output
+
+
+@click.group(name="set")
+def set_group() -> None:
+    """Set a device parameter."""
+
+
+@set_group.command("device")
+@click.argument("param", metavar="PARAM")
+@click.argument("value", metavar="VALUE")
+@click.option("--dry-run", is_flag=True, help="Show what would be set without setting it.")
+@output_option
+@click.pass_obj
+def set_device_command(
+    state: Any, param: str, value: str, dry_run: bool, output_override: str | None
+) -> None:
+    """Set device parameter PARAM to VALUE.
+
+    \b
+    Known parameters: {params}
+    """
+    if dry_run:
+        click.echo(f"would set {param} to {value!r} (dry run)")
+        return
+    if param not in DEVICE_PARAMS:
+        raise click.ClickException(
+            f"unknown device parameter {param!r} (expected one of: {', '.join(DEVICE_PARAMS)})"
+        )
+
+    async def run(connection: MeshCoreConnection) -> None:
+        await set_device_param(connection, param, value)
+
+    state.call(run)
+    text = f"{param} set to {value!r}"
+    fmt = resolve_output(state.output, output_override)
+    click.echo(render_result({"param": param, "value": value}, fmt, text))
+
+
+def _format_params_help(raw_help: str, params: tuple[str, ...]) -> str:
+    """Fill `raw_help`'s `{params}` placeholder with `params`, wrapped to a
+    readable width.
+
+    `raw_help` is dedented (`inspect.cleandoc`) *before* substituting, not
+    after: Python only auto-dedents docstrings at compile time starting in
+    3.13, so on 3.10-3.12 a bare `f.__doc__` still carries its original
+    source indentation. Substituting a multi-line, zero-indent wrapped
+    value into that indented text and dedenting afterward (which is what
+    Click's own `--help` rendering does to `.help`) breaks: the newly
+    inserted line has no indentation of its own, which drags the computed
+    common indent down to zero and defeats the dedent for every other line.
+    Dedenting first avoids the whole problem, on every Python version.
+    """
+    wrapped = textwrap.fill(", ".join(params), width=76)
+    return inspect.cleandoc(raw_help).format(params=wrapped)
+
+
+# Click captures `help` from the docstring at decoration time, so `{params}`
+# is filled in on the Command's `.help` afterward, not the original
+# function's `__doc__`.
+set_device_command.help = _format_params_help(set_device_command.help or "", DEVICE_PARAMS)

meshcorectl/commands/top.py

@@ -0,0 +1,77 @@
+"""`meshcorectl top` -- telemetry, the mesh analogue of `kubectl top node/pod`."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import click
+
+from ..connect import MeshCoreConnection
+from ..durations import parse_duration
+from ..mesh_data import (
+    AmbiguousMatchError,
+    fetch_contacts,
+    fetch_telemetry,
+    fetch_telemetry_history,
+    find_contact,
+)
+from ..output import output_option, render, resolve_output
+
+
+@click.group(name="top")
+def top_group() -> None:
+    """Show telemetry (instant readings, or --history min/max/avg)."""
+
+
+@top_group.command("contact")
+@click.argument("name")
+@click.option(
+    "--history",
+    is_flag=True,
+    help="Show min/max/avg history instead of instant readings.",
+)
+@click.option(
+    "--since",
+    "since_text",
+    default="1h",
+    show_default=True,
+    metavar="DURATION",
+    help="History window for --history, e.g. 30m, 2h, 1d.",
+)
+@output_option
+@click.pass_obj
+def top_contact(
+    state: Any, name: str, history: bool, since_text: str, output_override: str | None
+) -> None:
+    """Request telemetry from a contact (typically a sensor)."""
+    start = end = 0
+    if history:
+        try:
+            duration = parse_duration(since_text)
+        except ValueError as exc:
+            raise click.ClickException(str(exc)) from exc
+        end = int(time.time())
+        start = end - int(duration)
+
+    # Contact resolution and the telemetry fetch share one connection, like
+    # send/delete/exec/login.
+    async def run(connection: MeshCoreConnection) -> list[dict[str, Any]]:
+        contacts = await fetch_contacts(connection)
+        try:
+            contact = find_contact(contacts, name)
+        except AmbiguousMatchError as exc:
+            raise click.ClickException(str(exc)) from exc
+        if contact is None:
+            raise click.ClickException(f"no contact matching {name!r}")
+        if history:
+            return await fetch_telemetry_history(connection, contact, start=start, end=end)
+        return await fetch_telemetry(connection, contact)
+
+    readings = state.call(run)
+    kind = "telemetry-history" if history else "telemetry"
+
+    if not readings:
+        click.echo("No telemetry readings.", err=True)
+        return
+    click.echo(render(readings, resolve_output(state.output, output_override), kind=kind))

meshcorectl/commands/trace.py

@@ -0,0 +1,39 @@
+"""`meshcorectl trace` -- trace the route through specific repeaters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from ..connect import MeshCoreConnection
+from ..mesh_data import run_trace
+from ..output import output_option, render, resolve_output
+
+
+@click.command(name="trace")
+@click.argument("path", metavar="PATH")
+@click.option(
+    "--timeout",
+    "timeout_override",
+    type=float,
+    default=None,
+    metavar="SECONDS",
+    help="Override the device-suggested wait for the trace reply.",
+)
+@output_option
+@click.pass_obj
+def trace_command(
+    state: Any, path: str, timeout_override: float | None, output_override: str | None
+) -> None:
+    """Trace the route through PATH, a comma-separated list of repeater
+    public-key prefixes (e.g. "23,5f,3a")."""
+
+    async def run(connection: MeshCoreConnection) -> list[dict[str, Any]]:
+        return await run_trace(connection, path, timeout=timeout_override)
+
+    hops = state.call(run)
+    if not hops:
+        click.echo("No hops in the trace reply.", err=True)
+        return
+    click.echo(render(hops, resolve_output(state.output, output_override), kind="trace-hop"))

meshcorectl/commands/version.py

@@ -0,0 +1,58 @@
+"""`meshcorectl version` -- client (this CLI) + device firmware/protocol
+version, mirroring `kubectl version`'s Client/Server split.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import click
+import yaml
+
+from .. import __version__
+from ..mesh_data import fetch_device
+from ..output import OutputFormat, output_option, resolve_output
+
+
+@click.command(name="version")
+@click.option(
+    "--client",
+    "client_only",
+    is_flag=True,
+    help="Only print the client (this CLI's) version; don't connect to a device.",
+)
+@output_option
+@click.pass_obj
+def version_command(state: Any, client_only: bool, output_override: str | None) -> None:
+    """Print the client version and, unless --client, the device's version."""
+    info: dict[str, Any] = {"client_version": __version__}
+    if not client_only:
+        device = state.call(fetch_device)
+        info["device"] = {
+            "name": device.get("name"),
+            "model": device.get("model"),
+            "version": device.get("ver"),
+            "protocol": device.get("fw ver"),
+            "build": device.get("fw_build"),
+        }
+    click.echo(format_version(info, resolve_output(state.output, output_override)))
+
+
+def format_version(info: dict[str, Any], fmt: OutputFormat) -> str:
+    if fmt is OutputFormat.JSON:
+        return json.dumps(info, indent=2)
+    if fmt is OutputFormat.YAML:
+        return yaml.safe_dump(info, sort_keys=False).rstrip("\n")
+
+    lines = [f"Client Version: {info['client_version']}"]
+    device = info.get("device")
+    if device is not None:
+        lines.append(f"Device Name:    {device.get('name') or '-'}")
+        lines.append(f"Device Model:   {device.get('model') or '-'}")
+        lines.append(
+            f"Device Version: {device.get('version') or '-'} "
+            f"(protocol {device.get('protocol') if device.get('protocol') is not None else '-'})"
+        )
+        lines.append(f"Device Build:   {device.get('build') or '-'}")
+    return "\n".join(lines)

meshcorectl/connect.py

@@ -0,0 +1,74 @@
+"""Opens a live connection to a device described by a `ConnectionSpec`.
+
+Command modules depend only on the `MeshCoreConnection` protocol below, not
+on `meshcore.MeshCore` directly, so the connection method can change without
+touching command code.
+
+`meshcore.MeshCore.create_ble/create_serial/create_tcp` are imported inside
+`connect()`, not at module scope, so tests can monkeypatch them without
+importing bleak/pyserial.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, cast, runtime_checkable
+
+from .context_store import ConnectionSpec
+
+
+class ConnectError(Exception):
+    """Raised when a connection to a device cannot be established."""
+
+
+@runtime_checkable
+class MeshCoreConnection(Protocol):
+    """The subset of `meshcore.MeshCore` a command module is allowed to use."""
+
+    self_info: dict[str, Any]
+    commands: Any
+
+    def subscribe(self, event_type: Any, handler: Any) -> None: ...  # pragma: no cover
+
+    async def disconnect(self) -> None: ...  # pragma: no cover
+
+    async def wait_for_event(
+        self,
+        event_type: Any,
+        attribute_filters: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> Any: ...  # pragma: no cover
+
+
+async def connect(
+    spec: ConnectionSpec, *, timeout: float, debug: bool = False
+) -> MeshCoreConnection:
+    """Open a direct (v1) connection described by `spec`.
+
+    Raises `ConnectError` wrapping whatever the underlying transport raised
+    (BleakError, ConnectionError, TimeoutError, ...), so callers only need
+    to handle one exception type.
+    """
+    from meshcore import MeshCore
+
+    try:
+        if spec.kind == "ble":
+            client = await MeshCore.create_ble(
+                address=spec.address, debug=debug, default_timeout=timeout
+            )
+        elif spec.kind == "serial":
+            assert spec.port is not None  # guaranteed by ConnectionSpec.__post_init__
+            client = await MeshCore.create_serial(
+                port=spec.port, baudrate=spec.baudrate, debug=debug, default_timeout=timeout
+            )
+        else:  # tcp
+            assert spec.host is not None  # guaranteed by ConnectionSpec.__post_init__
+            client = await MeshCore.create_tcp(
+                host=spec.host, port=spec.tcp_port, debug=debug, default_timeout=timeout
+            )
+    except Exception as exc:
+        raise ConnectError(f"failed to connect ({spec.summary()}): {exc}") from exc
+
+    # MeshCore satisfies MeshCoreConnection structurally, but self_info is a
+    # property and subscribe()'s signature is wider than this protocol
+    # exposes -- both read as mismatches to a structural type checker.
+    return cast(MeshCoreConnection, client)