feat(ble/bluedroid): Support bluedroid dual identity

(cherry picked from commit 2358786647)

Co-authored-by: zhiweijian <zhiweijian@espressif.com>

docs/conf_common.py

@@ -43,6 +43,10 @@ BLE_DOCS = ['api-guides/ble/index.rst',
             'api-reference/bluetooth/nimble/index.rst',
             'migration-guides/release-5.x/5.0/bluetooth-low-energy.rst']
 
+BLE_DUAL_IDENTITY_DOCS = [
+    'api-guides/ble/bluedroid-dual-identity-host-dev.rst',
+]
+
 BLE_MESH_DOCS = ['api-guides/esp-ble-mesh/ble-mesh-index.rst',
                  'api-guides/esp-ble-mesh/ble-mesh-feature-list.rst',
                  'api-guides/esp-ble-mesh/ble-mesh-terminology.rst',
@@ -250,6 +254,7 @@ ESP32P4_DOCS = ['api-reference/system/ipc.rst',
 # format: {tag needed to include: documents to included}, tags are parsed from sdkconfig and peripheral_caps.h headers
 conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
                             'SOC_BLE_SUPPORTED':BLE_DOCS,
+                            'SOC_BLE_50_SUPPORTED':BLE_DUAL_IDENTITY_DOCS,
                             'SOC_BLE_MESH_SUPPORTED':BLE_MESH_DOCS,
                             'SOC_BLUFI_SUPPORTED':BLUFI_DOCS,
                             'SOC_WIFI_SUPPORTED':WIFI_DOCS,

docs/en/api-guides/ble/bluedroid-dual-identity-host-dev.rst

@@ -0,0 +1,25 @@
+Bluedroid Host Support for Dual Local Identities
+================================================
+
+:link_to_translation:`zh_CN:[中文]`
+
+Introduction
+------------
+
+When a single peer phone connects to an ESP32 peripheral through two different **local identities** (for example, a Public address and a fixed Static Random address from two extended advertising sets), the default Bluedroid Host treats both links as the same peer. Bonds, LTK, and NVS sections can overwrite each other.
+
+Enable :ref:`BT_BLE_PERIPH_PSEUDO_ADDR_BOND <CONFIG_BT_BLE_PERIPH_PSEUDO_ADDR_BOND>` to derive a Host-internal **pseudo address** ``f(local_identity, peer)`` per link. The application sees two different ``remote_bda`` values for the same phone, while SMP and the controller still use the real peer identity on air.
+
+Example
+-------
+
+See :example:`ble50_dual_identity_server <bluetooth/bluedroid/ble_50/ble50_dual_identity_server>` for a Bluetooth LE 5.0 peripheral that advertises two identities concurrently, pairs with both, and keeps **isolated bonds per (local, peer) pair**.
+
+Application Notes
+-----------------
+
+- Use **conn_id** as the link key in GATTS calls; do not use ``remote_bda`` to tell links apart.
+- ``remote_bda`` in GAP/GATTS events is the **pseudo address** when this feature is enabled.
+- Call ``esp_ble_gap_get_conn_identity()`` while connected to recover the real peer and local identity.
+- Use ``esp_ble_gap_remove_bond_for_identity()`` to delete one identity's bond without affecting the other.
+- For controller operations (whitelist, directed advertising), use the **real peer** address, never the pseudo.

docs/en/api-guides/ble/index.rst

@@ -15,6 +15,7 @@ Overview
    ble-qualification
    Low Power Mode Introduction <ble-low-power-mode>
    ble-multiconnection-guide
+   :SOC_BLE_50_SUPPORTED: bluedroid-dual-identity-host-dev
 
 ***************
 Get Started

docs/zh_CN/api-guides/ble/bluedroid-dual-identity-host-dev.rst

@@ -0,0 +1,25 @@
+Bluedroid 双本地身份 Host 开发说明
+=====================================
+
+:link_to_translation:`en:[English]`
+
+简介
+----
+
+当同一部手机通过两个不同的**本地身份**（例如来自两个扩展广播集的 Public 地址与固定的 Static Random 地址）连接到 ESP32 外围设备时，默认 Bluedroid Host 会将两条链路视为同一对端。Bond、LTK 与 NVS 区段可能相互覆盖。
+
+启用 :ref:`BT_BLE_PERIPH_PSEUDO_ADDR_BOND <CONFIG_BT_BLE_PERIPH_PSEUDO_ADDR_BOND>`\ 后，Host 会为每条链路派生内部 **伪地址 (pseudo address)** ``f(local_identity, peer)``。应用层对同一手机会看到两个不同的 ``remote_bda``，而 SMP 与控制器仍使用空口真实对端身份。
+
+示例
+----
+
+请参阅 :example:`ble50_dual_identity_server <bluetooth/bluedroid/ble_50/ble50_dual_identity_server>`\ ：该 Bluetooth LE 5.0 外围设备同时广播两个身份、分别配对，并为每个 **(local, peer)** 对保留**独立的 bond**。
+
+应用要点
+--------
+
+- 在 GATTS 调用中以 **conn_id** 作为链路键；不要用 ``remote_bda`` 区分链路。
+- 启用本特性后，GAP/GATTS 事件中的 ``remote_bda`` 为 **pseudo 地址**。
+- 连接态下调用 ``esp_ble_gap_get_conn_identity()`` 可恢复真实对端与本地身份。
+- 使用 ``esp_ble_gap_remove_bond_for_identity()`` 只删除一路身份的 bond，不影响另一路。
+- 控制器相关操作（白名单、定向广播）须使用**真实对端**地址，切勿使用伪地址。

docs/zh_CN/api-guides/ble/index.rst

@@ -15,6 +15,7 @@
    ble-qualification
    低功耗模式介绍 <ble-low-power-mode>
    ble-multiconnection-guide
+   :SOC_BLE_50_SUPPORTED: bluedroid-dual-identity-host-dev
 
 **********
 快速入门