From f271b96b5c8d6a4abedc81459a1c5710eb187abb Mon Sep 17 00:00:00 2001 From: Jim Mussared Date: Fri, 11 Sep 2020 13:24:12 +1000 Subject: [PATCH] docs/library/ubluetooth.rst: Add docs for MTU API. --- docs/library/ubluetooth.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/library/ubluetooth.rst b/docs/library/ubluetooth.rst index e4471f8054..03d03583a1 100644 --- a/docs/library/ubluetooth.rst +++ b/docs/library/ubluetooth.rst @@ -72,6 +72,13 @@ Configuration Increasing this allows better handling of bursty incoming data (for example scan results) and the ability to receive larger characteristic values. + - ``'mtu'``: Get/set the MTU that will be used during an MTU exchange. The + resulting MTU will be the minimum of this and the remote device's MTU. + MTU exchange will not happen automatically (unless the remote device initiates + it), and must be manually initiated with + :meth:`gattc_exchange_mtu`. + Use the ``_IRQ_MTU_EXCHANGED`` event to discover the MTU for a given connection. + Event Handling -------------- @@ -161,6 +168,9 @@ Event Handling # A client has acknowledged the indication. # Note: Status will be zero on successful acknowledgment, implementation-specific value otherwise. conn_handle, value_handle, status = data + elif event == _IRQ_MTU_EXCHANGED: + # MTU exchange complete (either initiated by us or the remote device). + conn_handle, mtu = data The event codes are:: @@ -185,6 +195,7 @@ The event codes are:: _IRQ_GATTC_NOTIFY = const(18) _IRQ_GATTC_INDICATE = const(19) _IRQ_GATTS_INDICATE_DONE = const(20) + _IRQ_MTU_EXCHANGED = const(21) In order to save space in the firmware, these constants are not included on the :mod:`ubluetooth` module. Add the ones that you need from the list above to your @@ -459,6 +470,18 @@ device name from the device information service). If a response is received from the remote server the ``_IRQ_GATTC_WRITE_DONE`` event will be raised. +.. method:: BLE.gattc_exchange_mtu(conn_handle, /) + + Initiate MTU exchange with a connected server, using the preferred MTU + set using ``BLE.config(mtu=value)``. + + The ``_IRQ_MTU_EXCHANGED`` event will be raised when MTU exchange + completes. + + **Note:** MTU exchange is typically initiated by the central. When using + the BlueKitchen stack in the central role, it does not support a remote + peripheral initiating the MTU exchange. NimBLE works for both roles. + class UUID ----------