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.
This commit is contained in:
Jim Mussared
Damien George
parent
5be3bfcb7e
commit
c200759290
@ -6,8 +6,8 @@
|
||||
|
||||
This module provides an interface to a Bluetooth controller on a board.
|
||||
Currently this supports Bluetooth Low Energy (BLE) in Central, Peripheral,
|
||||
Broadcaster, and Observer roles, and a device may operate in multiple
|
||||
roles concurrently.
|
||||
Broadcaster, and Observer roles, as well as GATT Server and Client. A device
|
||||
may operate in multiple roles concurrently.
|
||||
|
||||
This API is intended to match the low-level Bluetooth protocol and provide
|
||||
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
|
||||
handles incoming data for all events, including all characteristics.
|
||||
Increasing this allows better handling of bursty incoming data (for
|
||||
example scan results) and the ability for a central role to receive
|
||||
larger characteristic values.
|
||||
example scan results) and the ability to receive larger characteristic values.
|
||||
|
||||
Event Handling
|
||||
--------------
|
||||
@ -99,10 +98,10 @@ Event Handling
|
||||
# A central has disconnected from this peripheral.
|
||||
conn_handle, addr_type, addr = data
|
||||
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
|
||||
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.
|
||||
# Note: This event is not supported on ESP32.
|
||||
conn_handle, attr_handle = data
|
||||
@ -153,13 +152,13 @@ Event Handling
|
||||
# Note: Status will be zero on success, implementation-specific value otherwise.
|
||||
conn_handle, value_handle, status = data
|
||||
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
|
||||
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
|
||||
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.
|
||||
conn_handle, value_handle, status = data
|
||||
|
||||
@ -249,28 +248,74 @@ Observer Role (Scanner)
|
||||
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
|
||||
descriptors, which themselves have values.
|
||||
|
||||
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
|
||||
to by a remote central device. Additionally, a peripheral can "notify" a
|
||||
characteristic to a connected central via a connection handle.
|
||||
to by a remote client device. Additionally, a server can "notify" a
|
||||
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.
|
||||
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
|
||||
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.
|
||||
``gatts_write(char_handle, bytes(100))``.
|
||||
|
||||
.. 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.
|
||||
|
||||
*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, /)
|
||||
|
||||
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, /)
|
||||
|
||||
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, /)
|
||||
|
||||
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.
|
||||
|
||||
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, /)
|
||||
|
||||
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
|
||||
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
|
||||
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, /)
|
||||
|
||||
Connect to a peripheral.
|
||||
|
||||
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.
|
||||
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
|
||||
information about the central that has connected to it (e.g. to read the
|
||||
device name from the device information service).
|
||||
|
||||
.. 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.
|
||||
|
||||
@ -381,7 +415,7 @@ Central Role (GATT Client)
|
||||
|
||||
.. 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
|
||||
characteristic only.
|
||||
@ -394,14 +428,14 @@ Central Role (GATT Client)
|
||||
|
||||
.. 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
|
||||
will be raised, followed by ``_IRQ_GATTC_DESCRIPTOR_DONE`` on completion.
|
||||
|
||||
.. 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.
|
||||
|
||||
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, /)
|
||||
|
||||
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.
|
||||
|
||||
The argument *mode* specifies the write behaviour, with the currently
|
||||
supported values being:
|
||||
|
||||
* ``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.
|
||||
* ``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
|
||||
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.
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user