0
# Bleak
1
2
Bleak is a comprehensive cross-platform Python library that provides an asynchronous GATT client implementation for Bluetooth Low Energy (BLE) communication. The library enables developers to discover, connect to, and interact with BLE devices acting as GATT servers across multiple operating systems including Windows 10+, Linux with BlueZ, macOS/OS X, and Android.
3
4
## Package Information
5
6
- **Package Name**: bleak
7
- **Language**: Python
8
- **Installation**: `pip install bleak`
9
- **Supported Platforms**: Windows 10+, Linux (BlueZ), macOS/OS X, Android
10
11
## Core Imports
12
13
```python
14
import bleak
15
```
16
17
Common for BLE operations:
18
19
```python
20
from bleak import BleakScanner, BleakClient
21
```
22
23
For device discovery:
24
25
```python
26
from bleak import BLEDevice, AdvertisementData
27
```
28
29
For GATT operations:
30
31
```python
32
from bleak.backends.characteristic import BleakGATTCharacteristic
33
from bleak.backends.descriptor import BleakGATTDescriptor
34
from bleak.backends.service import BleakGATTService, BleakGATTServiceCollection
35
```
36
37
## Basic Usage
38
39
```python
40
import asyncio
41
from bleak import BleakScanner, BleakClient
42
43
async def scan_and_connect():
44
# Discover devices
45
devices = await BleakScanner.discover(timeout=5.0)
46
for device in devices:
47
print(f"Found device: {device.name} ({device.address})")
48
49
# Connect to first device
50
if devices:
51
device = devices[0]
52
async with BleakClient(device) as client:
53
print(f"Connected to {client.name}")
54
55
# Read device name characteristic
56
device_name = await client.read_gatt_char("00002a00-0000-1000-8000-00805f9b34fb")
57
print(f"Device name: {device_name.decode()}")
58
59
# List all services
60
for service in client.services:
61
print(f"Service: {service.uuid} - {service.description}")
62
for char in service.characteristics:
63
print(f" Characteristic: {char.uuid} - {char.description}")
64
65
# Run the async function
66
asyncio.run(scan_and_connect())
67
```
68
69
## Architecture
70
71
Bleak's architecture centers around two main components designed for cross-platform BLE operations:
72
73
- **Scanner**: Discovers BLE devices and collects advertisement data using platform-specific backends
74
- **Client**: Establishes GATT connections and performs characteristic/descriptor operations
75
- **Platform Backends**: Native implementations for Windows (WinRT), macOS (CoreBluetooth), Linux (BlueZ), and Android (P4Android)
76
- **Data Models**: Structured representations of BLE devices, services, characteristics, and descriptors
77
78
This design provides a unified async/await API across all platforms while leveraging native Bluetooth stacks for optimal performance and compatibility.
79
80
## Capabilities
81
82
### Device Discovery and Scanning
83
84
Comprehensive BLE device discovery with filtering, callback support, and advertisement data collection. Supports both active and passive scanning modes with platform-specific optimizations.
85
86
```python { .api }
87
class BleakScanner:
88
def __init__(
89
self,
90
detection_callback: Optional[AdvertisementDataCallback] = None,
91
service_uuids: Optional[list[str]] = None,
92
scanning_mode: Literal["active", "passive"] = "active",
93
*,
94
bluez: BlueZScannerArgs = {},
95
cb: CBScannerArgs = {},
96
backend: Optional[type[BaseBleakScanner]] = None,
97
**kwargs: Any,
98
) -> None: ...
99
100
async def start(self) -> None: ...
101
async def stop(self) -> None: ...
102
103
@classmethod
104
async def discover(
105
cls,
106
timeout: float = 5.0,
107
*,
108
return_adv: bool = False,
109
**kwargs: Unpack[ExtraArgs],
110
): ...
111
112
@classmethod
113
async def find_device_by_address(
114
cls, device_identifier: str, timeout: float = 10.0, **kwargs: Unpack[ExtraArgs]
115
) -> Optional[BLEDevice]: ...
116
```
117
118
[Device Discovery and Scanning](./device-discovery.md)
119
120
### GATT Client Operations
121
122
Complete GATT client functionality for connecting to BLE devices and performing read, write, and notification operations on services, characteristics, and descriptors.
123
124
```python { .api }
125
class BleakClient:
126
def __init__(
127
self,
128
address_or_ble_device: Union[BLEDevice, str],
129
disconnected_callback: Optional[Callable[[BleakClient], None]] = None,
130
services: Optional[Iterable[str]] = None,
131
*,
132
timeout: float = 10.0,
133
pair: bool = False,
134
winrt: WinRTClientArgs = {},
135
backend: Optional[type[BaseBleakClient]] = None,
136
**kwargs: Any,
137
) -> None: ...
138
139
async def connect(self, **kwargs: Any) -> None: ...
140
async def disconnect(self) -> None: ...
141
142
async def read_gatt_char(
143
self,
144
char_specifier: Union[BleakGATTCharacteristic, int, str, uuid.UUID],
145
**kwargs: Any,
146
) -> bytearray: ...
147
148
async def write_gatt_char(
149
self,
150
char_specifier: Union[BleakGATTCharacteristic, int, str, uuid.UUID],
151
data: Buffer,
152
response: Optional[bool] = None,
153
) -> None: ...
154
```
155
156
[GATT Client Operations](./gatt-client.md)
157
158
### Data Structures and Models
159
160
Core data structures representing BLE devices, advertisement data, and GATT hierarchy components including services, characteristics, and descriptors.
161
162
```python { .api }
163
class BLEDevice:
164
def __init__(self, address: str, name: Optional[str], details: Any, **kwargs: Any): ...
165
166
address: str
167
name: Optional[str]
168
details: Any
169
170
class AdvertisementData(NamedTuple):
171
local_name: Optional[str]
172
manufacturer_data: dict[int, bytes]
173
service_data: dict[str, bytes]
174
service_uuids: list[str]
175
tx_power: Optional[int]
176
rssi: int
177
platform_data: tuple[Any, ...]
178
```
179
180
[Data Structures and Models](./data-structures.md)
181
182
### Exception Handling and Error Management
183
184
Comprehensive exception hierarchy for handling BLE operation errors, device connectivity issues, and platform-specific error conditions.
185
186
```python { .api }
187
class BleakError(Exception): ...
188
189
class BleakCharacteristicNotFoundError(BleakError):
190
char_specifier: Union[int, str, uuid.UUID]
191
def __init__(self, char_specifier: Union[int, str, uuid.UUID]) -> None: ...
192
193
class BleakDeviceNotFoundError(BleakError):
194
identifier: str
195
def __init__(self, identifier: str, *args: object) -> None: ...
196
```
197
198
[Exception Handling](./exception-handling.md)
199
200
### UUID Utilities and Constants
201
202
Utilities for UUID normalization, conversion, and lookup of Bluetooth assigned numbers including service and characteristic UUIDs.
203
204
```python { .api }
205
from bleak.uuids import normalize_uuid_str, normalize_uuid_16, normalize_uuid_32, uuidstr_to_str, register_uuids
206
207
def normalize_uuid_str(uuid: str) -> str: ...
208
def normalize_uuid_16(uuid: int) -> str: ...
209
def normalize_uuid_32(uuid: int) -> str: ...
210
def uuidstr_to_str(uuid_: str) -> str: ...
211
def register_uuids(uuids_to_descriptions: dict[str, str]) -> None: ...
212
```
213
214
[UUID Utilities](./uuid-utilities.md)
215
216
## Types
217
218
```python { .api }
219
# Type aliases for callbacks and filters
220
AdvertisementDataCallback = Callable[
221
[BLEDevice, AdvertisementData],
222
Optional[Coroutine[Any, Any, None]],
223
]
224
225
AdvertisementDataFilter = Callable[
226
[BLEDevice, AdvertisementData],
227
bool,
228
]
229
230
# Platform-specific argument types
231
class BlueZScannerArgs(TypedDict, total=False):
232
filters: BlueZDiscoveryFilters
233
or_patterns: list[OrPatternLike]
234
235
class BlueZDiscoveryFilters(TypedDict, total=False):
236
UUIDs: list[str]
237
RSSI: int
238
Pathloss: int
239
Transport: str
240
DuplicateData: bool
241
Discoverable: bool
242
Pattern: str
243
244
class CBScannerArgs(TypedDict, total=False):
245
use_bdaddr: bool
246
247
class WinRTClientArgs(TypedDict, total=False):
248
address_type: Literal["public", "random"]
249
use_cached_services: bool
250
251
class CBStartNotifyArgs(TypedDict, total=False):
252
use_bdaddr: bool
253
254
# Buffer protocol type for data writing
255
if sys.version_info < (3, 12):
256
from typing_extensions import Buffer
257
else:
258
from collections.abc import Buffer
259
260
# Additional platform type aliases
261
OrPatternLike = Any # Platform-specific BlueZ pattern type
262
```