Add asyncronous client connect and MTU exchange.

h2zero · h2zero · commit 63f05ba12c97 · 2024-11-03T19:14:22.000-07:00
* Adds parameters `asyncConnect` and `exchangeMTU` to `NimBLEClient::connect`, default values work as the original connect method.
* * `asyncConnect`; if true, will send the connect command and return immediately with a true value for successfully sending the command, else false.
* * `exchangeMTU`; if true will send the exchange MTU command upon connection, otherwise not and the application can choose to do this later via the `exchangeMTU` method.
* Adds `onMTUChange` callback to `NimBLEClientCallbacks`
diff --git a/src/NimBLEClient.cpp b/src/NimBLEClient.cpp
@@ -65,6 +65,8 @@ NimBLEClient::NimBLEClient(const NimBLEAddress& peerAddress)
       m_terminateFailCount{0},
       m_deleteCallbacks{false},
       m_connEstablished{false},
+      m_asyncConnect{false},
+      m_exchangeMTU{true},
 # if CONFIG_BT_NIMBLE_EXT_ADV
       m_phyMask{BLE_GAP_LE_PHY_1M_MASK | BLE_GAP_LE_PHY_2M_MASK | BLE_GAP_LE_PHY_CODED_MASK},
 # endif
@@ -123,37 +125,54 @@ size_t NimBLEClient::deleteService(const NimBLEUUID& uuid) {
 } // deleteServices
 
 /**
- * @brief Connect to the BLE Server.
+ * @brief Connect to the BLE Server using the address of the last connected device, or the address\n
+ * passed to the constructor.
  * @param [in] deleteAttributes If true this will delete any attribute objects this client may already\n
- * have created and clears the vectors after successful connection.
- * @return True on success.
+ * have created when last connected.
+ * @param [in] asyncConnect If true, the connection will be made asynchronously and this function will return immediately.\n
+ * If false, this function will block until the connection is established or the connection attempt times out.
+ * @param [in] exchangeMTU If true, the client will attempt to exchange MTU with the server after connection.\n
+ * If false, the client will use the default MTU size and the application will need to call exchangeMTU() later.
+ * @return true on success.
  */
-bool NimBLEClient::connect(bool deleteAttributes) {
-    return connect(m_peerAddress, deleteAttributes);
+bool NimBLEClient::connect(bool deleteAttributes, bool asyncConnect, bool exchangeMTU) {
+    return connect(m_peerAddress, deleteAttributes, asyncConnect, exchangeMTU);
 }
 
 /**
  * @brief Connect to an advertising device.
  * @param [in] device The device to connect to.
  * @param [in] deleteAttributes If true this will delete any attribute objects this client may already\n
- * have created and clears the vectors after successful connection.
- * @return True on success.
+ * have created when last connected.
+ * @param [in] asyncConnect If true, the connection will be made asynchronously and this function will return immediately.\n
+ * If false, this function will block until the connection is established or the connection attempt times out.
+ * @param [in] exchangeMTU If true, the client will attempt to exchange MTU with the server after connection.\n
+ * If false, the client will use the default MTU size and the application will need to call exchangeMTU() later.
+ * @return true on success.
  */
-bool NimBLEClient::connect(NimBLEAdvertisedDevice* device, bool deleteAttributes) {
+bool NimBLEClient::connect(NimBLEAdvertisedDevice* device, bool deleteAttributes, bool asyncConnect, bool exchangeMTU) {
     NimBLEAddress address(device->getAddress());
-    return connect(address, deleteAttributes);
+    return connect(address, deleteAttributes, asyncConnect, exchangeMTU);
 }
 
 /**
  * @brief Connect to a BLE Server by address.
  * @param [in] address The address of the server.
  * @param [in] deleteAttributes If true this will delete any attribute objects this client may already\n
- * have created and clears the vectors after successful connection.
- * @return True on success.
+ * have created when last connected.
+ * @param [in] asyncConnect If true, the connection will be made asynchronously and this function will return immediately.\n
+ * If false, this function will block until the connection is established or the connection attempt times out.
+ * @param [in] exchangeMTU If true, the client will attempt to exchange MTU with the server after connection.\n
+ * If false, the client will use the default MTU size and the application will need to call exchangeMTU() later.
+ * @return true on success.
  */
-bool NimBLEClient::connect(const NimBLEAddress& address, bool deleteAttributes) {
+bool NimBLEClient::connect(const NimBLEAddress& address, bool deleteAttributes, bool asyncConnect, bool exchangeMTU) {
     NIMBLE_LOGD(LOG_TAG, ">> connect(%s)", address.toString().c_str());
 
+    if (deleteAttributes) {
+        deleteServices();
+    }
+
     if (!NimBLEDevice::m_synced) {
         NIMBLE_LOGE(LOG_TAG, "Host reset, wait for sync.");
         return false;
@@ -177,10 +196,14 @@ bool NimBLEClient::connect(const NimBLEAddress& address, bool deleteAttributes)
         m_peerAddress = address;
     }
 
+    int rc                = 0;
+    m_asyncConnect        = asyncConnect;
+    m_exchangeMTU         = exchangeMTU;
     TaskHandle_t cur_task = xTaskGetCurrentTaskHandle();
     BleTaskData  taskData = {this, cur_task, 0, nullptr};
-    m_pTaskData           = &taskData;
-    int rc                = 0;
+    if (!asyncConnect) {
+        m_pTaskData = &taskData;
+    }
 
     do {
 # if CONFIG_BT_NIMBLE_EXT_ADV
@@ -236,13 +259,16 @@ bool NimBLEClient::connect(const NimBLEAddress& address, bool deleteAttributes)
 
     } while (rc == BLE_HS_EBUSY);
 
-    m_lastErr = rc;
-
     if (rc != 0) {
+        m_lastErr   = rc;
         m_pTaskData = nullptr;
         return false;
     }
 
+    if (m_asyncConnect) {
+        return true;
+    }
+
 # ifdef ulTaskNotifyValueClear
     // Clear the task notification value to ensure we block
     ulTaskNotifyValueClear(cur_task, ULONG_MAX);
@@ -275,10 +301,6 @@ bool NimBLEClient::connect(const NimBLEAddress& address, bool deleteAttributes)
         NIMBLE_LOGI(LOG_TAG, "Connection established");
     }
 
-    if (deleteAttributes) {
-        deleteServices();
-    }
-
     m_connEstablished = true;
     m_pClientCallbacks->onConnect(this);
 
@@ -852,6 +874,41 @@ uint16_t NimBLEClient::getMTU() const {
     return ble_att_mtu(m_connHandle);
 } // getMTU
 
+/**
+ * @brief Callback for the MTU exchange API function.
+ * @details When the MTU exchange is complete the API will call this and report the new MTU.
+ */
+int NimBLEClient::exchangeMTUCb(uint16_t conn_handle, const ble_gatt_error* error, uint16_t mtu, void* arg) {
+    NIMBLE_LOGD(LOG_TAG, "exchangeMTUCb: status=%d, mtu=%d", error->status, mtu);
+
+    NimBLEClient* pClient = (NimBLEClient*)arg;
+    if (pClient->getConnHandle() != conn_handle) {
+        return 0;
+    }
+
+    if (error->status != 0) {
+        NIMBLE_LOGE(LOG_TAG, "exchangeMTUCb() rc=%d %s", error->status, NimBLEUtils::returnCodeToString(error->status));
+        pClient->m_lastErr = error->status;
+    }
+
+    return 0;
+}
+
+/**
+ * @brief Begin the MTU exchange process with the server.
+ * @returns true if the request was sent successfully.
+ */
+bool NimBLEClient::exchangeMTU() {
+    int rc = ble_gattc_exchange_mtu(m_connHandle, NimBLEClient::exchangeMTUCb, this);
+    if (rc != 0) {
+        NIMBLE_LOGE(LOG_TAG, "MTU exchange error; rc=%d %s", rc, NimBLEUtils::returnCodeToString(rc));
+        m_lastErr = rc;
+        return false;
+    }
+
+    return true;
+} // exchangeMTU
+
 /**
  * @brief Handle a received GAP event.
  * @param [in] event The event structure sent by the NimBLE stack.
@@ -906,7 +963,7 @@ int NimBLEClient::handleGapEvent(struct ble_gap_event* event, void* arg) {
 
         case BLE_GAP_EVENT_CONNECT: {
             // If we aren't waiting for this connection response we should drop the connection immediately.
-            if (pClient->isConnected() || pClient->m_pTaskData == nullptr) {
+            if (pClient->isConnected() || (!pClient->m_asyncConnect && pClient->m_pTaskData == nullptr)) {
                 ble_gap_terminate(event->connect.conn_handle, BLE_ERR_REM_USER_CONN_TERM);
                 return 0;
             }
@@ -916,19 +973,28 @@ int NimBLEClient::handleGapEvent(struct ble_gap_event* event, void* arg) {
                 NIMBLE_LOGI(LOG_TAG, "Connected event");
 
                 pClient->m_connHandle = event->connect.conn_handle;
-
-                rc = ble_gattc_exchange_mtu(pClient->m_connHandle, NULL, NULL);
-                if (rc != 0) {
-                    NIMBLE_LOGE(LOG_TAG, "MTU exchange error; rc=%d %s", rc, NimBLEUtils::returnCodeToString(rc));
-                    break;
+                if (pClient->m_exchangeMTU) {
+                    if (!pClient->exchangeMTU() && !pClient->m_asyncConnect) {
+                        rc = pClient->m_lastErr;
+                        break;
+                    }
                 }
 
                 // In the case of a multi-connecting device we ignore this device when
                 // scanning since we are already connected to it
                 NimBLEDevice::addIgnored(pClient->m_peerAddress);
             } else {
                 pClient->m_connHandle = BLE_HS_CONN_HANDLE_NONE;
-                break;
+                if (!pClient->m_asyncConnect) {
+                    break;
+                }
+            }
+
+            if (pClient->m_asyncConnect) {
+                pClient->m_connEstablished = rc == 0;
+                pClient->m_pClientCallbacks->onConnect(pClient);
+            } else if (!pClient->m_exchangeMTU) {
+                break; // not wating for MTU exchange so release the task now.
             }
 
             return 0;
@@ -1070,7 +1136,9 @@ int NimBLEClient::handleGapEvent(struct ble_gap_event* event, void* arg) {
             if (pClient->m_connHandle != event->mtu.conn_handle) {
                 return 0;
             }
-            NIMBLE_LOGI(LOG_TAG, "mtu update event; conn_handle=%d mtu=%d", event->mtu.conn_handle, event->mtu.value);
+
+            NIMBLE_LOGI(LOG_TAG, "mtu update: mtu=%d", event->mtu.value);
+            pClient->m_pClientCallbacks->onMTUChange(pClient, event->mtu.value);
             rc = 0;
             break;
         } // BLE_GAP_EVENT_MTU
@@ -1202,4 +1270,8 @@ void NimBLEClientCallbacks::onConfirmPasskey(NimBLEConnInfo& connInfo, uint32_t
     NimBLEDevice::injectConfirmPasskey(connInfo, true);
 }
 
+void NimBLEClientCallbacks::onMTUChange(NimBLEClient* pClient, uint16_t mtu) {
+    NIMBLE_LOGD(CB_TAG, "onMTUChange: default");
+}
+
 #endif /* CONFIG_BT_ENABLED && CONFIG_BT_NIMBLE_ROLE_CENTRAL */
diff --git a/src/NimBLEClient.h b/src/NimBLEClient.h
@@ -44,9 +44,12 @@ struct BleTaskData;
  */
 class NimBLEClient {
   public:
-    bool           connect(NimBLEAdvertisedDevice* device, bool deleteAttributes = true);
-    bool           connect(const NimBLEAddress& address, bool deleteAttributes = true);
-    bool           connect(bool deleteAttributes = true);
+    bool connect(NimBLEAdvertisedDevice* device,
+                 bool                    deleteAttributes = true,
+                 bool                    asyncConnect     = false,
+                 bool                    exchangeMTU      = true);
+    bool connect(const NimBLEAddress& address, bool deleteAttributes = true, bool asyncConnect = false, bool exchangeMTU = true);
+    bool           connect(bool deleteAttributes = true, bool asyncConnect = false, bool exchangeMTU = true);
     bool           disconnect(uint8_t reason = BLE_ERR_REM_USER_CONN_TERM);
     NimBLEAddress  getPeerAddress() const;
     bool           setPeerAddress(const NimBLEAddress& address);
@@ -59,6 +62,7 @@ class NimBLEClient {
     bool           setConnection(const NimBLEConnInfo& connInfo);
     bool           setConnection(uint16_t connHandle);
     uint16_t       getMTU() const;
+    bool           exchangeMTU();
     bool           secureConnection() const;
     void           setConnectTimeout(uint32_t timeout);
     bool           setDataLen(uint16_t txOctets);
@@ -98,6 +102,7 @@ class NimBLEClient {
 
     bool       retrieveServices(const NimBLEUUID* uuidFilter = nullptr);
     static int handleGapEvent(struct ble_gap_event* event, void* arg);
+    static int exchangeMTUCb(uint16_t conn_handle, const ble_gatt_error* error, uint16_t mtu, void* arg);
     static int serviceDiscoveredCB(uint16_t                     connHandle,
                                    const struct ble_gatt_error* error,
                                    const struct ble_gatt_svc*   service,
@@ -113,6 +118,8 @@ class NimBLEClient {
     uint8_t                           m_terminateFailCount;
     bool                              m_deleteCallbacks;
     bool                              m_connEstablished;
+    bool                              m_asyncConnect;
+    bool                              m_exchangeMTU;
 # if CONFIG_BT_NIMBLE_EXT_ADV
     uint8_t m_phyMask;
 # endif
@@ -174,6 +181,14 @@ class NimBLEClientCallbacks {
      * @param [in] connInfo A reference to a NimBLEConnInfo instance with information
      */
     virtual void onIdentity(NimBLEConnInfo& connInfo);
+
+    /**
+     * @brief Called when the connection MTU changes.
+     * @param [in] pClient A pointer to the client that the MTU change is associated with.
+     * @param [in] MTU The new MTU value.
+     * about the peer connection parameters.
+     */
+    virtual void onMTUChange(NimBLEClient* pClient, uint16_t MTU);
 };
 
 #endif /* CONFIG_BT_ENABLED && CONFIG_BT_NIMBLE_ROLE_CENTRAL */
