docs/library: Update ubluetooth for new events and discover by uuid.

1 files changed, 54 insertions, 30 deletions

diff --git a/docs/library/ubluetooth.rst b/docs/library/ubluetooth.rst
index fd2efe87d..ee8fd75ad 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