Add asyncronous client connect and MTU exchange.

* 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`
* Add `NimBLEDevice::getConnectedClients()` which returns a vector of pointers to the currently connected client instances.

Author: h2zero

examples/NimBLE_Async_Client/CMakeLists.txt

@@ -0,0 +1,6 @@
+# The following lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(NimBLE_Async_Client)

examples/NimBLE_Async_Client/Makefile

@@ -0,0 +1,3 @@
+PROJECT_NAME := NimBLE_Async_Client
+
+include $(IDF_PATH)/make/project.mk

examples/NimBLE_Async_Client/main/CMakeLists.txt

@@ -0,0 +1,4 @@
+set(COMPONENT_SRCS "main.cpp")
+set(COMPONENT_ADD_INCLUDEDIRS ".")
+
+register_component()

examples/NimBLE_Async_Client/main/component.mk

@@ -0,0 +1,4 @@
+#
+# "main" pseudo-component makefile.
+#
+# (Uses default behaviour of compiling all source files in directory, adding 'include' to include path.)

examples/NimBLE_Async_Client/main/main.cpp

@@ -0,0 +1,83 @@
+
+/**
+ *  NimBLE_Async_client Demo:
+ *
+ *  Demonstrates asynchronous client operations.
+ *
+ *  Created: on November 4, 2024
+ *      Author: H2zero
+ *
+ */
+
+#include <NimBLEDevice.h>
+
+static constexpr uint32_t scanTimeMs = 5 * 1000;
+
+class ClientCallbacks : public NimBLEClientCallbacks {
+    void onConnect(NimBLEClient* pClient) {
+        printf("Connected to: %s\n", pClient->getPeerAddress().toString().c_str());
+    }
+
+    void onDisconnect(NimBLEClient* pClient, int reason) {
+        printf("%s Disconnected, reason = %d - Starting scan\n", pClient->getPeerAddress().toString().c_str(), reason);
+        NimBLEDevice::getScan()->start(scanTimeMs);
+    }
+} clientCB;
+
+class scanCallbacks : public NimBLEScanCallbacks {
+    void onResult(NimBLEAdvertisedDevice* advertisedDevice) {
+        printf("Advertised Device found: %s\n", advertisedDevice->toString().c_str());
+        if (advertisedDevice->haveName() && advertisedDevice->getName() == "NimBLE-Server") {
+            printf("Found Our Device\n");
+
+            auto pClient = NimBLEDevice::getDisconnectedClient();
+            if (!pClient) {
+                pClient = NimBLEDevice::createClient(advertisedDevice->getAddress());
+                if (!pClient) {
+                    printf("Failed to create client\n");
+                    return;
+                }
+            }
+
+            pClient->setClientCallbacks(&clientCB, false);
+            if (!pClient->connect(true, true, false)) { // delete attributes, async connect, no MTU exchange
+                NimBLEDevice::deleteClient(pClient);
+                printf("Failed to connect\n");
+                return;
+            }
+        }
+    }
+
+    void onScanEnd(NimBLEScanResults results) {
+        printf("Scan Ended\n");
+        NimBLEDevice::getScan()->start(scanTimeMs);
+    }
+};
+
+extern "C" void app_main(void) {
+    printf("Starting NimBLE Async Client\n");
+    NimBLEDevice::init("");
+    NimBLEDevice::setPower(3); /** +3db */
+
+    NimBLEScan* pScan = NimBLEDevice::getScan();
+    pScan->setScanCallbacks(new scanCallbacks());
+    pScan->setInterval(45);
+    pScan->setWindow(15);
+    pScan->setActiveScan(true);
+    pScan->start(scanTimeMs);
+
+    for (;;) {
+        vTaskDelay(pdMS_TO_TICKS(1000));
+        auto pClients = NimBLEDevice::getConnectedClients();
+        if (!pClients.size()) {
+            continue;
+        }
+
+        for (auto& pClient : pClients) {
+            printf("%s\n", pClient->toString().c_str());
+            NimBLEDevice::deleteClient(pClient);
+        }
+
+        NimBLEDevice::getScan()->start(scanTimeMs);
+    }
+}

examples/NimBLE_Async_Client/sdkconfig.defaults

@@ -0,0 +1,12 @@
+# Override some defaults so BT stack is enabled
+# in this example
+
+#
+# BT config
+#
+CONFIG_BT_ENABLED=y
+CONFIG_BTDM_CTRL_MODE_BLE_ONLY=y
+CONFIG_BTDM_CTRL_MODE_BR_EDR_ONLY=n
+CONFIG_BTDM_CTRL_MODE_BTDM=n
+CONFIG_BT_BLUEDROID_ENABLED=n
+CONFIG_BT_NIMBLE_ENABLED=y

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;
+    }
 
     // Set the connection in progress flag to prevent a scan from starting while connecting.
     NimBLEDevice::setConnectionInProgress(true);
@@ -242,10 +265,15 @@ bool NimBLEClient::connect(const NimBLEAddress& address, bool deleteAttributes)
     NimBLEDevice::setConnectionInProgress(false);
     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);
@@ -278,10 +306,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);
 
@@ -854,6 +878,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.
@@ -908,7 +967,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;
             }
@@ -918,19 +977,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;
@@ -1072,7 +1140,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
@@ -1204,4 +1274,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 */