summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJim Mussared <jim.mussared@gmail.com>2020-11-27 00:17:56 +1100
committerDamien George <damien@micropython.org>2020-12-02 14:42:46 +1100
commitb799fe142117f5c503c9c73fbe5f1cb4479d6f7b (patch)
tree51bfe67e8a3df1ad2b31ab442702b5e29a95ca35
parentc4d08aa4e3641a1d05d35051454d4bce8ef14fcf (diff)
docs/library/ubluetooth.rst: Add bonding docs.
Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
-rw-r--r--docs/library/ubluetooth.rst51
1 files changed, 40 insertions, 11 deletions
diff --git a/docs/library/ubluetooth.rst b/docs/library/ubluetooth.rst
index 594d73c87..9ce400e7e 100644
--- a/docs/library/ubluetooth.rst
+++ b/docs/library/ubluetooth.rst
@@ -8,7 +8,7 @@ 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, as well as GATT Server and Client and L2CAP
connection-oriented-channels. A device may operate in multiple roles
-concurrently.
+concurrently. Pairing (and bonding) is supported on some ports.
This API is intended to match the low-level Bluetooth protocol and provide
building-blocks for higher-level abstractions such as specific device types.
@@ -96,7 +96,8 @@ Configuration
_IO_CAPABILITY_NO_INPUT_OUTPUT = const(3)
_IO_CAPABILITY_KEYBOARD_DISPLAY = const(4)
- - ``'le_secure'``: Sets whether "LE Secure" pairing is required. Default is "Legacy Pairing".
+ - ``'le_secure'``: Sets whether "LE Secure" pairing is required. Default is
+ false (i.e. allow "Legacy Pairing").
Event Handling
--------------
@@ -223,6 +224,16 @@ Event Handling
elif event == _IRQ_ENCRYPTION_UPDATE:
# The encryption state has changed (likely as a result of pairing or bonding).
conn_handle, encrypted, authenticated, bonded, key_size = data
+ elif event == _IRQ_GET_SECRET:
+ # Return a stored secret.
+ # If key is None, return the index'th value of this sec_type.
+ # Otherwise return the corresponding value for this sec_type and key.
+ sec_type, index, key = data
+ return value
+ elif event == _IRQ_SET_SECRET:
+ # Save a secret to the store for this sec_type and key.
+ sec_type, key, value = data
+ return True
The event codes are::
@@ -255,6 +266,8 @@ The event codes are::
_IRQ_L2CAP_SEND_READY = const(26)
_IRQ_CONNECTION_UPDATE = const(27)
_IRQ_ENCRYPTION_UPDATE = const(28)
+ _IRQ_GET_SECRET = const(29)
+ _IRQ_SET_SECRET = const(30)
For the ``_IRQ_GATTS_READ_REQUEST`` event, the available return codes are::
@@ -368,15 +381,6 @@ Central & Peripheral Roles
Returns ``False`` if the connection handle wasn't connected, and ``True``
otherwise.
-.. method:: BLE.gap_pair(conn_handle, /)
-
- Initiate pairing with the remote device.
-
- Before calling this, ensure that the ``io``, ``mitm``, ``le_secure``, and
- ``bond`` configuration options are set (via :meth:`config<BLE.config>`).
-
- On successful pairing, the ``_IRQ_ENCRYPTION_UPDATED`` event will be raised.
-
GATT Server
-----------
@@ -664,6 +668,31 @@ L2CAP connection-oriented-channels
more channel credits and will be unable to send any more data.
+Pairing and bonding
+-------------------
+
+ Pairing allows a connection to be encrypted and authenticated via exchange
+ of secrets (with optional MITM protection via passkey authentication).
+
+ Bonding is the process of storing those secrets into non-volatile storage.
+ When bonded, a device is able to resolve a resolvable private address (RPA)
+ from another device based on the stored identity resolving key (IRK).
+ To support bonding, an application must implement the ``_IRQ_GET_SECRET``
+ and ``_IRQ_SET_SECRET`` events.
+
+ **Note:** This is currently only supported when using the NimBLE stack on
+ STM32 and Unix (not ESP32).
+
+.. method:: BLE.gap_pair(conn_handle, /)
+
+ Initiate pairing with the remote device.
+
+ Before calling this, ensure that the ``io``, ``mitm``, ``le_secure``, and
+ ``bond`` configuration options are set (via :meth:`config<BLE.config>`).
+
+ On successful pairing, the ``_IRQ_ENCRYPTION_UPDATE`` event will be raised.
+
+
class UUID
----------