modified notes about esp_gap_ble_api

espressif · Jul 31, 2024 · 3525d58 · 3525d58
1 parent b3082e2
commit 3525d58
Show file tree

Hide file tree

Showing 2 changed files with 3,250 additions and 1,834 deletions.
diff --git a/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h b/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h
@@ -169,12 +169,18 @@ typedef enum {
 /// Bluetooth device address
 typedef uint8_t esp_bd_addr_t[ESP_BD_ADDR_LEN];
 
-/// BLE device address type
+/**
+ * @brief LE device address type
+ */
 typedef enum {
-    BLE_ADDR_TYPE_PUBLIC        = 0x00,     /*!< Public Device Address */
-    BLE_ADDR_TYPE_RANDOM        = 0x01,     /*!< Random Device Address. To set this address, use the function esp_ble_gap_set_rand_addr(esp_bd_addr_t rand_addr) */
-    BLE_ADDR_TYPE_RPA_PUBLIC    = 0x02,     /*!< Resolvable Private Address (RPA) with public identity address */
-    BLE_ADDR_TYPE_RPA_RANDOM    = 0x03,     /*!< Resolvable Private Address (RPA) with random identity address. To set this address, use the function esp_ble_gap_set_rand_addr(esp_bd_addr_t rand_addr) */
+    BLE_ADDR_TYPE_PUBLIC        = 0x00,     /*!< Public Device Address.
+                                                Ideal for those scenarios where the device address is known or pre-configured. Suitable for use in situations where devices need to be easily recognizable. */
+    BLE_ADDR_TYPE_RANDOM        = 0x01,     /*!< Random Device Address. To set this address, use the function `esp_ble_gap_set_rand_addr`.
+                                                For scenarios where anonymity is required. */
+    BLE_ADDR_TYPE_RPA_PUBLIC    = 0x02,     /*!< Resolvable Private Address (RPA) with public identity address.
+                                                Typically used for privacy-sensitive applications that need to maintain a consistent identity but want to change addresses frequently to prevent tracking by unauthorized parties. */
+    BLE_ADDR_TYPE_RPA_RANDOM    = 0x03,     /*!< Resolvable Private Address (RPA) with random identity address. To set this address, use the function `esp_ble_gap_set_rand_addr`.
+                                                Ideal for application scenarios that require a high degree of privacy, where the device address changes frequently but still needs to be resolved by a known peer. */
 } esp_ble_addr_type_t;
 
 /// white list address type