djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/library/ubluetooth.rst: Clarify peripheral/central vs server/client

Browse Source 
Previously this documentation assumed peripheral=server and central=client,
but this is not accurate or true to the implementation.
This commit is contained in:
Jim Mussared 2020-09-11 12:26:09 +10:00 committed by Damien George
parent 5be3bfcb7e
commit c200759290
1 changed files with 82 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
docs/library/ubluetooth.rst
View File

@ -6,8 +6,8 @@
This module provides an interface to a Bluetooth controller on a board. This module provides an interface to a Bluetooth controller on a board.
Currently this supports Bluetooth Low Energy (BLE) in Central, Peripheral, Currently this supports Bluetooth Low Energy (BLE) in Central, Peripheral,
Broadcaster, and Observer roles, and a device may operate in multiple Broadcaster, and Observer roles, as well as GATT Server and Client. A device
roles concurrently. may operate in multiple roles concurrently.
This API is intended to match the low-level Bluetooth protocol and provide This API is intended to match the low-level Bluetooth protocol and provide
building-blocks for higher-level abstractions such as specific device types. building-blocks for higher-level abstractions such as specific device types.
@ -70,8 +70,7 @@ Configuration
incoming events. This buffer is global to the entire BLE driver and so incoming events. This buffer is global to the entire BLE driver and so
handles incoming data for all events, including all characteristics. handles incoming data for all events, including all characteristics.
Increasing this allows better handling of bursty incoming data (for Increasing this allows better handling of bursty incoming data (for
example scan results) and the ability for a central role to receive example scan results) and the ability to receive larger characteristic values.
larger characteristic values.
Event Handling Event Handling
-------------- --------------
@ -99,10 +98,10 @@ Event Handling
# A central has disconnected from this peripheral. # A central has disconnected from this peripheral.
conn_handle, addr_type, addr = data conn_handle, addr_type, addr = data
elif event == _IRQ_GATTS_WRITE: elif event == _IRQ_GATTS_WRITE:
# A central has written to this characteristic or descriptor. # A client has written to this characteristic or descriptor.
conn_handle, attr_handle = data conn_handle, attr_handle = data
elif event == _IRQ_GATTS_READ_REQUEST: elif event == _IRQ_GATTS_READ_REQUEST:
# A central has issued a read. Note: this is a hard IRQ. # A client has issued a read. Note: this is a hard IRQ.
# Return None to deny the read. # Return None to deny the read.
# Note: This event is not supported on ESP32. # Note: This event is not supported on ESP32.
conn_handle, attr_handle = data conn_handle, attr_handle = data
@ -153,13 +152,13 @@ Event Handling
# Note: Status will be zero on success, implementation-specific value otherwise. # Note: Status will be zero on success, implementation-specific value otherwise.
conn_handle, value_handle, status = data conn_handle, value_handle, status = data
elif event == _IRQ_GATTC_NOTIFY: elif event == _IRQ_GATTC_NOTIFY:
# A peripheral has sent a notify request. # A server has sent a notify request.
conn_handle, value_handle, notify_data = data conn_handle, value_handle, notify_data = data
elif event == _IRQ_GATTC_INDICATE: elif event == _IRQ_GATTC_INDICATE:
# A peripheral has sent an indicate request. # A server has sent an indicate request.
conn_handle, value_handle, notify_data = data conn_handle, value_handle, notify_data = data
elif event == _IRQ_GATTS_INDICATE_DONE: elif event == _IRQ_GATTS_INDICATE_DONE:
# A central has acknowledged the indication. # A client has acknowledged the indication.
# Note: Status will be zero on successful acknowledgment, implementation-specific value otherwise. # Note: Status will be zero on successful acknowledgment, implementation-specific value otherwise.
conn_handle, value_handle, status = data conn_handle, value_handle, status = data
@ -249,28 +248,74 @@ Observer Role (Scanner)
explicitly stopped), the ``_IRQ_SCAN_DONE`` event will be raised. explicitly stopped), the ``_IRQ_SCAN_DONE`` event will be raised.
Peripheral Role (GATT Server) Central Role
----------------------------- ------------
A BLE peripheral has a set of registered services. Each service may contain 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.
.. method:: BLE.gap_connect(addr_type, addr, scan_duration_ms=2000, /)
Connect to a peripheral.
See :meth:`gap_scan <BLE.gap_scan>` for details about address types.
On success, the ``_IRQ_PERIPHERAL_CONNECT`` event will be raised.
Peripheral Role
---------------
A peripheral device is expected to send connectable advertisements (see
:meth:`gap_advertise<BLE.gap_advertise>`). It will usually be acting as a GATT
server, having first registered services and characteristics using
:meth:`gatts_register_services<BLE.gatts_register_services>`.
When a central connects, the ``_IRQ_CENTRAL_CONNECT`` event will be raised.
Central & Peripheral Roles
--------------------------
.. method:: BLE.gap_disconnect(conn_handle, /)
Disconnect the specified connection handle. This can either be a
central that has connected to this device (if acting as a peripheral)
or a peripheral that was previously connected to by this device (if acting
as a central).
On success, the ``_IRQ_PERIPHERAL_DISCONNECT`` or ``_IRQ_CENTRAL_DISCONNECT``
event will be raised.
Returns ``False`` if the connection handle wasn't connected, and ``True``
otherwise.
GATT Server
-----------
A GATT server has a set of registered services. Each service may contain
characteristics, which each have a value. Characteristics can also contain characteristics, which each have a value. Characteristics can also contain
descriptors, which themselves have values. descriptors, which themselves have values.
These values are stored locally, and are accessed by their "value handle" which These values are stored locally, and are accessed by their "value handle" which
is generated during service registration. They can also be read from or written is generated during service registration. They can also be read from or written
to by a remote central device. Additionally, a peripheral can "notify" a to by a remote client device. Additionally, a server can "notify" a
characteristic to a connected central via a connection handle. characteristic to a connected client via a connection handle.
A device in either central or peripheral roles may function as a GATT server,
however in most cases it will be more common for a peripheral device to act
as the server.
Characteristics and descriptors have a default maximum size of 20 bytes. Characteristics and descriptors have a default maximum size of 20 bytes.
Anything written to them by a central will be truncated to this length. However, Anything written to them by a client will be truncated to this length. However,
any local write will increase the maximum size, so if you want to allow larger any local write will increase the maximum size, so if you want to allow larger
writes from a central to a given characteristic, use writes from a client to a given characteristic, use
:meth:`gatts_write<BLE.gatts_write>` after registration. e.g. :meth:`gatts_write<BLE.gatts_write>` after registration. e.g.
``gatts_write(char_handle, bytes(100))``. ``gatts_write(char_handle, bytes(100))``.
.. method:: BLE.gatts_register_services(services_definition, /) .. method:: BLE.gatts_register_services(services_definition, /)
Configures the peripheral with the specified services, replacing any Configures the server with the specified services, replacing any
existing services. existing services.
*services_definition* is a list of **services**, where each **service** is a *services_definition* is a list of **services**, where each **service** is a
@ -311,17 +356,17 @@ writes from a central to a given characteristic, use
.. method:: BLE.gatts_read(value_handle, /) .. method:: BLE.gatts_read(value_handle, /)
Reads the local value for this handle (which has either been written by Reads the local value for this handle (which has either been written by
:meth:`gatts_write <BLE.gatts_write>` or by a remote central). :meth:`gatts_write <BLE.gatts_write>` or by a remote client).
.. method:: BLE.gatts_write(value_handle, data, /) .. method:: BLE.gatts_write(value_handle, data, /)
Writes the local value for this handle, which can be read by a central. Writes the local value for this handle, which can be read by a client.
.. method:: BLE.gatts_notify(conn_handle, value_handle, data=None, /) .. method:: BLE.gatts_notify(conn_handle, value_handle, data=None, /)
Sends a notification request to a connected central. Sends a notification request to a connected client.
If *data* is not ``None``, then that value is sent to the central as part of If *data* is not ``None``, then that value is sent to the client as part of
the notification. The local value will not be modified. the notification. The local value will not be modified.
Otherwise, if *data* is ``None``, then the current local value (as Otherwise, if *data* is ``None``, then the current local value (as
@ -329,7 +374,7 @@ writes from a central to a given characteristic, use
.. method:: BLE.gatts_indicate(conn_handle, value_handle, /) .. method:: BLE.gatts_indicate(conn_handle, value_handle, /)
Sends an indication request to a connected central. Sends an indication request to a connected client.
**Note:** This does not currently support sending a custom value, it will **Note:** This does not currently support sending a custom value, it will
always send the current local value (as set with :meth:`gatts_write 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
be cleared after reading. This feature is useful when implementing something be cleared after reading. This feature is useful when implementing something
like the Nordic UART Service. like the Nordic UART Service.
GATT Client
-----------
Central Role (GATT Client) A GATT client can discover and read/write characteristics on a remote GATT server.
--------------------------
.. method:: BLE.gap_connect(addr_type, addr, scan_duration_ms=2000, /) It is more common for a central role device to act as the GATT client, however
it's also possible for a peripheral to act as a client in order to discover
Connect to a peripheral. information about the central that has connected to it (e.g. to read the
device name from the device information service).
See :meth:`gatts_write <BLE.gap_scan>` for details about address types.
On success, the ``_IRQ_PERIPHERAL_CONNECT`` event will be raised.
.. method:: BLE.gap_disconnect(conn_handle, /)
Disconnect the specified connection handle.
On success, the ``_IRQ_PERIPHERAL_DISCONNECT`` event will be raised.
Returns ``False`` if the connection handle wasn't connected, and ``True``
otherwise.
.. method:: BLE.gattc_discover_services(conn_handle, uuid=None, /) .. method:: BLE.gattc_discover_services(conn_handle, uuid=None, /)
Query a connected peripheral for its services. Query a connected server for its services.
Optionally specify a service *uuid* to query for that service only. Optionally specify a service *uuid* to query for that service only.
@ -381,7 +415,7 @@ Central Role (GATT Client)
.. method:: BLE.gattc_discover_characteristics(conn_handle, start_handle, end_handle, uuid=None, /) .. method:: BLE.gattc_discover_characteristics(conn_handle, start_handle, end_handle, uuid=None, /)
Query a connected peripheral for characteristics in the specified range. Query a connected server for characteristics in the specified range.
Optionally specify a characteristic *uuid* to query for that Optionally specify a characteristic *uuid* to query for that
characteristic only. characteristic only.
@ -394,14 +428,14 @@ Central Role (GATT Client)
.. method:: BLE.gattc_discover_descriptors(conn_handle, start_handle, end_handle, /) .. method:: BLE.gattc_discover_descriptors(conn_handle, start_handle, end_handle, /)
Query a connected peripheral for descriptors in the specified range. Query a connected server for descriptors in the specified range.
For each descriptor discovered, the ``_IRQ_GATTC_DESCRIPTOR_RESULT`` event For each descriptor discovered, the ``_IRQ_GATTC_DESCRIPTOR_RESULT`` event
will be raised, followed by ``_IRQ_GATTC_DESCRIPTOR_DONE`` on completion. will be raised, followed by ``_IRQ_GATTC_DESCRIPTOR_DONE`` on completion.
.. method:: BLE.gattc_read(conn_handle, value_handle, /) .. method:: BLE.gattc_read(conn_handle, value_handle, /)
Issue a remote read to a connected peripheral for the specified Issue a remote read to a connected server for the specified
characteristic or descriptor handle. characteristic or descriptor handle.
When a value is available, the ``_IRQ_GATTC_READ_RESULT`` event will be When a value is available, the ``_IRQ_GATTC_READ_RESULT`` event will be
@ -409,20 +443,20 @@ Central Role (GATT Client)
.. method:: BLE.gattc_write(conn_handle, value_handle, data, mode=0, /) .. method:: BLE.gattc_write(conn_handle, value_handle, data, mode=0, /)
Issue a remote write to a connected peripheral for the specified Issue a remote write to a connected server for the specified
characteristic or descriptor handle. characteristic or descriptor handle.
The argument *mode* specifies the write behaviour, with the currently The argument *mode* specifies the write behaviour, with the currently
supported values being: supported values being:
* ``mode=0`` (default) is a write-without-response: the write will * ``mode=0`` (default) is a write-without-response: the write will
be sent to the remote peripheral but no confirmation will be be sent to the remote server but no confirmation will be
returned, and no event will be raised. returned, and no event will be raised.
* ``mode=1`` is a write-with-response: the remote peripheral is * ``mode=1`` is a write-with-response: the remote server is
requested to send a response/acknowledgement that it received the requested to send a response/acknowledgement that it received the
data. data.
If a response is received from the remote peripheral the If a response is received from the remote server the
``_IRQ_GATTC_WRITE_DONE`` event will be raised. ``_IRQ_GATTC_WRITE_DONE`` event will be raised.