fix(nimble): Improve safety, fix bugs, and update docs across NimBLE examples

- Remove unused headers from examples
- Improve periodic adv/sync example functionality and readability
- Use ble_hs_id_infer_auto() instead of hardcoded BLE_OWN_ADDR_PUBLIC/RANDOM
- Add ble_hs_util_ensure_addr() calls in on_sync for proper address setup
- Use correct ext adv instance (0 instead of 1) in phy_prph, l2cap_coc, multi_conn
- Fix struct name: ble_gap_periodic_adv_enable_params -> ble_gap_periodic_adv_start_params
- Add CONFIG_BT_NIMBLE_GAP_SERVICE guards around ble_svc_gap_device_name_set
- Fix unsafe AD data parsing with bounds checks in central examples
- Fix UUID matching bugs (off-by-one loop condition and byte order) in
  phy_cent, htp_cent, and proximity_sensor_cent
- Fix ble_multi_conn_cent address type to use dynamic inference
- Remove contradictory sm_sc=0 after sm_sc=1 in ble_multi_adv
- Add CONFIG_BT_NIMBLE_EXT_ADV=y to ble_multi_adv sdkconfig defaults
- Check return values for ble_gap_set_host_feat, nimble_port_init
- Update tutorials and READMEs to match code changes

examples/bluetooth/nimble/ble_cte/ble_periodic_adv_with_cte/main/main.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2025-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: CC0-1.0
  */
@@ -10,9 +10,7 @@
 #include "nimble/nimble_port_freertos.h"
 #include "host/ble_hs.h"
 #include "host/util/util.h"
-#include "console/console.h"
 #include "services/gap/ble_svc_gap.h"
-#include "periodic_adv.h"
 #include "host/ble_gap.h"
 #include "host/ble_hs_adv.h"
 #include "cte_config.h"
@@ -21,25 +19,17 @@
 static const char *TAG = "CTE_ADV_EXAMPLE";
 static uint8_t s_periodic_adv_raw_data[] = {0x0D, BLE_HS_ADV_TYPE_COMP_NAME, 'C','T','E',' ','P','e','r','i','o','d','i','c'};
 
-/* Configuration based on Kconfig settings */
-#if CONFIG_EXAMPLE_RANDOM_ADDR
-static uint8_t s_own_addr_type = BLE_OWN_ADDR_RANDOM;
-#else
-static uint8_t s_own_addr_type;
-#endif
-
-
 /**
  * @brief Configure and start periodic advertising with CTE
  */
-static void start_periodic_adv_cte(void)
+static void start_periodic_adv_cte(uint8_t own_addr_type)
 {
     int rc;
-    uint8_t instance = 1;
+    uint8_t instance = 0;
     ble_addr_t addr;
+    uint8_t addr_type = own_addr_type == BLE_OWN_ADDR_RANDOM ? BLE_ADDR_RANDOM : BLE_ADDR_PUBLIC;
 
-    /* Generate random address for instance */
-    rc = ble_hs_id_gen_rnd(1, &addr);
+    rc = ble_hs_id_copy_addr(addr_type, addr.val, NULL);
     assert(rc == 0);
 
     ESP_LOGI(TAG, "Device Address: ");
@@ -48,26 +38,23 @@ static void start_periodic_adv_cte(void)
 
     /* Configure extended advertising parameters */
     struct ble_gap_ext_adv_params ext_adv_params = {
-        .own_addr_type = BLE_OWN_ADDR_RANDOM,
+        .own_addr_type = own_addr_type,
         .primary_phy = BLE_HCI_LE_PHY_1M,
         .secondary_phy = BLE_HCI_LE_PHY_1M,
         .sid = 2,
-        .tx_power = 0
+        .tx_power = 0x7f
     };
 
     rc = ble_gap_ext_adv_configure(instance, &ext_adv_params, NULL, NULL, NULL);
     assert(rc == 0);
 
-    rc = ble_gap_ext_adv_set_addr(instance, &addr);
-    assert(rc == 0);
-
     /* Configure advertising data */
     struct ble_hs_adv_fields adv_fields = {
         .name = (const uint8_t *)"CTE_Periodic_Adv",
         .name_len = strlen((char *)adv_fields.name)
     };
 
-    struct os_mbuf *data = os_msys_get_pkthdr(BLE_HCI_MAX_ADV_DATA_LEN, 0);
+    struct os_mbuf *data = os_msys_get_pkthdr(BLE_HS_ADV_MAX_FIELD_SZ, 0);
     assert(data);
 
     rc = ble_hs_adv_set_fields_mbuf(&adv_fields, data);
@@ -79,8 +66,8 @@ static void start_periodic_adv_cte(void)
     /* Configure periodic advertising parameters */
     struct ble_gap_periodic_adv_params pparams = {
         .include_tx_power = 0,
-        .itvl_min = BLE_GAP_ADV_ITVL_MS(200),
-        .itvl_max = BLE_GAP_ADV_ITVL_MS(400)
+        .itvl_min = BLE_GAP_PERIODIC_ITVL_MS(200),
+        .itvl_max = BLE_GAP_PERIODIC_ITVL_MS(400)
     };
 
     rc = ble_gap_periodic_adv_configure(instance, &pparams);
@@ -98,11 +85,15 @@ static void start_periodic_adv_cte(void)
 
     /* Configure CTE parameters */
 #if defined(CONFIG_EXAMPLE_ADV_DIRECTION_FINDING_AOA)
-    /* Configure CTE parameters */
+    /* Configure CTE parameters for AoA (receiver does antenna switching).
+     * A minimal switching pattern is provided to satisfy the NimBLE host
+     * API; the controller ignores it for AoA transmissions. */
     struct ble_gap_periodic_adv_cte_params cte_params = {
         .cte_length = 0x14,
         .cte_type = BLE_CTE_TYPE_AOA,
         .cte_count = 1,
+        .switching_pattern_length = 2,
+        .antenna_ids = (uint8_t[]){0, 0},
     };
 #elif defined(CONFIG_EXAMPLE_ADV_DIRECTION_FINDING_AOD)
     struct ble_gap_periodic_adv_cte_params cte_params = {
@@ -151,27 +142,19 @@ static void periodic_adv_on_reset(int reason)
 static void periodic_sync_cb(void)
 {
     int rc;
+    uint8_t own_addr_type;
 #if CONFIG_EXAMPLE_RANDOM_ADDR
-    ble_addr_t addr;
-    if (ble_hs_id_gen_rnd(0, &addr) == 0) {
-        ble_hs_id_set_rnd(addr.val);
-    }
-    /* Ensure proper identity address */
     rc = ble_hs_util_ensure_addr(1);
 #else
     rc = ble_hs_util_ensure_addr(0);
 #endif
     assert(rc == 0);
 
-    /* Infer address type */
-    rc = ble_hs_id_infer_auto(0, &s_own_addr_type);
-    if (rc != 0) {
-        ESP_LOGE(TAG, "Failed to infer address type (rc=%d)", rc);
-        return;
-    }
+    rc = ble_hs_id_infer_auto(0, &own_addr_type);
+    assert(rc == 0);
 
     /* Start advertising */
-    start_periodic_adv_cte();
+    start_periodic_adv_cte(own_addr_type);
 }
 
 /**
@@ -210,7 +193,7 @@ void app_main(void)
     ESP_LOGI(TAG, "%s", direction_finding_logo);
 #if defined(CONFIG_EXAMPLE_ADV_DIRECTION_FINDING_AOD)
     ESP_LOGI(TAG, "DIRECTION_FINDING Example Periodic Adv AOD Mode");
-    ble_direction_finding_antenna_init(antenna_use_gpio,CONFIG_EXAMPLE_AOD_GPIO_BIT_COUNT);
+    ble_direction_finding_antenna_init(antenna_use_gpio,CONFIG_EXAMPLE_ANT_GPIO_BIT_COUNT);
 #elif defined(CONFIG_EXAMPLE_ADV_DIRECTION_FINDING_AOA)
     ESP_LOGI(TAG, "DIRECTION_FINDING Example Periodic Adv AOA Mode");
 #endif
@@ -221,8 +204,10 @@ void app_main(void)
     ble_hs_cfg.sync_cb = periodic_sync_cb;
 
     /* Set device name */
+#if CONFIG_BT_NIMBLE_GAP_SERVICE
     rc = ble_svc_gap_device_name_set("Periodic ADV with CTE");
     assert(rc == 0);
+#endif
 
     /* Start BLE host task */
     nimble_port_freertos_init(periodic_adv_host_task);

examples/bluetooth/nimble/ble_cte/ble_periodic_sync_with_cte/main/main.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2025-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: CC0-1.0
  */
@@ -13,9 +13,6 @@
 #include "host/ble_hs.h"
 #include "host/util/util.h"
 #include "services/gap/ble_svc_gap.h"
-#include "console/console.h"
-
-#include "periodic_sync.h"
 #include "cte_config.h"
 
 static const char *TAG = "CTE_SYNC_EXAMPLE";
@@ -36,20 +33,17 @@ static struct ble_gap_cte_sampling_params sync_cte_sampling_params = {
 static void periodic_sync_scan(void)
 {
     uint8_t own_addr_type;
-    struct ble_gap_disc_params disc_params = {0};
+    struct ble_gap_ext_disc_params disc_params = {0};
     int rc = ble_hs_id_infer_auto(0, &own_addr_type);
     if (rc != 0) {
         ESP_LOGE(TAG, "Failed to determine address type; rc=%d", rc);
         return;
     }
 
-    /**
-     * Perform a passive scan.  I.e., don't send follow-up scan requests to
-     * each advertiser.
-     */
     disc_params.passive = 1;
-    rc = ble_gap_disc(own_addr_type, BLE_HS_FOREVER, &disc_params,
-                      periodic_sync_gap_event, NULL);
+    rc = ble_gap_ext_disc(own_addr_type, 0, 0,
+                          0, 0, 0, &disc_params, &disc_params,
+                          periodic_sync_gap_event, NULL);
     if (rc != 0) {
         ESP_LOGE(TAG, "GAP discovery failed; rc=%d", rc);
     }
@@ -146,8 +140,7 @@ static int periodic_sync_gap_event(struct ble_gap_event *event, void *arg)
 {
     switch (event->type) {
     case BLE_GAP_EVENT_EXT_DISC: {
-        const struct ble_gap_ext_disc_desc *disc = ((struct ble_gap_ext_disc_desc *)(&event->disc));
-
+        const struct ble_gap_ext_disc_desc *disc = &event->ext_disc;
         if (is_synced) {
             return 0;
         }
@@ -216,6 +209,11 @@ static int periodic_sync_gap_event(struct ble_gap_event *event, void *arg)
     }
 
     case BLE_GAP_EVENT_PERIODIC_SYNC:
+        if (event->periodic_sync.status != 0) {
+            ESP_LOGE(TAG, "Periodic Sync Failed; status=%d", event->periodic_sync.status);
+            is_synced = 0;
+            return 0;
+        }
         ESP_LOGI(TAG, "Periodic Sync Established");
         print_periodic_sync_data(event);
         ble_gap_disc_cancel();
@@ -260,7 +258,7 @@ static void periodic_sync_on_sync(void)
     rc = ble_hs_util_ensure_addr(0);
     assert(rc == 0);
 
-    /* Begin scanning for a peripheral to connect to. */
+    /* Begin scanning for a periodic advertiser to sync with. */
     periodic_sync_scan();
 }
 
@@ -296,8 +294,10 @@ void app_main(void)
     ble_hs_cfg.sync_cb = periodic_sync_on_sync;
 
     /* Set the default device name. */
+#if CONFIG_BT_NIMBLE_GAP_SERVICE
     rc = ble_svc_gap_device_name_set("periodic_sync_CTE");
     assert(rc == 0);
+#endif
 
 
 #if MYNEWT_VAL(BLE_AOA_AOD)