Add Bluetooth LE companion support alongside serial

Companions can now be reached over Bluetooth as well as USB. Rather than
a parallel BLE path, this generalizes the existing serial abstractions so
a device is identified by a transport (serial | ble) plus a target (COM
port or Bluetooth address); every feature rides the same Device interface
and works over either link unchanged.

- discovery: DiscoveredDevice gains transport/address/name and
  transport-aware stable_id/label/confidence/target; discover_ble_devices
  scans for MeshCore* adverts via bleak, discover_all merges both.
- connection: MeshCoreDevice opens create_ble vs create_serial by
  transport; new link_present() liveness (OS port enumeration for serial,
  the BLE client's is_connected flag for Bluetooth); is_connection_lost
  recognizes Bleak errors and BLE transport callbacks; probe_device is the
  transport-aware smoke test.
- disconnect: the session watcher polls transport-neutral link_alive(), so
  a dropped BLE link raises the same reconnect dialog and auto-resume as an
  unplugged cable; reconnect rebuilds the same endpoint by address.
- selection/context/store/profiles: --ble address, remembered BLE default,
  and BLE device profiles all resolve to the right transport.
- UI/CLI: startup picker scans both transports behind a spinner and tags
  Bluetooth companions; `devices` lists them (--no-ble to skip); global
  --ble/--ble-pin flags; README and example config updated.

Validated on hardware: discovery, connect, reconnect, and channel
messaging (send + receive) over BLE.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 4.8 committed 2026-07-09 18:44:39 -04:00
1 parent 6decc11c65
commit 7850587e2a
15 files changed
+982 -192

No files matched your search

+6 -2
View File
@@ -1,7 +1,8 @@
# MeshTerm
A modern, extensible command-line toolkit for tuning and exploring a
[MeshCore](https://meshcore.co.uk/) mesh through a serial-connected companion device.
[MeshCore](https://meshcore.co.uk/) mesh through a serial- or Bluetooth-connected companion
device.
MeshTerm is interactive by default (a Rich + Questionary menu) and fully scriptable
(every menu option is also a Typer subcommand). Every run is logged to SQLite and can be
@@ -15,7 +16,7 @@ turned into interactive HTML visualizations.
| **Device info** | ✅ skeleton | Show the connected companion device's identity and radio config. |
| **Node list** | ✅ working | List this node and its known contacts — full public keys with the path-hash prefix highlighted. |
| **Device config** | ✅ working | View and change every setting (name, radio, behavior, experimental), with TOML backup/restore, channels, and gated destructive ops. |
| **Device discovery** | ✅ working | Enumerate serial devices, pick one interactively, and remember the last good default. |
| **Device discovery** | ✅ working | Enumerate serial *and* Bluetooth LE companions, pick one interactively, and remember the last good default. A dropped link (unplug, power-off, or BLE out-of-range) is detected live and offers to reconnect. |
| **History / DB** | ✅ skeleton | Every tool execution and measurement is persisted and queryable. |
| **TX-power optimization** | ✅ working | Sweep transmit power (coarse + refine), converge on the best signal, optionally apply, render an interactive chart. |
| **Link budget** | ✅ working | Predict time-on-air, receiver sensitivity, range, and duty-cycle/dwell headroom for a radio config — offline, no radio needed. |
@@ -40,6 +41,9 @@ Python 3.10+ is required (matching the `meshcore` library).
# Interactive menu (default)
meshterm
# Connect over Bluetooth instead of USB (address from `meshterm devices`)
meshterm --ble AA:BB:CC:DD:EE:FF info
# Scripted: every menu option is also a subcommand
meshterm trace --target Alice --samples 10 --profile yagi
+13 -4
View File
@@ -1,10 +1,11 @@
# MeshTerm configuration.
# Copy to ~/.meshterm/config.toml (or pass --db / --port on the CLI).
#
# Profiles are optional. With no profile and no --port, MeshTerm discovers attached
# serial devices, lets you pick one (interactively) or uses the single one present, and
# remembers the last device that connected as the default for next time. Define profiles
# below only to give your hardware stable aliases (e.g. --profile yagi).
# Profiles are optional. With no profile, no --port, and no --ble, MeshTerm discovers
# attached serial devices and nearby Bluetooth companions, lets you pick one (interactively)
# or uses the single one present, and remembers the last device that connected as the default
# for next time. Define profiles below only to give your hardware stable aliases
# (e.g. --profile yagi, or --profile handheld for a Bluetooth device).
default_profile = "s3"
trace_cooldown_s = 1.0
@@ -29,3 +30,11 @@ description = "Local-range repeater"
[profiles.observer]
port = "COM8"
description = "XIAO observer running a bot"
# A Bluetooth LE companion: give it an `address` (from `meshterm devices`) instead of a port.
# The `transport = "ble"` line is optional — a bare `address` already implies Bluetooth.
[profiles.handheld]
address = "AA:BB:CC:DD:EE:FF"
# transport = "ble"
# ble_pin = "123456" # only if your device requires a pairing PIN
description = "Pocket handheld over Bluetooth"
+11 -1
View File
@@ -44,6 +44,12 @@ def main_callback(
ctx: typer.Context,
profile: Optional[str] = typer.Option(None, "--profile", "-p", help="Device profile."),
port: Optional[str] = typer.Option(None, "--port", help="Serial port override."),
ble: Optional[str] = typer.Option(
None, "--ble", help="Bluetooth address of a companion device (selects the BLE transport)."
),
ble_pin: Optional[str] = typer.Option(
None, "--ble-pin", help="BLE pairing PIN, if the Bluetooth companion requires one."
),
mock: bool = typer.Option(False, "--mock", help="Use the built-in simulator."),
db_path: Optional[Path] = typer.Option(None, "--db", help="SQLite database path."),
json_output: bool = typer.Option(False, "--json", help="Machine-readable output."),
@@ -55,6 +61,8 @@ def main_callback(
ctx: The Click/Typer context.
profile: Named device profile to use.
port: Explicit serial port, overriding the profile.
ble: Explicit Bluetooth address, selecting the BLE transport.
ble_pin: Optional BLE pairing PIN for the Bluetooth companion.
mock: Whether to use the simulator instead of real hardware.
db_path: Override the database location.
json_output: Request machine-readable output from tools.
@@ -80,8 +88,10 @@ def main_callback(
profile=settings.resolve_profile(profile),
mock=mock,
port_override=port,
ble_override=ble,
ble_pin=ble_pin,
json_output=json_output,
explicit_selection=profile is not None or port is not None,
explicit_selection=profile is not None or port is not None or ble is not None,
)
_state = app_ctx
ctx.call_on_close(app_ctx.repo.close)
+106 -12
View File
@@ -42,11 +42,14 @@ class AppContext:
mock: Whether the simulator device is in use.
port_override: Explicit serial port (from ``--port`` or the interactive picker),
overriding the profile.
ble_override: Explicit Bluetooth address (from ``--ble`` or the interactive picker),
selecting the BLE transport. Takes precedence over ``port_override``.
ble_pin: Optional BLE pairing PIN for the chosen Bluetooth device.
json_output: Whether tools should emit machine-readable output.
selected_device: The discovered device chosen for this session, when known, so it
can be remembered after a successful connection.
explicit_selection: Whether ``--port``/``--profile`` was passed explicitly (which
suppresses the interactive picker and auto-discovery).
explicit_selection: Whether ``--port``/``--ble``/``--profile`` was passed explicitly
(which suppresses the interactive picker and auto-discovery).
"""
console: Console
@@ -57,11 +60,15 @@ class AppContext:
profile: Optional[DeviceProfile] = None
mock: bool = False
port_override: Optional[str] = None
ble_override: Optional[str] = None
ble_pin: Optional[str] = None
json_output: bool = False
selected_device: Optional[DiscoveredDevice] = None
explicit_selection: bool = False
_device: Optional[Device] = field(default=None, init=False, repr=False)
_active_port: Optional[str] = field(default=None, init=False, repr=False)
_active_transport: Optional[str] = field(default=None, init=False, repr=False)
_active_address: Optional[str] = field(default=None, init=False, repr=False)
_resume_intent: Optional[tuple[bool, bool, bool]] = field(
default=None, init=False, repr=False
)
@@ -82,15 +89,47 @@ class AppContext:
@property
def active_port(self) -> Optional[str]:
"""The serial port the current connection is open on, if any (``None`` for --mock).
"""The serial port the current connection is open on, if any (``None`` for --mock/BLE).
Set when a real connection is opened so the liveness watcher knows which OS port to
poll for a mid-session unplug. Falls back to an explicit ``--port`` override when a
connection hasn't recorded one yet.
Set when a real *serial* connection is opened so the reconnect flow knows which OS
port to wait on. ``None`` for the simulator and for BLE connections (which have no
serial port). Falls back to an explicit ``--port`` override when a connection hasn't
recorded one yet.
"""
if self.mock or self.active_transport == "ble":
return None
return self._active_port or self.port_override
@property
def active_transport(self) -> Optional[str]:
"""The transport of the current/selected connection: ``"serial"``, ``"ble"``, or ``None``.
``None`` for the simulator. For a real device it reflects the open connection when
one exists, otherwise the transport implied by the pending selection (an explicit
``--ble`` selects BLE), defaulting to serial.
"""
if self.mock:
return None
return self._active_port or self.port_override
if self._active_transport is not None:
return self._active_transport
return "ble" if self.ble_override else "serial"
async def link_alive(self) -> bool:
"""Whether the current device's transport link is still up (best-effort, non-invasive).
Delegates to the connected device's :meth:`~meshterm.core.connection.Device.link_present`
— OS port enumeration for serial, the BLE client's connection flag for Bluetooth — so
the session's liveness watcher is transport-agnostic. Returns ``False`` when nothing is
connected (there is no live link), and ``True`` on any check hiccup so a transient
lookup failure never fakes a disconnect.
"""
device = self._device
if device is None:
return False
try:
return await device.link_present()
except Exception: # noqa: BLE001 - a liveness-check failure must not fake a disconnect
return True
@property
def ui(self) -> "Ui":
@@ -174,9 +213,12 @@ class AppContext:
device: A connected :class:`Device` to serve as this session's radio.
"""
self._device = device
# Record the port so the liveness watcher knows which OS port to poll (the picker
# opened it directly, bypassing the resolution in ``device()`` that normally sets it).
# Record the transport and endpoint the picker opened directly, bypassing the
# resolution in ``device()`` that normally sets them — so the liveness watcher knows
# what to poll and ``reconnect`` can rebuild the same connection.
self._active_transport = getattr(device, "transport", "serial")
self._active_port = getattr(device, "_port", None)
self._active_address = getattr(device, "_address", None)
async def device(self) -> Device:
"""Return a connected :class:`Device`, opening the connection on first use.
@@ -197,8 +239,25 @@ class AppContext:
if self.mock:
self._device = make_device(mock=True, port=None)
self._active_transport = None
self._active_port = None
self._active_address = None
await self._device.connect()
return self._device
# A Bluetooth endpoint (an explicit ``--ble``, a BLE profile, a device picked at
# startup, or the remembered BLE default) is opened directly by address — no serial
# resolution, and no re-scan needed to reconnect to a known address.
ble_address, ble_pin = self._resolve_ble_endpoint()
if ble_address:
self._device = make_device(
mock=False, port=None, transport="ble", address=ble_address, pin=ble_pin
)
self._active_transport = "ble"
self._active_address = ble_address
self._active_port = None
await self._device.connect()
await self._remember_connected()
return self._device
resolution = resolve_device(
@@ -211,15 +270,50 @@ class AppContext:
self.selected_device = resolution.device
baudrate = self.profile.baudrate if self.profile else 115200
self._device = make_device(mock=False, port=resolution.port, baudrate=baudrate)
self._active_transport = "serial"
self._active_port = resolution.port
self._active_address = None
await self._device.connect()
# Connection succeeded: this is now the last known good device. Learn its mesh node
# name (best-effort — a probe failure must not block a good connection).
await self._remember_connected()
return self._device
def _resolve_ble_endpoint(self) -> tuple[Optional[str], Optional[str]]:
"""Return the ``(address, pin)`` to open over Bluetooth, or ``(None, None)`` for serial.
Resolves a BLE endpoint in priority order — an explicit ``--ble``, a BLE
:class:`~meshterm.core.config.DeviceProfile`, then the remembered BLE default — so a
Bluetooth companion is honored wherever a serial one would be. Returns ``(None, None)``
when the session should fall through to serial resolution.
"""
if self.ble_override:
return self.ble_override, self.ble_pin
# An explicit serial selection (``--port`` or a serial profile with a port) wins over a
# remembered BLE default, mirroring the serial resolution priority.
explicit_serial = bool(self.port_override) or (
self.profile is not None and not self.profile.is_ble and bool(self.profile.port)
)
if self.profile is not None and self.profile.is_ble and self.profile.address:
return self.profile.address, self.ble_pin or self.profile.ble_pin
if explicit_serial:
return None, None
remembered = self.device_store.load()
if remembered is not None and remembered.is_ble and remembered.target:
self.selected_device = None # remembered, not freshly discovered this session
return remembered.target, self.ble_pin
return None, None
async def _remember_connected(self) -> None:
"""Record the just-connected device as the last known good default (best-effort).
Learns the device's mesh node name (a probe failure must not block a good
connection). Only devices discovered this session carry a
:class:`~meshterm.core.discovery.DiscoveredDevice` to remember; a bare ``--port`` or
remembered-by-address reconnect has nothing new to upsert.
"""
if self.selected_device is not None:
self.device_store.remember(
self.selected_device, node_name=await self._node_name()
)
return self._device
async def reconnect(self) -> None:
"""Drop a lost device connection and rebuild it, restoring live services.
+23 -1
View File
@@ -35,12 +35,19 @@ def default_config_dir() -> Path:
class DeviceProfile:
"""Connection defaults for one physical companion device.
A profile addresses either a serial companion (via ``port``) or a Bluetooth one (via
``transport = "ble"`` and ``address``). ``transport`` defaults to serial, so existing
port-only profiles are unchanged.
Attributes:
name: The profile alias (e.g. ``"yagi"``).
port: Serial port path (e.g. ``COM5`` or ``/dev/ttyUSB0``).
port: Serial port path (e.g. ``COM5`` or ``/dev/ttyUSB0``); serial profiles.
baudrate: Serial baud rate.
default_tx_power: TX power to assume/restore for this device, if known.
description: Free-text note about the hardware.
transport: ``"serial"`` (default) or ``"ble"``.
address: Bluetooth address (e.g. ``AA:BB:CC:DD:EE:FF``); BLE profiles.
ble_pin: Optional BLE pairing PIN, if the Bluetooth companion requires one.
"""
name: str
@@ -48,6 +55,14 @@ class DeviceProfile:
baudrate: int = 115200
default_tx_power: Optional[int] = None
description: str = ""
transport: str = "serial"
address: Optional[str] = None
ble_pin: Optional[str] = None
@property
def is_ble(self) -> bool:
"""Whether this profile addresses a Bluetooth LE companion."""
return self.transport == "ble"
@dataclass(slots=True)
@@ -121,12 +136,19 @@ class Settings:
profiles: dict[str, DeviceProfile] = {}
for pname, pdata in (data.get("profiles") or {}).items():
# A profile with an ``address`` (or ``transport = "ble"``) is a Bluetooth device;
# otherwise it's serial. Defaulting the transport this way keeps port-only
# profiles working untouched while a bare ``address`` is enough to declare a BLE one.
transport = pdata.get("transport") or ("ble" if pdata.get("address") else "serial")
profiles[pname] = DeviceProfile(
name=pname,
port=pdata.get("port"),
baudrate=pdata.get("baudrate", 115200),
default_tx_power=pdata.get("default_tx_power"),
description=pdata.get("description", ""),
transport=transport,
address=pdata.get("address"),
ble_pin=pdata.get("ble_pin"),
)
return cls(
+228 -43
View File
@@ -18,7 +18,7 @@ import logging
import random
from abc import ABC, abstractmethod
from datetime import datetime, timezone
from typing import Callable, Optional
from typing import TYPE_CHECKING, Callable, Optional
from .channels import CHANNEL_SLOT_PROBE_CAP
from .events import MeshEvent
@@ -33,6 +33,9 @@ from .models import (
TraceResult,
)
if TYPE_CHECKING:
from .discovery import DiscoveredDevice
#: Module logger; enable DEBUG on ``meshterm.core.connection`` to trace the message pump.
_log = logging.getLogger(__name__)
@@ -75,13 +78,14 @@ class DeviceCommandError(RuntimeError):
"""
#: Exception class names that signal the serial link to the companion has dropped — the
#: device was unplugged, powered off, or its port otherwise vanished — as opposed to an
#: ordinary command-level failure. Matched by name in :func:`is_connection_lost` so the
#: optional ``pyserial`` dependency need not be imported here (it isn't installed on the
#: ``--mock`` path). ``SerialException`` covers pyserial's read/write failures (including the
#: Windows ``ClearCommError``/``WriteFile`` variants); the ``OSError`` subclasses cover a
#: link torn down at the OS layer.
#: Exception class names that signal the link to the companion has dropped — the device was
#: unplugged, powered off, moved out of range, or its port/transport otherwise vanished — as
#: opposed to an ordinary command-level failure. Matched by name in :func:`is_connection_lost`
#: so the optional ``pyserial``/``bleak`` dependencies need not be imported here (neither is
#: installed on the ``--mock`` path). ``SerialException`` covers pyserial's read/write failures
#: (including the Windows ``ClearCommError``/``WriteFile`` variants); the ``Bleak*`` names cover
#: a Bluetooth link that dropped or a peripheral that went out of range; the ``OSError``
#: subclasses cover a link torn down at the OS layer.
_CONNECTION_LOST_TYPES = frozenset(
{
"SerialException",
@@ -89,6 +93,11 @@ _CONNECTION_LOST_TYPES = frozenset(
"ConnectionResetError",
"ConnectionAbortedError",
"BrokenPipeError",
"BleakError",
"BleakDeviceNotFoundError",
"BleakDBusError",
"BleakGATTError",
"BleakCharacteristicNotFoundError",
}
)
@@ -106,6 +115,12 @@ _CONNECTION_LOST_HINTS = (
"port is closed",
"no such device",
"input/output error",
# BLE link-loss phrasings (bleak errors / meshcore BLE transport callback reasons).
"ble_transport_lost",
"ble_write_failed",
"ble_disconnect",
"not connected to a ble device",
"device is no longer connected",
)
@@ -182,6 +197,22 @@ class Device(ABC):
async def disconnect(self) -> None:
"""Close the connection and release resources. Idempotent."""
async def link_present(self) -> bool:
"""Return whether the underlying transport link is still up (best-effort).
A cheap, *non-invasive* liveness probe — it never transmits and never opens a new
handle — so the interactive session can poll it while the device is in use to notice
a mid-session drop (a serial cable pulled, a companion powered off, a BLE peripheral
out of range). Each transport implements it against the signal that actually reflects
its link state (OS port enumeration for serial, the BLE client's connection flag for
Bluetooth). It returns ``True`` whenever presence can't be determined, so a lookup
hiccup never fakes a disconnect.
Returns:
``True`` if the link appears up (or can't be checked), ``False`` if it is gone.
"""
return True
@abstractmethod
async def get_self_info(self) -> dict:
"""Return identity and radio configuration of the connected device.
@@ -482,7 +513,12 @@ class Device(ABC):
class MeshCoreDevice(Device):
"""A :class:`Device` backed by the ``meshcore`` serial companion client.
"""A :class:`Device` backed by the ``meshcore`` companion client (serial or BLE).
The same wrapper serves both transports: which one it opens is chosen by ``transport``
(``"serial"`` opens ``port``; ``"ble"`` opens ``address``). Everything above the
connection — commands, event mapping, trace parsing — is transport-agnostic, so only
:meth:`connect` and :meth:`link_present` differ between the two.
Note:
The trace mapping here follows the documented companion protocol (trace replies
@@ -491,22 +527,35 @@ class MeshCoreDevice(Device):
"""
def __init__(
self, port: str, baudrate: int = 115200, connect_timeout: Optional[float] = None
self,
port: Optional[str] = None,
baudrate: int = 115200,
connect_timeout: Optional[float] = None,
*,
transport: str = "serial",
address: Optional[str] = None,
pin: Optional[str] = None,
) -> None:
"""Initialize the device wrapper.
Args:
port: Serial port path (e.g. ``COM5`` or ``/dev/ttyUSB0``).
port: Serial port path (e.g. ``COM5`` or ``/dev/ttyUSB0``); serial transport only.
baudrate: Serial baud rate.
connect_timeout: Handshake timeout (seconds) for the initial connection, passed
to the client as its default command timeout. ``None`` uses the ``meshcore``
library default (~15s). The startup smoke test sets a short value so a
non-responsive port is rejected quickly instead of blocking on the full
default handshake window.
transport: ``"serial"`` (default) or ``"ble"``.
address: Bluetooth address (e.g. ``AA:BB:CC:DD:EE:FF``); BLE transport only.
pin: Optional BLE pairing PIN, when the peripheral requires one (BLE only).
"""
self._port = port
self._baudrate = baudrate
self._connect_timeout = connect_timeout
self._transport = transport
self._address = address
self._pin = pin
self._mc = None # type: ignore[var-annotated] # meshcore.MeshCore
# Serializes channel reads. The meshcore library's get_channel waits for "the next
# CHANNEL_INFO event" with no correlation to the index it asked for, and the dispatcher
@@ -515,6 +564,16 @@ class MeshCoreDevice(Device):
# keeps at most one channel read outstanding, so the response is unambiguously ours.
self._channel_read_lock = asyncio.Lock()
@property
def transport(self) -> str:
"""Which transport this device connects over (``"serial"`` or ``"ble"``)."""
return self._transport
@property
def endpoint(self) -> Optional[str]:
"""The connection endpoint: the BLE address for BLE, else the serial port."""
return self._address if self._transport == "ble" else self._port
async def connect(self) -> None: # noqa: D102 - inherited docstring
if self._mc is not None:
return
@@ -527,20 +586,20 @@ class MeshCoreDevice(Device):
"--mock for the simulator."
) from exc
self._mc = await MeshCore.create_serial(
self._port, self._baudrate, default_timeout=self._connect_timeout
)
# ``create_serial`` returns ``None`` (after cleaning up its own connection) when the
# node never answers the identity handshake — i.e. the port isn't a MeshCore serial
# companion. Surface that as a clean, recoverable error rather than leaving a
# half-open device whose next command fails with a confusing "not connected".
if self._mc is None:
raise DeviceCommandError(
f"no response from a MeshCore companion on {self._port}; it may not be a "
"MeshCore device, or it may be powered off or in use by another program."
if self._transport == "ble":
self._mc = await self._create_ble(MeshCore)
else:
self._mc = await MeshCore.create_serial(
self._port, self._baudrate, default_timeout=self._connect_timeout
)
# ``create_*`` returns ``None`` (after cleaning up its own connection) when the node
# never answers the identity handshake — i.e. the endpoint isn't a MeshCore companion.
# Surface that as a clean, recoverable error rather than leaving a half-open device
# whose next command fails with a confusing "not connected".
if self._mc is None:
raise DeviceCommandError(self._no_response_message())
# A short ``connect_timeout`` is only meant to bound the initial identity handshake
# (so a dead port is rejected quickly). Now that we're connected, restore the
# (so a dead endpoint is rejected quickly). Now that we're connected, restore the
# library's normal per-command timeout so the rest of the session isn't rushed.
if self._connect_timeout is not None:
commands = getattr(self._mc, "commands", None)
@@ -548,6 +607,62 @@ class MeshCoreDevice(Device):
if commands is not None and default is not None:
commands.default_timeout = default
async def _create_ble(self, mesh_core): # type: ignore[no-untyped-def]
"""Open the BLE companion connection, translating a missing-bleak import cleanly.
``auto_reconnect`` is deliberately left off: MeshTerm drives reconnection itself (the
same reconnect dialog the serial path uses), so the meshcore client should surface a
dropped link promptly via ``is_connected`` rather than silently retrying underneath us.
Args:
mesh_core: The imported ``meshcore.MeshCore`` class.
Returns:
The connected ``MeshCore`` client, or ``None`` if the peripheral never answered.
"""
try:
return await mesh_core.create_ble(
address=self._address,
pin=self._pin,
default_timeout=self._connect_timeout,
auto_reconnect=False,
)
except ImportError as exc:
raise DeviceCommandError(
"Bluetooth support requires the 'bleak' package, which isn't installed. "
"Run `pip install -e .` (or `pip install bleak`), use a USB device, or "
"run with --mock."
) from exc
def _no_response_message(self) -> str:
"""A clean, recoverable error for an endpoint that didn't answer as a companion."""
if self._transport == "ble":
where = self._address or "the selected Bluetooth device"
return (
f"no response from a MeshCore companion over Bluetooth ({where}); it may be "
"out of range, powered off, already connected to another device, or not a "
"MeshCore device."
)
return (
f"no response from a MeshCore companion on {self._port}; it may not be a "
"MeshCore device, or it may be powered off or in use by another program."
)
async def link_present(self) -> bool: # noqa: D102 - inherited docstring
if self._mc is None:
return True # not connected yet / already torn down — nothing to declare lost
if self._transport == "ble":
# The meshcore client flips ``is_connected`` to False the moment bleak reports the
# peripheral dropped (via its disconnect callback), so this is the BLE analogue of
# the serial port-enumeration check — a cheap, non-transmitting liveness read.
try:
return bool(self._mc.is_connected)
except Exception: # noqa: BLE001 - a status hiccup must not fake a disconnect
return True
if not self._port:
return True # no port recorded (shouldn't happen once connected) — can't tell
return serial_port_present(self._port)
async def disconnect(self) -> None: # noqa: D102 - inherited docstring
if self._mc is None:
return
@@ -1747,23 +1862,37 @@ def make_device(
port: Optional[str],
baudrate: int = 115200,
mock_optimal_tx: int = 14,
transport: str = "serial",
address: Optional[str] = None,
pin: Optional[str] = None,
) -> Device:
"""Construct the appropriate :class:`Device` for the current invocation.
Args:
mock: When ``True`` return a :class:`MockDevice` simulator.
port: Serial port for a real device. Required unless ``mock`` is set.
baudrate: Serial baud rate for a real device.
port: Serial port for a real serial device. Required for the serial transport
unless ``mock`` is set.
baudrate: Serial baud rate for a real serial device.
mock_optimal_tx: Peak TX power for the simulator.
transport: ``"serial"`` (default) or ``"ble"``.
address: Bluetooth address for the BLE transport. Required when ``transport="ble"``.
pin: Optional BLE pairing PIN (BLE only).
Returns:
A connected-on-enter :class:`Device` instance.
Raises:
ValueError: If a real device is requested without a serial port.
ValueError: If a real device is requested without a usable endpoint for its transport.
"""
if mock:
return MockDevice(optimal_tx=mock_optimal_tx)
if transport == "ble":
if not address:
raise ValueError(
"No Bluetooth address configured. Pass --ble, pick a device at startup, "
"or use --mock."
)
return MeshCoreDevice(transport="ble", address=address, pin=pin)
if not port:
raise ValueError(
"No serial port configured. Pass --port, set a profile, or use --mock."
@@ -1771,20 +1900,61 @@ def make_device(
return MeshCoreDevice(port=port, baudrate=baudrate)
async def probe_meshcore(
port: str, baudrate: int = 115200, *, timeout: float = 6.0
) -> Optional[tuple["MeshCoreDevice", dict]]:
"""Open ``port``, confirm a MeshCore companion answers, and return the live connection.
#: Handshake window (seconds) for probing a serial companion. A genuine board answers in well
#: under a second; a non-MeshCore port is rejected within this bound.
_PROBE_TIMEOUT_SERIAL_S = 6.0
Opens a real serial connection and issues an identity query (the APPSTART that backs
:meth:`MeshCoreDevice.get_self_info`). A genuine companion replies with a self-info
payload; anything else — a non-MeshCore serial gadget, the wrong baud rate, an
unresponsive port — never answers and is rejected within ``timeout``.
#: Handshake window (seconds) for probing a BLE companion. Longer than serial: a BLE connect
#: involves a link-layer connection and GATT service discovery before the identity reply.
_PROBE_TIMEOUT_BLE_S = 20.0
async def probe_device(
device: "DiscoveredDevice", *, baudrate: int = 115200, pin: Optional[str] = None
) -> Optional[tuple["MeshCoreDevice", dict]]:
"""Open a discovered device, confirm a MeshCore companion answers, and keep it connected.
Transport-agnostic front door for the startup smoke test: it opens the right connection
for ``device`` (serial port or BLE address) and issues an identity query (the APPSTART
that backs :meth:`MeshCoreDevice.get_self_info`). A genuine companion replies with a
self-info payload; anything else — a non-MeshCore gadget, an unresponsive port, a BLE
device out of range — never answers and is rejected within the transport's timeout.
On success the connection is **left open** and returned to the caller, which reuses it as
the session device. This is deliberate: many companion boards reset on each serial open,
so a probe-then-reopen cycle is slow and flaky — opening the radio exactly once is both
faster and far more reliable. On any failure the probe connection is closed.
the session device. This is deliberate: many companion boards reset on each serial open
(and a BLE reconnect re-runs service discovery), so a probe-then-reopen cycle is slow and
flaky — opening the radio exactly once is both faster and far more reliable. On any
failure the probe connection is closed.
Args:
device: The discovered device to probe (serial or BLE).
baudrate: Serial baud rate (serial transport only).
pin: Optional BLE pairing PIN (BLE transport only).
Returns:
``(device, self_info)`` with a connected :class:`MeshCoreDevice` on success (the
caller owns and must eventually close it), or ``None`` if it is not a reachable
MeshCore companion.
"""
if device.is_ble:
timeout = _PROBE_TIMEOUT_BLE_S
probe = MeshCoreDevice(
transport="ble", address=device.address, pin=pin, connect_timeout=timeout
)
else:
timeout = _PROBE_TIMEOUT_SERIAL_S
probe = MeshCoreDevice(
port=device.port, baudrate=baudrate, connect_timeout=timeout
)
return await _probe(probe, timeout)
async def probe_meshcore(
port: str, baudrate: int = 115200, *, timeout: float = _PROBE_TIMEOUT_SERIAL_S
) -> Optional[tuple["MeshCoreDevice", dict]]:
"""Probe a serial ``port`` for a MeshCore companion (see :func:`probe_device`).
Thin serial-only convenience wrapper retained for callers that hold a bare port string.
Args:
port: Serial port to probe (e.g. ``COM5`` or ``/dev/ttyUSB0``).
@@ -1792,16 +1962,31 @@ async def probe_meshcore(
timeout: Seconds to bound the connection handshake and the identity reply.
Returns:
``(device, self_info)`` with a connected :class:`MeshCoreDevice` on success (the
caller owns and must eventually close it), or ``None`` if the port is not a reachable
``(device, self_info)`` on success, or ``None`` if the port is not a reachable
MeshCore companion.
"""
# ``timeout`` is the handshake window handed to the client, so a non-MeshCore port is
return await _probe(
MeshCoreDevice(port=port, baudrate=baudrate, connect_timeout=timeout), timeout
)
async def _probe(
device: "MeshCoreDevice", timeout: float
) -> Optional[tuple["MeshCoreDevice", dict]]:
"""Connect ``device`` and read its identity, returning it live or closing it on failure.
Args:
device: An unconnected :class:`MeshCoreDevice` configured for its transport.
timeout: Handshake window bounding both the connect and the identity read.
Returns:
``(device, self_info)`` with the connection left open, or ``None`` on any failure.
"""
# ``timeout`` is the handshake window handed to the client, so a non-MeshCore endpoint is
# rejected in ~``timeout`` seconds and the client cleans up its own connection. The outer
# ``wait_for`` is only a safety net a few seconds beyond that, so we never cancel the
# client mid-handshake (which would leak the open port). A real companion answers in well
# under a second, so this never delays a good device.
device = MeshCoreDevice(port=port, baudrate=baudrate, connect_timeout=timeout)
# client mid-handshake (which would leak the open connection). A real companion answers in
# well under a second (serial) or a few seconds (BLE), so this never delays a good device.
try:
await asyncio.wait_for(device.connect(), timeout + 4.0)
info = await asyncio.wait_for(device.get_self_info(), timeout)
+27 -5
View File
@@ -20,7 +20,7 @@ from dataclasses import dataclass
from pathlib import Path
from typing import Optional
from .discovery import DiscoveredDevice
from .discovery import TRANSPORT_BLE, TRANSPORT_SERIAL, DiscoveredDevice
from .models import utcnow
@@ -30,10 +30,14 @@ class RememberedDevice:
Attributes:
stable_id: The device's :attr:`DiscoveredDevice.stable_id` at connect time.
port: The serial port it was last seen on (informational; may have changed).
port: The serial port it was last seen on (informational; may have changed). Blank
for a BLE device.
label: A friendly label for display in prompts and tables.
node_name: The device's own mesh node name, learned at connect time (may be empty).
last_connected: ISO-8601 timestamp of the last successful connection.
node_name: The device's own mesh node name, learned at connect time (may be empty).
transport: ``"serial"`` or ``"ble"`` — how this device was last reached.
address: The Bluetooth address, for a BLE device (blank otherwise), so it can be
reconnected directly without re-scanning.
"""
stable_id: str
@@ -41,6 +45,18 @@ class RememberedDevice:
label: str
last_connected: str
node_name: str = ""
transport: str = TRANSPORT_SERIAL
address: str = ""
@property
def is_ble(self) -> bool:
"""Whether this remembered device was reached over Bluetooth LE."""
return self.transport == TRANSPORT_BLE
@property
def target(self) -> str:
"""The connection target: the BLE address for a BLE device, else the serial port."""
return self.address or self.port if self.is_ble else self.port
def matches(self, device: DiscoveredDevice) -> bool:
"""Return whether ``device`` is the same hardware as this record."""
@@ -98,10 +114,12 @@ class DeviceStore:
try:
return RememberedDevice(
stable_id=entry["stable_id"],
port=entry["port"],
label=entry.get("label", entry["port"]),
port=entry.get("port", ""),
label=entry.get("label", entry.get("port", "")),
last_connected=entry.get("last_connected", ""),
node_name=entry.get("node_name", ""),
transport=entry.get("transport", TRANSPORT_SERIAL),
address=entry.get("address", ""),
)
except (KeyError, TypeError):
return None
@@ -150,6 +168,8 @@ class DeviceStore:
label=device.label,
last_connected=utcnow().isoformat(),
node_name=node_name,
transport=device.transport,
address=device.address or "",
)
self._write(registry, device.stable_id)
@@ -164,6 +184,8 @@ class DeviceStore:
"label": record.label,
"last_connected": record.last_connected,
"node_name": record.node_name,
"transport": record.transport,
"address": record.address,
}
for stable_id, record in registry.items()
},
+150 -26
View File
@@ -1,20 +1,40 @@
"""Serial-port enumeration for companion-device discovery.
"""Companion-device discovery across transports (serial + Bluetooth LE).
Discovery is protocol-agnostic: it lists USB serial ports via ``pyserial`` and flags the
ones whose USB vendor ID matches hardware commonly used for LoRa companion devices
(ESP32/nRF boards and their USB-UART bridges). Nothing is hidden — unrecognized adapters
still appear, just sorted after the likely candidates.
Discovery enumerates two kinds of companion:
This module has no UI and no persistent state; it only reads what is currently plugged in.
The companion connection itself still goes through
:class:`~meshterm.core.connection.MeshCoreDevice`.
* **Serial**: USB serial ports via ``pyserial``, flagging the ones whose USB vendor ID
matches hardware commonly used for LoRa companion devices (ESP32/nRF boards and their
USB-UART bridges). Nothing is hidden — unrecognized adapters still appear, just sorted
after the likely candidates.
* **Bluetooth LE**: nearby devices advertising a ``MeshCore*`` name, scanned via ``bleak``.
Unlike a bare serial adapter, a BLE advert that names itself MeshCore is a strong signal,
so scanned devices are always treated as likely companions.
This module has no UI and no persistent state; it only reads what is currently attached or
in range. The companion connection itself still goes through
:class:`~meshterm.core.connection.MeshCoreDevice`, which the ``transport`` field selects.
"""
from __future__ import annotations
import logging
from dataclasses import dataclass
from typing import Optional
_log = logging.getLogger(__name__)
#: Transport discriminators for a :class:`DiscoveredDevice` (also stored/remembered as-is).
TRANSPORT_SERIAL = "serial"
TRANSPORT_BLE = "ble"
#: BLE advertisements from a MeshCore companion begin with this name prefix; the scan filters
#: to it so unrelated Bluetooth gadgets (headphones, watches, beacons) never clutter the list.
BLE_NAME_PREFIX = "MeshCore"
#: Default seconds to scan for BLE companions. Long enough to hear a nearby device's periodic
#: advertisement, short enough not to stall the startup splash noticeably.
BLE_SCAN_TIMEOUT_S = 5.0
# USB vendor IDs frequently seen on MeshCore/Meshtastic companion hardware and the
# USB-UART bridges they ship with. Used only to name, flag, and sort likely devices.
KNOWN_LORA_VIDS: dict[int, str] = {
@@ -41,20 +61,28 @@ _CONFIDENCE_RANK: dict[str, int] = {"board": 0, "bridge": 1, "unknown": 2}
@dataclass(slots=True)
class DiscoveredDevice:
"""A serial port found on the system, with USB metadata when available.
"""A companion device found on the system, with transport metadata.
A serial device carries its USB metadata; a Bluetooth LE device carries its BLE
``address`` and advertised ``name`` instead (its ``port`` is left blank). The
``transport`` field says which, and :attr:`target` returns the identifier used to
open a connection regardless of kind.
Attributes:
port: Serial port path (e.g. ``COM5`` or ``/dev/ttyUSB0``).
description: Human-readable description reported by the OS/driver.
hwid: Raw hardware id string from ``pyserial`` (VID/PID/serial blob).
port: Serial port path (e.g. ``COM5`` or ``/dev/ttyUSB0``); ``""`` for BLE.
description: Human-readable description reported by the OS/driver/advert.
hwid: Raw hardware id string from ``pyserial`` (VID/PID/serial blob); serial only.
vid: USB vendor ID, if the port is a USB device.
pid: USB product ID, if the port is a USB device.
serial_number: USB serial number, if exposed by the device.
manufacturer: USB manufacturer string, if available.
product: USB product string, if available.
transport: ``"serial"`` or ``"ble"`` — which connection layer opens this device.
address: Bluetooth address for a BLE device (e.g. ``AA:BB:CC:DD:EE:FF``).
name: Advertised BLE local name (e.g. ``"MeshCore-Basestation"``); BLE only.
"""
port: str
port: str = ""
description: str = ""
hwid: str = ""
vid: Optional[int] = None
@@ -62,17 +90,33 @@ class DiscoveredDevice:
serial_number: Optional[str] = None
manufacturer: Optional[str] = None
product: Optional[str] = None
transport: str = TRANSPORT_SERIAL
address: Optional[str] = None
name: Optional[str] = None
@property
def is_ble(self) -> bool:
"""Whether this device is reached over Bluetooth LE rather than a serial port."""
return self.transport == TRANSPORT_BLE
@property
def target(self) -> str:
"""The identifier a connection opens on: the BLE address, else the serial port."""
return self.address or self.port if self.is_ble else self.port
@property
def stable_id(self) -> str:
"""Return an identifier stable across replug/reboot.
Prefers the USB serial number (survives a changed COM number), then the
``vid:pid`` pair, and finally the port name as a last resort.
For BLE, the Bluetooth address (stable per adapter pairing). For serial, the USB
serial number (survives a changed COM number), then the ``vid:pid`` pair, and
finally the port name as a last resort.
Returns:
A non-empty identifier string used to recognize this device later.
"""
if self.is_ble:
return f"ble:{(self.address or self.name or '').lower()}"
if self.serial_number:
return f"sn:{self.serial_number}"
if self.vid is not None and self.pid is not None:
@@ -81,13 +125,15 @@ class DiscoveredDevice:
@property
def confidence(self) -> str:
"""How likely this port is a LoRa companion, by USB vendor ID.
"""How likely this device is a LoRa companion.
Returns:
``"board"`` for a LoRa dev board's native USB (a strong signal), ``"bridge"``
for a generic USB-UART chip (a weak hint — could be anything), or ``"unknown"``
for an unrecognized adapter.
``"board"`` for a BLE device that named itself MeshCore or a LoRa dev board's
native USB (both strong signals), ``"bridge"`` for a generic USB-UART chip (a
weak hint — could be anything), or ``"unknown"`` for an unrecognized adapter.
"""
if self.is_ble:
return "board" # a MeshCore-named BLE advert is a confident companion signal
if self.vid in NATIVE_LORA_VIDS:
return "board"
if self.vid in UART_BRIDGE_VIDS:
@@ -96,23 +142,32 @@ class DiscoveredDevice:
@property
def is_likely_lora(self) -> bool:
"""Whether the VID belongs to a LoRa board or a serial bridge one commonly uses."""
"""Whether this looks like a companion: a MeshCore BLE advert or a known-VID board."""
return self.confidence != "unknown"
@property
def vendor_label(self) -> str:
"""A friendly vendor name from the known-VID table, or the manufacturer string."""
"""A friendly vendor/transport name for display.
``"Bluetooth"`` for a BLE device, else a known-VID vendor name or the USB
manufacturer string.
"""
if self.is_ble:
return "Bluetooth"
if self.vid in KNOWN_LORA_VIDS:
return KNOWN_LORA_VIDS[self.vid]
return self.manufacturer or ""
@property
def label(self) -> str:
"""A concise human-friendly label, e.g. ``"Wio SX1262 (COM5)"``.
"""A concise human-friendly label, e.g. ``"Wio SX1262 (COM5)"`` or ``"…(BLE)"``.
The OS description often already ends with the port (Windows reports
``"USB Serial Device (COM11)"``), so the port is not appended a second time.
``"USB Serial Device (COM11)"``), so the identifier is not appended a second time.
"""
if self.is_ble:
name = self.name or self.product or self.description or "Bluetooth device"
return f"{name} (BLE)"
name = self.product or self.description or self.vendor_label or "Serial device"
suffix = f"({self.port})"
if name.endswith(suffix): # avoid "… (COM11) (COM11)"
@@ -121,8 +176,8 @@ class DiscoveredDevice:
def _sort_key(device: DiscoveredDevice) -> tuple[int, str]:
"""Sort LoRa boards first, then serial bridges, then unknown adapters; ties by port."""
return (_CONFIDENCE_RANK[device.confidence], device.port)
"""Sort likely companions first, then bridges, then unknown; ties by target id."""
return (_CONFIDENCE_RANK[device.confidence], device.target)
def discover_devices() -> list[DiscoveredDevice]:
@@ -133,7 +188,7 @@ def discover_devices() -> list[DiscoveredDevice]:
so callers can fall back to ``--port``/``--mock`` with a friendly message.
Returns:
Discovered devices, likely candidates first, then sorted by port name.
Discovered serial devices, likely candidates first, then sorted by port name.
"""
try:
from serial.tools import list_ports
@@ -155,3 +210,72 @@ def discover_devices() -> list[DiscoveredDevice]:
]
devices.sort(key=_sort_key)
return devices
async def discover_ble_devices(timeout: float = BLE_SCAN_TIMEOUT_S) -> list[DiscoveredDevice]:
"""Scan for nearby Bluetooth LE companions advertising a ``MeshCore*`` name.
Uses ``bleak`` to listen for advertisements for ``timeout`` seconds and keeps only the
ones whose advertised name marks them as a MeshCore companion. If ``bleak`` is
unavailable, or the platform has no usable Bluetooth adapter, this returns an empty list
rather than raising — BLE is an optional transport, and its absence must never block
serial discovery or the simulator.
Args:
timeout: Seconds to scan for advertising devices.
Returns:
Discovered BLE companions (deduplicated by address), sorted by name.
"""
try:
from bleak import BleakScanner
except ImportError: # bleak not installed → BLE simply unavailable
return []
try:
found = await BleakScanner.discover(timeout=timeout, return_adv=True)
except Exception as exc: # noqa: BLE001 - no adapter / OS Bluetooth off / driver hiccup
_log.debug("BLE scan unavailable: %s", exc)
return []
devices: list[DiscoveredDevice] = []
for dev, adv in found.values():
name = (getattr(adv, "local_name", None) or getattr(dev, "name", None) or "").strip()
if not name.startswith(BLE_NAME_PREFIX):
continue
devices.append(
DiscoveredDevice(
transport=TRANSPORT_BLE,
address=dev.address,
name=name,
description=name,
product=name,
)
)
devices.sort(key=lambda d: (d.name or "").casefold())
return devices
async def discover_all(
*, ble: bool = True, ble_timeout: float = BLE_SCAN_TIMEOUT_S
) -> list[DiscoveredDevice]:
"""Enumerate every attached or in-range companion across all transports.
Serial enumeration is instant; the BLE scan is what takes ``ble_timeout`` seconds. Serial
devices are listed first (they're already attached and connect fastest), then BLE
companions.
Args:
ble: Whether to include a Bluetooth LE scan (skip it to avoid the scan delay).
ble_timeout: Seconds to spend scanning for BLE companions.
Returns:
All discovered devices: serial (likely-LoRa first), then BLE companions.
"""
serial = discover_devices()
if not ble:
return serial
# A device paired over both USB and BLE is vanishingly unlikely to collide by stable_id
# (USB serial number vs BLE address), so no cross-transport dedup is needed here.
ble_devices = await discover_ble_devices(ble_timeout)
return serial + ble_devices
+50 -26
View File
@@ -13,7 +13,7 @@ from typing import Optional
from .config import DeviceProfile
from .device_store import RememberedDevice
from .discovery import DiscoveredDevice
from .discovery import TRANSPORT_BLE, TRANSPORT_SERIAL, DiscoveredDevice
class DeviceSelectionError(ValueError):
@@ -29,22 +29,33 @@ class Resolution:
"""The outcome of resolving which device to use.
Attributes:
port: The chosen serial port.
port: The chosen connection target — the serial port for a serial device, or the
Bluetooth address for a BLE device. (Named ``port`` for historical reasons; use
:attr:`target`.)
device: The matching discovered device, when enumeration knows it (so the caller
can remember it on a successful connection). ``None`` for an explicit
``--port``/profile port that is not currently enumerable.
source: Where the choice came from (``"port"``, ``"profile"``, ``"remembered"``,
or ``"only"``), for logging and messaging.
target that is not currently enumerable.
source: Where the choice came from (``"port"``, ``"ble"``, ``"profile"``,
``"remembered"``, or ``"only"``), for logging and messaging.
transport: ``"serial"`` or ``"ble"`` — which connection layer opens the device.
"""
port: str
device: Optional[DiscoveredDevice]
source: str
transport: str = TRANSPORT_SERIAL
@property
def target(self) -> str:
"""The connection target (serial port or BLE address); alias for :attr:`port`."""
return self.port
def _find_by_port(devices: list[DiscoveredDevice], port: str) -> Optional[DiscoveredDevice]:
"""Return the discovered device on ``port``, if enumeration found one."""
return next((d for d in devices if d.port == port), None)
def _find_by_target(
devices: list[DiscoveredDevice], target: str
) -> Optional[DiscoveredDevice]:
"""Return the discovered device whose port or BLE address equals ``target``."""
return next((d for d in devices if d.target == target or d.port == target), None)
def _format_device_list(devices: list[DiscoveredDevice]) -> str:
@@ -54,7 +65,10 @@ def _format_device_list(devices: list[DiscoveredDevice]) -> str:
lines = []
for d in devices:
flag = " [likely LoRa]" if d.is_likely_lora else ""
lines.append(f" • {d.port} — {d.product or d.description or 'serial device'}{flag}")
kind = "BLE" if d.is_ble else "serial"
lines.append(
f" • {d.target} ({kind}) — {d.product or d.description or 'device'}{flag}"
)
return "\n".join(lines)
@@ -63,54 +77,64 @@ def resolve_device(
remembered: Optional[RememberedDevice],
*,
explicit_port: Optional[str] = None,
explicit_ble: Optional[str] = None,
profile: Optional[DeviceProfile] = None,
) -> Resolution:
"""Decide which serial port to use without prompting.
"""Decide which companion to connect to without prompting.
Resolution priority:
1. ``explicit_port`` (an explicit ``--port``).
2. ``profile.port`` (an explicitly chosen profile with a port).
3. The remembered "last known good" device, if it is currently attached.
4. The single attached device, if exactly one is present.
1. ``explicit_ble`` (an explicit ``--ble`` Bluetooth address).
2. ``explicit_port`` (an explicit ``--port``).
3. ``profile.port`` (an explicitly chosen profile with a port).
4. The remembered "last known good" device, if it is currently attached/in range.
5. The single attached device, if exactly one is present.
Otherwise a :class:`DeviceSelectionError` is raised listing the candidates.
Args:
devices: Currently discovered devices (see ``discover_devices``).
devices: Currently discovered devices (serial and/or BLE).
remembered: The remembered default, if any.
explicit_port: A serial port supplied on the command line.
explicit_ble: A Bluetooth address supplied on the command line.
profile: A device profile supplied on the command line.
Returns:
A :class:`Resolution` naming the chosen port.
A :class:`Resolution` naming the chosen target and transport.
Raises:
DeviceSelectionError: If no port can be chosen unambiguously.
DeviceSelectionError: If no device can be chosen unambiguously.
"""
if explicit_ble:
return Resolution(
explicit_ble, _find_by_target(devices, explicit_ble), "ble", TRANSPORT_BLE
)
if explicit_port:
return Resolution(explicit_port, _find_by_port(devices, explicit_port), "port")
match = _find_by_target(devices, explicit_port)
return Resolution(explicit_port, match, "port", TRANSPORT_SERIAL)
if profile is not None and profile.port:
return Resolution(profile.port, _find_by_port(devices, profile.port), "profile")
match = _find_by_target(devices, profile.port)
return Resolution(profile.port, match, "profile", TRANSPORT_SERIAL)
if remembered is not None:
match = next((d for d in devices if remembered.matches(d)), None)
if match is not None:
return Resolution(match.port, match, "remembered")
return Resolution(match.target, match, "remembered", match.transport)
if len(devices) == 1:
return Resolution(devices[0].port, devices[0], "only")
return Resolution(devices[0].target, devices[0], "only", devices[0].transport)
if not devices:
raise DeviceSelectionError(
"No serial devices detected. Connect a companion device, or pass --port "
"explicitly, or use --mock for the simulator."
"No companion devices detected. Connect a companion device (USB or Bluetooth), "
"or pass --port / --ble explicitly, or use --mock for the simulator."
)
raise DeviceSelectionError(
"Multiple serial devices detected and no default to fall back on.\n"
"Multiple companion devices detected and no default to fall back on.\n"
f"{_format_device_list(devices)}\n"
"Choose one with --port <PORT> (or run 'meshterm devices' to inspect them). "
"The chosen device is remembered as the default after it connects."
"Choose one with --port <PORT> or --ble <ADDRESS> (or run 'meshterm devices' to "
"inspect them). The chosen device is remembered as the default after it connects."
)
+35 -24
View File
@@ -1,12 +1,12 @@
"""The ``devices`` tool: enumerate attached serial companion devices.
"""The ``devices`` tool: enumerate attached serial and in-range Bluetooth companions.
Discovery never opens the radio — it only lists what is attached. This is a CLI-only,
read-only inventory (``menu_visible = False``): by the time the interactive menu is up a
device is already selected, so the listing has no job there — it belongs on the command line
as a startup-time "which port is my radio?" diagnostic. It marks devices already confirmed as
MeshCore companions (and the active one). Selecting a companion is a startup-only concern:
pass ``--port`` on the CLI (remembered after it connects), or pick from the prompt shown when
the menu launches (which smoke-tests the choice before confirming it).
Discovery never opens the radio — it only lists what is attached or advertising. This is a
CLI-only, read-only inventory (``menu_visible = False``): by the time the interactive menu is
up a device is already selected, so the listing has no job there — it belongs on the command
line as a startup-time "which port/address is my radio?" diagnostic. It marks devices already
confirmed as MeshCore companions (and the active one). Selecting a companion is a startup-only
concern: pass ``--port`` or ``--ble`` on the CLI (remembered after it connects), or pick from
the prompt shown when the menu launches (which smoke-tests the choice before confirming it).
"""
from __future__ import annotations
@@ -17,7 +17,7 @@ import typer
from rich.table import Table
from ..context import AppContext
from ..core.discovery import discover_devices
from ..core.discovery import discover_all, discover_devices
from .base import Tool, ToolResult, register
#: "MeshCore?" table cell per discovery confidence tier, for devices we have *not* yet
@@ -36,10 +36,10 @@ _CONFIRMED_CELL = "[ok]yes[/ok]"
@register
class DevicesTool(Tool):
"""List attached serial devices, flag likely LoRa hardware, mark the default."""
"""List attached serial + in-range Bluetooth companions, flag likely LoRa, mark the default."""
name = "devices"
help = "List attached serial devices and flag likely LoRa hardware."
help = "List attached serial and Bluetooth companion devices and flag likely LoRa hardware."
category = "Device"
order = 5
menu_visible = False # CLI-only: a startup diagnostic with no place in a connected session
@@ -54,18 +54,24 @@ class DevicesTool(Tool):
Returns:
A :class:`ToolResult` summarizing how many devices were found.
"""
devices = discover_devices()
scan_ble = params.get("ble", True)
devices = await discover_all(ble=scan_ble) if scan_ble else discover_devices()
known = ctx.device_store.load_all()
remembered = ctx.device_store.load()
active = ctx.selected_device
active_port = ctx.port_override or (active.port if active else None)
active_target = ctx.ble_override or ctx.port_override or (
active.target if active else None
)
if ctx.json_output:
import json
payload = [
{
"transport": d.transport,
"port": d.port,
"address": d.address,
"target": d.target,
"label": d.label,
"vendor": d.vendor_label,
"likely_lora": d.is_likely_lora,
@@ -74,7 +80,7 @@ class DevicesTool(Tool):
"serial_number": d.serial_number,
"stable_id": d.stable_id,
"remembered": remembered is not None and remembered.matches(d),
"active": d.port == active_port,
"active": d.target == active_target,
}
for d in devices
]
@@ -83,28 +89,29 @@ class DevicesTool(Tool):
if not devices:
ctx.ui.note(
"[warn]No serial devices detected.[/warn] "
"Connect a companion device, or use [accent]--mock[/accent] for the simulator."
"[warn]No companion devices detected.[/warn] "
"Connect one over USB or power on a Bluetooth companion nearby, or use "
"[accent]--mock[/accent] for the simulator."
)
return ToolResult(summary={"count": 0})
table = Table(title="Serial devices", border_style="muted", expand=False)
table = Table(title="Companion devices", border_style="muted", expand=False)
table.add_column("", style="ok", no_wrap=True) # active/confirmed markers
table.add_column("Port", style="brand")
table.add_column("Port / Address", style="brand")
table.add_column("Device")
table.add_column("Vendor", style="muted")
table.add_column("MeshCore?", justify="center")
table.add_column("Serial", style="muted")
for d in devices:
confirmed = known.get(d.stable_id) # the remembered record, if ever confirmed
is_active = d.port == active_port
is_active = d.target == active_target
marker = ("●" if is_active else "") + ("★" if confirmed else "")
device_name = d.product or d.description or "[muted]?[/muted]"
device_name = d.name or d.product or d.description or "[muted]?[/muted]"
if confirmed and confirmed.node_name: # the mesh name learned on connect
device_name = f"{confirmed.node_name} [muted]({device_name})[/muted]"
table.add_row(
marker,
d.port,
d.target,
device_name,
d.vendor_label or "[muted]?[/muted]",
_CONFIRMED_CELL if confirmed else _MAYBE_CELL[d.confidence],
@@ -113,7 +120,7 @@ class DevicesTool(Tool):
ctx.ui.show(table)
ctx.ui.note(
"[muted]● active ★ confirmed MeshCore device. "
"Pass --port <PORT> to select on the CLI.[/muted]"
"Pass --port <PORT> or --ble <ADDRESS> to select on the CLI.[/muted]"
)
return ToolResult(summary={"count": len(devices)})
@@ -126,5 +133,9 @@ class DevicesTool(Tool):
from ..cli import run_tool_command
@app.command(name=self.name, help=self.help)
def _devices() -> None:
run_tool_command(self, {})
def _devices(
ble: bool = typer.Option(
True, "--ble/--no-ble", help="Include a Bluetooth LE scan (adds a few seconds)."
),
) -> None:
run_tool_command(self, {"ble": ble})
+38 -12
View File
@@ -49,6 +49,8 @@ def _pad(text: str, width: int) -> str:
def _hardware_name(device: DiscoveredDevice) -> str:
"""The device's product name without its trailing ``(port)`` (that is its own column)."""
if device.is_ble:
return device.name or device.product or device.description or "Bluetooth device"
name = device.product or device.description or device.vendor_label or "Serial device"
suffix = f"({device.port})"
if name.endswith(suffix):
@@ -56,6 +58,11 @@ def _hardware_name(device: DiscoveredDevice) -> str:
return name
def _where(device: DiscoveredDevice) -> str:
"""The connection target shown in the middle column: serial port or BLE address."""
return device.target
def _node_name_from(info: dict) -> str:
"""Return a device's own mesh node name from its self-info payload, or ``""``."""
return str(info.get("adv_name") or info.get("name") or "")
@@ -89,8 +96,10 @@ async def prompt_device(
if not devices:
await ui.notify_startup(
Text.from_markup(
"[warn]No serial devices detected.[/warn]\n"
"Plug one in, pass [accent]--port[/accent], or run with [accent]--mock[/accent]."
"[warn]No companion devices detected.[/warn]\n"
"Plug one in over USB or power on a Bluetooth companion nearby, pass "
"[accent]--port[/accent]/[accent]--ble[/accent], or run with "
"[accent]--mock[/accent]."
),
title="Select a companion device",
banner=load_logo(),
@@ -126,10 +135,13 @@ async def prompt_device(
name = remembered.node_name if (
remembered and remembered.matches(chosen) and remembered.node_name
) else _hardware_name(chosen)
# "over Bluetooth" reads better than an address; a serial device names its port.
where = "over Bluetooth" if chosen.is_ble else f"on {chosen.port}"
# Smoke-test the choice in place: the splash keeps its wordmark and box, only the box
# contents swap for an animated spinner while we talk to the device.
# contents swap for an animated spinner while we talk to the device. BLE connect and
# service discovery take a few seconds, so the spinner matters most here.
info = await ui.busy_startup(
f"Talking to {name} on {chosen.port}…",
f"Talking to {name} {where}…",
verify(chosen),
title="Checking companion",
banner=load_logo(),
@@ -137,10 +149,15 @@ async def prompt_device(
)
if info is None:
reason = (
"It may be out of range, powered off, already connected elsewhere, or busy."
if chosen.is_ble
else "It may be a different kind of serial device, powered off, or busy."
)
await ui.notify_startup(
Text.from_markup(
f"[warn]{name} on {chosen.port} didn't answer as a MeshCore device.[/warn]\n"
"It may be a different kind of serial device, powered off, or busy.\n"
f"[warn]{name} {where} didn't answer as a MeshCore device.[/warn]\n"
f"{reason}\n"
"Choose another device."
),
title="Not a MeshCore device",
@@ -174,8 +191,13 @@ def _build_items(
name_w = max(cell_len(_name(d)) for d in devices)
name_w = max(name_w, len("DEVICE"))
port_w = max(cell_len(d.port) for d in devices)
port_w = max(port_w, len("PORT"))
# The middle column holds a serial port or a BLE address; label it for whichever kinds
# are present so a Bluetooth address never sits under a bare "PORT" heading.
port_label = "PORT"
if any(d.is_ble for d in devices):
port_label = "ADDRESS" if all(d.is_ble for d in devices) else "PORT / ADDRESS"
port_w = max(cell_len(_where(d)) for d in devices)
port_w = max(port_w, len(port_label))
vendor_w = max(cell_len(d.vendor_label) for d in devices)
vendor_w = max(vendor_w, len("VENDOR"))
@@ -184,7 +206,7 @@ def _build_items(
header = Separator(
" "
+ _pad("DEVICE", name_w)
+ " " + _pad("PORT", port_w)
+ " " + _pad(port_label, port_w)
+ " " + "VENDOR"
)
@@ -196,14 +218,18 @@ def _build_items(
row.append(" ")
row.append(_pad(_name(device), name_w))
row.append(" ")
row.append(_pad(device.port, port_w), style="muted")
row.append(_pad(_where(device), port_w), style="muted")
row.append(" ")
row.append(_pad(device.vendor_label, vendor_w), style="muted")
# Only devices we've actually confirmed are billed as MeshCore companions; the USB
# vendor ID is a sort hint, not a claim. A bare serial bridge earns an honest label.
# Only devices we've actually confirmed are billed as MeshCore companions; a USB
# vendor ID (or a BLE advert) is a sort hint, not a claim. A bare serial bridge earns
# an honest label; a MeshCore-named BLE advert is flagged as a likely companion.
if device.stable_id in known:
row.append(" ")
row.append("· MeshCore device", style="ok")
elif device.is_ble:
row.append(" ")
row.append("· Bluetooth companion", style="muted")
elif device.confidence == "bridge":
row.append(" ")
row.append("· serial adapter", style="muted")
+53 -33
View File
@@ -262,22 +262,34 @@ async def _startup(ctx: AppContext) -> bool:
splash (pressed Esc or picked Quit) — in which case the caller skips the menu loop.
"""
if not (ctx.mock or ctx.explicit_selection):
from ..core.connection import probe_meshcore
from ..core.discovery import DiscoveredDevice, discover_devices
from ..core.connection import probe_device
from ..core.discovery import DiscoveredDevice, discover_all
from .device_picker import prompt_device
from .logo import load_logo
devices = discover_devices()
baudrate = ctx.profile.baudrate if ctx.profile else 115200
# Enumerate serial ports (instant) and scan for BLE companions (a few seconds), behind
# the splash spinner so the wait reads as intentional rather than a hang.
from datetime import datetime
footnote = f"© {datetime.now().year} Johnputer"
devices = await ctx.ui.busy_startup(
"Scanning for companion devices…",
discover_all(ble=True),
title="Select a companion device",
banner=load_logo(),
footnote=footnote,
)
# The smoke test opens the radio; on success we keep that live connection and reuse
# it for the session rather than reopening (boards often reset on each serial open).
# it for the session rather than reopening (boards often reset on each open).
probed: dict = {}
async def verify(device: DiscoveredDevice):
result = await probe_meshcore(device.port, baudrate)
result = await probe_device(device, baudrate=baudrate, pin=ctx.ble_pin)
if result is None:
return None
connection, info = result
probed["port"] = device.port
probed["device_id"] = device.stable_id
probed["device"] = connection
return info
@@ -285,8 +297,13 @@ async def _startup(ctx: AppContext) -> bool:
if chosen is None:
return False # the user quit at the splash — exit without opening the menu
ctx.selected_device = chosen
ctx.port_override = chosen.port
if probed.get("port") == chosen.port:
if chosen.is_ble:
ctx.ble_override = chosen.address
ctx.port_override = None
else:
ctx.port_override = chosen.port
ctx.ble_override = None
if probed.get("device_id") == chosen.stable_id:
ctx.adopt_device(probed["device"])
await _resume_monitor(ctx)
return True
@@ -420,31 +437,30 @@ async def _cancel_and_wait(task: "asyncio.Future") -> None:
async def _wait_for_disconnect(ctx: AppContext) -> None:
"""Resolve once the connected companion's serial port disappears from the OS.
"""Resolve once the connected companion's transport link drops.
Polls the OS serial-port enumeration rather than watching for a failed command: the
``meshcore`` client keeps serving cached data after an unplug and never raises (confirmed
on hardware), so an *active* liveness check is the only thing that reliably notices a
pulled cable. Never resolves for the simulator (it can't be unplugged) or before a real
device has actually been opened.
Polls a cheap, non-invasive liveness check (:meth:`AppContext.link_alive`) rather than
watching for a failed command: the ``meshcore`` client keeps serving cached data after a
serial unplug and never raises (confirmed on hardware), so an *active* liveness check is
the only thing that reliably notices a pulled cable. The same check covers Bluetooth,
where it reads the BLE client's connection flag (which flips the moment the peripheral
drops or goes out of range). Never resolves for the simulator (it can't be unplugged) or
before a real device has actually been opened.
Args:
ctx: The shared application context (read for the active port and connection state).
ctx: The shared application context (read for the connection state and liveness).
"""
from ..core.connection import serial_port_present
if ctx.mock:
await asyncio.Event().wait() # the simulator is never "unplugged"; wait forever
return
while True:
await asyncio.sleep(_LIVENESS_POLL_S)
port = ctx.active_port
if port is None or not ctx.is_connected:
if not ctx.is_connected:
continue # nothing connected to watch yet (deferred connect / no device)
if serial_port_present(port):
if await ctx.link_alive():
continue
await asyncio.sleep(_LIVENESS_CONFIRM_S) # debounce a transient enumeration gap
if not serial_port_present(port):
await asyncio.sleep(_LIVENESS_CONFIRM_S) # debounce a transient enumeration/link gap
if not await ctx.link_alive():
return
@@ -498,11 +514,14 @@ async def _animate_dialog(session: TuiSession, dialog: ReconnectDialog) -> None:
async def _auto_reconnect(ctx: AppContext, dialog: ReconnectDialog) -> None:
"""Poll for the device to return, reconnect when it does, then dismiss ``dialog``.
Waits for the OS to re-enumerate the port the connection was opened on before each
attempt, so a reconnect is only tried once there's a device to reach; a failed attempt
(the port is back but the board isn't ready yet, or it dropped again) simply loops and
retries. On the first success the dialog's future is resolved with ``"reconnected"``,
which dismisses the popup. Runs until it succeeds or the task is cancelled (the user quit).
For serial, waits for the OS to re-enumerate the port the connection was opened on before
each attempt, so a reconnect is only tried once there's a device to reach. For Bluetooth
there is no cheap "is it back yet" probe short of a full scan, so it simply attempts a
reconnect each interval — ``create_ble`` connects directly by address and fails fast when
the peripheral isn't in range. Either way a failed attempt (the endpoint is back but the
board isn't ready yet, or it dropped again) just loops and retries. On the first success
the dialog's future is resolved with ``"reconnected"``, dismissing the popup. Runs until
it succeeds or the task is cancelled (the user quit).
Args:
ctx: The shared application context.
@@ -511,12 +530,13 @@ async def _auto_reconnect(ctx: AppContext, dialog: ReconnectDialog) -> None:
from ..core.connection import serial_port_present
while True:
port = ctx.active_port
# Wait for the port to re-appear before touching the radio (skip the wait when there's
# no port to poll — e.g. an unknown/deferred port — and just retry on the interval).
if port is not None and not serial_port_present(port):
await asyncio.sleep(_LIVENESS_POLL_S)
continue
# Serial: wait for the port to re-appear before touching the radio. BLE (and an
# unknown/deferred serial port): skip the wait and just retry the reconnect itself.
if ctx.active_transport == "serial":
port = ctx.active_port
if port is not None and not serial_port_present(port):
await asyncio.sleep(_LIVENESS_POLL_S)
continue
try:
await ctx.reconnect()
except Exception: # noqa: BLE001 - not reachable yet; keep the popup up and retry
+1
View File
@@ -15,6 +15,7 @@ keywords = ["meshcore", "lora", "mesh", "radio", "cli"]
dependencies = [
"meshcore>=2.3", # companion-device protocol (serial/BLE/TCP)
"pyserial>=3.5", # serial-port enumeration for device discovery
"bleak>=0.22", # Bluetooth LE scanning + companion connection
"typer>=0.12", # scripted CLI; subcommands mirror the menu
"rich>=13.7", # modern console rendering (progress, tables, panels)
"prompt_toolkit>=3.0", # full-screen interactive TUI (terminal, input, resize)
+126 -1
View File
@@ -30,6 +30,23 @@ class _SerialException(Exception):
"""A stand-in for ``serial.SerialException`` (matched by type name, not import)."""
class _FakeSerialDevice:
"""A minimal stand-in for a connected serial :class:`Device` in liveness tests.
Its :meth:`link_present` mirrors the real serial device: it reports whether the port is
still enumerated by the OS, reading through the (monkeypatched) module function so tests
can flip presence on and off.
"""
transport = "serial"
def __init__(self, port: str = "COM_TEST") -> None:
self._port = port
async def link_present(self) -> bool:
return connection.serial_port_present(self._port)
def test_is_connection_lost_matches_serial_exception() -> None:
"""A pyserial-style read/write failure is classified as a dropped link."""
assert is_connection_lost(_SerialException("ClearCommError failed (Access is denied.)"))
@@ -58,6 +75,24 @@ def test_is_connection_lost_ignores_ordinary_failures() -> None:
assert not is_connection_lost(ValueError("bad value"))
# These stand-ins are named to match bleak's real classes, since the classifier matches by
# type name (not import) — see ``_CONNECTION_LOST_TYPES``.
class BleakError(Exception): # noqa: N818 - mirrors bleak's own (non-Error-suffixed) name
"""A stand-in for ``bleak.exc.BleakError`` (matched by type name, not import)."""
class BleakDeviceNotFoundError(Exception):
"""A stand-in for ``bleak.exc.BleakDeviceNotFoundError``."""
def test_is_connection_lost_matches_ble_errors() -> None:
"""A dropped Bluetooth link is classified as a lost connection, like a serial unplug."""
assert is_connection_lost(BleakError("gatt operation failed")) # matched by type name
assert is_connection_lost(BleakDeviceNotFoundError("AA:BB:CC not found"))
# The meshcore BLE transport reports link loss via a callback reason string.
assert is_connection_lost(RuntimeError("ble_transport_lost"))
def _make_ctx(tmp_path: Path) -> AppContext:
"""Build a real, mock-backed application context for reconnect tests."""
settings = Settings(config_dir=tmp_path, db_path=tmp_path / "disc.db")
@@ -94,6 +129,56 @@ async def test_reconnect_rebuilds_device_and_restores_services(tmp_path: Path) -
await ctx.aclose()
async def test_ble_profile_opens_bluetooth_transport(tmp_path: Path, monkeypatch) -> None:
"""A BLE profile makes ``device()`` build a Bluetooth connection by address."""
from meshterm.core import connection as conn
from meshterm.core.config import DeviceProfile
settings = Settings(config_dir=tmp_path, db_path=tmp_path / "ble.db")
ctx = AppContext(
console=Console(file=io.StringIO()),
settings=settings,
repo=Repository(settings.db_path),
device_store=DeviceStore(tmp_path / "devices.json"),
admin_store=AdminStore(tmp_path / "admin.json"),
profile=DeviceProfile(name="handheld", transport="ble", address="AA:BB:CC:DD:EE:FF"),
)
built: dict = {}
class _FakeBle:
transport = "ble"
def __init__(self, **kw):
built.update(kw)
self._port = None
self._address = kw.get("address")
async def connect(self):
pass
async def get_self_info(self):
return {"name": "Handheld"}
def fake_make_device(**kw):
assert kw["transport"] == "ble"
return _FakeBle(**kw)
monkeypatch.setattr(conn, "make_device", fake_make_device)
# context imported make_device by name, so patch the reference it actually calls.
import meshterm.context as context_mod
monkeypatch.setattr(context_mod, "make_device", fake_make_device)
try:
device = await ctx.device()
assert device.transport == "ble"
assert built["address"] == "AA:BB:CC:DD:EE:FF"
assert ctx.active_transport == "ble"
assert ctx.active_port is None # BLE has no serial port to watch
finally:
ctx.repo.close()
async def test_reconnect_leaves_idle_services_idle(tmp_path: Path) -> None:
"""Reconnect only restores what was live: idle services stay idle afterward."""
ctx = _make_ctx(tmp_path)
@@ -187,7 +272,8 @@ async def test_wait_for_disconnect_fires_when_port_vanishes(
ctx = _make_ctx(tmp_path)
# Pose as a live real-hardware session on COM_TEST (the mock can't be unplugged).
ctx.mock = False
ctx._device = object() # stand-in for a connected device; is_connected -> True
ctx._device = _FakeSerialDevice("COM_TEST") # connected device; is_connected -> True
ctx._active_transport = "serial"
ctx._active_port = "COM_TEST"
checks = {"n": 0}
@@ -215,6 +301,45 @@ async def test_wait_for_disconnect_ignores_the_simulator(tmp_path: Path) -> None
ctx.repo.close()
class _FakeBleDevice:
"""A minimal stand-in for a connected BLE :class:`Device` in liveness tests.
Its :meth:`link_present` reads an ``is_connected`` flag, mirroring how the real BLE
device reads the meshcore client's connection state.
"""
transport = "ble"
def __init__(self) -> None:
self.is_connected = True
async def link_present(self) -> bool:
return self.is_connected
async def test_wait_for_disconnect_fires_when_ble_link_drops(
tmp_path: Path, monkeypatch
) -> None:
"""The same watcher fires for BLE once the peripheral's connection flag flips false."""
ctx = _make_ctx(tmp_path)
ctx.mock = False
device = _FakeBleDevice()
ctx._device = device
ctx._active_transport = "ble"
ctx._active_address = "AA:BB:CC:DD:EE:FF"
async def drop_soon() -> None:
device.is_connected = False # the peripheral goes out of range
monkeypatch.setattr(menu, "_LIVENESS_POLL_S", 0.0)
monkeypatch.setattr(menu, "_LIVENESS_CONFIRM_S", 0.0)
try:
await drop_soon()
await asyncio.wait_for(menu._wait_for_disconnect(ctx), timeout=2.0)
finally:
ctx.repo.close()
class _FakeSession:
"""A minimal stand-in for :class:`TuiSession` recording pushes/pops for dialog tests."""
+115 -2
View File
@@ -119,6 +119,78 @@ def test_stable_id_precedence() -> None:
assert DiscoveredDevice("COM5").stable_id == "port:COM5"
# -- BLE transport -------------------------------------------------------------
def _ble(address: str = "AA:BB:CC:DD:EE:FF", name: str = "MeshCore-Base") -> DiscoveredDevice:
"""Build a BLE DiscoveredDevice as the scanner would."""
return DiscoveredDevice(
transport="ble", address=address, name=name, description=name, product=name
)
def test_ble_device_identity_and_labels() -> None:
"""A BLE device reports its address as the target, a stable ble: id, and a BLE label."""
dev = _ble()
assert dev.is_ble
assert dev.target == "AA:BB:CC:DD:EE:FF" # the connection identifier is the address
assert dev.stable_id == "ble:aa:bb:cc:dd:ee:ff" # stable across sessions, case-folded
assert dev.confidence == "board" and dev.is_likely_lora # a MeshCore advert is confident
assert dev.vendor_label == "Bluetooth"
assert dev.label == "MeshCore-Base (BLE)"
def test_ble_and_serial_stable_ids_never_collide() -> None:
"""A BLE address and a serial number/port can't map to the same remembered device."""
assert _ble().stable_id != DiscoveredDevice("COM5", serial_number="SN1").stable_id
async def test_discover_ble_filters_to_meshcore(monkeypatch: pytest.MonkeyPatch) -> None:
"""The BLE scan keeps only MeshCore-named adverts and maps them to devices."""
from types import SimpleNamespace
import meshterm.core.discovery as discovery
class _FakeScanner:
@staticmethod
async def discover(timeout: float, return_adv: bool):
return {
"AA:BB:CC:DD:EE:FF": (
SimpleNamespace(address="AA:BB:CC:DD:EE:FF", name="MeshCore-Base"),
SimpleNamespace(local_name="MeshCore-Base", rssi=-60),
),
"11:22:33:44:55:66": ( # a random unrelated Bluetooth gadget — filtered out
SimpleNamespace(address="11:22:33:44:55:66", name="AirPods"),
SimpleNamespace(local_name="AirPods", rssi=-70),
),
}
monkeypatch.setattr(discovery, "BleakScanner", _FakeScanner, raising=False)
# ``discover_ble_devices`` imports BleakScanner from bleak inside the function; patch there.
import bleak
monkeypatch.setattr(bleak, "BleakScanner", _FakeScanner, raising=False)
devices = await discovery.discover_ble_devices(timeout=0.0)
assert [d.name for d in devices] == ["MeshCore-Base"]
assert devices[0].is_ble and devices[0].address == "AA:BB:CC:DD:EE:FF"
async def test_discover_ble_survives_no_adapter(monkeypatch: pytest.MonkeyPatch) -> None:
"""A scan failure (no adapter / Bluetooth off) yields an empty list, never raises."""
import bleak
import meshterm.core.discovery as discovery
class _BoomScanner:
@staticmethod
async def discover(timeout: float, return_adv: bool):
raise OSError("no Bluetooth adapter")
monkeypatch.setattr(bleak, "BleakScanner", _BoomScanner, raising=False)
assert await discovery.discover_ble_devices(timeout=0.0) == []
# -- device store --------------------------------------------------------------
@@ -228,19 +300,60 @@ def test_resolve_single_device_auto() -> None:
assert res.port == "COM3" and res.source == "only"
def test_resolve_prefers_explicit_ble() -> None:
"""An explicit --ble selects the BLE transport and wins over everything else."""
res = resolve_device([], None, explicit_ble="AA:BB:CC:DD:EE:FF")
assert res.target == "AA:BB:CC:DD:EE:FF"
assert res.transport == "ble" and res.source == "ble"
def test_resolve_single_ble_device_auto() -> None:
"""A lone in-range BLE companion is chosen automatically, transport and all."""
dev = _ble()
res = resolve_device([dev], None)
assert res.target == dev.address and res.transport == "ble" and res.source == "only"
def test_resolve_uses_remembered_ble_device() -> None:
"""A remembered BLE default reconnects by address when it's back in range."""
from meshterm.core.device_store import RememberedDevice
dev = _ble()
remembered = RememberedDevice(
stable_id=dev.stable_id, port="", label=dev.label, last_connected="",
transport="ble", address=dev.address,
)
res = resolve_device([dev], remembered)
assert res.transport == "ble" and res.target == dev.address and res.source == "remembered"
def test_ble_device_store_round_trip(tmp_path: Path) -> None:
"""A remembered BLE device persists its transport and address, matched by stable_id."""
store = DeviceStore(tmp_path / "devices.json")
dev = _ble(name="MeshCore-Roamer")
store.remember(dev, node_name="Roamer")
loaded = store.load()
assert loaded is not None
assert loaded.is_ble and loaded.transport == "ble"
assert loaded.address == dev.address and loaded.target == dev.address
assert loaded.node_name == "Roamer"
assert loaded.matches(dev)
def test_resolve_ambiguous_raises(tmp_path: Path) -> None:
"""Multiple devices with no usable default raise a guidance error."""
devices = [
DiscoveredDevice("COM3", serial_number="SN1"),
DiscoveredDevice("COM4", serial_number="SN2"),
]
with pytest.raises(DeviceSelectionError, match="Multiple serial devices"):
with pytest.raises(DeviceSelectionError, match="Multiple companion devices"):
resolve_device(devices, None)
def test_resolve_no_devices_raises() -> None:
"""No devices at all raises a clear error mentioning --mock."""
with pytest.raises(DeviceSelectionError, match="No serial devices"):
with pytest.raises(DeviceSelectionError, match="No companion devices"):
resolve_device([], None)