extmod/modbluetooth: Add gap_indicate_service_changed.

pi-anl · pi-anl · commit e537b25849ef · 2025-05-09T10:34:24.000+10:00
This function triggers an indication on the GATT service changed characteristic.
diff --git a/docs/library/bluetooth.rst b/docs/library/bluetooth.rst
@@ -749,6 +749,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
@@ -709,6 +709,21 @@ static mp_obj_t bluetooth_ble_gap_disconnect(mp_obj_t self_in, mp_obj_t conn_han
 static MP_DEFINE_CONST_FUN_OBJ_2(bluetooth_ble_gap_disconnect_obj, bluetooth_ble_gap_disconnect);
 
 #if MICROPY_PY_BLUETOOTH_ENABLE_PAIRING_BONDING
+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);
+
 static mp_obj_t bluetooth_ble_gap_pair(mp_obj_t self_in, mp_obj_t conn_handle_in) {
     (void)self_in;
     uint16_t conn_handle = mp_obj_get_int(conn_handle_in);
@@ -943,6 +958,7 @@ static const mp_rom_map_elem_t bluetooth_ble_locals_dict_table[] = {
     #endif
     { MP_ROM_QSTR(MP_QSTR_gap_disconnect), MP_ROM_PTR(&bluetooth_ble_gap_disconnect_obj) },
     #if MICROPY_PY_BLUETOOTH_ENABLE_PAIRING_BONDING
+    { MP_ROM_QSTR(MP_QSTR_gap_indicate_service_changed), MP_ROM_PTR(&bluetooth_indicate_service_changed_obj) },
     { 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) },
     #endif
diff --git a/extmod/modbluetooth.h b/extmod/modbluetooth.h
@@ -355,6 +355,9 @@ int mp_bluetooth_get_preferred_mtu(void);
 int mp_bluetooth_set_preferred_mtu(uint16_t mtu);
 
 #if MICROPY_PY_BLUETOOTH_ENABLE_PAIRING_BONDING
+// 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);
+
 // Initiate pairing on the specified connection.
 int mp_bluetooth_gap_pair(uint16_t conn_handle);
 
diff --git a/extmod/nimble/modbluetooth_nimble.c b/extmod/nimble/modbluetooth_nimble.c
@@ -1095,6 +1095,16 @@ int mp_bluetooth_set_preferred_mtu(uint16_t mtu) {
 }
 
 #if MICROPY_PY_BLUETOOTH_ENABLE_PAIRING_BONDING
+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);
+    }
+}
+
 int mp_bluetooth_gap_pair(uint16_t conn_handle) {
     DEBUG_printf("mp_bluetooth_gap_pair: conn_handle=%d\n", conn_handle);
     return ble_hs_err_to_errno(ble_gap_security_initiate(conn_handle));
