From 9708fe8788eebb87bf3b0d6232dbed2012cf7358 Mon Sep 17 00:00:00 2001 From: Jim Mussared Date: Wed, 13 May 2020 16:49:57 +1000 Subject: [PATCH] docs/library: Update ubluetooth for new events and discover by uuid. --- docs/library/ubluetooth.rst | 84 ++++++++++++++++++++++++------------- 1 file changed, 54 insertions(+), 30 deletions(-) diff --git a/docs/library/ubluetooth.rst b/docs/library/ubluetooth.rst index fd2efe87d9..ee8fd75ade 100644 --- a/docs/library/ubluetooth.rst +++ b/docs/library/ubluetooth.rst @@ -65,15 +65,12 @@ Configuration Event Handling -------------- -.. method:: BLE.irq(handler, trigger=0xffff) +.. method:: BLE.irq(handler) Registers a callback for events from the BLE stack. The *handler* takes two arguments, ``event`` (which will be one of the codes below) and ``data`` (which is an event-specific tuple of values). - The optional *trigger* parameter allows you to set a mask of events that - your program is interested in. The default is all events. - Note: the ``addr``, ``adv_data``, ``char_data``, ``notify_data``, and ``uuid`` entries in the tuples are references to data managed by the :mod:`ubluetooth` module (i.e. the same @@ -101,7 +98,7 @@ Event Handling elif event == _IRQ_SCAN_RESULT: # A single scan result. addr_type, addr, adv_type, rssi, adv_data = data - elif event == _IRQ_SCAN_COMPLETE: + elif event == _IRQ_SCAN_DONE: # Scan duration finished or manually stopped. pass elif event == _IRQ_PERIPHERAL_CONNECT: @@ -113,17 +110,31 @@ Event Handling elif event == _IRQ_GATTC_SERVICE_RESULT: # Called for each service found by gattc_discover_services(). conn_handle, start_handle, end_handle, uuid = data + elif event == _IRQ_GATTC_SERVICE_DONE: + # Called once service discovery is complete. + conn_handle, status = data elif event == _IRQ_GATTC_CHARACTERISTIC_RESULT: # Called for each characteristic found by gattc_discover_services(). conn_handle, def_handle, value_handle, properties, uuid = data + elif event == _IRQ_GATTC_CHARACTERISTIC_DONE: + # Called once service discovery is complete. + conn_handle, status = data elif event == _IRQ_GATTC_DESCRIPTOR_RESULT: # Called for each descriptor found by gattc_discover_descriptors(). conn_handle, dsc_handle, uuid = data + elif event == _IRQ_GATTC_DESCRIPTOR_DONE: + # Called once service discovery is complete. + conn_handle, status = data elif event == _IRQ_GATTC_READ_RESULT: # A gattc_read() has completed. conn_handle, value_handle, char_data = data - elif event == _IRQ_GATTC_WRITE_STATUS: + elif event == _IRQ_GATTC_READ_DONE: + # A gattc_read() has completed. + # Note: The value_handle will be zero on btstack (but present on NimBLE). + conn_handle, value_handle, status = data + elif event == _IRQ_GATTC_WRITE_DONE: # A gattc_write() has completed. + # Note: The value_handle will be zero on btstack (but present on NimBLE). conn_handle, value_handle, status = data elif event == _IRQ_GATTC_NOTIFY: # A peripheral has sent a notify request. @@ -135,21 +146,25 @@ Event Handling The event codes are:: from micropython import const - _IRQ_CENTRAL_CONNECT = const(1 << 0) - _IRQ_CENTRAL_DISCONNECT = const(1 << 1) - _IRQ_GATTS_WRITE = const(1 << 2) - _IRQ_GATTS_READ_REQUEST = const(1 << 3) - _IRQ_SCAN_RESULT = const(1 << 4) - _IRQ_SCAN_COMPLETE = const(1 << 5) - _IRQ_PERIPHERAL_CONNECT = const(1 << 6) - _IRQ_PERIPHERAL_DISCONNECT = const(1 << 7) - _IRQ_GATTC_SERVICE_RESULT = const(1 << 8) - _IRQ_GATTC_CHARACTERISTIC_RESULT = const(1 << 9) - _IRQ_GATTC_DESCRIPTOR_RESULT = const(1 << 10) - _IRQ_GATTC_READ_RESULT = const(1 << 11) - _IRQ_GATTC_WRITE_STATUS = const(1 << 12) - _IRQ_GATTC_NOTIFY = const(1 << 13) - _IRQ_GATTC_INDICATE = const(1 << 14) + _IRQ_CENTRAL_CONNECT = const(1) + _IRQ_CENTRAL_DISCONNECT = const(2) + _IRQ_GATTS_WRITE = const(3) + _IRQ_GATTS_READ_REQUEST = const(4) + _IRQ_SCAN_RESULT = const(5) + _IRQ_SCAN_DONE = const(6) + _IRQ_PERIPHERAL_CONNECT = const(7) + _IRQ_PERIPHERAL_DISCONNECT = const(8) + _IRQ_GATTC_SERVICE_RESULT = const(9) + _IRQ_GATTC_SERVICE_DONE = const(10) + _IRQ_GATTC_CHARACTERISTIC_RESULT = const(11) + _IRQ_GATTC_CHARACTERISTIC_DONE = const(12) + _IRQ_GATTC_DESCRIPTOR_RESULT = const(13) + _IRQ_GATTC_DESCRIPTOR_DONE = const(14) + _IRQ_GATTC_READ_RESULT = const(15) + _IRQ_GATTC_READ_DONE = const(16) + _IRQ_GATTC_WRITE_DONE = const(17) + _IRQ_GATTC_NOTIFY = const(18) + _IRQ_GATTC_INDICATE = const(19) 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 @@ -203,7 +218,7 @@ Observer Role (Scanner) * 0x04 - SCAN_RSP - scan response When scanning is stopped (either due to the duration finishing or when - explicitly stopped), the ``_IRQ_SCAN_COMPLETE`` event will be raised. + explicitly stopped), the ``_IRQ_SCAN_DONE`` event will be raised. Peripheral Role (GATT Server) @@ -313,33 +328,42 @@ Central Role (GATT Client) Returns ``False`` if the connection handle wasn't connected, and ``True`` otherwise. -.. method:: BLE.gattc_discover_services(conn_handle) +.. method:: BLE.gattc_discover_services(conn_handle, [uuid]) Query a connected peripheral for its services. - For each service discovered, the ``_IRQ_GATTC_SERVICE_RESULT`` event will be - raised. + Optionally specify a service *uuid* to query for that service only. -.. method:: BLE.gattc_discover_characteristics(conn_handle, start_handle, end_handle) + For each service discovered, the ``_IRQ_GATTC_SERVICE_RESULT`` event will + be raised, followed by ``_IRQ_GATTC_SERVICE_DONE`` on completion. + +.. method:: BLE.gattc_discover_characteristics(conn_handle, start_handle, end_handle, [uuid]) Query a connected peripheral for characteristics in the specified range. + Optionally specify a characteristic *uuid* to query for that + characteristic only. + + You can use ``start_handle=1``, ``end_handle=0xffff`` to search for a + characteristic in any service. + For each characteristic discovered, the ``_IRQ_GATTC_CHARACTERISTIC_RESULT`` - event will be raised. + event will be raised, followed by ``_IRQ_GATTC_CHARACTERISTIC_DONE`` on completion. .. method:: BLE.gattc_discover_descriptors(conn_handle, start_handle, end_handle) Query a connected peripheral for descriptors in the specified range. For each descriptor discovered, the ``_IRQ_GATTC_DESCRIPTOR_RESULT`` event - will be raised. + 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 characteristic or descriptor handle. - On success, the ``_IRQ_GATTC_READ_RESULT`` event will be raised. + When a value is available, the ``_IRQ_GATTC_READ_RESULT`` event will be + raised. Additionally, the ``_IRQ_GATTC_READ_DONE`` will be raised. .. method:: BLE.gattc_write(conn_handle, value_handle, data, mode=0, /) @@ -357,7 +381,7 @@ Central Role (GATT Client) data. If a response is received from the remote peripheral the - ``_IRQ_GATTC_WRITE_STATUS`` event will be raised. + ``_IRQ_GATTC_WRITE_DONE`` event will be raised. class UUID