Merge branch 'main' into fix/standalone-bugs-and-cleanup

Author: fdlamotte

src/meshcore/ble_cx.py

@@ -51,6 +51,14 @@ def __init__(self, address=None, device=None, client=None, pin=None):
         self.pin = pin
         self.rx_char = None
         self._disconnect_callback = None
+        self._background_tasks: set[asyncio.Task] = set()
+
+    def _spawn_background(self, coro) -> asyncio.Task:
+        """Create a tracked background task (prevents GC of fire-and-forget tasks)."""
+        task = asyncio.create_task(coro)
+        self._background_tasks.add(task)
+        task.add_done_callback(self._background_tasks.discard)
+        return task
 
     async def connect(self):
         """
@@ -116,9 +124,12 @@ def match_meshcore_device(d: BLEDevice, adv: AdvertisementData):
                     await self.client.pair()
                     logger.info("BLE pairing successful")
                 except Exception as e:
-                    logger.warning(f"BLE pairing failed: {e}")
-                    # Don't fail the connection if pairing fails, as the device
-                    # might already be paired or not require pairing
+                    logger.error(f"BLE pairing failed: {e}")
+                    # A failed pairing leaves the transport in a half-usable
+                    # state — re-raise so the caller gets a clean failure
+                    # instead of a silently degraded connection.
+                    await self.client.disconnect()
+                    raise
 
         except BleakDeviceNotFoundError:
             return None
@@ -154,8 +165,19 @@ def handle_disconnect(self, client: BleakClient):
         self.client = self._user_provided_client
         self.device = self._user_provided_device
 
+        # Re-register disconnect callback on the reset client so subsequent
+        # disconnects after a reconnect cycle are still detected.
+        if self.client is not None and hasattr(self.client, 'set_disconnected_callback'):
+            try:
+                self.client.set_disconnected_callback(self.handle_disconnect)
+            except Exception:
+                # set_disconnected_callback may not be available on all bleak
+                # versions; the next connect() call will re-create the client
+                # with the callback anyway.
+                pass
+
         if self._disconnect_callback:
-            asyncio.create_task(self._disconnect_callback("ble_disconnect"))
+            self._spawn_background(self._disconnect_callback("ble_disconnect"))
 
     def set_disconnect_callback(self, callback):
         """Set callback to handle disconnections."""
@@ -166,16 +188,24 @@ def set_reader(self, reader):
 
     def handle_rx(self, _: BleakGATTCharacteristic, data: bytearray):
         if self.reader is not None:
-            asyncio.create_task(self.reader.handle_rx(data))
+            self._spawn_background(self.reader.handle_rx(data))
 
     async def send(self, data):
         if not self.client:
             logger.error("Client is not connected")
+            if self._disconnect_callback:
+                await self._disconnect_callback("ble_transport_lost")
             return False
         if not self.rx_char:
             logger.error("RX characteristic not found")
             return False
-        await self.client.write_gatt_char(self.rx_char, bytes(data), response=True)
+        try:
+            await self.client.write_gatt_char(self.rx_char, bytes(data), response=True)
+        except Exception as exc:
+            logger.warning(f"BLE write failed: {exc}")
+            if self._disconnect_callback:
+                await self._disconnect_callback(f"ble_write_failed: {exc}")
+            return False
 
     async def disconnect(self):
         """Disconnect from the BLE device."""

src/meshcore/commands/base.py

@@ -58,17 +58,32 @@ def _validate_destination(dst: DestinationType, prefix_length: int = 6) -> bytes
 
 
 class CommandHandlerBase:
+    """Base class for command handlers.
+
+    .. note::
+        The internal ``asyncio.Lock`` is created lazily on first access
+        so that it binds to the correct running event loop (required for
+        Python 3.9/3.10 compatibility).
+    """
+
     DEFAULT_TIMEOUT = 15.0
 
     def __init__(self, default_timeout: Optional[float] = None):
         self._sender_func: Optional[Callable[[bytes], Coroutine[Any, Any, None]]] = None
         self._reader: Optional[MessageReader] = None
         self.dispatcher: Optional[EventDispatcher] = None
-        self._mesh_request_lock = asyncio.Lock()
+        self.__mesh_request_lock: Optional[asyncio.Lock] = None
         self.default_timeout = (
             default_timeout if default_timeout is not None else self.DEFAULT_TIMEOUT
         )
 
+    @property
+    def _mesh_request_lock(self) -> asyncio.Lock:
+        """Lazy-init lock so it binds to the running loop, not import-time."""
+        if self.__mesh_request_lock is None:
+            self.__mesh_request_lock = asyncio.Lock()
+        return self.__mesh_request_lock
+
     def set_connection(self, connection: Any) -> None:
         async def sender(data: bytes) -> None:
             await connection.send(data)
@@ -90,6 +105,14 @@ async def wait_for_events(
         expected_events: Optional[Union[EventType, List[EventType]]] = None,
         timeout: Optional[float] = None,
     ) -> Event:
+        """Wait for the first of *expected_events* to arrive.
+
+        Returns the first matched ``Event``.  When ``EventType.ERROR`` is
+        among the expected types, the caller **must** check
+        ``result.is_error()`` before accessing command-specific payload
+        keys — an ERROR payload is ``{"reason": "..."}`` and will
+        ``KeyError`` on any other key.
+        """
         try:
             # Convert single event to list if needed
             if not isinstance(expected_events, list):
@@ -129,9 +152,6 @@ async def wait_for_events(
             logger.debug(f"Command error: {e}")
             return Event(EventType.ERROR, {"error": str(e)})
 
-        return Event(EventType.ERROR, {})
-
-
     async def send(
         self,
         data: bytes,
@@ -151,7 +171,14 @@ async def send(
             timeout: Timeout in seconds, or None to use default_timeout
 
         Returns:
-            Event: The full event object that was received in response to the command
+            Event: The full event object that was received in response to
+            the command.
+
+        Important:
+            When ``EventType.ERROR`` is included in *expected_events*, the
+            returned event may be an error response.  Callers **must**
+            check ``result.is_error()`` before accessing command-specific
+            payload keys to avoid ``KeyError``.
         """
         if not self.dispatcher:
             raise RuntimeError("Dispatcher not set, cannot send commands")
@@ -170,7 +197,7 @@ async def send(
             futures: List[asyncio.Future] = []
             subscriptions = []
 
-            loop = asyncio.get_event_loop()
+            loop = asyncio.get_running_loop()
             for event_type in expected_events:
                 future = loop.create_future()
 
@@ -279,6 +306,7 @@ async def send_anon_req(self, dst: DestinationType, request_type: AnonReqType, d
         contact = self._get_contact_by_prefix(dst_bytes.hex()) # need a contact for return path
         if contact is None:
             logger.error("No contact found")
+            return Event(EventType.ERROR, {"reason": "contact_not_found"})
 
         zero_hop = False
         if contact["out_path_len"] == -1: 

src/meshcore/commands/contact.py

@@ -191,6 +191,24 @@ async def get_autoadd_config(self) -> Event:
         data = b"\x3B"
         return await self.send(data, [EventType.AUTOADD_CONFIG, EventType.ERROR])
 
+    async def get_contact_by_key(self, pubkey: bytes) -> Event:
+        """N09: Retrieve a single contact by its public key (CMD 30).
+
+        Args:
+            pubkey: 32-byte public key of the contact.
+
+        Returns:
+            Event with the contact data (same format as CONTACT/NEXT_CONTACT),
+            or ERROR if not found.
+        """
+        if not isinstance(pubkey, (bytes, bytearray)):
+            raise TypeError("pubkey must be bytes-like")
+        # Truncate or pad to 32 bytes
+        key_bytes = bytes(pubkey[:32])
+        logger.debug(f"Getting contact by key: {key_bytes.hex()}")
+        data = b"\x1e" + key_bytes
+        return await self.send(data, [EventType.NEXT_CONTACT, EventType.ERROR])
+
     async def get_advert_path(self, key: DestinationType) -> Event:
         key_bytes = _validate_destination(key, prefix_length=32)
         logger.debug(f"getting advert path for: {key} {key_bytes.hex()}")

src/meshcore/commands/device.py

@@ -4,6 +4,7 @@
 from typing import Optional
 
 from ..events import Event, EventType
+from ..packets import CommandType
 from .base import CommandHandlerBase, DestinationType, _validate_destination
 
 logger = logging.getLogger("meshcore")
@@ -13,7 +14,7 @@ class DeviceCommands(CommandHandlerBase):
     async def send_appstart(self) -> Event:
         logger.debug("Sending appstart command")
         b1 = bytearray(b"\x01\x03      mccli")
-        return await self.send(b1, [EventType.SELF_INFO])
+        return await self.send(b1, [EventType.SELF_INFO, EventType.ERROR])
 
     async def send_device_query(self) -> Event:
         logger.debug("Sending device query command")
@@ -129,32 +130,50 @@ async def set_other_params_from_infos(self, infos) -> Event:
         return await self.send(data, [EventType.OK, EventType.ERROR])
 
     async def set_telemetry_mode_base(self, telemetry_mode_base: int) -> Event:
-        infos = (await self.send_appstart()).payload
+        result = await self.send_appstart()
+        if result.is_error():
+            return result
+        infos = result.payload
         infos["telemetry_mode_base"] = telemetry_mode_base
         return await self.set_other_params_from_infos(infos)
 
     async def set_telemetry_mode_loc(self, telemetry_mode_loc: int) -> Event:
-        infos = (await self.send_appstart()).payload
+        result = await self.send_appstart()
+        if result.is_error():
+            return result
+        infos = result.payload
         infos["telemetry_mode_loc"] = telemetry_mode_loc
         return await self.set_other_params_from_infos(infos)
 
     async def set_telemetry_mode_env(self, telemetry_mode_env: int) -> Event:
-        infos = (await self.send_appstart()).payload
+        result = await self.send_appstart()
+        if result.is_error():
+            return result
+        infos = result.payload
         infos["telemetry_mode_env"] = telemetry_mode_env
         return await self.set_other_params_from_infos(infos)
 
     async def set_manual_add_contacts(self, manual_add_contacts: bool) -> Event:
-        infos = (await self.send_appstart()).payload
+        result = await self.send_appstart()
+        if result.is_error():
+            return result
+        infos = result.payload
         infos["manual_add_contacts"] = manual_add_contacts
         return await self.set_other_params_from_infos(infos)
 
     async def set_advert_loc_policy(self, advert_loc_policy: int) -> Event:
-        infos = (await self.send_appstart()).payload
+        result = await self.send_appstart()
+        if result.is_error():
+            return result
+        infos = result.payload
         infos["adv_loc_policy"] = advert_loc_policy
         return await self.set_other_params_from_infos(infos)
 
     async def set_multi_acks(self, multi_acks: int) -> Event:
-        infos = (await self.send_appstart()).payload
+        result = await self.send_appstart()
+        if result.is_error():
+            return result
+        infos = result.payload
         infos["multi_acks"] = multi_acks
         return await self.set_other_params_from_infos(infos)
 
@@ -273,20 +292,89 @@ async def sign(self, data: bytes, chunk_size: int = 120, timeout: Optional[float
 
         return await self.sign_finish(timeout=timeout, data_size=len(data))
 
+    async def has_connection(self) -> Event:
+        """N09: Check if the device has an active connection (CMD 28).
+
+        Returns:
+            Event with a 1-byte response indicating connection status,
+            or ERROR.
+        """
+        logger.debug("Checking device connection status")
+        return await self.send(b"\x1c", [EventType.OK, EventType.ERROR])
+
+    async def get_tuning(self) -> Event:
+        """N03/N09: Request current tuning parameters (CMD_GET_TUNING_PARAMS = 43).
+
+        Firmware responds with RESP_CODE_TUNING_PARAMS (23): 9 bytes containing
+        rx_delay (4 bytes LE) and airtime_factor (4 bytes LE).
+
+        Returns:
+            Event of type TUNING_PARAMS with rx_delay and airtime_factor,
+            or ERROR.
+        """
+        logger.debug("Getting tuning parameters")
+        return await self.send(b"\x2b", [EventType.TUNING_PARAMS, EventType.ERROR])
+
+    async def request_factory_reset(self) -> str:
+        """N09: Request a factory reset token (step 1 of 2).
+
+        This method returns a confirmation token string. Pass it to
+        ``confirm_factory_reset(token)`` to actually execute the reset.
+        The two-step pattern is a Python-side safety measure; the firmware
+        itself has no token verification.
+
+        Returns:
+            A confirmation token string to pass to confirm_factory_reset().
+        """
+        import secrets
+        token = secrets.token_hex(8)
+        logger.warning(
+            "Factory reset requested. Call confirm_factory_reset('%s') to proceed. "
+            "This will ERASE ALL DATA on the device.", token
+        )
+        # Store the token on the instance for validation
+        self._factory_reset_token = token
+        return token
+
+    async def confirm_factory_reset(self, token: str) -> Event:
+        """N09: Execute factory reset after token confirmation (step 2 of 2).
+
+        Args:
+            token: The token returned by request_factory_reset().
+
+        Returns:
+            Event with OK or ERROR.
+
+        Raises:
+            ValueError: If the token does not match.
+        """
+        expected = getattr(self, "_factory_reset_token", None)
+        if expected is None or token != expected:
+            raise ValueError(
+                "Invalid or expired factory reset token. "
+                "Call request_factory_reset() first."
+            )
+        self._factory_reset_token = None  # Consume the token
+        logger.warning("Executing factory reset — all device data will be erased")
+        return await self.send(b"\x33", [EventType.OK, EventType.ERROR])
+
     async def get_stats_core(self) -> Event:
         logger.debug("Getting core statistics")
-        # CMD_GET_STATS (56) + STATS_TYPE_CORE (0)
-        return await self.send(b"\x38\x00", [EventType.STATS_CORE, EventType.ERROR])
+        # R04: Use CommandType enum instead of literal bytes
+        cmd = bytes([CommandType.GET_STATS.value, 0x00])  # GET_STATS + STATS_TYPE_CORE
+        return await self.send(cmd, [EventType.STATS_CORE, EventType.ERROR])
 
     async def get_stats_radio(self) -> Event:
         logger.debug("Getting radio statistics")
-        # CMD_GET_STATS (56) + STATS_TYPE_RADIO (1)
-        return await self.send(b"\x38\x01", [EventType.STATS_RADIO, EventType.ERROR])
+        # R04: Use CommandType enum instead of literal bytes
+        cmd = bytes([CommandType.GET_STATS.value, 0x01])  # GET_STATS + STATS_TYPE_RADIO
+        return await self.send(cmd, [EventType.STATS_RADIO, EventType.ERROR])
 
     async def get_stats_packets(self) -> Event:
         logger.debug("Getting packet statistics")
-        # CMD_GET_STATS (56) + STATS_TYPE_PACKETS (2)
-        return await self.send(b"\x38\x02", [EventType.STATS_PACKETS, EventType.ERROR])
+        # R04: Use CommandType enum instead of literal bytes
+        cmd = bytes([CommandType.GET_STATS.value, 0x02])  # GET_STATS + STATS_TYPE_PACKETS
+        return await self.send(cmd, [EventType.STATS_PACKETS, EventType.ERROR])
 
     async def get_allowed_repeat_freq(self) -> Event:
         logger.debug("Getting allowed repeat freqs")