1919 Awaitable ,
2020 Callable ,
2121 Dict ,
22+ Iterable ,
2223 List ,
2324 Optional ,
2425 Tuple ,
2829)
2930from warnings import warn
3031
31- import async_timeout
32+ if sys .version_info < (3 , 11 ):
33+ from async_timeout import timeout as async_timeout
34+ else :
35+ from asyncio import timeout as async_timeout
3236
3337if sys .version_info [:2 ] < (3 , 8 ):
3438 from typing_extensions import Literal
4751)
4852from .backends .service import BleakGATTServiceCollection
4953from .exc import BleakError
54+ from .uuids import normalize_uuid_str
5055
5156if TYPE_CHECKING :
5257 from .backends .bluezdbus .scanner import BlueZScannerArgs
58+ from .backends .corebluetooth .scanner import CBScannerArgs
5359 from .backends .winrt .client import WinRTClientArgs
5460
5561
5662_logger = logging .getLogger (__name__ )
5763_logger .addHandler (logging .NullHandler ())
5864if bool (os .environ .get ("BLEAK_LOGGING" , False )):
59- FORMAT = "%(asctime)-15s %(name)-8s %(levelname)s: %(message)s"
65+ FORMAT = "%(asctime)-15s %(name)-8s %(threadName)s %( levelname)s: %(message)s"
6066 handler = logging .StreamHandler (sys .stdout )
6167 handler .setLevel (logging .DEBUG )
6268 handler .setFormatter (logging .Formatter (fmt = FORMAT ))
@@ -89,12 +95,21 @@ class BleakScanner:
8995 :class:`BleakError` if set to ``"passive"`` on macOS.
9096 bluez:
9197 Dictionary of arguments specific to the BlueZ backend.
98+ cb:
99+ Dictionary of arguments specific to the CoreBluetooth backend.
92100 backend:
93101 Used to override the automatically selected backend (i.e. for a
94102 custom backend).
95103 **kwargs:
96104 Additional args for backwards compatibility.
97105
106+ .. tip:: The first received advertisement in ``detection_callback`` may or
107+ may not include scan response data if the remote device supports it.
108+ Be sure to take this into account when handing the callback. For example,
109+ the scan response often contains the local name of the device so if you
110+ are matching a device based on other data but want to display the local
111+ name to the user, be sure to wait for ``adv_data.local_name is not None``.
112+
98113 .. versionchanged:: 0.15.0
99114 ``detection_callback``, ``service_uuids`` and ``scanning_mode`` are no longer keyword-only.
100115 Added ``bluez`` parameter.
@@ -111,6 +126,7 @@ def __init__(
111126 scanning_mode : Literal ["active" , "passive" ] = "active" ,
112127 * ,
113128 bluez : BlueZScannerArgs = {},
129+ cb : CBScannerArgs = {},
114130 backend : Optional [Type [BaseBleakScanner ]] = None ,
115131 ** kwargs ,
116132 ):
@@ -119,7 +135,12 @@ def __init__(
119135 )
120136
121137 self ._backend = PlatformBleakScanner (
122- detection_callback , service_uuids , scanning_mode , bluez = bluez , ** kwargs
138+ detection_callback ,
139+ service_uuids ,
140+ scanning_mode ,
141+ bluez = bluez ,
142+ cb = cb ,
143+ ** kwargs ,
123144 )
124145
125146 async def __aenter__ (self ):
@@ -188,7 +209,7 @@ async def discover(
188209 @overload
189210 @classmethod
190211 async def discover (
191- cls , timeout : float = 5.0 , * , return_adv : Literal [True ], ** kwargs
212+ cls , timeout : float = 5.0 , * , return_adv : Literal [True ] = True , ** kwargs
192213 ) -> Dict [str , Tuple [BLEDevice , AdvertisementData ]]:
193214 ...
194215
@@ -272,11 +293,9 @@ async def find_device_by_address(
272293 """Obtain a ``BLEDevice`` for a BLE server specified by Bluetooth address or (macOS) UUID address.
273294
274295 Args:
275- device_identifier (str): The Bluetooth/UUID address of the Bluetooth peripheral sought.
276- timeout (float): Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.
277-
278- Keyword Args:
279- adapter (str): Bluetooth adapter to use for discovery.
296+ device_identifier: The Bluetooth/UUID address of the Bluetooth peripheral sought.
297+ timeout: Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.
298+ **kwargs: additional args passed to the :class:`BleakScanner` constructor.
280299
281300 Returns:
282301 The ``BLEDevice`` sought or ``None`` if not detected.
@@ -289,6 +308,28 @@ async def find_device_by_address(
289308 ** kwargs ,
290309 )
291310
311+ @classmethod
312+ async def find_device_by_name (
313+ cls , name : str , timeout : float = 10.0 , ** kwargs
314+ ) -> Optional [BLEDevice ]:
315+ """Obtain a ``BLEDevice`` for a BLE server specified by the local name in the advertising data.
316+
317+ Args:
318+ name: The name sought.
319+ timeout: Optional timeout to wait for detection of specified peripheral before giving up. Defaults to 10.0 seconds.
320+ **kwargs: additional args passed to the :class:`BleakScanner` constructor.
321+
322+ Returns:
323+ The ``BLEDevice`` sought or ``None`` if not detected.
324+
325+ .. versionadded:: 0.20.0
326+ """
327+ return await cls .find_device_by_filter (
328+ lambda d , ad : ad .local_name == name ,
329+ timeout = timeout ,
330+ ** kwargs ,
331+ )
332+
292333 @classmethod
293334 async def find_device_by_filter (
294335 cls , filterfunc : AdvertisementDataFilter , timeout : float = 10.0 , ** kwargs
@@ -322,7 +363,7 @@ def apply_filter(d: BLEDevice, ad: AdvertisementData):
322363
323364 async with cls (detection_callback = apply_filter , ** kwargs ):
324365 try :
325- async with async_timeout . timeout (timeout ):
366+ async with async_timeout (timeout ):
326367 return await found_device_queue .get ()
327368 except asyncio .TimeoutError :
328369 return None
@@ -345,6 +386,12 @@ class BleakClient:
345386 Callback that will be scheduled in the event loop when the client is
346387 disconnected. The callable must take one argument, which will be
347388 this client object.
389+ services:
390+ Optional list of services to filter. If provided, only these services
391+ will be resolved. This may or may not reduce the time needed to
392+ enumerate the services depending on if the OS supports such filtering
393+ in the Bluetooth stack or not (should affect Windows and Mac).
394+ These can be 16-bit or 128-bit UUIDs.
348395 timeout:
349396 Timeout in seconds passed to the implicit ``discover`` call when
350397 ``address_or_ble_device`` is not a :class:`BLEDevice`. Defaults to 10.0.
@@ -381,6 +428,7 @@ def __init__(
381428 self ,
382429 address_or_ble_device : Union [BLEDevice , str ],
383430 disconnected_callback : Optional [Callable [[BleakClient ], None ]] = None ,
431+ services : Optional [Iterable [str ]] = None ,
384432 * ,
385433 timeout : float = 10.0 ,
386434 winrt : WinRTClientArgs = {},
@@ -393,7 +441,12 @@ def __init__(
393441
394442 self ._backend = PlatformBleakClient (
395443 address_or_ble_device ,
396- disconnected_callback = disconnected_callback ,
444+ disconnected_callback = None
445+ if disconnected_callback is None
446+ else functools .partial (disconnected_callback , self ),
447+ services = None
448+ if services is None
449+ else set (map (normalize_uuid_str , services )),
397450 timeout = timeout ,
398451 winrt = winrt ,
399452 ** kwargs ,
@@ -456,7 +509,9 @@ def set_disconnected_callback(
456509 FutureWarning ,
457510 stacklevel = 2 ,
458511 )
459- self ._backend .set_disconnected_callback (callback , ** kwargs )
512+ self ._backend .set_disconnected_callback (
513+ None if callback is None else functools .partial (callback , self ), ** kwargs
514+ )
460515
461516 async def connect (self , ** kwargs ) -> bool :
462517 """Connect to the specified GATT server.
@@ -545,7 +600,13 @@ def services(self) -> BleakGATTServiceCollection:
545600 Gets the collection of GATT services available on the device.
546601
547602 The returned value is only valid as long as the device is connected.
603+
604+ Raises:
605+ BleakError: if service discovery has not been performed yet during this connection.
548606 """
607+ if not self ._backend .services :
608+ raise BleakError ("Service Discovery has not been performed yet" )
609+
549610 return self ._backend .services
550611
551612 # I/O methods
@@ -608,7 +669,7 @@ async def start_notify(
608669
609670 .. code-block:: python
610671
611- def callback(sender: int , data: bytearray):
672+ def callback(sender: BleakGATTCharacteristic , data: bytearray):
612673 print(f"{sender}: {data}")
613674
614675 client.start_notify(char_uuid, callback)
0 commit comments