esp32: Add API to add extra GATT service and support for nimble ext_adv (#38067)

* esp32: Add API to add extra GATT service and support for nimble ext_adv

* Restyled by clang-format

* Restyled by gn

* Add documents and replace all ErrorStr(err) with err.Format()

* Restyled by prettier-markdown

---------

Co-authored-by: Restyled.io <commits@restyled.io>

Author: wqx6

docs/platforms/esp32/ble_settings.md

@@ -33,3 +33,137 @@ advertising packets.
 ```
 
 Note: Scan response should be configure before `InitServer`.
+
+## Nimble: additional custom GATT services
+
+The `ConfigureExtraServices` API is used to configure additional services
+alongside the Matter services. This API allows users to add their own custom
+services for provisioning or other purposes.
+
+### Usage
+
+```
+/* Service access callback */
+static int gatt_svc_access(uint16_t conn_handle, uint16_t attr_handle,
+                           struct ble_gatt_access_ctxt *ctxt, void *arg);
+
+/* Service UUID */
+static const ble_uuid128_t gatt_svr_svc_uuid =
+    BLE_UUID128_INIT(0x2d, 0x71, 0xa2, 0x59, 0xb4, 0x58, 0xc8, 0x12,
+                     0x99, 0x99, 0x43, 0x95, 0x12, 0x2f, 0x46, 0x59);
+
+/* A characteristic that can be subscribed to */
+static uint16_t gatt_svr_chr_val_handle;
+static const ble_uuid128_t gatt_svr_chr_uuid =
+    BLE_UUID128_INIT(0x00, 0x00, 0x00, 0x00, 0x11, 0x11, 0x11, 0x11,
+                     0x22, 0x22, 0x22, 0x22, 0x33, 0x33, 0x33, 0x33);
+
+/* A custom descriptor */
+static const ble_uuid128_t gatt_svr_dsc_uuid =
+    BLE_UUID128_INIT(0x01, 0x01, 0x01, 0x01, 0x12, 0x12, 0x12, 0x12,
+                     0x23, 0x23, 0x23, 0x23, 0x34, 0x34, 0x34, 0x34);
+
+{
+    std::vector<struct ble_gatt_svc_def> gatt_svr_svcs = {
+        {
+            /*** Service ***/
+            .type = BLE_GATT_SVC_TYPE_PRIMARY,
+            .uuid = &gatt_svr_svc_uuid.u,
+            .characteristics = (struct ble_gatt_chr_def[])
+            { {
+                    /*** This characteristic can be subscribed to by writing 0x00 and 0x01 to the CCCD ***/
+                    .uuid = &gatt_svr_chr_uuid.u,
+                    .access_cb = gatt_svc_access,
+                    .flags = BLE_GATT_CHR_F_READ | BLE_GATT_CHR_F_WRITE | BLE_GATT_CHR_F_NOTIFY | BLE_GATT_CHR_F_INDICATE,
+                    .val_handle = &gatt_svr_chr_val_handle,
+                    .descriptors = (struct ble_gatt_dsc_def[]) {
+                        {
+                            .uuid = &gatt_svr_dsc_uuid.u,
+                            .att_flags = BLE_ATT_F_READ,
+                            .access_cb = gatt_svc_access,
+                        }, {
+                            0, /* No more descriptors in this characteristic */
+                        }
+                    },
+                }, {
+                    0, /* No more characteristics in this service. */
+                }
+            },
+        },
+    };
+
+    /* Add Extra service after Matter service */
+    CHIP_ERROR err = chip::DeviceLayer::Internal::BLEMgrImpl().ConfigureExtraServices(gatt_svr_svcs, ture);
+}
+```
+
+Note: Extra service should be configure before `InitServer`.
+
+## Nimble: multiple BLE advertisement
+
+The chips that support BLE 5.0 features can advertise their custom BLE GAP
+advertisement alongside Matter's BLE advertisement if `CONFIG_BT_NIMBLE_EXT_ADV`
+is enabled and `CONFIG_BT_NIMBLE_MAX_EXT_ADV_INSTANCES` is a value greater
+than 1.
+
+### Usage
+
+```
+static uint8_t connectable_adv_pattern[] = {
+    0x02, 0x01, 0x06,
+    0x03, 0x03, 0xab, 0xcd,
+    0x03, 0x03, 0x18, 0x11,
+    0x12, 0X09, 'n', 'i', 'm', 'b', 'l', 'e', '-', 'c', 'o', 'n', 'n', 'e', 't', 'a', 'b', 'l', 'e'
+};
+
+/* GAP event handler */
+static int ble_multi_adv_gap_event(struct ble_gap_event *event, void *arg);
+
+{
+    /* Use instance except 0 as Matter advertisement uses instance 0 */
+    uint8_t instance = 1;
+    struct ble_gap_ext_adv_params params;
+    int size_pattern = sizeof(connectable_adv_pattern) / sizeof(connectable_adv_pattern[0]);
+
+    memset (&params, 0, sizeof(params));
+
+    params.connectable = 1;
+    params.scannable = 1;
+    params.own_addr_type = BLE_OWN_ADDR_RANDOM;
+    params.sid = 1;
+    params.primary_phy = BLE_HCI_LE_PHY_1M;
+    params.secondary_phy = BLE_HCI_LE_PHY_1M;
+    params.tx_power = 127;
+
+    int rc;
+    struct os_mbuf *data;
+    int size_pattern = sizeof(legacy_dur_adv_pattern) / sizeof(legacy_dur_adv_pattern[0]);
+
+    if (ble_gap_ext_adv_active(instance)) {
+        ESP_LOGI(tag, "Instance already advertising");
+        return;
+    }
+
+    rc = ble_gap_ext_adv_configure(instance, params, NULL,
+                                   ble_multi_adv_gap_event, NULL);
+    assert (rc == 0);
+
+    /* get mbuf for adv data */
+    data = os_msys_get_pkthdr(size_pattern, 0);
+    assert(data);
+
+    /* fill mbuf with adv data */
+    rc = os_mbuf_append(data, legacy_dur_adv_pattern, size_pattern);
+    assert(rc == 0);
+
+    rc = ble_gap_ext_adv_set_data(instance, data);
+    assert (rc == 0);
+
+    /* start advertising */
+    rc = ble_gap_ext_adv_start(instance, 500, 0);
+    assert (rc == 0);
+}
+```
+
+Note: The custom additional advertisement should be configured after BLE stack
+is started.

src/platform/BUILD.gn

@@ -149,7 +149,7 @@ if (chip_device_platform != "none" && chip_device_platform != "external") {
         chip_device_platform == "tizen" || chip_device_platform == "android" ||
         chip_device_platform == "webos" || chip_device_platform == "bl602" ||
         chip_device_platform == "bl702" || chip_device_platform == "bl702l" ||
-        chip_device_platform == "bl616") {
+        chip_device_platform == "bl616" || chip_device_platform == "esp32") {
       defines += [ "CHIP_DEVICE_CONFIG_ENABLE_CHIPOBLE=${chip_enable_ble}" ]
     }
 

src/platform/ESP32/BLEManagerImpl.h

@@ -24,11 +24,7 @@
  */
 
 #pragma once
-#include <string>
-
-#if CHIP_DEVICE_CONFIG_ENABLE_CHIPOBLE
-
-#include "sdkconfig.h"
+#include <sdkconfig.h>
 
 #include <lib/core/Optional.h>
 
@@ -117,19 +113,18 @@ struct BLEScanConfig
 };
 
 #endif // CONFIG_ENABLE_ESP32_BLE_CONTROLLER
+
 /**
  * Concrete implementation of the BLEManager singleton object for the ESP32 platform.
  */
 class BLEManagerImpl final : public BLEManager,
                              private Ble::BleLayer,
                              private Ble::BlePlatformDelegate,
 #ifdef CONFIG_ENABLE_ESP32_BLE_CONTROLLER
-                             private Ble::BleApplicationDelegate,
                              private Ble::BleConnectionDelegate,
-                             private ChipDeviceScannerDelegate
-#else
-                             private Ble::BleApplicationDelegate
+                             private ChipDeviceScannerDelegate,
 #endif // CONFIG_ENABLE_ESP32_BLE_CONTROLLER
+                             private Ble::BleApplicationDelegate
 {
 public:
     BLEManagerImpl() {}
@@ -142,6 +137,9 @@ class BLEManagerImpl final : public BLEManager,
 
     CHIP_ERROR ConfigureScanResponseData(ByteSpan data);
     void ClearScanResponseData(void);
+#ifdef CONFIG_BT_NIMBLE_ENABLED
+    CHIP_ERROR ConfigureExtraServices(std::vector<struct ble_gatt_svc_def> & extGattSvcs, bool afterMatterSvc);
+#endif
 
 private:
     chip::Optional<chip::ByteSpan> mScanResponse;
@@ -240,6 +238,12 @@ class BLEManagerImpl final : public BLEManager,
     BLEAdvConfig mBLEAdvConfig;
 #endif // CONFIG_ENABLE_ESP32_BLE_CONTROLLER
 #ifdef CONFIG_BT_NIMBLE_ENABLED
+#ifdef CONFIG_BT_NIMBLE_EXT_ADV
+    static constexpr size_t kMaxMatterAdvDataLen = 31;
+    static constexpr uint8_t kMatterAdvInstance  = 0;
+    uint8_t mMatterAdvData[kMaxMatterAdvDataLen];
+    uint16_t mMatterAdvDataLen = 0;
+#endif
     uint16_t mSubscribedConIds[kMaxConnections];
 #endif // CONFIG_BT_NIMBLE_ENABLED
 
@@ -278,6 +282,7 @@ class BLEManagerImpl final : public BLEManager,
     esp_gatt_if_t mAppIf;
 #elif defined(CONFIG_BT_NIMBLE_ENABLED)
     uint16_t mNumGAPCons;
+    std::vector<struct ble_gatt_svc_def> mGattSvcs;
 #endif // CONFIG_BT_BLUEDROID_ENABLED
     uint16_t mServiceAttrHandle;
     uint16_t mRXCharAttrHandle;
@@ -347,7 +352,7 @@ class BLEManagerImpl final : public BLEManager,
     static void bleprph_host_task(void * param);
     static void bleprph_on_sync(void);
     static void bleprph_on_reset(int);
-    static const struct ble_gatt_svc_def CHIPoBLEGATTAttrs[];
+    static const struct ble_gatt_svc_def CHIPoBLEGATTSvc;
     static int ble_svr_gap_event(struct ble_gap_event * event, void * arg);
 
     static int gatt_svr_chr_access(uint16_t conn_handle, uint16_t attr_handle, struct ble_gatt_access_ctxt * ctxt, void * arg);
@@ -423,5 +428,3 @@ inline bool BLEManagerImpl::_IsAdvertising(void)
 } // namespace Internal
 } // namespace DeviceLayer
 } // namespace chip
-
-#endif // CHIP_DEVICE_CONFIG_ENABLE_CHIPOBLE

src/platform/ESP32/BUILD.gn

@@ -100,33 +100,29 @@ static_library("ESP32") {
     ]
   }
 
-  if (chip_enable_chipoble) {
-    sources += [
-      "BLEManagerImpl.h",
-      "ChipDeviceScanner.h",
-    ]
-  }
-
-  if (chip_enable_ble_controller) {
-    sources += [ "ChipDeviceScanner.h" ]
-  }
-
-  if (chip_bt_nimble_enabled) {
-    sources += [ "nimble/BLEManagerImpl.cpp" ]
+  if (chip_enable_ble) {
+    sources += [ "BLEManagerImpl.h" ]
     if (chip_enable_ble_controller) {
-      sources += [
-        "nimble/ChipDeviceScanner.cpp",
-        "nimble/blecent.h",
-        "nimble/misc.c",
-        "nimble/peer.c",
-      ]
+      sources += [ "ChipDeviceScanner.h" ]
     }
-  }
 
-  if (chip_bt_bluedroid_enabled) {
-    sources += [ "bluedroid/BLEManagerImpl.cpp" ]
-    if (chip_enable_ble_controller) {
-      sources += [ "bluedroid/ChipDeviceScanner.cpp" ]
+    if (chip_bt_nimble_enabled) {
+      sources += [ "nimble/BLEManagerImpl.cpp" ]
+      if (chip_enable_ble_controller) {
+        sources += [
+          "nimble/ChipDeviceScanner.cpp",
+          "nimble/blecent.h",
+          "nimble/misc.c",
+          "nimble/peer.c",
+        ]
+      }
+    }
+
+    if (chip_bt_bluedroid_enabled) {
+      sources += [ "bluedroid/BLEManagerImpl.cpp" ]
+      if (chip_enable_ble_controller) {
+        sources += [ "bluedroid/ChipDeviceScanner.cpp" ]
+      }
     }
   }
 

src/platform/ESP32/CHIPDevicePlatformConfig.h

@@ -96,12 +96,6 @@
 #define CHIP_DEVICE_CONFIG_ICD_FAST_POLL_INTERVAL chip::System::Clock::Milliseconds32(CONFIG_ICD_FAST_POLL_INTERVAL_MS)
 #endif // CHIP_CONFIG_ENABLE_ICD_SERVER
 
-#ifdef CONFIG_ENABLE_CHIPOBLE
-#define CHIP_DEVICE_CONFIG_ENABLE_CHIPOBLE CONFIG_ENABLE_CHIPOBLE
-#else
-#define CHIP_DEVICE_CONFIG_ENABLE_CHIPOBLE 0
-#endif // CONFIG_ENABLE_CHIPOBLE
-
 #ifdef CONFIG_ENABLE_EXTENDED_DISCOVERY
 #define CHIP_DEVICE_CONFIG_ENABLE_EXTENDED_DISCOVERY CONFIG_ENABLE_EXTENDED_DISCOVERY
 #else

src/platform/ESP32/ConfigurationManagerImpl.h

@@ -35,6 +35,7 @@
 #include <platform/internal/GenericConnectivityManagerImpl_NoBLE.h>
 #endif
 
+#include <freertos/timers.h>
 #include <platform/ESP32/ESP32Config.h>
 
 namespace chip {

src/platform/ESP32/bluedroid/BLEManagerImpl.cpp

@@ -23,17 +23,12 @@
  *          for the ESP32 platform.
  */
 /* this file behaves like a config.h, comes first */
-#include <platform/internal/CHIPDeviceLayerInternal.h>
-
-#if CHIP_DEVICE_CONFIG_ENABLE_CHIPOBLE
-
 #include "sdkconfig.h"
+#include <platform/internal/CHIPDeviceLayerInternal.h>
 #ifdef CONFIG_ENABLE_ESP32_BLE_CONTROLLER
 #include <lib/support/CodeUtils.h>
 #endif
 
-#ifdef CONFIG_BT_BLUEDROID_ENABLED
-
 #ifdef CONFIG_ENABLE_ESP32_BLE_CONTROLLER
 #include <ble/Ble.h>
 #endif
@@ -2158,7 +2153,3 @@ void BLEManagerImpl::DriveBLEState(intptr_t arg)
 } // namespace Internal
 } // namespace DeviceLayer
 } // namespace chip
-
-#endif // CONFIG_BT_BLUEDROID_ENABLED
-
-#endif // CHIP_DEVICE_CONFIG_ENABLE_CHIPOBLE