extmod/modbluetooth: Add gap_indicate_service_changed.

pi-anl · pi-anl · commit 7444b7a047ce · 2021-11-25T10:03:16.000+11:00
This function triggers an indication on the GATT service changed characteristic.
diff --git a/docs/library/bluetooth.rst b/docs/library/bluetooth.rst
@@ -738,6 +738,32 @@ Pairing and bonding
           should show the passkey that was provided in the ``_IRQ_PASSKEY_ACTION`` event
           and then respond with either ``0`` (cancel pairing), or ``1`` (accept pairing).
 
+.. method:: BLE.gap_indicate_service_changed(conn_handle, handle_start, handle_end, /)
+
+    When a client is bonded to a server it will typically cache the results of the discovery 
+    process to speed up future connections. If the services/characteristic handles change on 
+    the server in future a previously-bonded client may not be able to communicate correctly 
+    as it will be using the previously cached handles.
+    This function can be run on the server to send an indication to the client that handles
+    have changed and trigger service discovery on the client.
+
+    If ``conn_handle`` is None, then all connected devices will be indicated. If CCCD bonding 
+    is supported then any un-connected bonded devices will automatically be indicated the next 
+    time they connect.
+
+    The ``handle_start`` and ``handle_end`` arguments can be used to specify the range of 
+    characteristics that have changed, or typically ``handle_start=0x0000, handle_end=0xFFFF``
+    will be used to discover all again.
+
+    Note: with an iOS client it's been seen that if this function is called greater than ~100ms 
+    after a new connection is established the connection can be dropped, or the characteristics
+    covered by the declared range will lock up and be no longer readable, so it's important to 
+    send this command within the first few ms after a connection is made.
+    
+    Alternatively, it appears that if the start and end handles are both set to ``0x0000``, 
+    the lock-up doesn't occur regardless of when the call is made. Android clients appear to 
+    accept the null handles as a re-discover all, though the BLE spec makes no mention of this.
+
 
 class UUID
 ----------
diff --git a/extmod/modbluetooth.c b/extmod/modbluetooth.c
@@ -710,6 +710,21 @@ STATIC mp_obj_t bluetooth_ble_gap_passkey(size_t n_args, const mp_obj_t *args) {
     return bluetooth_handle_errno(mp_bluetooth_gap_passkey(conn_handle, action, passkey));
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(bluetooth_ble_gap_passkey_obj, 4, 4, bluetooth_ble_gap_passkey);
+
+STATIC mp_obj_t bluetooth_indicate_service_changed(size_t n_args, const mp_obj_t *args) {
+    (void)n_args;
+    int16_t handle = -1;
+    if (args[1] != mp_const_none) {
+        handle = mp_obj_get_int(args[1]);
+    }
+
+    uint16_t hdl_start = mp_obj_get_int(args[2]);
+    uint16_t hdl_end = mp_obj_get_int(args[3]);
+
+    mp_bluetooth_indicate_service_changed(handle, hdl_start, hdl_end);
+    return mp_const_none;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(bluetooth_indicate_service_changed_obj, 4, 4, bluetooth_indicate_service_changed);
 #endif // MICROPY_PY_BLUETOOTH_ENABLE_PAIRING_BONDING
 
 // ----------------------------------------------------------------------------
@@ -935,6 +950,7 @@ STATIC const mp_rom_map_elem_t bluetooth_ble_locals_dict_table[] = {
     #if MICROPY_PY_BLUETOOTH_ENABLE_PAIRING_BONDING
     { MP_ROM_QSTR(MP_QSTR_gap_pair), MP_ROM_PTR(&bluetooth_ble_gap_pair_obj) },
     { MP_ROM_QSTR(MP_QSTR_gap_passkey), MP_ROM_PTR(&bluetooth_ble_gap_passkey_obj) },
+    { MP_ROM_QSTR(MP_QSTR_gap_indicate_service_changed), MP_ROM_PTR(&bluetooth_indicate_service_changed_obj) },
     #endif
     // GATT Server
     { MP_ROM_QSTR(MP_QSTR_gatts_register_services), MP_ROM_PTR(&bluetooth_ble_gatts_register_services_obj) },
diff --git a/extmod/modbluetooth.h b/extmod/modbluetooth.h
@@ -360,6 +360,9 @@ int mp_bluetooth_gap_pair(uint16_t conn_handle);
 
 // Respond to a pairing request.
 int mp_bluetooth_gap_passkey(uint16_t conn_handle, uint8_t action, mp_int_t passkey);
+
+// Send an indication on the service changed characteristic, send -1 on conn_handle to indicate to all devices.
+void mp_bluetooth_indicate_service_changed(int16_t conn_handle, uint16_t hdl_start, uint16_t hdl_end);
 #endif // MICROPY_PY_BLUETOOTH_ENABLE_PAIRING_BONDING
 
 #if MICROPY_PY_BLUETOOTH_ENABLE_CENTRAL_MODE
diff --git a/extmod/nimble/modbluetooth_nimble.c b/extmod/nimble/modbluetooth_nimble.c
@@ -1113,6 +1113,16 @@ int mp_bluetooth_gap_passkey(uint16_t conn_handle, uint8_t action, mp_int_t pass
     DEBUG_printf("mp_bluetooth_gap_passkey: injecting IO: conn_handle=%d, action=%d, passkey=" UINT_FMT ", numcmp_accept=%d\n", conn_handle, io.action, (mp_uint_t)io.passkey, io.numcmp_accept);
     return ble_hs_err_to_errno(ble_sm_inject_io(conn_handle, &io));
 }
+
+void mp_bluetooth_indicate_service_changed(int16_t conn_handle, uint16_t hdl_start, uint16_t hdl_end) {
+    if (conn_handle == -1) {
+        DEBUG_printf("mp_bluetooth_indicate_service_changed all\n");
+        return ble_svc_gatt_changed(hdl_start, hdl_end);
+    } else {
+        DEBUG_printf("mp_bluetooth_indicate_service_changed: conn_handle=%d\n", conn_handle);
+        return ble_svc_conn_gatt_changed(conn_handle, hdl_start, hdl_end);
+    }
+}
 #endif // MICROPY_PY_BLUETOOTH_ENABLE_PAIRING_BONDING
 
 #if MICROPY_PY_BLUETOOTH_ENABLE_CENTRAL_MODE
