added BleakDeviceNotFoundError

CHANGELOG.rst

@@ -14,6 +14,7 @@ Added
 -----
 * Added support for Python 3.11.
 * Added better error message for Bluetooth not authorized on macOS.
+* ``BleakDeviceNotFoundError`` which should be raised if a device can not be found by ``connect``, ``pair`` and ``unpair``
 
 Fixed
 -----

bleak/backends/bluezdbus/client.py

@@ -11,12 +11,12 @@
 
 import async_timeout
 from dbus_fast.aio import MessageBus
-from dbus_fast.constants import BusType, ErrorType
+from dbus_fast.constants import BusType, ErrorType, MessageType
 from dbus_fast.message import Message
 from dbus_fast.signature import Variant
 
 from ... import BleakScanner
-from ...exc import BleakDBusError, BleakError
+from ...exc import BleakDBusError, BleakError, BleakDeviceNotFoundError
 from ..characteristic import BleakGATTCharacteristic
 from ..client import BaseBleakClient, NotifyCallback
 from ..device import BLEDevice
@@ -116,8 +116,8 @@ async def connect(self, dangerous_use_bleak_cache: bool = False, **kwargs) -> bo
                 self._device_info = device.details.get("props")
                 self._device_path = device.details["path"]
             else:
-                raise BleakError(
-                    "Device with address {0} was not found.".format(self.address)
+                raise BleakDeviceNotFoundError(
+                    self.address, f"Device with address {self.address} was not found."
                 )
 
         manager = await get_global_bluez_manager()
@@ -176,6 +176,15 @@ def on_value_changed(char_path: str, value: bytes) -> None:
                                 member="Connect",
                             )
                         )
+                    if (
+                        reply is not None
+                        and reply.message_type == MessageType.ERROR
+                        and reply.error_name == ErrorType.UNKNOWN_OBJECT
+                    ):
+                        raise BleakDeviceNotFoundError(
+                            self.address,
+                            f"Device with address {self.address} was not found.",
+                        )
                     assert_reply(reply)
 
                 self._is_connected = True

bleak/backends/corebluetooth/client.py

@@ -17,7 +17,7 @@
 from Foundation import NSArray, NSData
 
 from ... import BleakScanner
-from ...exc import BleakError
+from ...exc import BleakError, BleakDeviceNotFoundError
 from ..characteristic import BleakGATTCharacteristic
 from ..client import BaseBleakClient, NotifyCallback
 from ..device import BLEDevice
@@ -80,8 +80,8 @@ async def connect(self, **kwargs) -> bool:
                 self._peripheral = device.details
                 self._central_manager_delegate = device.metadata["delegate"]
             else:
-                raise BleakError(
-                    "Device with address {} was not found".format(self.address)
+                raise BleakDeviceNotFoundError(
+                    self.address, f"Device with address {self.address} was not found"
                 )
 
         if self._delegate is None:

bleak/backends/device.py

@@ -23,7 +23,7 @@ class BLEDevice:
     - When using macOS backend, ``details`` attribute will be a CBPeripheral object.
     """
 
-    def __init__(self, address, name, details=None, rssi=0, **kwargs):
+    def __init__(self, address, name=None, details=None, rssi=0, **kwargs):
         #: The Bluetooth address of the device on this machine.
         self.address = address
         #: The advertised name of the device.

bleak/backends/winrt/client.py

@@ -48,7 +48,7 @@
 from bleak_winrt.windows.storage.streams import Buffer
 
 from ... import BleakScanner
-from ...exc import PROTOCOL_ERROR_CODES, BleakError
+from ...exc import PROTOCOL_ERROR_CODES, BleakError, BleakDeviceNotFoundError
 from ..characteristic import BleakGATTCharacteristic
 from ..client import BaseBleakClient, NotifyCallback
 from ..device import BLEDevice
@@ -197,7 +197,7 @@ def __str__(self):
 
     # Connectivity methods
 
-    def _create_requester(self, bluetooth_address: int):
+    def _create_requester(self, bluetooth_address: int) -> BluetoothLEDevice:
         args = [
             bluetooth_address,
         ]
@@ -207,7 +207,12 @@ def _create_requester(self, bluetooth_address: int):
                 if self._address_type == "public"
                 else BluetoothAddressType.RANDOM
             )
-        return BluetoothLEDevice.from_bluetooth_address_async(*args)
+        requester = BluetoothLEDevice.from_bluetooth_address_async(*args)
+        if requester is None:
+            raise BleakDeviceNotFoundError(
+                self.address, f"Device with address {self.address} was not found."
+            )
+        return requester
 
     async def connect(self, **kwargs) -> bool:
         """Connect to the specified GATT server.
@@ -226,10 +231,12 @@ async def connect(self, **kwargs) -> bool:
                 self.address, timeout=timeout, backend=BleakScannerWinRT
             )
 
-            if device:
-                self._device_info = device.details.adv.bluetooth_address
-            else:
-                raise BleakError(f"Device with address {self.address} was not found.")
+            if device is None:
+                raise BleakDeviceNotFoundError(
+                    self.address, f"Device with address {self.address} was not found."
+                )
+
+            self._device_info = device.details.adv.bluetooth_address
 
         logger.debug("Connecting to BLE device @ %s", self.address)
 
@@ -476,9 +483,6 @@ async def unpair(self) -> bool:
             else _address_to_int(self.address)
         )
 
-        if device is None:
-            raise BleakError(f"Device with address {self.address} was not found.")
-
         try:
             unpairing_result = await device.device_information.pairing.unpair_async()
             if unpairing_result.status not in (

bleak/exc.py

@@ -8,6 +8,23 @@ class BleakError(Exception):
     pass
 
 
+class BleakDeviceNotFoundError(BleakError):
+    """
+    Exception which is raised if a device can not be found by ``connect``, ``pair`` and ``unpair``.
+    This is the case if the OS Bluetooth stack has never seen this device or it was removed and forgotten.
+    """
+
+    identifier: str
+
+    def __init__(self, identifier: str, *args: object) -> None:
+        """
+        Args:
+            identifier (str): device identifier (Bluetooth address or UUID) of the device which was not found
+        """
+        super().__init__(*args)
+        self.identifier = identifier
+
+
 class BleakDBusError(BleakError):
     """Specialized exception type for D-Bus errors."""