1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
=================
BleakClient class
=================
.. currentmodule:: bleak
.. autoclass:: bleak.BleakClient
----------------------------
Connecting and disconnecting
----------------------------
Before doing anything else with a :class:`BleakClient` object, it must be connected.
:class:`bleak.BleakClient` is a an async context manager, so the recommended
way of connecting is to use it as such::
import asyncio
from bleak import BleakClient
async def main():
async with BleakClient("XX:XX:XX:XX:XX:XX") as client:
# Read a characteristic, etc.
...
# Device will disconnect when block exits.
...
# Using asyncio.run() is important to ensure that device disconnects on
# KeyboardInterrupt or other unhandled exception.
asyncio.run(main())
It is also possible to connect and disconnect without a context manager, however
this can leave the device still connected when the program exits:
.. automethod:: bleak.BleakClient.connect
.. automethod:: bleak.BleakClient.disconnect
The current connection status can be retrieved with:
.. autoproperty:: bleak.BleakClient.is_connected
A callback can be provided to the :class:`BleakClient` constructor via the
``disconnect_callback`` argument to be notified of disconnection events.
------------------
Device information
------------------
.. autoproperty:: bleak.BleakClient.name
.. autoproperty:: bleak.BleakClient.address
.. autoproperty:: bleak.BleakClient.mtu_size
.. autoproperty:: bleak.BleakClient.backend_id
----------------------
GATT Client Operations
----------------------
All Bluetooth Low Energy devices use a common Generic Attribute Profile (GATT)
for interacting with the device after it is connected. Some GATT operations
like discovering the services/characteristic/descriptors and negotiating the
MTU are handled automatically by Bleak and/or the OS Bluetooth stack.
The primary operations for the Bleak client are reading, writing and subscribing
to characteristics.
Services
========
The available services on a device are automatically enumerated when connecting
to a device. Services describe the devices capabilities.
.. autoproperty:: bleak.BleakClient.services
GATT characteristics
====================
Most I/O with a device is done via the characteristics.
.. automethod:: bleak.BleakClient.read_gatt_char
.. automethod:: bleak.BleakClient.write_gatt_char
.. automethod:: bleak.BleakClient.start_notify
.. automethod:: bleak.BleakClient.stop_notify
GATT descriptors
================
Descriptors can provide additional information about a characteristic.
.. automethod:: bleak.BleakClient.read_gatt_descriptor
.. automethod:: bleak.BleakClient.write_gatt_descriptor
---------------
Pairing/bonding
---------------
On some devices, some characteristics may require authentication in order to
read or write the characteristic. In this case pairing/bonding the device is
required.
.. tip:: If you need to pair the device *before* connecting, pass ``pair=True``
to the :class:`BleakClient` constructor. Then pairing will happen during
the connection process and you do not need to call the :meth:`pair <BleakClient.pair>`
method explicitly.
.. automethod:: bleak.BleakClient.pair
.. automethod:: bleak.BleakClient.unpair
|
