0
# BLE and Device Discovery
1
2
Bluetooth Low Energy connectivity and device discovery functionality for finding and connecting to Matter devices during commissioning and setup.
3
4
## Capabilities
5
6
### BLE Manager
7
8
Manages Bluetooth Low Energy connections for Matter device discovery and commissioning.
9
10
```python { .api }
11
class BleManager:
12
"""BLE manager for Matter device connectivity."""
13
14
def __init__(self):
15
"""Initialize BLE manager."""
16
...
17
18
def scan(self, timeout: int = 10) -> list:
19
"""
20
Scan for BLE devices advertising Matter services.
21
22
Parameters:
23
- timeout: Scan timeout in seconds
24
25
Returns:
26
List of discovered device information dictionaries
27
"""
28
...
29
30
def connect(self, identifier: str) -> bool:
31
"""
32
Connect to a specific BLE device.
33
34
Parameters:
35
- identifier: Device identifier (MAC address or UUID)
36
37
Returns:
38
True if connection successful
39
"""
40
...
41
42
def disconnect(self) -> bool:
43
"""
44
Disconnect from current BLE device.
45
46
Returns:
47
True if disconnection successful
48
"""
49
...
50
51
def get_connected_device(self):
52
"""
53
Get currently connected BLE device.
54
55
Returns:
56
Connected device object or None
57
"""
58
...
59
```
60
61
### Platform-Specific BLE Managers
62
63
Platform-specific implementations for different operating systems.
64
65
```python { .api }
66
class ChipBluezMgr:
67
"""Linux BlueZ BLE manager for CHIP operations."""
68
69
def __init__(self, adapter_name: str = None):
70
"""
71
Initialize BlueZ manager.
72
73
Parameters:
74
- adapter_name: Bluetooth adapter name (default: first available)
75
"""
76
...
77
78
def start_scan(self) -> bool:
79
"""Start BLE device scanning."""
80
...
81
82
def stop_scan(self) -> bool:
83
"""Stop BLE device scanning."""
84
...
85
86
def get_peripheral(self, identifier: str):
87
"""Get peripheral device by identifier."""
88
...
89
90
def connect_peripheral(self, peripheral) -> bool:
91
"""Connect to a peripheral device."""
92
...
93
94
def disconnect_peripheral(self, peripheral) -> bool:
95
"""Disconnect from a peripheral device."""
96
...
97
98
class ChipCoreBluetoothMgr:
99
"""macOS Core Bluetooth manager for CHIP operations."""
100
101
def __init__(self):
102
"""Initialize Core Bluetooth manager."""
103
...
104
105
def start_scan(self, service_uuids: list = None) -> bool:
106
"""
107
Start scanning for peripherals.
108
109
Parameters:
110
- service_uuids: List of service UUIDs to filter (optional)
111
112
Returns:
113
True if scan started successfully
114
"""
115
...
116
117
def stop_scan(self) -> bool:
118
"""Stop peripheral scanning."""
119
...
120
121
def connect_peripheral(self, peripheral_id: str) -> bool:
122
"""
123
Connect to peripheral by identifier.
124
125
Parameters:
126
- peripheral_id: Peripheral identifier
127
128
Returns:
129
True if connection initiated successfully
130
"""
131
...
132
133
def disconnect_peripheral(self, peripheral_id: str) -> bool:
134
"""
135
Disconnect from peripheral.
136
137
Parameters:
138
- peripheral_id: Peripheral identifier
139
140
Returns:
141
True if disconnection initiated successfully
142
"""
143
...
144
```
145
146
### Device Discovery
147
148
Discover Matter devices on the network using various discovery methods.
149
150
```python { .api }
151
class DiscoveryManager:
152
"""Manager for Matter device discovery."""
153
154
def __init__(self):
155
"""Initialize discovery manager."""
156
...
157
158
def discover_commissionable_nodes(
159
self,
160
timeout: int = 30,
161
filter_type: int = None,
162
filter_value: str = None
163
) -> list:
164
"""
165
Discover commissionable Matter nodes on the network.
166
167
Parameters:
168
- timeout: Discovery timeout in seconds
169
- filter_type: Discovery filter type (0=None, 1=Short Discriminator, 2=Long Discriminator, 3=Vendor ID, 4=Device Type)
170
- filter_value: Filter value based on filter_type
171
172
Returns:
173
List of discovered node information dictionaries
174
"""
175
...
176
177
def discover_operational_devices(
178
self,
179
fabric_id: int = None,
180
timeout: int = 30
181
) -> list:
182
"""
183
Discover operational (commissioned) Matter devices.
184
185
Parameters:
186
- fabric_id: Fabric ID to filter by (optional)
187
- timeout: Discovery timeout in seconds
188
189
Returns:
190
List of operational device information dictionaries
191
"""
192
...
193
194
def resolve_device(self, node_id: int, fabric_id: int = None) -> dict:
195
"""
196
Resolve specific device information.
197
198
Parameters:
199
- node_id: Target node ID
200
- fabric_id: Fabric ID (optional)
201
202
Returns:
203
Device information dictionary or None if not found
204
"""
205
...
206
207
def stop_discovery(self):
208
"""Stop all active discovery operations."""
209
...
210
```
211
212
### Commissionable Node Controller
213
214
Specialized controller for managing commissionable nodes during device setup.
215
216
```python { .api }
217
class ChipCommissionableNodeCtrl:
218
"""Controller for commissionable node operations."""
219
220
def __init__(self):
221
"""Initialize commissionable node controller."""
222
...
223
224
def discover_commissionable_nodes_long_discriminator(
225
self,
226
long_discriminator: int,
227
timeout: int = 30
228
) -> list:
229
"""
230
Discover nodes by long discriminator.
231
232
Parameters:
233
- long_discriminator: Long discriminator value (0-4095)
234
- timeout: Discovery timeout in seconds
235
236
Returns:
237
List of matching node information dictionaries
238
"""
239
...
240
241
def discover_commissionable_nodes_short_discriminator(
242
self,
243
short_discriminator: int,
244
timeout: int = 30
245
) -> list:
246
"""
247
Discover nodes by short discriminator.
248
249
Parameters:
250
- short_discriminator: Short discriminator value (0-15)
251
- timeout: Discovery timeout in seconds
252
253
Returns:
254
List of matching node information dictionaries
255
"""
256
...
257
258
def discover_commissionable_nodes_vendor_id(
259
self,
260
vendor_id: int,
261
timeout: int = 30
262
) -> list:
263
"""
264
Discover nodes by vendor ID.
265
266
Parameters:
267
- vendor_id: Vendor ID to search for
268
- timeout: Discovery timeout in seconds
269
270
Returns:
271
List of matching node information dictionaries
272
"""
273
...
274
275
def discover_commissionable_nodes_device_type(
276
self,
277
device_type: int,
278
timeout: int = 30
279
) -> list:
280
"""
281
Discover nodes by device type.
282
283
Parameters:
284
- device_type: Device type ID to search for
285
- timeout: Discovery timeout in seconds
286
287
Returns:
288
List of matching node information dictionaries
289
"""
290
...
291
292
def discover_commissionable_nodes_commissioning_enabled(
293
self,
294
timeout: int = 30
295
) -> list:
296
"""
297
Discover all nodes with commissioning enabled.
298
299
Parameters:
300
- timeout: Discovery timeout in seconds
301
302
Returns:
303
List of commissionable node information dictionaries
304
"""
305
...
306
```
307
308
### BLE Utility Functions
309
310
Utility functions for BLE operations and device management.
311
312
```python { .api }
313
class ChipBleUtility:
314
"""Utility class for CHIP BLE operations."""
315
316
@staticmethod
317
def scan_devices(timeout: int = 10) -> list:
318
"""
319
Scan for CHIP-enabled BLE devices.
320
321
Parameters:
322
- timeout: Scan timeout in seconds
323
324
Returns:
325
List of device dictionaries with name, address, and RSSI
326
"""
327
...
328
329
@staticmethod
330
def connect_device(device_address: str) -> bool:
331
"""
332
Connect to BLE device by address.
333
334
Parameters:
335
- device_address: BLE device MAC address
336
337
Returns:
338
True if connection successful
339
"""
340
...
341
342
@staticmethod
343
def disconnect_device(device_address: str) -> bool:
344
"""
345
Disconnect from BLE device.
346
347
Parameters:
348
- device_address: BLE device MAC address
349
350
Returns:
351
True if disconnection successful
352
"""
353
...
354
355
@staticmethod
356
def get_device_info(device_address: str) -> dict:
357
"""
358
Get detailed information about a BLE device.
359
360
Parameters:
361
- device_address: BLE device MAC address
362
363
Returns:
364
Dictionary with device information or None if not found
365
"""
366
...
367
368
@staticmethod
369
def is_chip_device(device_address: str) -> bool:
370
"""
371
Check if BLE device supports CHIP protocol.
372
373
Parameters:
374
- device_address: BLE device MAC address
375
376
Returns:
377
True if device supports CHIP
378
"""
379
...
380
```
381
382
## Usage Examples
383
384
### Device Discovery
385
386
```python
387
from chip.discovery import DiscoveryManager
388
from chip.ChipCommissionableNodeCtrl import ChipCommissionableNodeCtrl
389
390
# Initialize discovery manager
391
discovery = DiscoveryManager()
392
393
# Discover all commissionable devices
394
devices = discovery.discover_commissionable_nodes(timeout=30)
395
396
for device in devices:
397
print(f"Found device: {device['instanceName']}")
398
print(f" Vendor ID: {device['vendorId']}")
399
print(f" Product ID: {device['productId']}")
400
print(f" Discriminator: {device['longDiscriminator']}")
401
print(f" IP Address: {device['addresses']}")
402
403
# Discover devices by vendor ID
404
commissionable = ChipCommissionableNodeCtrl()
405
vendor_devices = commissionable.discover_commissionable_nodes_vendor_id(
406
vendor_id=0x1234,
407
timeout=30
408
)
409
410
# Discover operational devices
411
operational_devices = discovery.discover_operational_devices(timeout=30)
412
print(f"Found {len(operational_devices)} operational devices")
413
```
414
415
### BLE Device Scanning and Connection
416
417
```python
418
from chip.ble import BleManager
419
from chip.ChipBleUtility import ChipBleUtility
420
421
# Scan for BLE devices
422
ble_devices = ChipBleUtility.scan_devices(timeout=15)
423
424
for device in ble_devices:
425
print(f"BLE Device: {device['name']} ({device['address']}) RSSI: {device['rssi']}")
426
427
# Check if it's a CHIP device
428
if ChipBleUtility.is_chip_device(device['address']):
429
print(f" -> CHIP-enabled device found!")
430
431
# Get detailed info
432
info = ChipBleUtility.get_device_info(device['address'])
433
if info:
434
print(f" Services: {info.get('services', [])}")
435
436
# Connect to a specific BLE device
437
ble_manager = BleManager()
438
success = ble_manager.connect("AA:BB:CC:DD:EE:FF")
439
440
if success:
441
print("BLE connection established")
442
443
# Use the BLE connection for commissioning
444
# (typically done through ChipDeviceController.CommissionWithCode)
445
446
# Disconnect when done
447
ble_manager.disconnect()
448
```
449
450
### Platform-Specific BLE Usage
451
452
```python
453
import platform
454
455
# Use platform-appropriate BLE manager
456
if platform.system() == "Linux":
457
from chip.ChipBluezMgr import ChipBluezMgr
458
459
ble_mgr = ChipBluezMgr(adapter_name="hci0")
460
ble_mgr.start_scan()
461
462
# Wait for scan results...
463
import time
464
time.sleep(10)
465
466
ble_mgr.stop_scan()
467
468
elif platform.system() == "Darwin": # macOS
469
from chip.ChipCoreBluetoothMgr import ChipCoreBluetoothMgr
470
471
ble_mgr = ChipCoreBluetoothMgr()
472
473
# Scan for CHIP service UUIDs
474
chip_service_uuids = ["0000FFF6-0000-1000-8000-00805F9B34FB"]
475
ble_mgr.start_scan(service_uuids=chip_service_uuids)
476
477
# Process scan results...
478
time.sleep(10)
479
480
ble_mgr.stop_scan()
481
```
482
483
### Commissioning with Discovery and BLE
484
485
```python
486
from chip.ChipDeviceCtrl import ChipDeviceController
487
from chip.discovery import DiscoveryManager
488
from chip.ble import BleManager
489
490
# Initialize controller and discovery
491
controller = ChipDeviceController(controllerNodeId=12345)
492
discovery = DiscoveryManager()
493
494
# First try network discovery
495
network_devices = discovery.discover_commissionable_nodes(timeout=30)
496
497
if network_devices:
498
# Commission via network
499
device = network_devices[0]
500
success = controller.CommissionOnNetwork(
501
nodeId=1,
502
setupPinCode=20202021,
503
filterType=2, # Long discriminator
504
filter=str(device['longDiscriminator'])
505
)
506
print(f"Network commissioning: {'Success' if success else 'Failed'}")
507
508
else:
509
# Fall back to BLE commissioning
510
print("No network devices found, trying BLE...")
511
512
ble_manager = BleManager()
513
ble_devices = ble_manager.scan(timeout=15)
514
515
if ble_devices:
516
# Connect to first CHIP BLE device
517
first_device = ble_devices[0]
518
if ble_manager.connect(first_device['identifier']):
519
520
# Commission via BLE (using setup payload)
521
setup_payload = "MT:YNJV00KA0648G00" # Example payload
522
success = controller.CommissionWithCode(
523
setupPayload=setup_payload,
524
nodeId=1,
525
discoveryType=1 # BLE only
526
)
527
print(f"BLE commissioning: {'Success' if success else 'Failed'}")
528
529
ble_manager.disconnect()
530
```