8000 docs/library/ubluetooth.rst: Clarify peripheral/central vs server/client · tve/micropython@c200759 · GitHub
[go: up one dir, main page]
Skip to content

Commit c200759

Browse files
jimmodpgeorge
jimmo
authored and
dpgeorge
committed
docs/library/ubluetooth.rst: Clarify peripheral/central vs server/client
Previously this documentation assumed peripheral=server and central=client, but this is not accurate or true to the implementation.
1 parent 5be3bfc commit c200759

File tree

1 file changed

+82
-48
lines changed

1 file changed

+82
-48
lines changed

‎docs/library/ubluetooth.rst

Lines changed: 82 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@
66

77
This module provides an interface to a Bluetooth controller on a board.
88
Currently this supports Bluetooth Low Energy (BLE) in Central, Peripheral,
9-
Broadcaster, and Observer roles, and a device may operate in multiple
10-
roles concurrently.
9+
Broadcaster, and Observer roles, as well as GATT Server and Client. A device
10+
may operate in multiple roles concurrently.
1111

1212
This API is intended to match the low-level Bluetooth protocol and provide
1313
building-blocks for higher-level abstractions such as specific device types.
@@ -70,8 +70,7 @@ Configuration
7070
incoming events. This buffer is global to the entire BLE driver and so
7171
handles incoming data for all events, including all characteristics.
7272
Increasing this allows better handling of bursty incoming data (for
73-
example scan results) and the ability for a central role to receive
74-
larger characteristic values.
73+
example scan results) and the ability to receive larger characteristic values.
7574

7675
Event Handling
7776
--------------
@@ -99,10 +98,10 @@ Event Handling
9998
# A central has disconnected from this peripheral.
10099
conn_handle, addr_type, addr = data
101100
elif event == _IRQ_GATTS_WRITE:
102-
# A central has written to this characteristic or descriptor.
101+
# A client has written to this characteristic or descriptor.
103102
conn_handle, attr_handle = data
104103
elif event == _IRQ_GATTS_READ_REQUEST:
105-
# A central has issued a read. Note: this is a hard IRQ.
104+
# A client has issued a read. Note: this is a hard IRQ.
106105
# Return None to deny the read.
107106
# Note: This event is not supported on ESP32.
108107
conn_handle, attr_handle = data
@@ -153,13 +152,13 @@ Event Handling
153152
# Note: Status will be zero on success, implementation-specific value otherwise.
154153
conn_handle, value_handle, status = data
155154
elif event == _IRQ_GATTC_NOTIFY:
156-
# A peripheral has sent a notify request.
155+
# A server has sent a notify request.
157156
conn_handle, value_handle, notify_data = data
158157
elif event == _IRQ_GATTC_INDICATE:
159-
# A peripheral has sent an indicate request.
158+
# A server has sent an indicate request.
160159
conn_handle, value_handle, notify_data = data
161160
elif event == _IRQ_GATTS_INDICATE_DONE:
162-
# A central has acknowledged the indication.
161+
# A client has acknowledged the indication.
163162
# Note: Status will be zero on successful acknowledgment, implementation-specific value otherwise.
164163
conn_handle, value_handle, status = data
165164

@@ -249,28 +248,74 @@ Observer Role (Scanner)
249248
explicitly stopped), the ``_IRQ_SCAN_DONE`` event will be raised.
250249

251250

252-
Peripheral Role (GATT Server)
253-
-----------------------------
251+
Central Role
252+
------------
253+
254+
A central device can connect to peripherals that it has discovered using the observer role (see :meth:`gap_scan<BLE.gap_scan>`) or with a known address.
255+
256+
.. method:: BLE.gap_connect(addr_type, addr, scan_duration_ms=2000, /)
257+
258+
Connect to a peripheral.
259+
260+
See :meth:`gap_scan <BLE.gap_scan>` for details about address types.
261+
262+
On success, the ``_IRQ_PERIPHERAL_CONNECT`` event will be raised.
263+
264+
265+
Peripheral Role
266+
---------------
267+
268+
A peripheral device is expected to send connectable advertisements (see
269+
:meth:`gap_advertise<BLE.gap_advertise>`). It will usually be acting as a GATT
270+
server, having first registered services and characteristics using
271+
:meth:`gatts_register_services<BLE.gatts_register_services>`.
272+
273+
When a central connects, the ``_IRQ_CENTRAL_CONNECT`` event will be raised.
274+
275+
276+
Central & Peripheral Roles
277+
--------------------------
278+
279+
.. method:: BLE.gap_disconnect(conn_handle, /)
280+
281+
Disconnect the specified connection handle. This can either be a
282+
central that has connected to this device (if acting as a peripheral)
283+
or a peripheral that was previously connected to by this device (if acting
284+
as a central).
285+
286+
On success, the ``_IRQ_PERIPHERAL_DISCONNECT`` or ``_IRQ_CENTRAL_DISCONNECT``
287+
event will be raised.
288+
289+
Returns ``False`` if the connection handle wasn't connected, and ``True``
290+
otherwise.
291+
254292

255-
A BLE peripheral has a set of registered services. Each service may contain
293+
GATT Server
294+
-----------
295+
296+
A GATT server has a set of registered services. Each service may contain
256297
characteristics, which each have a value. Characteristics can also contain
257298
descriptors, which themselves have values.
258299

259300
These values are stored locally, and are accessed by their "value handle" which
260301
is generated during service registration. They can also be read from or written
261-
to by a remote central device. Additionally, a peripheral can "notify" a
262-
characteristic to a connected central via a connection handle.
302+
to by a remote client device. Additionally, a server can "notify" a
303+
characteristic to a connected client via a connection handle.
304+
305+
A device in either central or peripheral roles may function as a GATT server,
306+
however in most cases it will be more common for a peripheral device to act
307+
as the server.
263308

264309
Characteristics and descriptors have a default maximum size of 20 bytes.
265-
Anything written to them by a central will be truncated to this length. However,
310+
Anything written to them by a client will be truncated to this length. However,
266311
any local write will increase the maximum size, so if you want to allow larger
267-
writes from a central to a given characteristic, use
312+
writes from a client to a given characteristic, use
268313
:meth:`gatts_write<BLE.gatts_write>` after registration. e.g.
269314
``gatts_write(char_handle, bytes(100))``.
270315

271316
.. method:: BLE.gatts_register_services(services_definition, /)
272317

273-
Configures the peripheral with the specified services, replacing any
318+
Configures the server with the specified services, replacing any
274319
existing services.
275320

276321
*services_definition* is a list of **services**, where each **service** is a
@@ -311,25 +356,25 @@ writes from a central to a given characteristic, use
311356
.. method:: BLE.gatts_read(value_handle, /)
312357

313358
Reads the local value for this handle (which has either been written by
314-
:meth:`gatts_write <BLE.gatts_write>` or by a remote central).
359+
:meth:`gatts_write <BLE.gatts_write>` or by a remote client).
315360

316361
.. method:: BLE.gatts_write(value_handle, data, /)
317362

318-
Writes the local value for this handle, which can be read by a central.
363+
Writes the local value for this handle, which can be read by a client.
319364

320365
.. method:: BLE.gatts_notify(conn_handle, value_handle, data=None, /)
321366

322-
Sends a notification request to a connected central.
367+
Sends a notification request to a connected client.
323368

324-
If *data* is not ``None``, then that value is sent to the central as part of
369+
If *data* is not ``None``, then that value is sent to the client as part of
325370
the notification. The local value will not be modified.
326371

327372
Otherwise, if *data* is ``None``, then the current local value (as
328373
set with :meth:`gatts_write <BLE.gatts_write>`) will be sent.
329374

330375
.. method:: BLE.gatts_indicate(conn_handle, value_handle, /)
331376

332-
Sends an indication request to a connected central.
377+
Sends an indication request to a connected client.
333378

334379
**Note:** This does not currently support sending a custom value, it will
335380
always send the current local value (as set with :meth:`gatts_write
@@ -349,30 +394,19 @@ writes from a central to a given characteristic, use
349394
be cleared after reading. This feature is useful when implementing something
350395
like the Nordic UART Service.
351396

397+
GATT Client
398+
-----------
352399

353-
Central Role (GATT Client)
354-
--------------------------
355-
356-
.. method:: BLE.gap_connect(addr_type, addr, scan_duration_ms=2000, /)
357-
358-
Connect to a peripheral.
359-
360-
See :meth:`gatts_write <BLE.gap_scan>` for details about address types.
361-
362-
On success, the ``_IRQ_PERIPHERAL_CONNECT`` event will be raised.
363-
364-
.. method:: BLE.gap_disconnect(conn_handle, /)
365-
366-
Disconnect the specified connection handle.
367-
368-
On success, the ``_IRQ_PERIPHERAL_DISCONNECT`` event will be raised.
400+
A GATT client can discover and read/write characteristics on a remote GATT server.
369401

370-
Returns ``False`` if the connection handle wasn't connected, and ``True``
371-
otherwise.
402+
It is more common for a central role device to act as the GATT client, however
403+
it's also possible for a peripheral to act as a client in order to discover
404+
information about the central that has connected to it (e.g. to read the
405+
device name from the device information service).
372406

373407
.. method:: BLE.gattc_discover_services(conn_handle, uuid=None, /)
374408

375-
Query a connected peripheral for its services.
409+
Query a connected server for its services.
376410

377411
Optionally specify a service *uuid* to query for that service only.
378412

@@ -381,7 +415,7 @@ Central Role (GATT Client)
381415

382416
.. method:: BLE.gattc_discover_characteristics(conn_handle, start_handle, end_handle, uuid=None, /)
383417

384-
Query a connected peripheral for characteristics in the specified range.
418+
Query a connected server for characteristics in the specified range.
385419

386420
Optionally specify a characteristic *uuid* to query for that
387421
characteristic only.
@@ -394,35 +428,35 @@ Central Role (GATT Client)
394428

395429
.. method:: BLE.gattc_discover_descriptors(conn_handle, start_handle, end_handle, /)
396430

397-
Query a connected peripheral for descriptors in the specified range.
431+
Query a connected server for descriptors in the specified range.
398432

399433
For each descriptor discovered, the ``_IRQ_GATTC_DESCRIPTOR_RESULT`` event
400434
will be raised, followed by ``_IRQ_GATTC_DESCRIPTOR_DONE`` on completion.
401435

402436
.. method:: BLE.gattc_read(conn_handle, value_handle, /)
403437

404-
Issue a remote read to a connected peripheral for the specified
438+
Issue a remote read to a connected server for the specified
405439
characteristic or descriptor handle.
406440

407441
When a value is available, the ``_IRQ_GATTC_READ_RESULT`` event will be
408442
raised. Additionally, the ``_IRQ_GATTC_READ_DONE`` will be raised.
409443

410444
.. method:: BLE.gattc_write(conn_handle, value_handle, data, mode=0, /)
411445

412-
Issue a remote write to a connected peripheral for the specified
446+
Issue a remote write to a connected server for the specified
413447
characteristic or descriptor handle.
414448

415449
The argument *mode* specifies the write behaviour, with the currently
416450
supported values being:
417451

418452
* ``mode=0`` (default) is a write-without-response: the write will
419-
be sent to the remote peripheral but no confirmation will be
453+
be sent to the remote server but no confirmation will be
420454
returned, and no event will be raised.
421-
* ``mode=1`` is a write-with-response: the remote peripheral is
455+
* ``mode=1`` is a write-with-response: the remote server is
422456
requested to send a response/acknowledgement that it received the
423457
data.
424458

425-
If a response is received from the remote peripheral the
459+
If a response is received from the remote server the
426460
``_IRQ_GATTC_WRITE_DONE`` event will be raised.
427461

428462

0 commit comments

Comments
 (0)
0