From ef57320962a5030cf16bbd18ab488e04ab2fbd26 Mon Sep 17 00:00:00 2001 From: zhangbowen Date: Wed, 24 Jul 2024 14:36:08 +0800 Subject: [PATCH] modified notes about esp_gap_ble_api --- .../api/include/api/esp_gap_ble_api.h | 4958 +++++++++++------ 1 file changed, 3128 insertions(+), 1830 deletions(-) diff --git a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h index 75fd3419e6e6..635d69d24675 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h @@ -17,2226 +17,3256 @@ extern "C" { #endif -/** - * @brief BLE_ADV_DATA_FLAG data flag bit definition used for advertising data flag - */ -#define ESP_BLE_ADV_FLAG_LIMIT_DISC (0x01 << 0) -#define ESP_BLE_ADV_FLAG_GEN_DISC (0x01 << 1) -#define ESP_BLE_ADV_FLAG_BREDR_NOT_SPT (0x01 << 2) -#define ESP_BLE_ADV_FLAG_DMT_CONTROLLER_SPT (0x01 << 3) -#define ESP_BLE_ADV_FLAG_DMT_HOST_SPT (0x01 << 4) -#define ESP_BLE_ADV_FLAG_NON_LIMIT_DISC (0x00 ) - - -/// relate to BTM_LE_KEY_xxx in stack/btm_api.h -#define ESP_LE_KEY_NONE 0 /*!< No encryption key */ -#define ESP_LE_KEY_PENC (1 << 0) /*!< encryption key, encryption information of peer device */ -#define ESP_LE_KEY_PID (1 << 1) /*!< identity key of the peer device */ -#define ESP_LE_KEY_PCSRK (1 << 2) /*!< peer SRK */ -#define ESP_LE_KEY_PLK (1 << 3) /*!< Link key*/ -#define ESP_LE_KEY_LLK (ESP_LE_KEY_PLK << 4) /*!< peer link key*/ -#define ESP_LE_KEY_LENC (ESP_LE_KEY_PENC << 4) /*!< master role security information:div */ -#define ESP_LE_KEY_LID (ESP_LE_KEY_PID << 4) /*!< master device ID key */ -#define ESP_LE_KEY_LCSRK (ESP_LE_KEY_PCSRK << 4) /*!< local CSRK has been deliver to peer */ -typedef uint8_t esp_ble_key_type_t; - -/// relate to BTM_LE_AUTH_xxx in stack/btm_api.h -#define ESP_LE_AUTH_NO_BOND 0x00 /*!< 0 no bondingv*/ -#define ESP_LE_AUTH_BOND 0x01 /*!< 1 << 0 device in the bonding with peer */ -#define ESP_LE_AUTH_REQ_MITM (1 << 2) /*!< 1 << 2 man in the middle attack */ -#define ESP_LE_AUTH_REQ_BOND_MITM (ESP_LE_AUTH_BOND | ESP_LE_AUTH_REQ_MITM) /*!< 0101 banding with man in the middle attack */ -#define ESP_LE_AUTH_REQ_SC_ONLY (1 << 3) /*!< 1 << 3 secure connection */ -#define ESP_LE_AUTH_REQ_SC_BOND (ESP_LE_AUTH_BOND | ESP_LE_AUTH_REQ_SC_ONLY) /*!< 1001 secure connection with band*/ -#define ESP_LE_AUTH_REQ_SC_MITM (ESP_LE_AUTH_REQ_MITM | ESP_LE_AUTH_REQ_SC_ONLY) /*!< 1100 secure conn with MITM */ -#define ESP_LE_AUTH_REQ_SC_MITM_BOND (ESP_LE_AUTH_REQ_MITM | ESP_LE_AUTH_REQ_SC_ONLY | ESP_LE_AUTH_BOND) /*!< 1101 SC with MITM and Bonding*/ -typedef uint8_t esp_ble_auth_req_t; /*!< combination of the above bit pattern */ - -#define ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_DISABLE 0 /*!< authentication disable*/ -#define ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_ENABLE 1 /*!< authentication enable*/ - -#define ESP_BLE_OOB_DISABLE 0 /*!< disable the out of bond*/ -#define ESP_BLE_OOB_ENABLE 1 /*!< enable the out of bond*/ - -/// relate to BTM_IO_CAP_xxx in stack/btm_api.h -#define ESP_IO_CAP_OUT 0 /*!< DisplayOnly */ -#define ESP_IO_CAP_IO 1 /*!< DisplayYesNo */ -#define ESP_IO_CAP_IN 2 /*!< KeyboardOnly */ -#define ESP_IO_CAP_NONE 3 /*!< NoInputNoOutput */ -#define ESP_IO_CAP_KBDISP 4 /*!< Keyboard display */ - -#define ESP_BLE_APPEARANCE_UNKNOWN 0x0000 /*!< relate to BTM_BLE_APPEARANCE_UNKNOWN in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_PHONE 0x0040 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_PHONE in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_COMPUTER 0x0080 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_COMPUTER in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_WATCH 0x00C0 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_WATCH in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_SPORTS_WATCH 0x00C1 /*!< relate to BTM_BLE_APPEARANCE_SPORTS_WATCH in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_CLOCK 0x0100 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_CLOCK in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_DISPLAY 0x0140 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_DISPLAY in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_REMOTE 0x0180 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_REMOTE in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_EYEGLASSES 0x01C0 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_EYEGLASSES in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_TAG 0x0200 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_TAG in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_KEYRING 0x0240 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_KEYRING in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_MEDIA_PLAYER 0x0280 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_MEDIA_PLAYER in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_BARCODE_SCANNER 0x02C0 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_BARCODE_SCANNER in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_THERMOMETER 0x0300 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_THERMOMETER in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_THERMOMETER_EAR 0x0301 /*!< relate to BTM_BLE_APPEARANCE_THERMOMETER_EAR in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_HEART_RATE 0x0340 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_HEART_RATE in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_HEART_RATE_BELT 0x0341 /*!< relate to BTM_BLE_APPEARANCE_HEART_RATE_BELT in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE 0x0380 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_BLOOD_PRESSURE_ARM 0x0381 /*!< relate to BTM_BLE_APPEARANCE_BLOOD_PRESSURE_ARM in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_BLOOD_PRESSURE_WRIST 0x0382 /*!< relate to BTM_BLE_APPEARANCE_BLOOD_PRESSURE_WRIST in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_HID 0x03C0 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_HID in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_HID_KEYBOARD 0x03C1 /*!< relate to BTM_BLE_APPEARANCE_HID_KEYBOARD in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_HID_MOUSE 0x03C2 /*!< relate to BTM_BLE_APPEARANCE_HID_MOUSE in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_HID_JOYSTICK 0x03C3 /*!< relate to BTM_BLE_APPEARANCE_HID_JOYSTICK in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_HID_GAMEPAD 0x03C4 /*!< relate to BTM_BLE_APPEARANCE_HID_GAMEPAD in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_HID_DIGITIZER_TABLET 0x03C5 /*!< relate to BTM_BLE_APPEARANCE_HID_DIGITIZER_TABLET in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_HID_CARD_READER 0x03C6 /*!< relate to BTM_BLE_APPEARANCE_HID_CARD_READER in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_HID_DIGITAL_PEN 0x03C7 /*!< relate to BTM_BLE_APPEARANCE_HID_DIGITAL_PEN in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_HID_BARCODE_SCANNER 0x03C8 /*!< relate to BTM_BLE_APPEARANCE_HID_BARCODE_SCANNER in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_GLUCOSE 0x0400 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_GLUCOSE in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_WALKING 0x0440 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_WALKING in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_WALKING_IN_SHOE 0x0441 /*!< relate to BTM_BLE_APPEARANCE_WALKING_IN_SHOE in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_WALKING_ON_SHOE 0x0442 /*!< relate to BTM_BLE_APPEARANCE_WALKING_ON_SHOE in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_WALKING_ON_HIP 0x0443 /*!< relate to BTM_BLE_APPEARANCE_WALKING_ON_HIP in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_CYCLING 0x0480 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_CYCLING in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_CYCLING_COMPUTER 0x0481 /*!< relate to BTM_BLE_APPEARANCE_CYCLING_COMPUTER in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_CYCLING_SPEED 0x0482 /*!< relate to BTM_BLE_APPEARANCE_CYCLING_SPEED in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_CYCLING_CADENCE 0x0483 /*!< relate to BTM_BLE_APPEARANCE_CYCLING_CADENCE in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_CYCLING_POWER 0x0484 /*!< relate to BTM_BLE_APPEARANCE_CYCLING_POWER in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_CYCLING_SPEED_CADENCE 0x0485 /*!< relate to BTM_BLE_APPEARANCE_CYCLING_SPEED_CADENCE in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_STANDALONE_SPEAKER 0x0841 /*!< relate to BTM_BLE_APPEARANCE_STANDALONE_SPEAKER in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_PULSE_OXIMETER 0x0C40 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_PULSE_OXIMETER in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_PULSE_OXIMETER_FINGERTIP 0x0C41 /*!< relate to BTM_BLE_APPEARANCE_PULSE_OXIMETER_FINGERTIP in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_PULSE_OXIMETER_WRIST 0x0C42 /*!< relate to BTM_BLE_APPEARANCE_PULSE_OXIMETER_WRIST in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_WEIGHT 0x0C80 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_WEIGHT in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_PERSONAL_MOBILITY_DEVICE 0x0CC0 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_PERSONAL_MOBILITY_DEVICE in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_POWERED_WHEELCHAIR 0x0CC1 /*!< relate to BTM_BLE_APPEARANCE_POWERED_WHEELCHAIR in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_MOBILITY_SCOOTER 0x0CC2 /*!< relate to BTM_BLE_APPEARANCE_MOBILITY_SCOOTER in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_CONTINUOUS_GLUCOSE_MONITOR 0x0D00 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_CONTINUOUS_GLUCOSE_MONITOR in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_INSULIN_PUMP 0x0D40 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_INSULIN_PUMP in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_INSULIN_PUMP_DURABLE_PUMP 0x0D41 /*!< relate to BTM_BLE_APPEARANCE_INSULIN_PUMP_DURABLE_PUMP in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_INSULIN_PUMP_PATCH_PUMP 0x0D44 /*!< relate to BTM_BLE_APPEARANCE_INSULIN_PUMP_PATCH_PUMP in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_INSULIN_PEN 0x0D48 /*!< relate to BTM_BLE_APPEARANCE_INSULIN_PEN in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_MEDICATION_DELIVERY 0x0D80 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_MEDICATION_DELIVERY in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_GENERIC_OUTDOOR_SPORTS 0x1440 /*!< relate to BTM_BLE_APPEARANCE_GENERIC_OUTDOOR_SPORTS in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION 0x1441 /*!< relate to BTM_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_AND_NAV 0x1442 /*!< relate to BTM_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_AND_NAV in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD 0x1443 /*!< relate to BTM_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD in stack/btm_ble_api.h */ -#define ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD_AND_NAV 0x1444 /*!< relate to BTM_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD_AND_NAV in stack/btm_ble_api.h */ +// These macros are used in setting the advertising data. +#define ESP_BLE_ADV_FLAG_LIMIT_DISC (0x01 << 0) /*!< Limited Discoverable Mode: Device is in limited discoverable mode. */ +#define ESP_BLE_ADV_FLAG_GEN_DISC (0x01 << 1) /*!< General Discoverable Mode: Device is in general discoverable mode. */ +#define ESP_BLE_ADV_FLAG_BREDR_NOT_SPT (0x01 << 2) /*!< BR/EDR Not Supported: Device does not support Basic Rate or Enhanced Data Rate. */ +#define ESP_BLE_ADV_FLAG_DMT_CONTROLLER_SPT (0x01 << 3) /*!< Dual-Mode Controller Supported: Device's controller supports both LE and BR/EDR. */ +#define ESP_BLE_ADV_FLAG_DMT_HOST_SPT (0x01 << 4) /*!< Dual-Mode Host Supported: Device's host supports both LE and BR/EDR. */ +#define ESP_BLE_ADV_FLAG_NON_LIMIT_DISC (0x00) /*!< Non-Limited Discoverable Mode: Device is not in limited discoverable mode. */ + +/* + These macros are used in describing different types of keys used in communication and security protocols. + Relates to BTM_LE_KEY_xxx in stack/btm_api.h (Reserved for internal use). +*/ +#define ESP_LE_KEY_NONE 0 /*!< No encryption key. */ +#define ESP_LE_KEY_PENC (1 << 0) /*!< Peer Encryption Key: Used for encrypting communication, containing encryption information of the peer device. */ +#define ESP_LE_KEY_PID (1 << 1) /*!< Peer Identity Resolving Key (IRK): Used for resolving the identity of the peer device. */ +#define ESP_LE_KEY_PCSRK (1 << 2) /*!< Peer Connection Signature Resolving Key (CSRK): Used for verifying the authenticity of signed data from the peer device. */ +#define ESP_LE_KEY_PLK (1 << 3) /*!< Peer Link Key: A key used to establish a secure connection with the peer device. */ +#define ESP_LE_KEY_LLK (ESP_LE_KEY_PLK << 4) /*!< Local Link Key: Equivalent to the peer link key, used in local device for secure connections. */ +#define ESP_LE_KEY_LENC (ESP_LE_KEY_PENC << 4) /*!< Local Encryption Key: Encryption key for the local device, providing master role security information. */ +#define ESP_LE_KEY_LID (ESP_LE_KEY_PID << 4) /*!< Local Identity Key: Identity key for the local device, used as the master device ID key. */ +#define ESP_LE_KEY_LCSRK (ESP_LE_KEY_PCSRK << 4) /*!< Local Connection Signature Resolving Key (CSRK): Indicates that the local CSRK has been delivered to the peer device. */ +typedef uint8_t esp_ble_key_type_t; /*!< Type definition for key types. */ + +/* + These macros are used in defining the BLE authentication requirements. + Relates to BTM_LE_AUTH_xxx in stack/btm_api.h (Reserved for internal use). +*/ +#define ESP_LE_AUTH_NO_BOND 0x00 /*!< No bonding required: Devices will not store pairing information for future connections. */ +#define ESP_LE_AUTH_BOND 0x01 /*!< Bonding: Device is bonded with the peer, storing pairing information for future secure connections. */ +#define ESP_LE_AUTH_REQ_MITM (1 << 2) /*!< Man-in-the-Middle (MITM) protection required: Ensures that the communication channel is secure from eavesdropping and tampering. */ +#define ESP_LE_AUTH_REQ_BOND_MITM (ESP_LE_AUTH_BOND | ESP_LE_AUTH_REQ_MITM) /*!< Bonding with MITM Protection: Devices are bonded and the connection is protected against MITM attacks.*/ +#define ESP_LE_AUTH_REQ_SC_ONLY (1 << 3) /*!< Secure Connections (SC) only: Uses Secure Connections for stronger security compared to Legacy Pairing. */ +#define ESP_LE_AUTH_REQ_SC_BOND (ESP_LE_AUTH_BOND | ESP_LE_AUTH_REQ_SC_ONLY) /*!< Bonding with Secure Connections: Devices are bonded using Secure Connections. */ +#define ESP_LE_AUTH_REQ_SC_MITM (ESP_LE_AUTH_REQ_MITM | ESP_LE_AUTH_REQ_SC_ONLY) /*!< Secure Connections with MITM Protection: Ensures the connection uses Secure Connections and is protected against MITM attacks. */ +#define ESP_LE_AUTH_REQ_SC_MITM_BOND (ESP_LE_AUTH_REQ_MITM | ESP_LE_AUTH_REQ_SC_ONLY | ESP_LE_AUTH_BOND) /*!< Secure Connections with MITM Protection and Bonding: Devices are bonded using Secure Connections and are protected against MITM attacks. */ +typedef uint8_t esp_ble_auth_req_t; /*!< Type definition for Bluetooth Low Energy authentication requirements. */ + +// These macros are used in settings for authentication enable or disable. +#define ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_DISABLE 0 /*!< Authentication disabled. */ +#define ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_ENABLE 1 /*!< Authentication enabled. */ + +// These macros are used in settings for Out of Band data authentication enable or disable. +#define ESP_BLE_OOB_DISABLE 0 /*!< Out of Band data authentication disabled. */ +#define ESP_BLE_OOB_ENABLE 1 /*!< Out of Band data authentication enabled. */ +/* + These macros define the various input/output capabilities. + Relate to BTM_IO_CAP_xxx in stack/btm_api.h (Reserved for internal use). +*/ +#define ESP_IO_CAP_OUT 0 /*!< Display Only: Device has output capabilities only, typically a display. */ +#define ESP_IO_CAP_IO 1 /*!< Display and Yes/No Input: Device has both output capabilities (display) and simple input capabilities (Yes/No buttons). */ +#define ESP_IO_CAP_IN 2 /*!< Keyboard Only: Device has input capabilities only, typically a keyboard. */ +#define ESP_IO_CAP_NONE 3 /*!< No Input and No Output: Device has neither input nor output capabilities. */ +#define ESP_IO_CAP_KBDISP 4 /*!< Keyboard and Display: Device has both input capabilities (keyboard) and output capabilities (display). */ + +//These macros define the appearance. +#define ESP_BLE_APPEARANCE_UNKNOWN 0x0000 /*!< Device appearance is unknown. Relates to BTM_BLE_APPEARANCE_UNKNOWN in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_PHONE 0x0040 /*!< Generic phone. Relates to BTM_BLE_APPEARANCE_GENERIC_PHONE in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_COMPUTER 0x0080 /*!< Generic computer. Relates to BTM_BLE_APPEARANCE_GENERIC_COMPUTER in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_WATCH 0x00C0 /*!< Generic watch. Relates to BTM_BLE_APPEARANCE_GENERIC_WATCH in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_SPORTS_WATCH 0x00C1 /*!< Sports watch. Relates to BTM_BLE_APPEARANCE_SPORTS_WATCH in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_CLOCK 0x0100 /*!< Generic clock. Relates to BTM_BLE_APPEARANCE_GENERIC_CLOCK in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_DISPLAY 0x0140 /*!< Generic display. Relates to BTM_BLE_APPEARANCE_GENERIC_DISPLAY in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_REMOTE 0x0180 /*!< Generic remote. Relates to BTM_BLE_APPEARANCE_GENERIC_REMOTE in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_EYEGLASSES 0x01C0 /*!< Generic eyeglasses. Relates to BTM_BLE_APPEARANCE_GENERIC_EYEGLASSES in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_TAG 0x0200 /*!< Generic tag. Relates to BTM_BLE_APPEARANCE_GENERIC_TAG in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_KEYRING 0x0240 /*!< Generic keyring. Relates to BTM_BLE_APPEARANCE_GENERIC_KEYRING in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_MEDIA_PLAYER 0x0280 /*!< Generic barcode scanner. Relates to BTM_BLE_APPEARANCE_GENERIC_MEDIA_PLAYER in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_BARCODE_SCANNER 0x02C0 /*!< Generic thermometer. Relates to BTM_BLE_APPEARANCE_GENERIC_BARCODE_SCANNER in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_THERMOMETER 0x0300 /*!< Generic thermometer. Relates to BTM_BLE_APPEARANCE_GENERIC_THERMOMETER in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_THERMOMETER_EAR 0x0301 /*!< Thermometer (ear). Relates to BTM_BLE_APPEARANCE_THERMOMETER_EAR in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_HEART_RATE 0x0340 /*!< Generic heart rate monitor. Relates to BTM_BLE_APPEARANCE_GENERIC_HEART_RATE in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_HEART_RATE_BELT 0x0341 /*!< Heart rate monitor (belt). Relates to BTM_BLE_APPEARANCE_HEART_RATE_BELT in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE 0x0380 /*!< Generic blood pressure monitor. Relates to BTM_BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_BLOOD_PRESSURE_ARM 0x0381 /*!< Blood pressure monitor (arm). Relates to BTM_BLE_APPEARANCE_BLOOD_PRESSURE_ARM in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_BLOOD_PRESSURE_WRIST 0x0382 /*!< Blood pressure monitor (wrist). Relates to BTM_BLE_APPEARANCE_BLOOD_PRESSURE_WRIST in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_HID 0x03C0 /*!< Generic HID (Human Interface Device). Relates to BTM_BLE_APPEARANCE_GENERIC_HID in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_HID_KEYBOARD 0x03C1 /*!< HID keyboard. Relates to BTM_BLE_APPEARANCE_HID_KEYBOARD in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_HID_MOUSE 0x03C2 /*!< HID mouse. Relates to BTM_BLE_APPEARANCE_HID_MOUSE in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_HID_JOYSTICK 0x03C3 /*!< HID joystick. Relates to BTM_BLE_APPEARANCE_HID_JOYSTICK in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_HID_GAMEPAD 0x03C4 /*!< HID game pad. Relates to BTM_BLE_APPEARANCE_HID_GAMEPAD in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_HID_DIGITIZER_TABLET 0x03C5 /*!< HID digitizer tablet. Relates to BTM_BLE_APPEARANCE_HID_DIGITIZER_TABLET in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_HID_CARD_READER 0x03C6 /*!< HID card reader. Relates to BTM_BLE_APPEARANCE_HID_CARD_READER in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_HID_DIGITAL_PEN 0x03C7 /*!< HID digital pen. Relates to BTM_BLE_APPEARANCE_HID_DIGITAL_PEN in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_HID_BARCODE_SCANNER 0x03C8 /*!< HID barcode scanner. Relates to BTM_BLE_APPEARANCE_HID_BARCODE_SCANNER in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_GLUCOSE 0x0400 /*!< Generic glucose meter. Relates to BTM_BLE_APPEARANCE_GENERIC_GLUCOSE in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_WALKING 0x0440 /*!< Generic pedometer. Relates to BTM_BLE_APPEARANCE_GENERIC_WALKING in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_WALKING_IN_SHOE 0x0441 /*!< Pedometer (in shoe). Relates to BTM_BLE_APPEARANCE_WALKING_IN_SHOE in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_WALKING_ON_SHOE 0x0442 /*!< Pedometer (on shoe). Relates to BTM_BLE_APPEARANCE_WALKING_ON_SHOE in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_WALKING_ON_HIP 0x0443 /*!< Pedometer (on hip). Relates to BTM_BLE_APPEARANCE_WALKING_ON_HIP in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_CYCLING 0x0480 /*!< Generic cycling device. Relates to BTM_BLE_APPEARANCE_GENERIC_CYCLING in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_CYCLING_COMPUTER 0x0481 /*!< Cycling computer. Relates to BTM_BLE_APPEARANCE_CYCLING_COMPUTER in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_CYCLING_SPEED 0x0482 /*!< Cycling speed sensor. Relates to BTM_BLE_APPEARANCE_CYCLING_SPEED in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_CYCLING_CADENCE 0x0483 /*!< Cycling cadence sensor. Relates to BTM_BLE_APPEARANCE_CYCLING_CADENCE in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_CYCLING_POWER 0x0484 /*!< Cycling power meter. Relates to BTM_BLE_APPEARANCE_CYCLING_POWER in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_CYCLING_SPEED_CADENCE 0x0485 /*!< Cycling speed and cadence sensor. Relates to BTM_BLE_APPEARANCE_CYCLING_SPEED_CADENCE in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_STANDALONE_SPEAKER 0x0841 /*!< Standalone speaker. Relates to BTM_BLE_APPEARANCE_STANDALONE_SPEAKER in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_PULSE_OXIMETER 0x0C40 /*!< Generic pulse oxi meter. Relates to BTM_BLE_APPEARANCE_GENERIC_PULSE_OXIMETER in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_PULSE_OXIMETER_FINGERTIP 0x0C41 /*!< Pulse oxi meter (fingertip). Relates to BTM_BLE_APPEARANCE_PULSE_OXIMETER_FINGERTIP in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_PULSE_OXIMETER_WRIST 0x0C42 /*!< Pulse oxi meter (wrist). Relates to BTM_BLE_APPEARANCE_PULSE_OXIMETER_WRIST in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_WEIGHT 0x0C80 /*!< Generic weight scale. Relates to BTM_BLE_APPEARANCE_GENERIC_WEIGHT in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_PERSONAL_MOBILITY_DEVICE 0x0CC0 /*!< Generic personal mobility device. Relates to BTM_BLE_APPEARANCE_GENERIC_PERSONAL_MOBILITY_DEVICE in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_POWERED_WHEELCHAIR 0x0CC1 /*!< Powered wheelchair. Relates to BTM_BLE_APPEARANCE_POWERED_WHEELCHAIR in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_MOBILITY_SCOOTER 0x0CC2 /*!< Mobility scooter. Relates to BTM_BLE_APPEARANCE_MOBILITY_SCOOTER in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_CONTINUOUS_GLUCOSE_MONITOR 0x0D00 /*!< Generic continuous glucose monitor. Relates to BTM_BLE_APPEARANCE_GENERIC_CONTINUOUS_GLUCOSE_MONITOR in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_INSULIN_PUMP 0x0D40 /*!< Generic insulin pump. Relates to BTM_BLE_APPEARANCE_GENERIC_INSULIN_PUMP in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_INSULIN_PUMP_DURABLE_PUMP 0x0D41 /*!< Insulin pump (durable). Relates to BTM_BLE_APPEARANCE_INSULIN_PUMP_DURABLE_PUMP in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_INSULIN_PUMP_PATCH_PUMP 0x0D44 /*!< Insulin pump (patch). Relates to BTM_BLE_APPEARANCE_INSULIN_PUMP_PATCH_PUMP in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_INSULIN_PEN 0x0D48 /*!< Insulin pen. Relates to BTM_BLE_APPEARANCE_INSULIN_PEN in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_MEDICATION_DELIVERY 0x0D80 /*!< Generic medication delivery device. Relates to BTM_BLE_APPEARANCE_GENERIC_MEDICATION_DELIVERY in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_GENERIC_OUTDOOR_SPORTS 0x1440 /*!< Generic outdoor sports device. Relates to BTM_BLE_APPEARANCE_GENERIC_OUTDOOR_SPORTS in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION 0x1441 /*!< Outdoor sports device with location. Relates to BTM_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_AND_NAV 0x1442 /*!< Outdoor sports device with location and navigation. Relates to BTM_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_AND_NAV in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD 0x1443 /*!< Outdoor sports location pod. Relates to BTM_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD in stack/btm_ble_api.h (Reserved for internal use). */ +#define ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD_AND_NAV 0x1444 /*!< Outdoor sports location pod with navigation. Relates to BTM_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD_AND_NAV in stack/btm_ble_api.h (Reserved for internal use). */ typedef uint8_t esp_ble_io_cap_t; /*!< combination of the io capability */ -#define BLE_DTM_PKT_PAYLOAD_0x00 0x00 /*!< PRBS9 sequence ‘11111111100000111101...’ (in transmission order) as described in [Vol 6] Part F, Section 4.1.5 */ -#define BLE_DTM_PKT_PAYLOAD_0x01 0x01 /*!< Repeated ‘11110000’ (in transmission order) sequence as described in [Vol 6] Part F, Section 4.1.5 */ -#define BLE_DTM_PKT_PAYLOAD_0x02 0x02 /*!< Repeated ‘10101010’ (in transmission order) sequence as described in [Vol 6] Part F, Section 4.1.5 */ -#define BLE_DTM_PKT_PAYLOAD_0x03 0x03 /*!< PRBS15 sequence as described in [Vol 6] Part F, Section 4.1.5 */ -#define BLE_DTM_PKT_PAYLOAD_0x04 0x04 /*!< Repeated ‘11111111’ (in transmission order) sequence */ -#define BLE_DTM_PKT_PAYLOAD_0x05 0x05 /*!< Repeated ‘00000000’ (in transmission order) sequence */ -#define BLE_DTM_PKT_PAYLOAD_0x06 0x06 /*!< Repeated ‘00001111’ (in transmission order) sequence */ -#define BLE_DTM_PKT_PAYLOAD_0x07 0x07 /*!< Repeated ‘01010101’ (in transmission order) sequence */ -#define BLE_DTM_PKT_PAYLOAD_MAX 0x08 /*!< 0x08 ~ 0xFF, Reserved for future use */ +// These macros define the Direct Test Mode (DTM) testing. +#define BLE_DTM_PKT_PAYLOAD_0x00 0x00 /*!< This is used for Direct Test Mode (DTM) testing to ensure accurate data transmission. Pseudo-Random Binary Sequence 9 (PRBS9) sequence '11111111100000111101...' (in transmission order) as described in [Vol 6] Part F, Section 4.1.5. */ +#define BLE_DTM_PKT_PAYLOAD_0x01 0x01 /*!< This is a fixed pattern used in DTM testing to check the receiver's bit error rate. repeated '11110000' */ +#define BLE_DTM_PKT_PAYLOAD_0x02 0x02 /*!< This pattern is also used for DTM testing, providing an alternating bit sequence. repeated '10101010' */ +#define BLE_DTM_PKT_PAYLOAD_0x03 0x03 /*!< This provides a longer pseudo-random sequence for more rigorous DTM testing. Pseudo-Random Binary Sequence 15 (PRBS15) sequence */ +#define BLE_DTM_PKT_PAYLOAD_0x04 0x04 /*!< This sequence is used in DTM to test continuous transmission of high bits. Repeated '11111111' (in transmission order) sequence. */ +#define BLE_DTM_PKT_PAYLOAD_0x05 0x05 /*!< This sequence tests continuous transmission of low bits in DTM. Repeated '00000000' (in transmission order) sequence. */ +#define BLE_DTM_PKT_PAYLOAD_0x06 0x06 /*!< This pattern is used for DTM testing to verify the receiver's ability to handle different bit patterns. Repeated '00001111' (in transmission order) sequence. */ +#define BLE_DTM_PKT_PAYLOAD_0x07 0x07 /*!< This alternating pattern is used in DTM to test receiver performance with rapid bit changes. Repeated '01010101' (in transmission order) sequence. */ +#define BLE_DTM_PKT_PAYLOAD_MAX 0x08 /*!< Any value from 0x08 to 0xFF is not currently used and is reserved for potential future extensions to the DTM packet payloads. Reserved for future use. */ +typedef uint8_t esp_ble_dtm_pkt_payload_t; /*!< Bluetooth Low Energy Direct Test Mode Packet Payload Type */ -typedef uint8_t esp_ble_dtm_pkt_payload_t; -/// GAP BLE callback event type +/** + * @brief Generic access profile Bluetooth LE callback event type + */ typedef enum { - //BLE_42_FEATURE_SUPPORT - ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT = 0, /*!< When advertising data set complete, the event comes */ - ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT, /*!< When scan response data set complete, the event comes */ - ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT, /*!< When scan parameters set complete, the event comes */ - ESP_GAP_BLE_SCAN_RESULT_EVT, /*!< When one scan result ready, the event comes each time */ - ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT, /*!< When raw advertising data set complete, the event comes */ - ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT, /*!< When raw scan response data set complete, the event comes */ - ESP_GAP_BLE_ADV_START_COMPLETE_EVT, /*!< When start advertising complete, the event comes */ - ESP_GAP_BLE_SCAN_START_COMPLETE_EVT, /*!< When start scan complete, the event comes */ - //BLE_INCLUDED - ESP_GAP_BLE_AUTH_CMPL_EVT = 8, /*!< Authentication complete indication. */ - ESP_GAP_BLE_KEY_EVT, /*!< BLE key event for peer device keys */ - ESP_GAP_BLE_SEC_REQ_EVT, /*!< BLE security request */ - ESP_GAP_BLE_PASSKEY_NOTIF_EVT, /*!< passkey notification event */ - ESP_GAP_BLE_PASSKEY_REQ_EVT, /*!< passkey request event */ - ESP_GAP_BLE_OOB_REQ_EVT, /*!< OOB request event */ - ESP_GAP_BLE_LOCAL_IR_EVT, /*!< BLE local IR (identity Root 128-bit random static value used to generate Long Term Key) event */ - ESP_GAP_BLE_LOCAL_ER_EVT, /*!< BLE local ER (Encryption Root value used to generate identity resolving key) event */ - ESP_GAP_BLE_NC_REQ_EVT, /*!< Numeric Comparison request event */ - //BLE_42_FEATURE_SUPPORT - ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT, /*!< When stop adv complete, the event comes */ - ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT, /*!< When stop scan complete, the event comes */ - //BLE_INCLUDED - ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT = 19, /*!< When set the static rand address complete, the event comes */ - ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT, /*!< When update connection parameters complete, the event comes */ - ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT, /*!< When set pkt length complete, the event comes */ - ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT, /*!< When Enable/disable privacy on the local device complete, the event comes */ - ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT, /*!< When remove the bond device complete, the event comes */ - ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT, /*!< When clear the bond device clear complete, the event comes */ - ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT, /*!< When get the bond device list complete, the event comes */ - ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT, /*!< When read the rssi complete, the event comes */ - ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT, /*!< When add or remove whitelist complete, the event comes */ - //BLE_42_FEATURE_SUPPORT - ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT, /*!< When update duplicate exceptional list complete, the event comes */ - //BLE_INCLUDED - ESP_GAP_BLE_SET_CHANNELS_EVT = 29, /*!< When setting BLE channels complete, the event comes */ - //BLE_50_FEATURE_SUPPORT - ESP_GAP_BLE_READ_PHY_COMPLETE_EVT, /*!< when reading phy complete, this event comes */ - ESP_GAP_BLE_SET_PREFERRED_DEFAULT_PHY_COMPLETE_EVT, /*!< when preferred default phy complete, this event comes */ - ESP_GAP_BLE_SET_PREFERRED_PHY_COMPLETE_EVT, /*!< when preferred phy complete , this event comes */ - ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT, /*!< when extended set random address complete, the event comes */ - ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT, /*!< when extended advertising parameter complete, the event comes */ - ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT, /*!< when extended advertising data complete, the event comes */ - ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT, /*!< when extended scan response data complete, the event comes */ - ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT, /*!< when extended advertising start complete, the event comes */ - ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT, /*!< when extended advertising stop complete, the event comes */ - ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT, /*!< when extended advertising set remove complete, the event comes */ - ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT, /*!< when extended advertising set clear complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT, /*!< when periodic advertising parameter complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT, /*!< when periodic advertising data complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT, /*!< when periodic advertising start complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT, /*!< when periodic advertising stop complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT, /*!< when periodic advertising create sync complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT, /*!< when extended advertising sync cancel complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLETE_EVT, /*!< when extended advertising sync terminate complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT, /*!< when extended advertising add device complete , the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT, /*!< when extended advertising remove device complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT, /*!< when extended advertising clear device, the event comes */ - ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETE_EVT, /*!< when extended scan parameter complete, the event comes */ - ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT, /*!< when extended scan start complete, the event comes */ - ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT, /*!< when extended scan stop complete, the event comes */ - ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETE_EVT, /*!< when extended prefer connection parameter set complete, the event comes */ - ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT, /*!< when ble phy update complete, the event comes */ - ESP_GAP_BLE_EXT_ADV_REPORT_EVT, /*!< when extended advertising report complete, the event comes */ - ESP_GAP_BLE_SCAN_TIMEOUT_EVT, /*!< when scan timeout complete, the event comes */ - ESP_GAP_BLE_ADV_TERMINATED_EVT, /*!< when advertising terminate data complete, the event comes */ - ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT, /*!< when scan req received complete, the event comes */ - ESP_GAP_BLE_CHANNEL_SELECT_ALGORITHM_EVT, /*!< when channel select algorithm complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT, /*!< when periodic report advertising complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT, /*!< when periodic advertising sync lost complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVT, /*!< when periodic advertising sync establish complete, the event comes */ - //BLE_INCLUDED - ESP_GAP_BLE_SC_OOB_REQ_EVT, /*!< Secure Connection OOB request event */ - ESP_GAP_BLE_SC_CR_LOC_OOB_EVT, /*!< Secure Connection create OOB data complete event */ - ESP_GAP_BLE_GET_DEV_NAME_COMPLETE_EVT, /*!< When getting BT device name complete, the event comes */ - //BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER - ESP_GAP_BLE_PERIODIC_ADV_RECV_ENABLE_COMPLETE_EVT, /*!< when set periodic advertising receive enable complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_SYNC_TRANS_COMPLETE_EVT, /*!< when periodic advertising sync transfer complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_SET_INFO_TRANS_COMPLETE_EVT, /*!< when periodic advertising set info transfer complete, the event comes */ - ESP_GAP_BLE_SET_PAST_PARAMS_COMPLETE_EVT, /*!< when set periodic advertising sync transfer params complete, the event comes */ - ESP_GAP_BLE_PERIODIC_ADV_SYNC_TRANS_RECV_EVT, /*!< when periodic advertising sync transfer received, the event comes */ - // DTM - ESP_GAP_BLE_DTM_TEST_UPDATE_EVT, /*!< when direct test mode state changes, the event comes */ - // BLE_INCLUDED - ESP_GAP_BLE_ADV_CLEAR_COMPLETE_EVT, /*!< When clear advertising complete, the event comes */ - ESP_GAP_BLE_SET_RPA_TIMEOUT_COMPLETE_EVT, /*!< When set the Resolvable Private Address (RPA) timeout completes, the event comes */ - ESP_GAP_BLE_ADD_DEV_TO_RESOLVING_LIST_COMPLETE_EVT, /*!< when add a device to the resolving list completes, the event comes*/ - ESP_GAP_BLE_VENDOR_CMD_COMPLETE_EVT, /*!< When vendor hci command complete, the event comes */ - ESP_GAP_BLE_SET_PRIVACY_MODE_COMPLETE_EVT, /*!< When set privacy mode complete, the event comes */ - ESP_GAP_BLE_EVT_MAX, /*!< when maximum advertising event complete, the event comes */ +//@{ +/** BLE_42_FEATURE_SUPPORT */ + ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT = 0, /*!< When advertising data set complete, the event comes. */ + ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT, /*!< When scan response data set complete, the event comes. */ + ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT, /*!< When scan parameters set complete, the event comes. */ + ESP_GAP_BLE_SCAN_RESULT_EVT, /*!< When one scan result ready, the event comes each time. */ + ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT, /*!< When raw advertising data set complete, the event comes. */ + ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT, /*!< When raw scan response data set complete, the event comes. */ + ESP_GAP_BLE_ADV_START_COMPLETE_EVT, /*!< When start advertising complete, the event comes. */ + ESP_GAP_BLE_SCAN_START_COMPLETE_EVT, /*!< When start scan complete, the event comes. */ +//@} +//@{ +/** BLE_INCLUDED */ + ESP_GAP_BLE_AUTH_CMPL_EVT = 8, /*!< When authentication completes, this event is generated. */ + ESP_GAP_BLE_KEY_EVT, /*!< When bluetooth low energy peer device keys are available, this event occurs. */ + ESP_GAP_BLE_SEC_REQ_EVT, /*!< When a bluetooth low energy security request is made, this event is generated. */ + ESP_GAP_BLE_PASSKEY_NOTIF_EVT, /*!< When a passkey notification is received, this event occurs. */ + ESP_GAP_BLE_PASSKEY_REQ_EVT, /*!< When a passkey request is initiated, this event is generated. */ + ESP_GAP_BLE_OOB_REQ_EVT, /*!< When an Out-of-Band (OOB) request is made, this event occurs. */ + ESP_GAP_BLE_LOCAL_IR_EVT, /*!< When the BLE local IR (Identity Root) event occurs, this event is generated. */ + ESP_GAP_BLE_LOCAL_ER_EVT, /*!< When the BLE local ER (Encryption Root) event occurs, this event is generated. */ + ESP_GAP_BLE_NC_REQ_EVT, /*!< When a Numeric Comparison request is made, this event occurs. */ +//@} +//@{ +/** BLE_42_FEATURE_SUPPORT */ + ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT, /*!< When stop advertisement complete, the event comes. */ + ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT, /*!< When stop scan complete, the event comes. */ +//@} +//@{ +/** BLE_INCLUDED */ + ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT = 19, /*!< When set the static rand address complete, the event comes. */ + ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT, /*!< When update connection parameters complete, the event comes. */ + ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT, /*!< When set packet length complete, the event comes. */ + ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT, /*!< When Enable/disable privacy on the local device complete, the event comes. */ + ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT, /*!< When remove the bond device complete, the event comes. */ + ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT, /*!< When clear the bond device clear complete, the event comes. */ + ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT, /*!< When get the bond device list complete, the event comes. */ + ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT, /*!< When read the received signal strength indication complete, the event comes. */ + ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT, /*!< When add or remove whitelist complete, the event comes. */ +//@} +//@{ +/** BLE_42_FEATURE_SUPPORT */ + ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT, /*!< When update duplicate exceptional list complete, the event comes. */ +//@} +//@{ +/** BLE_INCLUDED */ + ESP_GAP_BLE_SET_CHANNELS_EVT = 29, /*!< When setting bluetooth low energy channels complete, the event comes. */ +//@} +//@{ +/** BLE_50_FEATURE_SUPPORT */ + ESP_GAP_BLE_READ_PHY_COMPLETE_EVT, /*!< When reading physical layer (phy) complete, this event comes. */ + ESP_GAP_BLE_SET_PREFERRED_DEFAULT_PHY_COMPLETE_EVT, /*!< When preferred default physical layer complete, this event comes. */ + ESP_GAP_BLE_SET_PREFERRED_PHY_COMPLETE_EVT, /*!< When preferred physical layer complete , this event comes. */ + ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT, /*!< When extended set random address complete, the event comes. */ + ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT, /*!< When extended advertising parameter complete, the event comes. */ + ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT, /*!< When extended advertising data complete, the event comes. */ + ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT, /*!< When extended scan response data complete, the event comes. */ + ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT, /*!< When extended advertising start complete, the event comes. */ + ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT, /*!< When extended advertising stop complete, the event comes. */ + ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT, /*!< When extended advertising set remove complete, the event comes. */ + ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT, /*!< When extended advertising set clear complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT, /*!< When periodic advertising parameter complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT, /*!< When periodic advertising data complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT, /*!< When periodic advertising start complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT, /*!< When periodic advertising stop complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT, /*!< When periodic advertising create synchronize complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT, /*!< When extended advertising synchronize cancel complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLETE_EVT, /*!< When extended advertising synchronize terminate complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT, /*!< When extended advertising add device complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT, /*!< When extended advertising remove device complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT, /*!< When extended advertising clear device, the event comes. */ + ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETE_EVT, /*!< When extended scan parameter complete, the event comes. */ + ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT, /*!< When extended scan start complete, the event comes. */ + ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT, /*!< When extended scan stop complete, the event comes. */ + ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETE_EVT, /*!< When extended prefer connection parameter set complete, the event comes. */ + ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT, /*!< When bluetooth low energy physical layer update complete, the event comes. */ + ESP_GAP_BLE_EXT_ADV_REPORT_EVT, /*!< When extended advertising report complete, the event comes. */ + ESP_GAP_BLE_SCAN_TIMEOUT_EVT, /*!< When scan timeout complete, the event comes. */ + ESP_GAP_BLE_ADV_TERMINATED_EVT, /*!< When advertising terminate data complete, the event comes. */ + ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT, /*!< When scan req received complete, the event comes. */ + ESP_GAP_BLE_CHANNEL_SELECT_ALGORITHM_EVT, /*!< When channel select algorithm complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT, /*!< When periodic report advertising complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT, /*!< When periodic advertising synchronize lost complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVT, /*!< When periodic advertising synchronize establish complete, the event comes. */ +//@} +//@{ +/** BLE_INCLUDED */ + ESP_GAP_BLE_SC_OOB_REQ_EVT, /*!< When Secure Connection Out-of-Band request, the event comes. */ + ESP_GAP_BLE_SC_CR_LOC_OOB_EVT, /*!< When Secure Connection create Out-of-Band data complete, the event comes. */ + ESP_GAP_BLE_GET_DEV_NAME_COMPLETE_EVT, /*!< When getting bluetooth device name complete, the event comes. */ +//@} +//@{ +/** if Bluetooth Low Energy Feature Periodic Advertising Synchronization Transfer Support */ + ESP_GAP_BLE_PERIODIC_ADV_RECV_ENABLE_COMPLETE_EVT, /*!< When set periodic advertising receive enable complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_SYNC_TRANS_COMPLETE_EVT, /*!< When periodic advertising sync transfer complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_SET_INFO_TRANS_COMPLETE_EVT, /*!< When periodic advertising set info transfer complete, the event comes. */ + ESP_GAP_BLE_SET_PAST_PARAMS_COMPLETE_EVT, /*!< When set periodic advertising sync transfer params complete, the event comes. */ + ESP_GAP_BLE_PERIODIC_ADV_SYNC_TRANS_RECV_EVT, /*!< When periodic advertising sync transfer received, the event comes. */ +//@} +//@{ +/** direct test mode */ + ESP_GAP_BLE_DTM_TEST_UPDATE_EVT, /*!< When direct test mode state changes, the event comes. */ +//@} +//@{ +/** BLE_INCLUDED */ + ESP_GAP_BLE_ADV_CLEAR_COMPLETE_EVT, /*!< When clear advertising complete, the event comes. */ + ESP_GAP_BLE_SET_RPA_TIMEOUT_COMPLETE_EVT, /*!< When set the Resolvable Private Address (RPA) timeout completes, the event comes. */ + ESP_GAP_BLE_ADD_DEV_TO_RESOLVING_LIST_COMPLETE_EVT, /*!< When add a device to the resolving list completes, the event comes. */ + ESP_GAP_BLE_VENDOR_CMD_COMPLETE_EVT, /*!< When vendor Host Controller Interface command complete, the event comes. */ + ESP_GAP_BLE_SET_PRIVACY_MODE_COMPLETE_EVT, /*!< When set privacy mode complete, the event comes. */ + ESP_GAP_BLE_EVT_MAX, /*!< When maximum advertising event complete, the event comes. */ +//@} } esp_gap_ble_cb_event_t; -#define ESP_GAP_BLE_CHANNELS_LEN 5 /*!< channel length*/ -typedef uint8_t esp_gap_ble_channels[ESP_GAP_BLE_CHANNELS_LEN]; - -/// This is the old name, just for backwards compatibility -#define ESP_GAP_BLE_ADD_WHITELIST_COMPLETE_EVT ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT - -/// Advertising data maximum length -#define ESP_BLE_ADV_DATA_LEN_MAX 31 -/// Scan response data maximum length -#define ESP_BLE_SCAN_RSP_DATA_LEN_MAX 31 +#define ESP_GAP_BLE_CHANNELS_LEN 5 /*!< Channel length includes three broadcast channels and two reserved channels. */ +typedef uint8_t esp_gap_ble_channels[ESP_GAP_BLE_CHANNELS_LEN]; /*!< Array type representing Bluetooth LE Adaptive Frequency Hopping (AFH) channel map. */ -#define VENDOR_HCI_CMD_MASK (0x3F << 10) /**!< 0xFC00 */ +#define ESP_GAP_BLE_ADD_WHITELIST_COMPLETE_EVT ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT /*!< This is the old name, just for backwards compatibility. */ +#define ESP_BLE_ADV_DATA_LEN_MAX 31 /*!< Advertising data maximum length. */ +#define ESP_BLE_SCAN_RSP_DATA_LEN_MAX 31 /*!< Scan response data maximum length. */ +#define VENDOR_HCI_CMD_MASK (0x3F << 10) /*!< Mask to extract vendor-specific Host Controller Interface command opcode from a 16-bit value: 0xFC00. */ -/* relate to BTM_BLE_AD_TYPE_xxx in stack/btm_ble_api.h */ -/// The type of advertising data(not adv_type) +/** + * @brief The type of advertising data(not adv_type). + * Relates to BTM_BLE_AD_TYPE_xxx in stack/btm_ble_api.h (Reserved for internal use). + */ typedef enum { - ESP_BLE_AD_TYPE_FLAG = 0x01, /* relate to BTM_BLE_AD_TYPE_FLAG in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_16SRV_PART = 0x02, /* relate to BTM_BLE_AD_TYPE_16SRV_PART in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_16SRV_CMPL = 0x03, /* relate to BTM_BLE_AD_TYPE_16SRV_CMPL in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_32SRV_PART = 0x04, /* relate to BTM_BLE_AD_TYPE_32SRV_PART in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_32SRV_CMPL = 0x05, /* relate to BTM_BLE_AD_TYPE_32SRV_CMPL in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_128SRV_PART = 0x06, /* relate to BTM_BLE_AD_TYPE_128SRV_PART in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_128SRV_CMPL = 0x07, /* relate to BTM_BLE_AD_TYPE_128SRV_CMPL in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_NAME_SHORT = 0x08, /* relate to BTM_BLE_AD_TYPE_NAME_SHORT in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_NAME_CMPL = 0x09, /* relate to BTM_BLE_AD_TYPE_NAME_CMPL in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_TX_PWR = 0x0A, /* relate to BTM_BLE_AD_TYPE_TX_PWR in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_DEV_CLASS = 0x0D, /* relate to BTM_BLE_AD_TYPE_DEV_CLASS in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_SM_TK = 0x10, /* relate to BTM_BLE_AD_TYPE_SM_TK in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_SM_OOB_FLAG = 0x11, /* relate to BTM_BLE_AD_TYPE_SM_OOB_FLAG in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_INT_RANGE = 0x12, /* relate to BTM_BLE_AD_TYPE_INT_RANGE in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_SOL_SRV_UUID = 0x14, /* relate to BTM_BLE_AD_TYPE_SOL_SRV_UUID in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_128SOL_SRV_UUID = 0x15, /* relate to BTM_BLE_AD_TYPE_128SOL_SRV_UUID in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_SERVICE_DATA = 0x16, /* relate to BTM_BLE_AD_TYPE_SERVICE_DATA in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_PUBLIC_TARGET = 0x17, /* relate to BTM_BLE_AD_TYPE_PUBLIC_TARGET in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_RANDOM_TARGET = 0x18, /* relate to BTM_BLE_AD_TYPE_RANDOM_TARGET in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_APPEARANCE = 0x19, /* relate to BTM_BLE_AD_TYPE_APPEARANCE in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_ADV_INT = 0x1A, /* relate to BTM_BLE_AD_TYPE_ADV_INT in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_LE_DEV_ADDR = 0x1b, /* relate to BTM_BLE_AD_TYPE_LE_DEV_ADDR in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_LE_ROLE = 0x1c, /* relate to BTM_BLE_AD_TYPE_LE_ROLE in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_SPAIR_C256 = 0x1d, /* relate to BTM_BLE_AD_TYPE_SPAIR_C256 in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_SPAIR_R256 = 0x1e, /* relate to BTM_BLE_AD_TYPE_SPAIR_R256 in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_32SOL_SRV_UUID = 0x1f, /* relate to BTM_BLE_AD_TYPE_32SOL_SRV_UUID in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_32SERVICE_DATA = 0x20, /* relate to BTM_BLE_AD_TYPE_32SERVICE_DATA in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_128SERVICE_DATA = 0x21, /* relate to BTM_BLE_AD_TYPE_128SERVICE_DATA in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_LE_SECURE_CONFIRM = 0x22, /* relate to BTM_BLE_AD_TYPE_LE_SECURE_CONFIRM in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_LE_SECURE_RANDOM = 0x23, /* relate to BTM_BLE_AD_TYPE_LE_SECURE_RANDOM in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_URI = 0x24, /* relate to BTM_BLE_AD_TYPE_URI in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_INDOOR_POSITION = 0x25, /* relate to BTM_BLE_AD_TYPE_INDOOR_POSITION in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_TRANS_DISC_DATA = 0x26, /* relate to BTM_BLE_AD_TYPE_TRANS_DISC_DATA in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_LE_SUPPORT_FEATURE = 0x27, /* relate to BTM_BLE_AD_TYPE_LE_SUPPORT_FEATURE in stack/btm_ble_api.h */ - ESP_BLE_AD_TYPE_CHAN_MAP_UPDATE = 0x28, /* relate to BTM_BLE_AD_TYPE_CHAN_MAP_UPDATE in stack/btm_ble_api.h */ - ESP_BLE_AD_MANUFACTURER_SPECIFIC_TYPE = 0xFF, /* relate to BTM_BLE_AD_MANUFACTURER_SPECIFIC_TYPE in stack/btm_ble_api.h */ + ESP_BLE_AD_TYPE_FLAG = 0x01, /*!< Flags for discovery and other Bluetooth LE capabilities. relate to BTM_BLE_AD_TYPE_FLAG in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_16SRV_PART = 0x02, /*!< Partial list of 16-bit service UUIDs. relate to BTM_BLE_AD_TYPE_16SRV_PART in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_16SRV_CMPL = 0x03, /*!< Complete list of 16-bit service UUIDs. relate to BTM_BLE_AD_TYPE_16SRV_CMPL in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_32SRV_PART = 0x04, /*!< Partial list of 32-bit service UUIDs. relate to BTM_BLE_AD_TYPE_32SRV_PART in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_32SRV_CMPL = 0x05, /*!< Complete list of 32-bit service UUIDs. relate to BTM_BLE_AD_TYPE_32SRV_CMPL in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_128SRV_PART = 0x06, /*!< Partial list of 128-bit service UUIDs. relate to BTM_BLE_AD_TYPE_128SRV_PART in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_NAME_SHORT = 0x08, /*!< Shortened device name. relate to BTM_BLE_AD_TYPE_NAME_SHORT in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_NAME_CMPL = 0x09, /*!< Complete device name. relate to BTM_BLE_AD_TYPE_NAME_CMPL in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_TX_PWR = 0x0A, /*!< Transmit power level. relate to BTM_BLE_AD_TYPE_TX_PWR in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_DEV_CLASS = 0x0D, /*!< Device class. relate to BTM_BLE_AD_TYPE_DEV_CLASS in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_SM_TK = 0x10, /*!< Security Manager TK value. relate to BTM_BLE_AD_TYPE_SM_TK in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_SM_OOB_FLAG = 0x11, /*!< Security Manager Out of Band flags. relate to BTM_BLE_AD_TYPE_SM_OOB_FLAG in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_INT_RANGE = 0x12, /*!< Slave connection interval range. relate to BTM_BLE_AD_TYPE_INT_RANGE in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_SOL_SRV_UUID = 0x14, /*!< List of 16-bit service solicitation UUIDs. relate to BTM_BLE_AD_TYPE_SOL_SRV_UUID in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_128SOL_SRV_UUID = 0x15, /*!< List of 128-bit service solicitation UUIDs. relate to BTM_BLE_AD_TYPE_128SOL_SRV_UUID in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_SERVICE_DATA = 0x16, /*!< Service data. relate to BTM_BLE_AD_TYPE_SERVICE_DATA in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_PUBLIC_TARGET = 0x17, /*!< Public target address. relate to BTM_BLE_AD_TYPE_PUBLIC_TARGET in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_RANDOM_TARGET = 0x18, /*!< Random target address. relate to BTM_BLE_AD_TYPE_RANDOM_TARGET in stack/btm_ble_api.h (Reserved for internal use)*/ + ESP_BLE_AD_TYPE_APPEARANCE = 0x19, /*!< Appearance. relate to BTM_BLE_AD_TYPE_APPEARANCE in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_ADV_INT = 0x1A, /*!< Advertising interval. relate to BTM_BLE_AD_TYPE_ADV_INT in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_LE_DEV_ADDR = 0x1b, /*!< Bluetooth LE device address. relate to BTM_BLE_AD_TYPE_LE_DEV_ADDR in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_LE_ROLE = 0x1c, /*!< Bluetooth LE role. relate to BTM_BLE_AD_TYPE_LE_ROLE in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_SPAIR_C256 = 0x1d, /*!< Pairing data, C256. relate to BTM_BLE_AD_TYPE_SPAIR_C256 in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_SPAIR_R256 = 0x1e, /*!< Pairing data, R256. relate to BTM_BLE_AD_TYPE_SPAIR_R256 in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_32SOL_SRV_UUID = 0x1f, /*!< List of 32-bit service solicitation UUIDs. relate to BTM_BLE_AD_TYPE_32SOL_SRV_UUID in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_32SERVICE_DATA = 0x20, /*!< 32-bit service data. relate to BTM_BLE_AD_TYPE_32SERVICE_DATA in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_128SERVICE_DATA = 0x21, /*!< 128-bit service data. relate to BTM_BLE_AD_TYPE_128SERVICE_DATA in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_LE_SECURE_CONFIRM = 0x22, /*!< Bluetooth LE secure connections confirmation value. relate to BTM_BLE_AD_TYPE_LE_SECURE_CONFIRM in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_LE_SECURE_RANDOM = 0x23, /*!< Bluetooth LE secure connections random value. relate to BTM_BLE_AD_TYPE_LE_SECURE_RANDOM in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_URI = 0x24, /*!< Uniform Resource Identifier. relate to BTM_BLE_AD_TYPE_URI in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_INDOOR_POSITION = 0x25, /*!< Indoor positioning. relate to BTM_BLE_AD_TYPE_INDOOR_POSITION in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_TRANS_DISC_DATA = 0x26, /*!< Transport discovery data. relate to BTM_BLE_AD_TYPE_TRANS_DISC_DATA in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_LE_SUPPORT_FEATURE = 0x27, /*!< Bluetooth LE supported features. relate to BTM_BLE_AD_TYPE_LE_SUPPORT_FEATURE in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_TYPE_CHAN_MAP_UPDATE = 0x28, /*!< Channel map update indication. relate to BTM_BLE_AD_TYPE_CHAN_MAP_UPDATE in stack/btm_ble_api.h (Reserved for internal use) */ + ESP_BLE_AD_MANUFACTURER_SPECIFIC_TYPE = 0xFF, /*!< Manufacturer specific data. relate to BTM_BLE_AD_MANUFACTURER_SPECIFIC_TYPE in stack/btm_ble_api.h (Reserved for internal use) */ } esp_ble_adv_data_type; -/// Advertising mode +/** + * @brief Advertising mode + * This enum represents the different types of Bluetooth Low Energy (BLE) advertising modes. Each mode dictates how a device advertises its presence and availability for connections. + */ typedef enum { - ADV_TYPE_IND = 0x00, - ADV_TYPE_DIRECT_IND_HIGH = 0x01, - ADV_TYPE_SCAN_IND = 0x02, - ADV_TYPE_NONCONN_IND = 0x03, - ADV_TYPE_DIRECT_IND_LOW = 0x04, + ADV_TYPE_IND = 0x00, /*!< Connectable undirected advertising (ADV_IND). + This is a general advertising mode used when the device is available to connect without a specific target. */ + ADV_TYPE_DIRECT_IND_HIGH = 0x01, /*!< Connectable high duty cycle directed advertising (ADV_DIRECT_IND). + This mode is used when the device intends to connect to a specific peer device quickly, using a high duty cycle to maximize connection speed. */ + ADV_TYPE_SCAN_IND = 0x02, /*!< Scannable undirected advertising (ADV_SCAN_IND). + This mode allows the device to respond to scan requests but not to accept connection requests. It is used when the device wants to advertise additional information to scanners. */ + ADV_TYPE_NONCONN_IND = 0x03, /*!< Non-connectable undirected advertising (ADV_NONCONN_IND). + This mode is used when the device is only broadcasting information and does not intend to accept connections or scan requests. */ + ADV_TYPE_DIRECT_IND_LOW = 0x04 /*!< Connectable low duty cycle directed advertising (ADV_DIRECT_IND_LOW). + This mode is used when the device intends to connect to a specific peer device but with a lower duty cycle to reduce power consumption compared to high duty cycle directed advertising. */ } esp_ble_adv_type_t; -/// Advertising channel mask +/** + * @brief Advertising channel mask + * These channels are used for broadcasting advertising packets in BLE. At least one of these channels must be used for advertising. + */ typedef enum { - ADV_CHNL_37 = 0x01, - ADV_CHNL_38 = 0x02, - ADV_CHNL_39 = 0x04, - ADV_CHNL_ALL = 0x07, + ADV_CHNL_37 = (1 << 0), /*!< Indicates the use of advertising channel 37 for broadcasting packets. */ + ADV_CHNL_38 = (1 << 1), /*!< Indicates the use of advertising channel 38 for broadcasting packets. */ + ADV_CHNL_39 = (1 << 2), /*!< Indicates the use of advertising channel 39 for broadcasting packets. */ + ADV_CHNL_ALL = ADV_CHNL_37 | ADV_CHNL_38 | ADV_CHNL_39, /*!< Indicates that all three advertising channels (37, 38, and 39) are used for broadcasting packets. */ } esp_ble_adv_channel_t; +/** + * @brief Advertising filter policies + * These policies control how scan and connection requests are filtered during advertising. The filters can restrict requests based on whether the requesters are on the White List. + */ typedef enum { - ///Allow both scan and connection requests from anyone - ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY = 0x00, - ///Allow both scan req from White List devices only and connection req from anyone - ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY, - ///Allow both scan req from anyone and connection req from White List devices only - ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST, - ///Allow scan and connection requests from White List devices only - ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST, - ///Enumeration end value for advertising filter policy value check -} esp_ble_adv_filter_t; + ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY = 0x00, /*!< Allow both scan and connection requests from any device. + This is the least restrictive policy and allows maximum visibility. */ + + ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY = 0x01, /*!< Allow scan requests only from devices on the White List, but allow connection requests from any device. + This policy restricts who can perform scans but allows connections from anyone. */ + ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST = 0x02, /*!< Allow scan requests from any device, but allow connection requests only from devices on the White List. + This policy restricts who can initiate connections but allows scans from anyone. */ + + ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST = 0x03 /*!< Allow both scan and connection requests only from devices on the White List. + This is the most restrictive policy and ensures that only known devices can interact with the advertising device. */ +} esp_ble_adv_filter_t; -/* relate to BTA_DM_BLE_SEC_xxx in bta/bta_api.h */ +/** + * @brief Security actions related to BTA_DM_BLE_SEC_xxx in bta/bta_api.h (Reserved for internal use). + * These security actions determine the level of encryption and authentication required for BLE connections. + */ typedef enum { - ESP_BLE_SEC_ENCRYPT = 1, /*!< relate to BTA_DM_BLE_SEC_ENCRYPT in bta/bta_api.h. If the device has already - bonded, the stack will used Long Term Key (LTK) to encrypt with the remote device directly. - Else if the device hasn't bonded, the stack will used the default authentication request - used the esp_ble_gap_set_security_param function set by the user. */ - ESP_BLE_SEC_ENCRYPT_NO_MITM, /*!< relate to BTA_DM_BLE_SEC_ENCRYPT_NO_MITM in bta/bta_api.h. If the device has been already - bonded, the stack will check the LTK (Long Term Key) Whether the authentication request has been met, and if met, use the LTK - to encrypt with the remote device directly, else re-pair with the remote device. - Else if the device hasn't been bonded, the stack will use NO MITM authentication request in the current link instead of - using the authreq in the esp_ble_gap_set_security_param function set by the user. */ - ESP_BLE_SEC_ENCRYPT_MITM, /*!< relate to BTA_DM_BLE_SEC_ENCRYPT_MITM in bta/bta_api.h. If the device has been already - bonded, the stack will check the LTK (Long Term Key) whether the authentication request has been met, and if met, use the LTK - to encrypt with the remote device directly, else re-pair with the remote device. - Else if the device hasn't been bonded, the stack will use MITM authentication request in the current link instead of - using the authreq in the esp_ble_gap_set_security_param function set by the user. */ -}esp_ble_sec_act_t; + ESP_BLE_SEC_ENCRYPT = 1, /*!< Relates to BTA_DM_BLE_SEC_ENCRYPT in bta/bta_api.h (Reserved for internal use). + If the device has already bonded, the stack will use the Long Term Key (LTK) to encrypt communication with the remote device directly. + If the device hasn't bonded, the stack will use the default authentication request (same as no Man-In-The-Middle (MITM) authentication request) + set by the user using the esp_ble_gap_set_security_param function. */ + + ESP_BLE_SEC_ENCRYPT_NO_MITM, /*!< Relates to BTA_DM_BLE_SEC_ENCRYPT_NO_MITM in bta/bta_api.h (Reserved for internal use). + If the device has already bonded, the stack will check if the Long Term Key (LTK) meets the authentication request, and if so, use it to encrypt communication with the remote device directly. + Otherwise, it will re-pair with the remote device. + If the device hasn't bonded, the stack will use no MITM authentication request in the current link instead of the MITM authentication set by the user in the esp_ble_gap_set_security_param function. */ + + ESP_BLE_SEC_ENCRYPT_MITM, /*!< Relates to BTA_DM_BLE_SEC_ENCRYPT_MITM in bta/bta_api.h (Reserved for internal use). + If the device has already bonded, the stack will check if the Long Term Key (LTK) meets the authentication request, and if so, use it to encrypt communication with the remote device directly. + Otherwise, it will re-pair with the remote device. + If the device hasn't bonded, the stack will use MITM authentication request in the current link instead of the MITM authentication set by the user in the esp_ble_gap_set_security_param function. */ +} esp_ble_sec_act_t; +/** + * @brief These annotations provide clearer explanations of each enum member's role in BLE security management. + */ typedef enum { - ESP_BLE_SM_PASSKEY = 0, - /*!< Authentication requirements of local device */ - ESP_BLE_SM_AUTHEN_REQ_MODE, - /*!< The IO capability of local device */ - ESP_BLE_SM_IOCAP_MODE, - /*!< Initiator Key Distribution/Generation */ - ESP_BLE_SM_SET_INIT_KEY, - /*!< Responder Key Distribution/Generation */ - ESP_BLE_SM_SET_RSP_KEY, - /*!< Maximum Encryption key size to support */ - ESP_BLE_SM_MAX_KEY_SIZE, - /*!< Minimum Encryption key size requirement from Peer */ - ESP_BLE_SM_MIN_KEY_SIZE, - /*!< Set static Passkey */ - ESP_BLE_SM_SET_STATIC_PASSKEY, - /*!< Reset static Passkey */ - ESP_BLE_SM_CLEAR_STATIC_PASSKEY, - /*!< Accept only specified SMP Authentication requirement */ - ESP_BLE_SM_ONLY_ACCEPT_SPECIFIED_SEC_AUTH, - /*!< Enable/Disable OOB support */ - ESP_BLE_SM_OOB_SUPPORT, - /*!< Appl encryption key size */ - ESP_BLE_APP_ENC_KEY_SIZE, - /*!< authentication max param */ - ESP_BLE_SM_MAX_PARAM, + ESP_BLE_SM_PASSKEY = 0, /*!< Authentication method using passkey input on the local device. */ + ESP_BLE_SM_AUTHEN_REQ_MODE, /*!< Authentication mode requirements of the local device. */ + ESP_BLE_SM_IOCAP_MODE, /*!< Input/output capabilities of the local device in pairing. */ + ESP_BLE_SM_SET_INIT_KEY, /*!< Initiator key distribution/generation during pairing. */ + ESP_BLE_SM_SET_RSP_KEY, /*!< Responder key distribution/generation during pairing. */ + ESP_BLE_SM_MAX_KEY_SIZE, /*!< Maximum encryption key size supported by the device. */ + ESP_BLE_SM_MIN_KEY_SIZE, /*!< Minimum encryption key size required from the peer device. */ + ESP_BLE_SM_SET_STATIC_PASSKEY, /*!< Set a static passkey for pairing. */ + ESP_BLE_SM_CLEAR_STATIC_PASSKEY, /*!< Clear previously set static passkey. */ + ESP_BLE_SM_ONLY_ACCEPT_SPECIFIED_SEC_AUTH, /*!< Accept only specified security authentication requirements. */ + ESP_BLE_SM_OOB_SUPPORT, /*!< Out of Band (OOB) data support for pairing. */ + ESP_BLE_APP_ENC_KEY_SIZE, /*!< Size of the application encryption key used. */ + ESP_BLE_SM_MAX_PARAM, /*!< End marker for the enumeration range of security manager parameters. */ } esp_ble_sm_param_t; +/** + * @brief These annotations clarify the purpose of each enum member related to Direct Test Mode (DTM) testing in Bluetooth Low Energy. + */ typedef enum { - /// DTM TX start event - DTM_TX_START_EVT = 0x00, - ///DTM RX start event - DTM_RX_START_EVT, - ///DTM test end event - DTM_TEST_STOP_EVT, + DTM_TX_START_EVT = 0x00, /*!< Event generated when the Direct Test Mode TX test starts. */ + DTM_RX_START_EVT, /*!< Event generated when the Direct Test Mode RX test starts. */ + DTM_TEST_STOP_EVT, /*!< Event generated when the Direct Test Mode test ends. */ } esp_ble_dtm_update_evt_t; /** - * @brief Vendor HCI command parameters + * @brief Vendor HCI (Host Controller Interface) command parameters. */ typedef struct { - uint16_t opcode; /*!< vendor hci command opcode */ - uint8_t param_len; /*!< the length of parameter */ - uint8_t *p_param_buf; /*!< the point of parameter buffer */ + uint16_t opcode; /*!< Vendor HCI command opcode. Value range: 0x0001-0xFFFF */ + uint8_t param_len; /*!< Length of the parameter. */ + uint8_t *p_param_buf; /*!< Pointer to the parameter buffer. */ } esp_ble_vendor_cmd_params_t; +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_42_FEATURE_SUPPORT == TRUE) /** -* @brief DTM TX parameters +* @brief Direct Test Mode TX parameters */ typedef struct { - uint8_t tx_channel; /*!< channel for sending test data, tx_channel = (Frequency -2402)/2, tx_channel range:0x00-0x27, Frequency range: 2402 MHz to 2480 MHz */ - uint8_t len_of_data; /*!< length in bytes of payload data in each packet */ - esp_ble_dtm_pkt_payload_t pkt_payload; /*!< packet payload type. value range: 0x00-0x07 */ + uint8_t tx_channel; /*!< channel for sending test data, tx_channel = (Frequency -2402)/2, tx_channel range:0x00-0x27, Frequency range: 2402 MHz to 2480 MHz */ + uint8_t len_of_data; /*!< Length in bytes of payload data in each packet. */ + esp_ble_dtm_pkt_payload_t pkt_payload; /*!< Packet payload type. Value range: 0x00-0x07 */ } esp_ble_dtm_tx_t; /** -* @brief DTM RX parameters +* @brief Direct Test Mode RX parameters */ typedef struct { - uint8_t rx_channel; /*!< channel for test data reception, rx_channel = (Frequency -2402)/2, tx_channel range:0x00-0x27, Frequency range: 2402 MHz to 2480 MHz */ + uint8_t rx_channel; /*!< Channel for test data reception, rx_channel = (Frequency -2402)/2, tx_channel range:0x00-0x27, Frequency range: 2402 MHz to 2480 MHz */ } esp_ble_dtm_rx_t; -/// Advertising parameters +/** + * @brief Advertising parameters + */ typedef struct { - uint16_t adv_int_min; /*!< Minimum advertising interval for - undirected and low duty cycle directed advertising. - Range: 0x0020 to 0x4000 Default: N = 0x0800 (1.28 second) - Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec */ - uint16_t adv_int_max; /*!< Maximum advertising interval for - undirected and low duty cycle directed advertising. - Range: 0x0020 to 0x4000 Default: N = 0x0800 (1.28 second) - Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec Advertising max interval */ - esp_ble_adv_type_t adv_type; /*!< Advertising type */ - esp_ble_addr_type_t own_addr_type; /*!< Owner bluetooth device address type */ - esp_bd_addr_t peer_addr; /*!< Peer device bluetooth device address */ - esp_ble_addr_type_t peer_addr_type; /*!< Peer device bluetooth device address type, only support public address type and random address type */ - esp_ble_adv_channel_t channel_map; /*!< Advertising channel map */ - esp_ble_adv_filter_t adv_filter_policy; /*!< Advertising filter policy */ + uint16_t adv_int_min; /*!< Minimum advertising interval for undirected and low duty cycle directed advertising. + Range: 0x0020 to 0x4000 (20 ms to 10.24 sec). Default: 0x0800 (1.28 seconds). + Time is calculated as N * 0.625 ms. */ + uint16_t adv_int_max; /*!< Maximum advertising interval for undirected and low duty cycle directed advertising. + Range: 0x0020 to 0x4000 (20 ms to 10.24 sec). Default: 0x0800 (1.28 seconds). + Time is calculated as N * 0.625 ms. */ + esp_ble_adv_type_t adv_type; /*!< Type of advertising. */ + esp_ble_addr_type_t own_addr_type; /*!< Address type of the local device. */ + esp_bd_addr_t peer_addr; /*!< Bluetooth device address of the peer device. */ + esp_ble_addr_type_t peer_addr_type; /*!< Address type of the peer device. */ + esp_ble_adv_channel_t channel_map; /*!< Channel map for advertising. */ + esp_ble_adv_filter_t adv_filter_policy; /*!< Advertising filter policy. */ } esp_ble_adv_params_t; -/// Advertising data content, according to "Supplement to the Bluetooth Core Specification" +/** + * @brief Advertising data content, according to "Supplement to the Bluetooth Core Specification" + */ typedef struct { - bool set_scan_rsp; /*!< Set this advertising data as scan response or not*/ - bool include_name; /*!< Advertising data include device name or not */ - bool include_txpower; /*!< Advertising data include TX power */ - int min_interval; /*!< Advertising data show slave preferred connection min interval. - The connection interval in the following manner: - connIntervalmin = Conn_Interval_Min * 1.25 ms - Conn_Interval_Min range: 0x0006 to 0x0C80 - Value of 0xFFFF indicates no specific minimum. - Values not defined above are reserved for future use.*/ - - int max_interval; /*!< Advertising data show slave preferred connection max interval. - The connection interval in the following manner: - connIntervalmax = Conn_Interval_Max * 1.25 ms - Conn_Interval_Max range: 0x0006 to 0x0C80 - Conn_Interval_Max shall be equal to or greater than the Conn_Interval_Min. - Value of 0xFFFF indicates no specific maximum. - Values not defined above are reserved for future use.*/ - - int appearance; /*!< External appearance of device */ - uint16_t manufacturer_len; /*!< Manufacturer data length */ - uint8_t *p_manufacturer_data; /*!< Manufacturer data point */ - uint16_t service_data_len; /*!< Service data length */ - uint8_t *p_service_data; /*!< Service data point */ - uint16_t service_uuid_len; /*!< Service uuid length */ - uint8_t *p_service_uuid; /*!< Service uuid array point */ - uint8_t flag; /*!< Advertising flag of discovery mode, see BLE_ADV_DATA_FLAG detail */ -} esp_ble_adv_data_t; - -#endif // #if (BLE_42_FEATURE_SUPPORT == TRUE) + bool set_scan_rsp; /*!< Set this advertising data as scan response or not. + true indicates the data is a scan response, false indicates it is not. */ + bool include_name; /*!< Advertising data includes the device name or not. + true indicates the device name is included, false indicates it is not. */ + bool include_txpower; /*!< Advertising data includes TX power or not. + true indicates TX power is included, false indicates it is not. */ + int min_interval; /*!< Advertising data shows the slave preferred connection minimum interval. + The connection interval is calculated as: + connIntervalMin = Conn_Interval_Min * 1.25 ms + Conn_Interval_Min range: 0x0006 to 0x0C80 (7.5 ms to 4 s). + A value of 0xFFFF indicates no specific minimum. + Values not defined above are reserved for future use. */ + int max_interval; /*!< Advertising data shows the slave preferred connection maximum interval. + The connection interval is calculated as: + connIntervalMax = Conn_Interval_Max * 1.25 ms + Conn_Interval_Max range: 0x0006 to 0x0C80 (7.5 ms to 4 s). + Conn_Interval_Max shall be equal to or greater than Conn_Interval_Min. + A value of 0xFFFF indicates no specific maximum. + Values not defined above are reserved for future use. */ + int appearance; /*!< External appearance of the device. + The value is defined by the Bluetooth SIG and represents the appearance of the device. */ + uint16_t manufacturer_len; /*!< Manufacturer data length in bytes. */ + uint8_t *p_manufacturer_data; /*!< Pointer to the manufacturer data. */ + uint16_t service_data_len; /*!< Service data length in bytes. */ + uint8_t *p_service_data; /*!< Pointer to the service data. */ + uint16_t service_uuid_len; /*!< Service UUID length in bytes. */ + uint8_t *p_service_uuid; /*!< Pointer to the service UUID array. */ + uint8_t flag; /*!< Advertising flag of discovery mode. + This field contains flags for various discovery modes. See BLE_ADV_DATA_FLAG for details. */ +} esp_ble_adv_data_t;// #if (BLE_42_FEATURE_SUPPORT == TRUE) +#endif +//@} -/// Ble scan type +/** + * @brief Bluetooth Low Energy (BLE) scan type + */ typedef enum { - BLE_SCAN_TYPE_PASSIVE = 0x0, /*!< Passive scan */ - BLE_SCAN_TYPE_ACTIVE = 0x1, /*!< Active scan */ + BLE_SCAN_TYPE_PASSIVE = 0x0, /*!< Passive scan. + The scanner listens for advertising packets without sending scan requests. + This method consumes less power and does not request additional information + from advertising devices. */ + BLE_SCAN_TYPE_ACTIVE = 0x1, /*!< Active scan. + The scanner listens for advertising packets and sends scan requests to advertisers. + This method allows the scanner to receive scan responses from advertising devices, + providing additional information such as device name or other data. */ } esp_ble_scan_type_t; -/// Ble scan filter type +/** + * @brief Bluetooth Low Energy (BLE) scan filter type + */ typedef enum { - BLE_SCAN_FILTER_ALLOW_ALL = 0x0, /*!< Accept all : - 1. advertisement packets except directed advertising packets not addressed to this device (default). */ - BLE_SCAN_FILTER_ALLOW_ONLY_WLST = 0x1, /*!< Accept only : - 1. advertisement packets from devices where the advertiser’s address is in the White list. - 2. Directed advertising packets which are not addressed for this device shall be ignored. */ - BLE_SCAN_FILTER_ALLOW_UND_RPA_DIR = 0x2, /*!< Accept all : - 1. undirected advertisement packets, and - 2. directed advertising packets where the initiator address is a resolvable private address, and - 3. directed advertising packets addressed to this device. */ - BLE_SCAN_FILTER_ALLOW_WLIST_RPA_DIR = 0x3, /*!< Accept all : - 1. advertisement packets from devices where the advertiser’s address is in the White list, and - 2. directed advertising packets where the initiator address is a resolvable private address, and - 3. directed advertising packets addressed to this device.*/ + BLE_SCAN_FILTER_ALLOW_ALL = 0x0, /*!< Accept all: + + 1. Advertisement packets except directed advertising packets not addressed to this device (default). + */ + BLE_SCAN_FILTER_ALLOW_ONLY_WLST = 0x1, /*!< Accept only: + + 1. Advertisement packets from devices where the advertiser??s address is in the White list. + + 2. Directed advertising packets not addressed to this device shall be ignored. + */ + BLE_SCAN_FILTER_ALLOW_UND_RPA_DIR = 0x2, /*!< Accept all: + + 1. Undirected advertisement packets. + + 2. Directed advertising packets where the initiator address is a resolvable private address. + + 3. Directed advertising packets addressed to this device. + */ + BLE_SCAN_FILTER_ALLOW_WLIST_RPA_DIR = 0x3, /*!< Accept all: + + 1. Advertisement packets from devices where the advertiser??s address is in the White list. + + 2. Directed advertising packets where the initiator address is a resolvable private address. + + 3. Directed advertising packets addressed to this device. + */ } esp_ble_scan_filter_t; -/// Ble scan duplicate type +/** + * @brief Bluetooth Low Energy (BLE) scan duplicate type + */ typedef enum { - BLE_SCAN_DUPLICATE_DISABLE = 0x0, /*!< the Link Layer should generate advertising reports to the host for each packet received */ - BLE_SCAN_DUPLICATE_ENABLE = 0x1, /*!< the Link Layer should filter out duplicate advertising reports to the Host */ + BLE_SCAN_DUPLICATE_DISABLE = 0x0, /*!< The Link Layer should generate advertising reports to the host for each packet received. + This means every advertising packet, including duplicates, will be reported. */ + BLE_SCAN_DUPLICATE_ENABLE = 0x1, /*!< The Link Layer should filter out duplicate advertising reports to the host. + This means only unique advertising packets will be reported, reducing redundant data. */ +//@{ +/** if Bluetooth Low Energy 5.0 Feature Support */ #if (BLE_50_FEATURE_SUPPORT == TRUE) - BLE_SCAN_DUPLICATE_ENABLE_RESET, /*!< Duplicate filtering enabled, reset for each scan period, only supported in BLE 5.0. */ - #endif + BLE_SCAN_DUPLICATE_ENABLE_RESET, /*!< Duplicate filtering enabled, reset for each scan period, only supported in bluetooth low energy 5.0. */ + #endif// #if (BLE_50_FEATURE_SUPPORT == TRUE) +//@} BLE_SCAN_DUPLICATE_MAX /*!< Reserved for future use. */ } esp_ble_scan_duplicate_t; + +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_42_FEATURE_SUPPORT == TRUE) -/// Ble scan parameters + +/** + * @brief Bluetooth Low Energy (BLE) scan parameters + */ typedef struct { - esp_ble_scan_type_t scan_type; /*!< Scan type */ - esp_ble_addr_type_t own_addr_type; /*!< Owner address type */ - esp_ble_scan_filter_t scan_filter_policy; /*!< Scan filter policy */ - uint16_t scan_interval; /*!< Scan interval. This is defined as the time interval from - when the Controller started its last LE scan until it begins the subsequent LE scan. - Range: 0x0004 to 0x4000 Default: 0x0010 (10 ms) - Time = N * 0.625 msec - Time Range: 2.5 msec to 10.24 seconds*/ - uint16_t scan_window; /*!< Scan window. The duration of the LE scan. LE_Scan_Window - shall be less than or equal to LE_Scan_Interval - Range: 0x0004 to 0x4000 Default: 0x0010 (10 ms) - Time = N * 0.625 msec - Time Range: 2.5 msec to 10240 msec */ - esp_ble_scan_duplicate_t scan_duplicate; /*!< The Scan_Duplicates parameter controls whether the Link Layer should filter out - duplicate advertising reports (BLE_SCAN_DUPLICATE_ENABLE) to the Host, or if the Link Layer should generate - advertising reports for each packet received */ + esp_ble_scan_type_t scan_type; /*!< Scan type, specifies whether to use passive or active scanning. + `0x0`: Passive scan, only listens for advertisements without sending scan requests. + `0x1`: Active scan, listens for advertisements and sends scan requests to gather additional data. */ + esp_ble_addr_type_t own_addr_type; /*!< Owner address type, specifies the type of Bluetooth address used by the scanning device. + Range: `0x00` to `0x03` (see details in `api/esp_bt_defs.h`). */ + esp_ble_scan_filter_t scan_filter_policy; /*!< Scan filter policy, defines the criteria for accepting advertisement packets. + `0x0`: Accept all advertisement packets except directed packets not addressed to this device. + `0x1`: Accept only advertisement packets from devices in the White List. + `0x2`: Accept undirected advertisement packets and directed packets with a resolvable private address. + `0x3`: Accept advertisement packets from devices in the White List and directed packets with a resolvable private address. */ + uint16_t scan_interval; /*!< Scan interval, the time between the start of consecutive scans. + Range: `0x0004` to `0x4000` (default: `0x0010` for 10 ms). + Time = N * 0.625 ms + Time Range: 2.5 ms to 10.24 seconds. */ + uint16_t scan_window; /*!< Scan window, the duration of each scan period. + LE_Scan_Window must be less than or equal to LE_Scan_Interval. + Range: `0x0004` to `0x4000` (default: `0x0010` for 10 ms). + Time = N * 0.625 ms + Time Range: 2.5 ms to 10.24 seconds. */ + esp_ble_scan_duplicate_t scan_duplicate; /*!< Scan duplicates setting, controls whether duplicate advertising reports are filtered. + `BLE_SCAN_DUPLICATE_DISABLE`: Report every advertisement packet, including duplicates. + `BLE_SCAN_DUPLICATE_ENABLE`: Filter out duplicate advertisement packets, reporting only unique packets. */ } esp_ble_scan_params_t; -#endif // #if (BLE_42_FEATURE_SUPPORT == TRUE) -/// connection parameters information +#endif// #if (BLE_42_FEATURE_SUPPORT == TRUE) +//@} + +/** + * @brief Connection parameters information for a Bluetooth Low Energy (BLE) connection. + */ typedef struct { - uint16_t interval; /*!< connection interval */ - uint16_t latency; /*!< Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3 */ - uint16_t timeout; /*!< Supervision timeout for the LE Link. Range: 0x000A to 0x0C80. - Mandatory Range: 0x000A to 0x0C80 Time = N * 10 msec - Time Range: 100 msec to 32 seconds */ + uint16_t interval; /*!< Connection interval, defines how frequently the devices will exchange data. + Time = N * 1.25 ms + Range: 0x0006 to 0x0C80 + Time Range: 7.5 ms to 4 seconds. */ + uint16_t latency; /*!< Slave latency for the connection, specifies the number of connection events the slave can skip. + Range: 0x0000 to 0x01F3 + A latency of 0 means no skipped events. */ + uint16_t timeout; /*!< Supervision timeout for the connection, defines the time the connection will be maintained without activity. + Time = N * 10 ms + Range: 0x000A to 0x0C80 + Time Range: 100 ms to 32 seconds. */ } esp_gap_conn_params_t; -/// Connection update parameters +/** + * @brief Parameters for updating BLE connection parameters. + */ typedef struct { - esp_bd_addr_t bda; /*!< Bluetooth device address */ - uint16_t min_int; /*!< Min connection interval */ - uint16_t max_int; /*!< Max connection interval */ - uint16_t latency; /*!< Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3 */ - uint16_t timeout; /*!< Supervision timeout for the LE Link. Range: 0x000A to 0x0C80. - Mandatory Range: 0x000A to 0x0C80 Time = N * 10 msec - Time Range: 100 msec to 32 seconds */ + esp_bd_addr_t bda; /*!< Bluetooth device address for which the connection parameters are being updated. */ + uint16_t min_int; /*!< Minimum connection interval, specifies the shortest time between connection events. + Time = N * 1.25 ms + Range: 0x0006 to 0x0C80 + Time Range: 7.5 ms to 4 seconds. */ + uint16_t max_int; /*!< Maximum connection interval, specifies the longest time between connection events. + Time = N * 1.25 ms + Range: 0x0006 to 0x0C80 + Time Range: 7.5 ms to 4 seconds. */ + uint16_t latency; /*!< Slave latency for the connection, specifies the number of connection events the slave can skip. + Range: 0x0000 to 0x01F3 + A latency of 0 means no skipped events. */ + uint16_t timeout; /*!< Supervision timeout for the LE connection, defines the time the connection will be maintained without activity. + Time = N * 10 ms + Range: 0x000A to 0x0C80 + Time Range: 100 ms to 32 seconds. */ } esp_ble_conn_update_params_t; /** -* @brief BLE pkt date length keys -*/ -typedef struct -{ - uint16_t rx_len; /*!< pkt rx data length value */ - uint16_t tx_len; /*!< pkt tx data length value */ + * @brief Packet data length parameters for Bluetooth Low Energy (BLE). + */ +typedef struct { + uint16_t rx_len; /*!< Maximum length of received packets, defines the maximum size of incoming data packets. + Value range: Dependent on BLE stack and controller configuration. */ + uint16_t tx_len; /*!< Maximum length of transmitted packets, defines the maximum size of outgoing data packets. + Value range: Dependent on BLE stack and controller configuration. */ } esp_ble_pkt_data_length_params_t; /** -* @brief BLE encryption keys -*/ -typedef struct -{ - esp_bt_octet16_t ltk; /*!< The long term key*/ - esp_bt_octet8_t rand; /*!< The random number*/ - uint16_t ediv; /*!< The ediv value*/ - uint8_t sec_level; /*!< The security level of the security link*/ - uint8_t key_size; /*!< The key size(7~16) of the security link*/ -} esp_ble_penc_keys_t; /*!< The key type*/ + * @brief Bluetooth Low Energy (BLE) encryption keys. + * The key type used for encryption in BLE security. + */ +typedef struct { + esp_bt_octet16_t ltk; /*!< Long Term Key (LTK) used for encryption of data between devices. + Used for decrypting data in future connections. */ + esp_bt_octet8_t rand; /*!< Random Number used during the pairing process to ensure encryption keys are unique. */ + uint16_t ediv; /*!< Encryption Diversifier (EDIV) used to generate the encryption key. + A 16-bit value generated during pairing to ensure key uniqueness. */ + uint8_t sec_level; /*!< Security level of the link. -/** -* @brief BLE CSRK keys -*/ -typedef struct -{ - uint32_t counter; /*!< The counter */ - esp_bt_octet16_t csrk; /*!< The csrk key */ - uint8_t sec_level; /*!< The security level */ -} esp_ble_pcsrk_keys_t; /*!< The pcsrk key type */ + 1: No Security (No Authentication, No Encryption) -/** -* @brief BLE pid keys -*/ -typedef struct -{ - esp_bt_octet16_t irk; /*!< The irk value */ - esp_ble_addr_type_t addr_type; /*!< The address type */ - esp_bd_addr_t static_addr; /*!< The static address */ -} esp_ble_pid_keys_t; /*!< The pid key type */ + 2: Security Mode 1 (No Encryption, Authentication Required) -/** -* @brief BLE Encryption reproduction keys -*/ -typedef struct -{ - esp_bt_octet16_t ltk; /*!< The long term key */ - uint16_t div; /*!< The div value */ - uint8_t key_size; /*!< The key size of the security link */ - uint8_t sec_level; /*!< The security level of the security link */ -} esp_ble_lenc_keys_t; /*!< The key type */ + 3: Security Mode 2 (Encryption, Authentication Optional) -/** -* @brief BLE SRK keys -*/ -typedef struct -{ - uint32_t counter; /*!< The counter value */ - uint16_t div; /*!< The div value */ - uint8_t sec_level; /*!< The security level of the security link */ - esp_bt_octet16_t csrk; /*!< The csrk key value */ -} esp_ble_lcsrk_keys; /*!< The csrk key type */ + 4: Security Mode 3 (Encryption with MITM Protection, Authentication Required) + */ + uint8_t key_size; /*!< Key size used in the security link. + Value range: 7 to 16 bytes. + Specifies the length of the encryption key in bytes. */ +} esp_ble_penc_keys_t; /** -* @brief Structure associated with ESP_KEY_NOTIF_EVT -*/ -typedef struct -{ - esp_bd_addr_t bd_addr; /*!< peer address */ - uint32_t passkey; /*!< the numeric value for comparison. If just_works, do not show this number to UI */ -} esp_ble_sec_key_notif_t; /*!< BLE key notify type*/ + * @brief Bluetooth Low Energy (BLE) connection signature resolving keys. + * The Privacy-Enhanced Connection Signature Resolving Key type. + */ +typedef struct { + uint32_t counter; /*!< Counter used to track the number of packets processed. + Ensures the uniqueness of each signature in the connection. */ + esp_bt_octet16_t csrk; /*!< Connection Signature Resolving Key (CSRK) used to sign data packets. + A 128-bit key used for integrity and authentication of data. */ + uint8_t sec_level; /*!< Security level associated with the CSRK. + Indicates the level of security used for signature resolution. */ +} esp_ble_pcsrk_keys_t; /** -* @brief Structure of the security request -*/ -typedef struct -{ - esp_bd_addr_t bd_addr; /*!< peer address */ -} esp_ble_sec_req_t; /*!< BLE security request type*/ + * @brief Bluetooth Low Energy (BLE) pairing identification keys. + * These keys are used for device identification and privacy. + */ +typedef struct { + esp_bt_octet16_t irk; /*!< Identity Resolving Key (IRK) used to resolve device identity and protect privacy.*/ + esp_ble_addr_type_t addr_type; /*!< Address type of the device. + Defines whether the address is public or random. */ + esp_bd_addr_t static_addr; /*!< Static address used for identity resolution. */ +} esp_ble_pid_keys_t; /** -* @brief union type of the security key value -*/ -typedef union -{ - esp_ble_penc_keys_t penc_key; /*!< received peer encryption key */ - esp_ble_pcsrk_keys_t pcsrk_key; /*!< received peer device SRK */ - esp_ble_pid_keys_t pid_key; /*!< peer device ID key */ - esp_ble_lenc_keys_t lenc_key; /*!< local encryption reproduction keys LTK = = d1(ER,DIV,0)*/ - esp_ble_lcsrk_keys lcsrk_key; /*!< local device CSRK = d1(ER,DIV,1)*/ -} esp_ble_key_value_t; /*!< ble key value type*/ + * @brief Bluetooth Low Energy (BLE) encryption reproduction keys. + * These keys are used for encryption in BLE security and are derived from the Long Term Key (LTK). + */ +typedef struct { + esp_bt_octet16_t ltk; /*!< Long Term Key (LTK) used for encryption. */ + uint16_t div; /*!< Diversifier value used in the key generation. */ + uint8_t key_size; /*!< Key size of the security link. */ + uint8_t sec_level; /*!< Security level of the security link. */ +} esp_ble_lenc_keys_t; /** -* @brief struct type of the bond key information value -*/ -typedef struct -{ - esp_ble_key_mask_t key_mask; /*!< the key mask to indicate witch key is present */ - esp_ble_penc_keys_t penc_key; /*!< received peer encryption key */ - esp_ble_pcsrk_keys_t pcsrk_key; /*!< received peer device SRK */ - esp_ble_pid_keys_t pid_key; /*!< peer device ID key */ -} esp_ble_bond_key_info_t; /*!< ble bond key information value type */ + * @brief Bluetooth Low Energy (BLE) signature resolving keys. + * These keys are used to resolve connection signatures and ensure data integrity. + */ +typedef struct { + uint32_t counter; /*!< Counter value used to maintain uniqueness of signatures. + Tracks the number of packets processed. */ + uint16_t div; /*!< Diversify value used in signature generation. + A 16-bit value that helps in generating unique signatures. */ + uint8_t sec_level; /*!< Security level of the signature resolving key. + Indicates the level of security applied to the signature. */ + esp_bt_octet16_t csrk; /*!< Connection Signature Resolving Key (CSRK) used for signing data packets. */ +} esp_ble_lcsrk_keys_t; + +/** + * @brief Structure associated with ESP_KEY_NOTIF_EVT (Key Notification Event). + * Contains information about key notifications in BLE security events. + */ +typedef struct { + esp_bd_addr_t bd_addr; /*!< Bluetooth device address of the peer. + Identifies the remote device involved in the key exchange. */ + uint32_t passkey; /*!< Numeric value for comparison during pairing. + If the pairing method is Just Works, this value may not be displayed to the user. */ +} esp_ble_sec_key_notif_t; /** -* @brief struct type of the bond device value -*/ -typedef struct -{ - esp_bd_addr_t bd_addr; /*!< peer address */ - esp_ble_bond_key_info_t bond_key; /*!< the bond key information */ -} esp_ble_bond_dev_t; /*!< the ble bond device type */ + * @brief Structure for Bluetooth Low Energy (BLE) security requests. + * Contains information related to security requests from a peer device. + */ +typedef struct { + esp_bd_addr_t bd_addr; /*!< Bluetooth device address of the peer. + Identifies the remote device making the security request. */ +} esp_ble_sec_req_t; +/** + * @brief Union type for Bluetooth Low Energy (BLE) key values. + * This union allows for different types of BLE keys to be accessed in a single structure. + */ +typedef union { + esp_ble_penc_keys_t penc_key; /*!< Received peer encryption key (Long Term Key, LTK). + Used for encrypting data in BLE connections. */ + esp_ble_pcsrk_keys_t pcsrk_key; /*!< Received peer device Secure Resolving Key (CSRK). + Used for signing data packets to ensure integrity. */ + esp_ble_pid_keys_t pid_key; /*!< Peer device Identity Resolving Key (IRK). + Used for device identity resolution and privacy. */ + esp_ble_lenc_keys_t lenc_key; /*!< Local encryption reproduction keys derived from LTK. + Used for local encryption operations. */ + esp_ble_lcsrk_keys_t lcsrk_key; /*!< Local device Connection Signature Resolving Key (CSRK). + Used for local signing of data packets. */ +} esp_ble_key_value_t; + +/** + * @brief Structure type for bond key information. + * Contains the bond key information for a bonded device. + */ +typedef struct { + esp_ble_key_mask_t key_mask; /*!< The key mask to indicate which keys are present. + Helps in determining which keys are available for a specific bonded device. */ + esp_ble_penc_keys_t penc_key; /*!< Received peer encryption key (Long Term Key, LTK). + Used for decrypting data from the bonded device. */ + esp_ble_pcsrk_keys_t pcsrk_key; /*!< Received peer device Secure Resolving Key (CSRK). + Used for verifying signatures from the bonded device. */ + esp_ble_pid_keys_t pid_key; /*!< Peer device Identity Resolving Key (IRK). + Used for device identity and privacy management. */ +} esp_ble_bond_key_info_t; + +/** + * @brief Structure type for bonded device information. + * Contains information about a bonded device and its associated bond key. + */ +typedef struct { + esp_bd_addr_t bd_addr; /*!< Bluetooth device address of the bonded peer. + Identifies the remote device. */ + esp_ble_bond_key_info_t bond_key; /*!< Bond key information associated with the bonded device. + Includes encryption and resolving keys. */ +} esp_ble_bond_dev_t; /** -* @brief union type of the security key value -*/ -typedef struct -{ - esp_bd_addr_t bd_addr; /*!< peer address */ - esp_ble_key_type_t key_type; /*!< key type of the security link */ - esp_ble_key_value_t p_key_value; /*!< the pointer to the key value */ -} esp_ble_key_t; /*!< the union to the ble key value type*/ + * @brief Structure type for security key value. + * Contains information about the security key and its type. + */ +typedef struct { + esp_bd_addr_t bd_addr; /*!< Bluetooth device address of the peer. + Identifies the remote device for which the security key is associated. */ + esp_ble_key_type_t key_type; /*!< Key type of the security link. + Indicates the type of key being used. */ + esp_ble_key_value_t p_key_value; /*!< Pointer to the key value. + Points to the specific key data based on the `key_type`. */ +} esp_ble_key_t; /** -* @brief structure type of the ble local id keys value -*/ + * @brief Structure for Bluetooth Low Energy (BLE) local identity keys. + * Contains local identity keys used in the BLE pairing process. + */ typedef struct { - esp_bt_octet16_t ir; /*!< the 16 bits of the ir value */ - esp_bt_octet16_t irk; /*!< the 16 bits of the ir key value */ - esp_bt_octet16_t dhk; /*!< the 16 bits of the dh key value */ -} esp_ble_local_id_keys_t; /*!< the structure of the ble local id keys value type*/ + esp_bt_octet16_t ir; /*!< The 16 bytes of the Identity Root value. + Used to derive Identity Resolving Key (IRK) in BLE. */ + esp_bt_octet16_t irk; /*!< The 16 bytes of the Identity Resolving Key (IRK). + Used to resolve device identity. */ + esp_bt_octet16_t dhk; /*!< The 16 bytes of the Diffie-Hellman key (DHK). + Used for secure key exchange in BLE pairing. */ +} esp_ble_local_id_keys_t; /** -* @brief structure type of the ble local oob data value -*/ + * @brief Structure for Bluetooth Low Energy (BLE) local Out-of-Band (OOB) data. + * Contains OOB data used for secure pairing when OOB is employed. + */ typedef struct { - esp_bt_octet16_t oob_c; /*!< the 128 bits of confirmation value */ - esp_bt_octet16_t oob_r; /*!< the 128 bits of randomizer value */ + esp_bt_octet16_t oob_c; /*!< The 128-bit confirmation value. + Used to confirm the pairing process in OOB scenarios. */ + esp_bt_octet16_t oob_r; /*!< The 128-bit random value. + Used to generate secure pairing data. */ } esp_ble_local_oob_data_t; /** -* @brief Definition of the authentication failed reason -*/ + * @brief Enumeration of authentication failure reasons in BLE pairing. + * Lists possible reasons for authentication failure. + */ typedef enum { - // Failure reason defined in Bluetooth Core Spec 5.0 Vol3, Part H, 3.5.5 - ESP_AUTH_SMP_PASSKEY_FAIL = 78, /*!< The user input of passkey failed */ - ESP_AUTH_SMP_OOB_FAIL, /*!< The OOB data is not available */ - ESP_AUTH_SMP_PAIR_AUTH_FAIL, /*!< The authentication requirements cannot be met */ - ESP_AUTH_SMP_CONFIRM_VALUE_FAIL, /*!< The confirm value does not match the calculated comparison value */ - ESP_AUTH_SMP_PAIR_NOT_SUPPORT, /*!< Pairing is not supported by the device */ - ESP_AUTH_SMP_ENC_KEY_SIZE, /*!< The resultant encryption key size is not long enough */ - ESP_AUTH_SMP_INVALID_CMD, /*!< The SMP command received is not supported by this device */ - ESP_AUTH_SMP_UNKNOWN_ERR, /*!< Pairing failed due to an unspecified reason */ - ESP_AUTH_SMP_REPEATED_ATTEMPT, /*!< Pairing or authentication procedure is disallowed */ - ESP_AUTH_SMP_INVALID_PARAMETERS, /*!< The command length is invalid or that a parameter is outside the specified range */ - ESP_AUTH_SMP_DHKEY_CHK_FAIL, /*!< The DHKey Check value received doesn’t match the one calculated by the local device */ - ESP_AUTH_SMP_NUM_COMP_FAIL, /*!< The confirm values in the numeric comparison protocol do not match */ - ESP_AUTH_SMP_BR_PARING_IN_PROGR, /*!< Pairing Request sent over the BR/EDR transport is in progress */ - ESP_AUTH_SMP_XTRANS_DERIVE_NOT_ALLOW, /*!< The BR/EDR Link Key or BLE LTK cannot be used to derive */ - - // Failure reason defined in Bluedroid Host - ESP_AUTH_SMP_INTERNAL_ERR, /*!< Internal error in pairing procedure */ - ESP_AUTH_SMP_UNKNOWN_IO, /*!< Unknown IO capability, unable to decide association model */ - ESP_AUTH_SMP_INIT_FAIL, /*!< SMP pairing initiation failed */ - ESP_AUTH_SMP_CONFIRM_FAIL, /*!< The confirm value does not match */ - ESP_AUTH_SMP_BUSY, /*!< Pending security request on going */ - ESP_AUTH_SMP_ENC_FAIL, /*!< The Controller failed to start encryption */ - ESP_AUTH_SMP_STARTED, /*!< SMP pairing process started */ - ESP_AUTH_SMP_RSP_TIMEOUT, /*!< Security Manager timeout due to no SMP command being received */ - ESP_AUTH_SMP_DIV_NOT_AVAIL, /*!< Encrypted Diversifier value not available */ - ESP_AUTH_SMP_UNSPEC_ERR, /*!< Unspecified failed reason */ - ESP_AUTH_SMP_CONN_TOUT, /*!< Pairing process failed due to connection timeout */ + ESP_AUTH_SMP_PASSKEY_FAIL = 78, /*!< User input of passkey failed. */ + ESP_AUTH_SMP_OOB_FAIL, /*!< OOB data is not available. */ + ESP_AUTH_SMP_PAIR_AUTH_FAIL, /*!< Authentication requirements cannot be met. */ + ESP_AUTH_SMP_CONFIRM_VALUE_FAIL, /*!< Confirm value does not match the calculated comparison value. */ + ESP_AUTH_SMP_PAIR_NOT_SUPPORT, /*!< Pairing is not supported by the device. */ + ESP_AUTH_SMP_ENC_KEY_SIZE, /*!< Resultant encryption key size is not long enough. */ + ESP_AUTH_SMP_INVALID_CMD, /*!< SMP command received is not supported. */ + ESP_AUTH_SMP_UNKNOWN_ERR, /*!< Pairing failed due to an unspecified reason. */ + ESP_AUTH_SMP_REPEATED_ATTEMPT, /*!< Pairing or authentication procedure is disallowed. */ + ESP_AUTH_SMP_INVALID_PARAMETERS, /*!< Command length is invalid or a parameter is out of range. */ + ESP_AUTH_SMP_DHKEY_CHK_FAIL, /*!< DHKey Check value received does not match the calculated value. */ + ESP_AUTH_SMP_NUM_COMP_FAIL, /*!< Confirm values in the numeric comparison protocol do not match. */ + ESP_AUTH_SMP_BR_PARING_IN_PROGR, /*!< Pairing Request over BR/EDR transport is in progress. */ + ESP_AUTH_SMP_XTRANS_DERIVE_NOT_ALLOW, /*!< BR/EDR Link Key or BLE LTK cannot be used for derivation. */ + ESP_AUTH_SMP_INTERNAL_ERR, /*!< Internal error in pairing procedure. */ + ESP_AUTH_SMP_UNKNOWN_IO, /*!< Unknown IO capability, unable to decide association model. */ + ESP_AUTH_SMP_INIT_FAIL, /*!< SMP pairing initiation failed. */ + ESP_AUTH_SMP_CONFIRM_FAIL, /*!< Confirm value does not match. */ + ESP_AUTH_SMP_BUSY, /*!< Pending security request ongoing. */ + ESP_AUTH_SMP_ENC_FAIL, /*!< Controller failed to start encryption. */ + ESP_AUTH_SMP_STARTED, /*!< SMP pairing process started. */ + ESP_AUTH_SMP_RSP_TIMEOUT, /*!< Security Manager timeout due to no SMP command received. */ + ESP_AUTH_SMP_DIV_NOT_AVAIL, /*!< Encrypted Diversify value not available. */ + ESP_AUTH_SMP_UNSPEC_ERR, /*!< Unspecified failure reason. */ + ESP_AUTH_SMP_CONN_TOUT, /*!< Pairing process failed due to connection timeout. */ } esp_ble_auth_fail_rsn_t; /** - * @brief Structure associated with ESP_AUTH_CMPL_EVT - */ -typedef struct -{ - esp_bd_addr_t bd_addr; /*!< BD address of peer device */ - bool key_present; /*!< True if the link key value is valid; false otherwise */ - esp_link_key key; /*!< Link key associated with peer device */ - uint8_t key_type; /*!< The type of link key */ - bool success; /*!< True if authentication succeeded; false otherwise */ - esp_ble_auth_fail_rsn_t fail_reason; /*!< The HCI reason/error code for failure when success is false */ - esp_ble_addr_type_t addr_type; /*!< Peer device address type */ - esp_bt_dev_type_t dev_type; /*!< Device type */ - esp_ble_auth_req_t auth_mode; /*!< Authentication mode */ -} esp_ble_auth_cmpl_t; /*!< The ble authentication complete cb type */ - -/** - * @brief union associated with ble security - */ + * @brief Structure associated with ESP_AUTH_CMPL_EVT. + * Represents the Bluetooth Low Energy authentication complete callback type. + */ +typedef struct { + esp_bd_addr_t bd_addr; /*!< Bluetooth device address of the peer device. */ + bool key_present; /*!< Indicates if a valid link key is present. */ + esp_link_key key; /*!< Link key associated with the peer device. */ + uint8_t key_type; /*!< The type of Link Key (e.g., Long Term Key, Short Term Key). */ + bool success; /*!< TRUE if authentication succeeded, FALSE if failed. */ + uint8_t fail_reason; /*!< Error code for failure, if authentication failed. */ + esp_ble_addr_type_t addr_type; /*!< Peer device address type. */ + esp_bt_dev_type_t dev_type; /*!< Device type. */ + esp_ble_auth_req_t auth_mode; /*!< Authentication mode used. */ +} esp_ble_auth_cmpl_t; + +/** + * @brief Union type associated with Bluetooth Low Energy (BLE) security. + * Contains different types of BLE security-related data. + */ typedef union { - esp_ble_sec_key_notif_t key_notif; /*!< passkey notification */ - esp_ble_sec_req_t ble_req; /*!< BLE SMP related request */ - esp_ble_key_t ble_key; /*!< BLE SMP keys used when pairing */ - esp_ble_local_id_keys_t ble_id_keys; /*!< BLE IR event */ - esp_ble_local_oob_data_t oob_data; /*!< BLE SMP secure connection OOB data */ - esp_ble_auth_cmpl_t auth_cmpl; /*!< Authentication complete indication. */ -} esp_ble_sec_t; /*!< BLE security type */ + esp_ble_sec_key_notif_t key_notif; /*!< Passkey notification information. */ + esp_ble_sec_req_t ble_req; /*!< BLE Security Manager Protocol (SMP) related request information. */ + esp_ble_key_t ble_key; /*!< BLE SMP keys used during pairing. */ + esp_ble_local_id_keys_t ble_id_keys; /*!< Local Identity Root keys and related values. */ + esp_ble_local_oob_data_t oob_data; /*!< OOB data for secure connection. */ + esp_ble_auth_cmpl_t auth_cmpl; /*!< Authentication completion information. */ +} esp_ble_sec_t; + +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_42_FEATURE_SUPPORT == TRUE) -/// Sub Event of ESP_GAP_BLE_SCAN_RESULT_EVT + +/** + * @brief Sub-events of the ESP_GAP_BLE_SCAN_RESULT_EVT event. + * These sub-events provide detailed results of the BLE scan operation. + */ typedef enum { - ESP_GAP_SEARCH_INQ_RES_EVT = 0, /*!< Inquiry result for a peer device. */ - ESP_GAP_SEARCH_INQ_CMPL_EVT = 1, /*!< Inquiry complete. */ - ESP_GAP_SEARCH_DISC_RES_EVT = 2, /*!< Discovery result for a peer device. */ - ESP_GAP_SEARCH_DISC_BLE_RES_EVT = 3, /*!< Discovery result for BLE GATT based service on a peer device. */ - ESP_GAP_SEARCH_DISC_CMPL_EVT = 4, /*!< Discovery complete. */ - ESP_GAP_SEARCH_DI_DISC_CMPL_EVT = 5, /*!< Discovery complete. */ - ESP_GAP_SEARCH_SEARCH_CANCEL_CMPL_EVT = 6, /*!< Search cancelled */ - ESP_GAP_SEARCH_INQ_DISCARD_NUM_EVT = 7, /*!< The number of pkt discarded by flow control */ + ESP_GAP_SEARCH_INQ_RES_EVT = 0, /*!< Inquiry result for a peer device. + Indicates that a device matching the search criteria has been found. */ + ESP_GAP_SEARCH_INQ_CMPL_EVT = 1, /*!< Inquiry complete. + Indicates that the inquiry process has been completed. */ + ESP_GAP_SEARCH_DISC_RES_EVT = 2, /*!< Discovery result for a peer device. + Provides information about a device discovered during the discovery process. */ + ESP_GAP_SEARCH_DISC_BLE_RES_EVT = 3, /*!< Discovery result for BLE GATT-based service on a peer device. + Provides details about a BLE GATT service discovered on a peer device. */ + ESP_GAP_SEARCH_DISC_CMPL_EVT = 4, /*!< Discovery complete. + Indicates that the discovery process has been completed. */ + ESP_GAP_SEARCH_DI_DISC_CMPL_EVT = 5, /*!< Discovery complete. + Used for discovery-related processes, indicating completion. */ + ESP_GAP_SEARCH_SEARCH_CANCEL_CMPL_EVT = 6, /*!< Search cancelled. + Indicates that the search operation has been cancelled. */ + ESP_GAP_SEARCH_INQ_DISCARD_NUM_EVT = 7, /*!< Number of packets discarded by flow control. + Provides the count of packets discarded due to flow control limitations. */ } esp_gap_search_evt_t; -#endif // #if (BLE_42_FEATURE_SUPPORT == TRUE) +#endif// #if (BLE_42_FEATURE_SUPPORT == TRUE) +//@} + /** - * @brief Ble scan result event type, to indicate the - * result is scan response or advertising data or other + * @brief Bluetooth Low Energy (BLE) scan result event types. + * These types indicate the nature of the BLE advertising or scan response data. */ typedef enum { - ESP_BLE_EVT_CONN_ADV = 0x00, /*!< Connectable undirected advertising (ADV_IND) */ - ESP_BLE_EVT_CONN_DIR_ADV = 0x01, /*!< Connectable directed advertising (ADV_DIRECT_IND) */ - ESP_BLE_EVT_DISC_ADV = 0x02, /*!< Scannable undirected advertising (ADV_SCAN_IND) */ - ESP_BLE_EVT_NON_CONN_ADV = 0x03, /*!< Non connectable undirected advertising (ADV_NONCONN_IND) */ - ESP_BLE_EVT_SCAN_RSP = 0x04, /*!< Scan Response (SCAN_RSP) */ + ESP_BLE_EVT_CONN_ADV = 0x00, /*!< Connectable undirected advertising (ADV_IND). + Advertising packets that allow a device to connect to the advertiser. */ + ESP_BLE_EVT_CONN_DIR_ADV = 0x01, /*!< Connectable directed advertising (ADV_DIRECT_IND). + Advertising packets that are directed at a specific device with the intention to establish a connection. */ + ESP_BLE_EVT_DISC_ADV = 0x02, /*!< Scannable undirected advertising (ADV_SCAN_IND). + Advertising packets that allow devices to scan for the advertiser but do not allow direct connection. */ + ESP_BLE_EVT_NON_CONN_ADV = 0x03, /*!< Non-connectable undirected advertising (ADV_NONCONN_IND). + Advertising packets that do not support connection requests and are typically used for broadcasting information. */ + ESP_BLE_EVT_SCAN_RSP = 0x04, /*!< Scan Response (SCAN_RSP). + Response packets sent after a scan request to provide additional information about the advertiser. */ } esp_ble_evt_type_t; -typedef enum{ - ESP_BLE_WHITELIST_REMOVE = 0X00, /*!< remove mac from whitelist */ - ESP_BLE_WHITELIST_ADD = 0X01, /*!< add address to whitelist */ - ESP_BLE_WHITELIST_CLEAR = 0x02, /*!< clear all device in whitelist */ +/** + * @brief Bluetooth Low Energy (BLE) whitelist operation types. + * These operations manage devices in the whitelist for scanning and connection filtering. + */ +typedef enum { + ESP_BLE_WHITELIST_REMOVE = 0x00, /*!< Remove a MAC address from the whitelist. + Used to exclude a specific device from the whitelist. */ + ESP_BLE_WHITELIST_ADD = 0x01, /*!< Add a MAC address to the whitelist. + Used to include a specific device in the whitelist. */ + ESP_BLE_WHITELIST_CLEAR = 0x02, /*!< Clear all devices from the whitelist. + Removes all devices from the whitelist. */ } esp_ble_wl_operation_t; + +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_42_FEATURE_SUPPORT == TRUE) +/** + * @brief Bluetooth Low Energy (BLE) duplicate exceptional list operations. + * This enumeration defines the types of operations that can be performed on the duplicate scan exceptional list. + */ typedef enum { - ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_ADD = 0, /*!< Add device info into duplicate scan exceptional list */ - ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_REMOVE, /*!< Remove device info from duplicate scan exceptional list */ - ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_CLEAN, /*!< Clean duplicate scan exceptional list */ + ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_ADD = 0, /*!< Add device information into the duplicate scan exceptional list. + This operation includes specific device information in the list to handle exceptional cases for duplicate scans. */ + ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_REMOVE, /*!< Remove device information from the duplicate scan exceptional list. + This operation removes specific device information from the list, effectively excluding it from exceptional handling. */ + ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_CLEAN, /*!< Clean the duplicate scan exceptional list. + This operation clears all entries from the exceptional list, resetting it to an empty state. */ } esp_bt_duplicate_exceptional_subcode_type_t; -#endif //#if (BLE_42_FEATURE_SUPPORT == TRUE) +#endif// #if (BLE_42_FEATURE_SUPPORT == TRUE) +//@} + +#define BLE_BIT(n) (1UL<<(n)) /*!< This macro defines a bitwise operation to create a bitmask with only the n-th bit set. */ -#define BLE_BIT(n) (1UL<<(n)) +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_42_FEATURE_SUPPORT == TRUE) +/** + * @brief Enumeration for different types of exceptional scan information in Bluetooth Low Energy (BLE). + * This enumeration defines various types of exceptional scan information that can be used to manage + * specific types of BLE advertising and scanning data. These types help in identifying and categorizing + * exceptional devices or advertisements based on their specific characteristics. + */ typedef enum { - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_ADV_ADDR = 0, /*!< BLE advertising address , device info will be added into ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ADDR_LIST */ - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_LINK_ID, /*!< BLE mesh link ID, it is for BLE mesh, device info will be added into ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_LINK_ID_LIST */ - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_BEACON_TYPE, /*!< BLE mesh beacon AD type, the format is | Len | 0x2B | Beacon Type | Beacon Data | */ - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_PROV_SRV_ADV, /*!< BLE mesh provisioning service uuid, the format is | 0x02 | 0x01 | flags | 0x03 | 0x03 | 0x1827 | .... |` */ - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_PROXY_SRV_ADV, /*!< BLE mesh adv with proxy service uuid, the format is | 0x02 | 0x01 | flags | 0x03 | 0x03 | 0x1828 | .... |` */ - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_PROXY_SOLIC_ADV, /*!< BLE mesh adv with proxy service uuid, the format is | 0x02 | 0x01 | flags | 0x03 | 0x03 | 0x1859 | .... |` */ - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_URI_ADV, /*!< BLE mesh URI adv, the format is ...| Len | 0x24 | data |... */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_ADV_ADDR = 0, /*!< Advertising Address: Represents a Bluetooth Low Energy (BLE) advertising address. + Devices with this type of information are added to the ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ADDR_LIST. + This list is used to manage devices based on their advertising addresses. */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_LINK_ID, /*!< Mesh Link ID: Represents the BLE mesh link ID. This is used specifically for BLE mesh networks. + Devices with this type of information are added to the ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_LINK_ID_LIST. + This list helps in managing devices within a BLE mesh network based on their link IDs. */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_BEACON_TYPE, /*!< Mesh Beacon Type: Represents the BLE mesh beacon advertising data type. + The format includes | Length | 0x2B | Beacon Type | Beacon Data |. + This type is used to handle and manage BLE mesh beacons, which broadcast specific beacon types and data. */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_PROV_SRV_ADV, /*!< Mesh Provisioning Service Advertising: Represents the BLE mesh provisioning service UUID in advertising. + The format includes | 0x02 | 0x01 | Flags | 0x03 | 0x03 | 0x1827 | .... |. + This type helps in identifying devices advertising the mesh provisioning service, which is used for setting up mesh networks. */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_PROXY_SRV_ADV, /*!< Mesh Proxy Service Advertising: Represents the BLE mesh proxy service UUID in advertising. + The format includes | 0x02 | 0x01 | Flags | 0x03 | 0x03 | 0x1828 | .... |. + This type is used to identify devices advertising the mesh proxy service, which allows communication between different parts of a mesh network. */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_PROXY_SOLIC_ADV, /*!< Mesh Proxy Solicitation Advertising: Represents BLE mesh proxy solicitation advertising with a specific UUID. + The format includes | 0x02 | 0x01 | Flags | 0x03 | 0x03 | 0x1859 | .... |. + This type is used for identifying devices that are soliciting connections through proxy services in a BLE mesh network. */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_INFO_MESH_URI_ADV, /*!< Mesh Uniform Resource Identifier (URI) Advertising: Represents BLE mesh URI advertising. + The format includes | Length | 0x24 | Data | .... |. + This type helps in managing devices that advertise URIs, which can provide resources or information relevant to a BLE mesh network. */ } esp_ble_duplicate_exceptional_info_type_t; +/** + * @brief Enumeration for different types of duplicate scan exceptional lists in Bluetooth Low Energy (BLE). + * This enumeration defines various lists that manage exceptional cases for duplicate scanning. + * These lists help in identifying and categorizing exceptional devices or advertisements based on specific characteristics. + */ typedef enum { - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ADDR_LIST = BLE_BIT(0), /*!< duplicate scan exceptional addr list */ - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_LINK_ID_LIST = BLE_BIT(1), /*!< duplicate scan exceptional mesh link ID list */ - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_BEACON_TYPE_LIST = BLE_BIT(2), /*!< duplicate scan exceptional mesh beacon type list */ - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_PROV_SRV_ADV_LIST = BLE_BIT(3), /*!< duplicate scan exceptional mesh adv with provisioning service uuid */ - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_PROXY_SRV_ADV_LIST = BLE_BIT(4), /*!< duplicate scan exceptional mesh adv with proxy service uuid */ - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_PROXY_SOLIC_ADV_LIST = BLE_BIT(5), /*!< duplicate scan exceptional mesh adv with proxy solicitation PDU uuid */ - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_URI_ADV_LIST = BLE_BIT(6), /*!< duplicate scan exceptional URI list */ - ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ALL_LIST = 0xFFFF, /*!< duplicate scan exceptional all list */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ADDR_LIST = BLE_BIT(0), /*!< Duplicate Scan Exceptional Address List: This list contains BLE advertising addresses that are considered exceptions for duplicate scanning. + Devices with addresses in this list will not be treated as duplicates. */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_LINK_ID_LIST = BLE_BIT(1), /*!< Duplicate Scan Exceptional Mesh Link ID List: This list contains BLE mesh link IDs that are considered exceptions for duplicate scanning. + Devices with link IDs in this list will not be treated as duplicates within the mesh network. */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_BEACON_TYPE_LIST = BLE_BIT(2), /*!< Duplicate Scan Exceptional Mesh Beacon Type List: This list contains BLE mesh beacon types that are considered exceptions for duplicate scanning. + Beacon types in this list will not be treated as duplicates. */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_PROV_SRV_ADV_LIST = BLE_BIT(3), /*!< Duplicate Scan Exceptional Mesh Provisioning Service Advertising List: This list contains BLE mesh provisioning service UUIDs that are considered exceptions for duplicate scanning. + Devices advertising provisioning services with UUIDs in this list will not be treated as duplicates. */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_PROXY_SRV_ADV_LIST = BLE_BIT(4), /*!< Duplicate Scan Exceptional Mesh Proxy Service Advertising List: This list contains BLE mesh proxy service UUIDs that are considered exceptions for duplicate scanning. + Devices advertising proxy services with UUIDs in this list will not be treated as duplicates. */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_PROXY_SOLIC_ADV_LIST = BLE_BIT(5), /*!< Duplicate Scan Exceptional Mesh Proxy Solicitation Advertising List: This list contains BLE mesh proxy solicitation UUIDs that are considered exceptions for duplicate scanning. + Devices advertising proxy solicitation with UUIDs in this list will not be treated as duplicates. */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_MESH_URI_ADV_LIST = BLE_BIT(6), /*!< Duplicate Scan Exceptional Mesh Uniform Resource Identifier (URI) Advertising List: This list contains BLE mesh URIs that are considered exceptions for duplicate scanning. + Devices advertising URIs in this list will not be treated as duplicates. */ + ESP_BLE_DUPLICATE_SCAN_EXCEPTIONAL_ALL_LIST = 0xFFFF, /*!< Duplicate Scan Exceptional All List: This list includes all types of BLE exceptional cases for duplicate scanning. + Devices in this list, regardless of their specific characteristics, will not be treated as duplicates. */ } esp_duplicate_scan_exceptional_list_type_t; typedef uint8_t esp_duplicate_info_t[ESP_BD_ADDR_LEN]; -#endif //#if (BLE_42_FEATURE_SUPPORT == TRUE) +#endif// #if (BLE_42_FEATURE_SUPPORT == TRUE) +//@} +//@{ +/** if Bluetooth Low Energy 5.0 Feature Support */ #if (BLE_50_FEATURE_SUPPORT == TRUE) -#define ESP_BLE_GAP_SET_EXT_ADV_PROP_NONCONN_NONSCANNABLE_UNDIRECTED (0 << 0) /*!< Non-Connectable and Non-Scannable Undirected advertising */ -#define ESP_BLE_GAP_SET_EXT_ADV_PROP_CONNECTABLE (1 << 0) /*!< Connectable advertising */ -#define ESP_BLE_GAP_SET_EXT_ADV_PROP_SCANNABLE (1 << 1) /*!< Scannable advertising */ -#define ESP_BLE_GAP_SET_EXT_ADV_PROP_DIRECTED (1 << 2) /*!< Directed advertising */ -#define ESP_BLE_GAP_SET_EXT_ADV_PROP_HD_DIRECTED (1 << 3) /*!< High Duty Cycle Directed Connectable advertising (<= 3.75 ms Advertising Interval) */ -#define ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY (1 << 4) /*!< Use legacy advertising PDUs */ -#define ESP_BLE_GAP_SET_EXT_ADV_PROP_ANON_ADV (1 << 5) /*!< Omit advertiser's address from all PDUs ("anonymous advertising") */ -#define ESP_BLE_GAP_SET_EXT_ADV_PROP_INCLUDE_TX_PWR (1 << 6) /*!< Include TxPower in the extended header of the advertising PDU */ -#define ESP_BLE_GAP_SET_EXT_ADV_PROP_MASK (0x7F) /*!< Reserved for future use */ - -/*!< If extended advertising PDU types are being used (bit 4 = 0) then: - The advertisement shall not be both connectable and scannable. - High duty cycle directed connectable advertising (<= 3.75 ms advertising interval) shall not be used (bit 3 = 0) +//Definitions for setting extended advertising properties in Bluetooth Low Energy (BLE). +#define ESP_BLE_GAP_SET_EXT_ADV_PROP_NONCONN_NONSCANNABLE_UNDIRECTED (0 << 0) /*!< Non-Connectable and Non-Scannable Undirected Advertising: The device does not accept connections or scan requests. */ +#define ESP_BLE_GAP_SET_EXT_ADV_PROP_CONNECTABLE (1 << 0) /*!< Connectable Advertising: The device accepts connections from other devices. */ +#define ESP_BLE_GAP_SET_EXT_ADV_PROP_SCANNABLE (1 << 1) /*!< Scannable Advertising: The device accepts scan requests from other devices, allowing them to request more information. */ +#define ESP_BLE_GAP_SET_EXT_ADV_PROP_DIRECTED (1 << 2) /*!< Directed Advertising: The advertising is targeted towards a specific device, indicated by the Target Address. */ +#define ESP_BLE_GAP_SET_EXT_ADV_PROP_HD_DIRECTED (1 << 3) /*!< High Duty Cycle Directed Connectable Advertising: The device uses a high duty cycle (<= 3.75 ms Advertising Interval) for directed connectable advertising, often used for fast reconnection. */ +#define ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY (1 << 4) /*!< Use Legacy Advertising Protocol Data Units: The advertising uses legacy Protocol Data Unit(PDU) formats, compatible with older BLE devices. */ +#define ESP_BLE_GAP_SET_EXT_ADV_PROP_ANON_ADV (1 << 5) /*!< Anonymous Advertising: The advertiser's address is omitted from all PDUs, enhancing privacy. */ +#define ESP_BLE_GAP_SET_EXT_ADV_PROP_INCLUDE_TX_PWR (1 << 6) /*!< Include Transmit Power in Extended Header: The advertising PDU includes the transmit power level in its extended header, allowing receivers to estimate the range. */ +#define ESP_BLE_GAP_SET_EXT_ADV_PROP_MASK (0x7F) /*!< Reserved for Future Use: This mask covers all defined property bits (0-6), allowing for future expansion. */ + +/* + If extended advertising Protocol Data Unit types are being used (bit 4 = 0) then: + The advertisement shall not be both connectable and scannable. + High duty cycle directed connectable advertising (<= 3.75 ms advertising interval) shall not be used (bit 3 = 0) */ -/*!< ADV_IND */ #define ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_IND (ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY |\ ESP_BLE_GAP_SET_EXT_ADV_PROP_CONNECTABLE |\ - ESP_BLE_GAP_SET_EXT_ADV_PROP_SCANNABLE) -/*!< ADV_DIRECT_IND (low duty cycle) */ + ESP_BLE_GAP_SET_EXT_ADV_PROP_SCANNABLE) /*!< Legacy Advertising Indication (ADV_IND) + This macro sets the properties for legacy connectable and scannable undirected advertising. + Connectable: Allows other devices to initiate a connection. + Scannable: Allows other devices to send scan requests for more information. + Legacy: Uses legacy PDU formats. */ #define ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_LD_DIR (ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY |\ ESP_BLE_GAP_SET_EXT_ADV_PROP_CONNECTABLE |\ - ESP_BLE_GAP_SET_EXT_ADV_PROP_DIRECTED) -/*!< ADV_DIRECT_IND (high duty cycle) */ + ESP_BLE_GAP_SET_EXT_ADV_PROP_DIRECTED) /*!< Legacy Low Duty Cycle Directed Advertising Indication (ADV_DIRECT_IND) + This macro sets the properties for legacy connectable and directed low duty cycle advertising. + Connectable: Allows other devices to initiate a connection. + Directed: Targets a specific device, indicated by the Target Address. + Legacy: Uses legacy PDU formats. + Low Duty Cycle: Does not use high duty cycle (<= 3.75 ms advertising interval). */ #define ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_HD_DIR (ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY |\ ESP_BLE_GAP_SET_EXT_ADV_PROP_CONNECTABLE |\ - ESP_BLE_GAP_SET_EXT_ADV_PROP_HD_DIRECTED) -/*!< ADV_SCAN_IND */ + ESP_BLE_GAP_SET_EXT_ADV_PROP_HD_DIRECTED) /*!< Legacy High Duty Cycle Directed Advertising Indication (ADV_DIRECT_IND) + This macro sets the properties for legacy connectable and directed high duty cycle advertising. + Connectable: Allows other devices to initiate a connection. + Directed: Targets a specific device, indicated by the Target Address. + Legacy: Uses legacy PDU formats. + High Duty Cycle: Uses high duty cycle (<= 3.75 ms advertising interval) for fast reconnection. */ #define ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_SCAN (ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY |\ - ESP_BLE_GAP_SET_EXT_ADV_PROP_SCANNABLE) -/*!< ADV_NONCONN_IND */ -#define ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_NONCONN (ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY) + ESP_BLE_GAP_SET_EXT_ADV_PROP_SCANNABLE) /*!< Legacy Scannable Indication (ADV_SCAN_IND) + This macro sets the properties for legacy scannable undirected advertising. + Scannable: Allows other devices to send scan requests for more information. + Legacy: Uses legacy PDU formats. */ +#define ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY_NONCONN (ESP_BLE_GAP_SET_EXT_ADV_PROP_LEGACY) /*!< Legacy Non-Connectable Indication (ADV_NONCONN_IND) + This macro sets the properties for legacy non-connectable undirected advertising. + Legacy: Uses legacy PDU formats. + Non-Connectable: Does not allow other devices to initiate a connection. */ typedef uint16_t esp_ble_ext_adv_type_mask_t; -#define ESP_BLE_GAP_PHY_1M 1 /*!< Secondery Advertisement PHY is LE1M */ -#define ESP_BLE_GAP_PHY_2M 2 /*!< Secondery Advertisement PHY is LE2M */ -#define ESP_BLE_GAP_PHY_CODED 3 /*!< Secondery Advertisement PHY is LE Coded */ +/* + Bluetooth Low Energy (BLE) Physical Layer settings for secondary advertisements. + These macros define the physical layer (PHY) options for BLE secondary advertising. +*/ +#define ESP_BLE_GAP_PHY_1M 1 /*!< Low Energy 1 Megabit per second (LE 1M PHY) + This PHY option is used for BLE secondary advertisements at a data rate of 1 Mbps. + It is the default PHY for most BLE operations, offering a balance between range and data rate. */ +#define ESP_BLE_GAP_PHY_2M 2 /*!< Low Energy 2 Megabit per second (LE 2M PHY) + This PHY option is used for BLE secondary advertisements at a higher data rate of 2 Mbps. + It provides faster data transfer rates compared to LE 1M PHY, but with a reduced range. */ +#define ESP_BLE_GAP_PHY_CODED 3 /*!< Low Energy Coded PHY (LE Coded PHY). + This PHY option is used for BLE secondary advertisements with enhanced range capabilities. + LE Coded PHY uses coding schemes to achieve longer range and better reliability, albeit at lower data rates. + It is particularly useful for applications requiring extended range and robustness in signal transmission. */ typedef uint8_t esp_ble_gap_phy_t; -#define ESP_BLE_GAP_NO_PREFER_TRANSMIT_PHY (1<<0) /*!< No Prefer TX PHY supported by controller */ -#define ESP_BLE_GAP_NO_PREFER_RECEIVE_PHY (1<<1) /*!< No Prefer RX PHY supported by controller */ +#define ESP_BLE_GAP_NO_PREFER_TRANSMIT_PHY (1<<0) /*!< No Prefer TX Physical Layer supported by controller. */ +#define ESP_BLE_GAP_NO_PREFER_RECEIVE_PHY (1<<1) /*!< No Prefer RX Physical Layer supported by controller. */ typedef uint8_t esp_ble_gap_all_phys_t; - -/// Primary phy only support 1M and LE coded phy -#define ESP_BLE_GAP_PRI_PHY_1M ESP_BLE_GAP_PHY_1M /*!< Primary Phy is LE1M */ -#define ESP_BLE_GAP_PRI_PHY_CODED ESP_BLE_GAP_PHY_CODED /*!< Primary Phy is LE CODED */ -typedef uint8_t esp_ble_gap_pri_phy_t; // primary phy - -#define ESP_BLE_GAP_PHY_1M_PREF_MASK (1 << 0) /*!< The Host prefers use the LE1M transmitter or receiver PHY */ -#define ESP_BLE_GAP_PHY_2M_PREF_MASK (1 << 1) /*!< The Host prefers use the LE2M transmitter or receiver PHY */ -#define ESP_BLE_GAP_PHY_CODED_PREF_MASK (1 << 2) /*!< The Host prefers use the LE CODED transmitter or receiver PHY */ + +/* + Bluetooth Low Energy (BLE) Physical Layer preferences for transmission and reception. + These macros define the options for specifying whether the controller has no preference for the TX (transmit) and RX (receive) PHYs. +*/ +#define ESP_BLE_GAP_PRI_PHY_1M ESP_BLE_GAP_PHY_1M /*!< No Preference for Transmit Physical Layer + This macro indicates that the BLE controller has no preference for the TX PHY. + The controller will choose the appropriate PHY for transmission based on its internal criteria and conditions. + It allows flexibility in selecting the PHY for data transmission, optimizing for factors such as range, speed, and reliability. */ +#define ESP_BLE_GAP_PRI_PHY_CODED ESP_BLE_GAP_PHY_CODED /*!< No Preference for Receive Physical Layer + This macro indicates that the BLE controller has no preference for the RX PHY. + The controller will select the suitable PHY for receiving data based on its internal criteria and conditions. + It provides flexibility in choosing the PHY for data reception, ensuring optimal performance for various BLE applications. */ +typedef uint8_t esp_ble_gap_pri_phy_t; + +/* + BLE Physical Layer Preference Masks + These macros define the preference masks for selecting the BLE Physical Layer (PHY) for transmission and reception. +*/ +#define ESP_BLE_GAP_PHY_1M_PREF_MASK (1 << 0) /*!< Low Energy 1 Megabit per second (1M) PHY Preference + This macro indicates that the Host prefers to use the 1M PHY for both transmission and reception. + The 1M PHY offers a balance between range and data rate, making it suitable for general BLE applications. */ +#define ESP_BLE_GAP_PHY_2M_PREF_MASK (1 << 1) /*!< Low Energy 2 Megabit per second (2M) PHY Preference + This macro indicates that the Host prefers to use the 2M PHY for both transmission and reception. + The 2M PHY provides a higher data rate, which is beneficial for applications requiring faster data transfer. */ +#define ESP_BLE_GAP_PHY_CODED_PREF_MASK (1 << 2) /*!< Low Energy Coded PHY Preference + This macro indicates that the Host prefers to use the coded PHY for both transmission and reception. + The coded PHY enhances range and reliability, especially in challenging environments, by using error correction techniques. */ typedef uint8_t esp_ble_gap_phy_mask_t; -#define ESP_BLE_GAP_PHY_OPTIONS_NO_PREF 0 /*!< The Host has no preferred coding when transmitting on the LE Coded PHY */ -#define ESP_BLE_GAP_PHY_OPTIONS_PREF_S2_CODING 1 /*!< The Host prefers that S=2 coding be used when transmitting on the LE Coded PHY */ -#define ESP_BLE_GAP_PHY_OPTIONS_PREF_S8_CODING 2 /*!< The Host prefers that S=8 coding be used when transmitting on the LE Coded PHY */ +/* + BLE PHY Options for Coded PHY + These macros define the preference options for coding schemes used when transmitting on the BLE Coded PHY. +*/ +#define ESP_BLE_GAP_PHY_OPTIONS_NO_PREF 0 /*!< No Preference for Coding Scheme + This macro indicates that the Host has no preference for the coding scheme when transmitting on the BLE Coded PHY. + The controller is free to choose any available coding scheme. */ +#define ESP_BLE_GAP_PHY_OPTIONS_PREF_S2_CODING 1 /*!< Preference for S=2 Coding Scheme + This macro indicates that the Host prefers to use S=2 coding when transmitting on the BLE Coded PHY. + The S=2 coding scheme provides a moderate trade-off between range and data rate. + It doubles the range compared to the 1M PHY but reduces the data rate. */ +#define ESP_BLE_GAP_PHY_OPTIONS_PREF_S8_CODING 2 /*!< Preference for S=8 Coding Scheme + This macro indicates that the Host prefers to use S=8 coding when transmitting on the BLE Coded PHY. + The S=8 coding scheme significantly enhances the range at the cost of a reduced data rate. + It is suitable for applications requiring long-range communication. */ typedef uint16_t esp_ble_gap_prefer_phy_options_t; -#define ESP_BLE_GAP_EXT_SCAN_CFG_UNCODE_MASK 0x01 /*!< Scan Advertisements on the LE1M PHY */ -#define ESP_BLE_GAP_EXT_SCAN_CFG_CODE_MASK 0x02 /*!< Scan advertisements on the LE coded PHY */ +/* + Extended Scanning Configuration Mask + These macros define the configuration options for scanning BLE advertisements on different Physical Layers. +*/ +#define ESP_BLE_GAP_EXT_SCAN_CFG_UNCODE_MASK 0x01 /*!< Scan on 1M PHY. + This macro enables scanning of BLE advertisements on the Low Energy 1 Megabit per second (1M) Physical Layer. + The 1M PHY is the standard BLE PHY providing a balance between data rate and range. */ +#define ESP_BLE_GAP_EXT_SCAN_CFG_CODE_MASK 0x02 /*!< Scan on Coded PHY + This macro enables scanning of BLE advertisements on the Low Energy coded Physical Layer. + The coded PHY enhances the range of BLE communication at the cost of a reduced data rate. + It is suitable for applications that require long-range scanning. */ typedef uint8_t esp_ble_ext_scan_cfg_mask_t; -/// Advertising data -#define ESP_BLE_GAP_EXT_ADV_DATA_COMPLETE 0x00 /*!< extended advertising data compete */ -#define ESP_BLE_GAP_EXT_ADV_DATA_INCOMPLETE 0x01 /*!< extended advertising data incomplete */ -#define ESP_BLE_GAP_EXT_ADV_DATA_TRUNCATED 0x02 /*!< extended advertising data truncated mode */ +/* + Extended Advertising Data Status + These macros define the status of extended advertising data packets in Bluetooth Low Energy (BLE). +*/ +#define ESP_BLE_GAP_EXT_ADV_DATA_COMPLETE 0x00 /*!< Extended Advertising Data Complete + This macro indicates that the extended advertising data is complete and contains all the necessary information. + Use this status when the entire dataset is included in the advertising packet. */ +#define ESP_BLE_GAP_EXT_ADV_DATA_INCOMPLETE 0x01 /*!< Extended Advertising Data Incomplete + This macro indicates that the extended advertising data is incomplete. + Use this status when the dataset is too large to fit in a single advertising packet and additional packets are expected. */ +#define ESP_BLE_GAP_EXT_ADV_DATA_TRUNCATED 0x02 /*!< Extended Advertising Data Truncated + This macro indicates that the extended advertising data is in truncated mode. + Use this status when the advertising packet contains only a portion of the dataset, and no further packets will be sent. */ typedef uint8_t esp_ble_gap_ext_adv_data_status_t; -/// Advertising SYNC policy -#define ESP_BLE_GAP_SYNC_POLICY_BY_ADV_INFO 0 /*!< sync policy by advertising info */ -#define ESP_BLE_GAP_SYNC_POLICY_BY_PERIODIC_LIST 1 /*!< periodic advertising sync policy */ +/* + Synchronous Connection Policy + These macros define the policies for establishing synchronous connections in Bluetooth Low Energy (BLE). +*/ +#define ESP_BLE_GAP_SYNC_POLICY_BY_ADV_INFO 0 /*!< Synchronous Connection by Advertising Information + This macro indicates that the synchronous connection policy is based on the advertising information received. + Use this policy when the connection parameters are determined by the advertising packets. */ +#define ESP_BLE_GAP_SYNC_POLICY_BY_PERIODIC_LIST 1 /*!< Periodic Advertising Synchronous Connection Policy + This macro indicates that the synchronous connection policy is based on a periodic advertising list. + Use this policy when the connection parameters are determined by entries in a predefined periodic advertising list. */ typedef uint8_t esp_ble_gap_sync_t; -/// Advertising report -#define ESP_BLE_ADV_REPORT_EXT_ADV_IND (1<<0) /*!< advertising report with extended advertising indication type */ -#define ESP_BLE_ADV_REPORT_EXT_SCAN_IND (1<<1) /*!< advertising report with extended scan indication type */ -#define ESP_BLE_ADV_REPORT_EXT_DIRECT_ADV (1<<2) /*!< advertising report with extended direct advertising indication type */ -#define ESP_BLE_ADV_REPORT_EXT_SCAN_RSP (1<<3) /*!< advertising report with extended scan response indication type */ - -/*!< Bluetooth 5.0, Vol 2, Part E, 7.7.65.13 */ -#define ESP_BLE_LEGACY_ADV_TYPE_IND (0x13) /*!< advertising report with legacy advertising indication type */ -#define ESP_BLE_LEGACY_ADV_TYPE_DIRECT_IND (0x15) /*!< advertising report with legacy direct indication type */ -#define ESP_BLE_LEGACY_ADV_TYPE_SCAN_IND (0x12) /*!< advertising report with legacy scan indication type */ -#define ESP_BLE_LEGACY_ADV_TYPE_NONCON_IND (0x10) /*!< advertising report with legacy non connectable indication type */ -#define ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADV_IND (0x1b) /*!< advertising report with legacy scan response indication type */ -#define ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADV_SCAN_IND (0x1a) /*!< advertising report with legacy advertising with scan response indication type */ +/* + Advertising Report Types + These macros define the types of advertising reports that can be received in Bluetooth Low Energy (BLE) scanning. +*/ +#define ESP_BLE_ADV_REPORT_EXT_ADV_IND (1<<0) /*!< Extended Advertising Indication Report + This macro indicates that the advertising report corresponds to an extended advertising indication type. + Extended advertising indications are used in Bluetooth LE 5.0 and later to advertise additional data and support larger payloads. */ +#define ESP_BLE_ADV_REPORT_EXT_SCAN_IND (1<<1) /*!< Extended Scan Indication Report + This macro indicates that the advertising report corresponds to an extended scan indication type. + Extended scan indications are used to inform scanners about the presence of devices in a more detailed manner, including larger advertising data. */ +#define ESP_BLE_ADV_REPORT_EXT_DIRECT_ADV (1<<2) /*!< Extended Direct Advertising Indication Report + This macro indicates that the advertising report corresponds to an extended direct advertising indication type. + Direct advertising indications are used for directed advertisements, which are targeted towards a specific device address. */ +#define ESP_BLE_ADV_REPORT_EXT_SCAN_RSP (1<<3) /*!< Extended Scan Response Indication Report + This macro indicates that the advertising report corresponds to an extended scan response indication type. + Extended scan responses provide additional data in response to a scan request and can include more extensive information about the advertising device. */ +/* + Legacy Advertising Report Types + These macros define the types of advertising reports that can be received in Bluetooth Low Energy (BLE) scanning, specifically for legacy advertising types. +*/ +#define ESP_BLE_LEGACY_ADV_TYPE_IND (0x13) /*!< Legacy Advertising Indication Report + This macro indicates that the advertising report corresponds to a legacy advertising indication type. + Legacy advertising indications are used in Bluetooth LE versions before 5.0, where the advertising data and payload are limited compared to extended advertising. */ +#define ESP_BLE_LEGACY_ADV_TYPE_DIRECT_IND (0x15) /*!< Legacy Direct Advertising Indication Report + This macro indicates that the advertising report corresponds to a legacy direct advertising indication type. + Direct advertising indications are used for targeted advertising, where the advertisement is directed towards a specific device address. */ +#define ESP_BLE_LEGACY_ADV_TYPE_SCAN_IND (0x12) /*!< Legacy Scan Indication Report + This macro indicates that the advertising report corresponds to a legacy scan indication type. + Scan indications are used to advertise the device's presence in a way that allows other devices to perform a scan and discover it. */ +#define ESP_BLE_LEGACY_ADV_TYPE_NONCON_IND (0x10) /*!< Legacy Non-Connectable Advertising Indication Report + This macro indicates that the advertising report corresponds to a legacy non-connectable advertising indication type. + Non-connectable advertisements are used for broadcasting information to nearby devices without establishing a connection. */ +#define ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADV_IND (0x1b) /*!< Legacy Scan Response to Advertising Indication Report + This macro indicates that the advertising report corresponds to a legacy scan response to advertising indication type. + This type of report is used when a scan response is sent in response to an advertising packet, providing additional information about the advertiser. */ +#define ESP_BLE_LEGACY_ADV_TYPE_SCAN_RSP_TO_ADV_SCAN_IND (0x1a) /*!< Legacy Scan Response to Advertising with Scan Indication Report + This macro indicates that the advertising report corresponds to a legacy advertising with scan response indication type. + This report is used for advertisements that include a scan response, providing additional information in response to a scan request. */ typedef uint8_t esp_ble_gap_adv_type_t; -/// Extend advertising tx power, range: [-127, +126] dBm -#define EXT_ADV_TX_PWR_NO_PREFERENCE (127) /*!< host has no preference for tx power */ +#define EXT_ADV_TX_PWR_NO_PREFERENCE (127) /*!< Extended Advertising Transmission Power Preference + This macro value indicates that the host does not have a specific preference for the transmission power level used during extended advertising. + When set to 127, it signifies that the host is indifferent to the power level and the BLE stack can select the power level based on other factors such as hardware capabilities or regulatory requirements. + Transmission power levels are specified in decibels milli watts (dBm). + The range of valid transmission power values is from -127 dBm (minimum) to +126 dBm (maximum). + Setting this value allows the BLE stack to choose an appropriate power level based on the device's configuration and operational environment. */ /** -* @brief ext adv parameters -*/ + * @brief Extended Advertising Parameters + * This structure holds the parameters used to configure extended advertising in Bluetooth Low Energy (BLE). + */ typedef struct { - esp_ble_ext_adv_type_mask_t type; /*!< ext adv type */ - uint32_t interval_min; /*!< ext adv minimum interval */ - uint32_t interval_max; /*!< ext adv maximum interval */ - esp_ble_adv_channel_t channel_map; /*!< ext adv channel map */ - esp_ble_addr_type_t own_addr_type; /*!< ext adv own address type */ - esp_ble_addr_type_t peer_addr_type; /*!< ext adv peer address type */ - esp_bd_addr_t peer_addr; /*!< ext adv peer address */ - esp_ble_adv_filter_t filter_policy; /*!< ext adv filter policy */ - int8_t tx_power; /*!< ext adv tx power */ - esp_ble_gap_pri_phy_t primary_phy; /*!< ext adv primary phy */ - uint8_t max_skip; /*!< ext adv maximum skip */ - esp_ble_gap_phy_t secondary_phy; /*!< ext adv secondary phy */ - uint8_t sid; /*!< ext adv sid */ - bool scan_req_notif; /*!< ext adv scan request event notify */ + esp_ble_ext_adv_type_mask_t type; /*!< Extended advertising type mask. Specifies the type of extended advertising being used. Possible values include connectable, scannable, and non-connectable types. */ + uint32_t interval_min; /*!< Minimum interval between extended advertising events, in units of 0.625 ms. This value sets the shortest duration between consecutive advertising events. The interval range is from 0x0020 (20 ms) to 0xFFFF (10.24 seconds). */ + uint32_t interval_max; /*!< Maximum interval between extended advertising events, in units of 0.625 ms. This value sets the longest duration between consecutive advertising events. The interval range is from 0x0020 (20 ms) to 0xFFFF (10.24 seconds). */ + esp_ble_adv_channel_t channel_map; /*!< Channel map for extended advertising. Defines the advertising channels that will be used for transmitting advertising packets. Typically, this includes channels 37, 38, and 39. */ + esp_ble_addr_type_t own_addr_type; /*!< Address type of the local device for extended advertising. This can be public, random, or any other valid address type. */ + esp_ble_addr_type_t peer_addr_type; /*!< Address type of the peer device to which the advertising is directed (if applicable). This can be public, random, or any other valid address type. */ + esp_bd_addr_t peer_addr; /*!< Address of the peer device to which the advertising is directed (if applicable). This field is used for directed advertising types. */ + esp_ble_adv_filter_t filter_policy; /*!< Filter policy for extended advertising. Determines which devices' scan requests and connections will be accepted or rejected based on their address and other criteria. */ + int8_t tx_power; /*!< Transmission power level for extended advertising, in dBm. This value specifies the power at which advertising packets are transmitted. Typical range is from -127 dBm (lowest) to +126 dBm (highest), with 127 indicating no preference. */ + esp_ble_gap_pri_phy_t primary_phy; /*!< Primary Physical Layer used for extended advertising. Specifies whether the advertising will use 1M, 2M, or Coded PHY. */ + uint8_t max_skip; /*!< Maximum number of advertising events to skip. This value controls how many consecutive advertising events can be skipped before resuming advertising. */ + esp_ble_gap_phy_t secondary_phy; /*!< Secondary Physical Layer used for extended advertising, if applicable. Specifies whether the secondary advertising will use 1M, 2M, or Coded PHY. */ + uint8_t sid; /*!< Advertising SID (Service ID) for extended advertising. Used to identify the advertising set when multiple sets are being used. */ + bool scan_req_notif; /*!< Flag indicating whether scan request notifications should be sent. If true, the device will notify when a scan request is received. */ } esp_ble_gap_ext_adv_params_t; /** -* @brief ext scan config -*/ + * @brief Extended Scan Configuration + * This structure holds configuration parameters for extended scanning in Bluetooth Low Energy (BLE). + */ typedef struct { - esp_ble_scan_type_t scan_type; /*!< ext scan type */ - uint16_t scan_interval; /*!< ext scan interval */ - uint16_t scan_window; /*!< ext scan window */ + esp_ble_scan_type_t scan_type; /*!< Type of scan to be performed. This determines whether the scan is active or passive: + `ESP_BLE_SCAN_TYPE_ACTIVE`: Active scan where scan requests are sent. + `ESP_BLE_SCAN_TYPE_PASSIVE`: Passive scan where only advertising packets are received. */ + uint16_t scan_interval; /*!< Interval between consecutive scanning events, in units of 0.625 ms. This value defines how often the scanning is performed. The interval range is from 0x0004 (2.5 ms) to 0xFFFF (10.24 seconds). */ + uint16_t scan_window; /*!< Duration of each scanning event, in units of 0.625 ms. This value sets how long the scanner will listen for advertising packets during each scanning event. The window range is from 0x0004 (2.5 ms) to 0xFFFF (10.24 seconds). */ } esp_ble_ext_scan_cfg_t; /** -* @brief ext scan parameters -*/ + * @brief Extended Scan Parameters + * This structure holds parameters used to configure extended scanning operations. + */ typedef struct { - esp_ble_addr_type_t own_addr_type; /*!< ext scan own address type */ - esp_ble_scan_filter_t filter_policy; /*!< ext scan filter policy */ - esp_ble_scan_duplicate_t scan_duplicate; /*!< ext scan duplicate scan */ - esp_ble_ext_scan_cfg_mask_t cfg_mask; /*!< ext scan config mask */ - esp_ble_ext_scan_cfg_t uncoded_cfg; /*!< ext scan uncoded config parameters */ - esp_ble_ext_scan_cfg_t coded_cfg; /*!< ext scan coded config parameters */ + esp_ble_addr_type_t own_addr_type; /*!< Address type of the local device used for extended scanning. */ + esp_ble_scan_filter_t filter_policy; /*!< Filter policy for extended scanning. Determines which devices' advertising packets will be accepted or rejected based on their address and other criteria. */ + esp_ble_scan_duplicate_t scan_duplicate; /*!< Duplicate filtering policy for scanning. */ + esp_ble_ext_scan_cfg_mask_t cfg_mask; /*!< Mask specifying which extended scan configuration parameters are set. */ + esp_ble_ext_scan_cfg_t uncoded_cfg; /*!< Configuration parameters for extended scanning on the Low Energy 1M and 2M PHYs. This includes scan interval and window settings for these PHYs. */ + esp_ble_ext_scan_cfg_t coded_cfg; /*!< Configuration parameters for extended scanning on the Low Energy Coded PHY. This includes scan interval and window settings for this PHY. */ } esp_ble_ext_scan_params_t; /** -* @brief create extend connection parameters -*/ + * @brief Create Extended Connection Parameters + * This structure holds the parameters used to establish and maintain an extended BLE connection. + */ typedef struct { - uint16_t scan_interval; /*!< init scan interval */ - uint16_t scan_window; /*!< init scan window */ - uint16_t interval_min; /*!< minimum interval */ - uint16_t interval_max; /*!< maximum interval */ - uint16_t latency; /*!< ext scan type */ - uint16_t supervision_timeout; /*!< connection supervision timeout */ - uint16_t min_ce_len; /*!< minimum ce length */ - uint16_t max_ce_len; /*!< maximum ce length */ + uint16_t scan_interval; /*!< Initial scan interval, in units of 0.625 ms. Determines how often the scanning is performed. The interval range is from 0x0004 (2.5 ms) to 0xFFFF (10.24 seconds). */ + uint16_t scan_window; /*!< Initial scan window, in units of 0.625 ms. Specifies the duration of each scan event. The window range is from 0x0004 (2.5 ms) to 0xFFFF (10.24 seconds). */ + uint16_t interval_min; /*!< Minimum connection interval, in units of 1.25 ms. The minimum time between two consecutive connection events. The interval range is from 0x0006 (7.5 ms) to 0x0C80 (4 seconds). */ + uint16_t interval_max; /*!< Maximum connection interval, in units of 1.25 ms. The maximum time between two consecutive connection events. The interval range is from 0x0006 (7.5 ms) to 0x0C80 (4 seconds). */ + uint16_t latency; /*!< Connection latency, which specifies the number of connection events that the slave device can skip. This helps to reduce the power consumption by skipping connection events. */ + uint16_t supervision_timeout; /*!< Connection supervision timeout, in units of 10 ms. The timeout period during which the master expects the slave to respond to connection events. If the slave does not respond within this time, the connection is considered lost. The timeout range is from 0x000A (100 ms) to 0x0C80 (32 seconds). */ + uint16_t min_ce_len; /*!< Minimum connection event length, in units of 1.25 ms. Defines the minimum length of each connection event. This value can be used to adjust how much time is allocated for data transfer during each connection event. */ + uint16_t max_ce_len; /*!< Maximum connection event length, in units of 1.25 ms. Defines the maximum length of each connection event. This value can be used to adjust how much time is allocated for data transfer during each connection event. */ } esp_ble_gap_conn_params_t; /** -* @brief extend adv enable parameters -*/ + * @brief Extended Advertising Enable Parameters + * This structure holds the parameters used to enable extended advertising. + */ typedef struct { - uint8_t instance; /*!< advertising handle */ - int duration; /*!< advertising duration */ - int max_events; /*!< maximum number of extended advertising events */ + uint8_t instance; /*!< Advertising handle, which identifies the advertising instance. Each advertising instance must have a unique handle. */ + int duration; /*!< Advertising duration, in units of seconds. Specifies how long the advertising should continue before stopping automatically. A value of 0 means that advertising will continue indefinitely. */ + int max_events; /*!< Maximum number of extended advertising events to be transmitted. If this value is greater than 0, advertising will stop after the specified number of events have been transmitted. */ } esp_ble_gap_ext_adv_t; /** -* @brief periodic adv parameters -*/ + * @brief Periodic Advertising Parameters + * This structure holds the parameters used for periodic advertising, which allows BLE devices to send periodic advertising packets that can be synchronized with other devices. + */ typedef struct { - uint16_t interval_min; /*!< periodic advertising minimum interval */ - uint16_t interval_max; /*!< periodic advertising maximum interval */ - uint8_t properties; /*!< periodic advertising properties */ + uint16_t interval_min; /*!< Minimum interval between consecutive periodic advertising events, in units of 1.25 ms. The range is from 0x0006 (7.5 ms) to 0xFFFF (81.92 seconds). */ + uint16_t interval_max; /*!< Maximum interval between consecutive periodic advertising events, in units of 1.25 ms. The range is from 0x0006 (7.5 ms) to 0xFFFF (81.92 seconds). */ + uint8_t properties; /*!< Periodic advertising properties, such as whether the periodic advertising is high duty cycle or low duty cycle. */ } esp_ble_gap_periodic_adv_params_t; /** -* @brief periodic adv sync parameters -*/ + * @brief Periodic Advertising Synchronization Parameters + * This structure is used to define parameters for synchronizing with periodic advertising events. + */ typedef struct { - esp_ble_gap_sync_t filter_policy; /*!< Configures the filter policy for periodic advertising sync: - 0: Use Advertising SID, Advertiser Address Type, and Advertiser Address parameters to determine the advertiser to listen to. - 1: Use the Periodic Advertiser List to determine the advertiser to listen to. */ + esp_ble_gap_sync_t filter_policy; /*!< Configures the filter policy for periodic advertising synchronization: + - `0`: Use Advertising Service Identifier, Advertiser Address Type, and Advertiser Address parameters to determine the advertiser to listen to. + - `1`: Use the Periodic Advertiser List to determine the advertiser to listen to. + This policy helps in filtering which periodic advertising events the device should sync with based on the given criteria. */ + #if (CONFIG_BT_BLE_FEAT_CREATE_SYNC_ENH) - esp_ble_gap_sync_t reports_disabled; /*!< Supported only by esp32c2, esp32c6, and esp32h2; can be set by menuconfig: - 0: Reporting initially enabled. - 1: Reporting initially disabled. */ - esp_ble_gap_sync_t filter_duplicates; /*!< Supported only by esp32c2, esp32c6, and esp32h2; can be set by menuconfig: - 0: Duplicate filtering initially disabled. - 1: Duplicate filtering initially enabled. */ + esp_ble_gap_sync_t reports_disabled; /*!< Supported only by specific ESP32 models (esp32c2, esp32c6, and esp32h2); configurable via menuconfig: + - `0`: Reporting initially enabled. The device will start reporting periodic advertising data as soon as synchronization is established. + - `1`: Reporting initially disabled. Reporting of periodic advertising data will be disabled until explicitly enabled. + This option allows control over whether periodic advertising data reporting is active at the start. */ + + esp_ble_gap_sync_t filter_duplicates; /*!< Supported only by specific ESP32 models (esp32c2, esp32c6, and esp32h2); configurable via menuconfig: + - `0`: Duplicate filtering initially disabled. All received periodic advertising packets will be processed, including duplicates. + - `1`: Duplicate filtering initially enabled. The device will filter out duplicate periodic advertising packets to avoid processing the same data multiple times. + This setting controls whether duplicate packets are filtered out, which can help reduce unnecessary processing of repeated data. */ #endif - uint8_t sid; /*!< SID of the periodic advertising */ - esp_ble_addr_type_t addr_type; /*!< Address type of the periodic advertising */ - esp_bd_addr_t addr; /*!< Address of the periodic advertising */ - uint16_t skip; /*!< Maximum number of periodic advertising events that can be skipped */ - uint16_t sync_timeout; /*!< Synchronization timeout */ + + uint8_t sid; /*!< Service Identifier (SID) of the periodic advertising. This identifier helps to filter and identify the specific service whose periodic advertising packets the device should synchronize with. */ + esp_ble_addr_type_t addr_type; /*!< Address type of the periodic advertising. This specifies the type of address used by the advertiser, such as public, random, etc. */ + esp_bd_addr_t addr; /*!< Address of the periodic advertising device. This is the Bluetooth address of the device that is broadcasting the periodic advertising packets. */ + uint16_t skip; /*!< Maximum number of periodic advertising events that can be skipped before synchronization is lost. This parameter helps manage synchronization reliability by specifying how many events can be missed before resynchronizing. */ + uint16_t sync_timeout; /*!< Synchronization timeout, in units of 10 ms. This is the maximum time allowed for maintaining synchronization with the periodic advertising device. If the synchronization is lost or not maintained within this timeout, the synchronization process may need to be restarted. */ } esp_ble_gap_periodic_adv_sync_params_t; + /** -* @brief extend adv report parameters -*/ + * @brief Extended Advertising Report Parameters + * This structure is used to represent the information obtained from an extended advertising report. + */ typedef struct { - // uint8_t props; - // uint8_t legacy_event_type; - esp_ble_gap_adv_type_t event_type; /*!< extend advertising type */ - uint8_t addr_type; /*!< extend advertising address type */ - esp_bd_addr_t addr; /*!< extend advertising address */ - esp_ble_gap_pri_phy_t primary_phy; /*!< extend advertising primary phy */ - esp_ble_gap_phy_t secondly_phy; /*!< extend advertising secondary phy */ - uint8_t sid; /*!< extend advertising sid */ - uint8_t tx_power; /*!< extend advertising tx power */ - int8_t rssi; /*!< extend advertising rssi */ - uint16_t per_adv_interval; /*!< periodic advertising interval */ - uint8_t dir_addr_type; /*!< direct address type */ - esp_bd_addr_t dir_addr; /*!< direct address */ - esp_ble_gap_ext_adv_data_status_t data_status; /*!< data type */ - uint8_t adv_data_len; /*!< extend advertising data length */ - uint8_t adv_data[251]; /*!< extend advertising data */ + esp_ble_gap_adv_type_t event_type; /*!< Extended advertising event type. Indicates the type of extended advertising event. */ + uint8_t addr_type; /*!< Extended advertising address type. Specifies the type of Bluetooth address used by the advertiser (e.g., public, random). */ + esp_bd_addr_t addr; /*!< Extended advertising address. The Bluetooth address of the device that is broadcasting the extended advertising packets. */ + esp_ble_gap_pri_phy_t primary_phy; /*!< Extended advertising primary Physical Layer. Indicates the PHY (Physical Layer) used for the primary advertising channel (e.g., 1M, 2M, Coded). */ + esp_ble_gap_phy_t secondly_phy; /*!< Extended advertising secondary Physical Layer. Indicates the PHY used for the secondary advertising channel. */ + uint8_t sid; /*!< Extended advertising Service ID (SID). Identifies the specific service associated with the advertising data. */ + uint8_t tx_power; /*!< Extended advertising transmission power. The power level of the transmitted advertising packets, measured in dBm. */ + int8_t rssi; /*!< Extended advertising Received Signal Strength Indication (RSSI). The strength of the received signal, measured in dBm. Range: -127 dBm to +20 dBm. */ + uint16_t per_adv_interval; /*!< Periodic advertising interval. The interval at which the periodic advertising packets are broadcasted. */ + uint8_t dir_addr_type; /*!< Direct address type. The address type used in directed advertising (e.g., public, random). */ + esp_bd_addr_t dir_addr; /*!< Direct address. The Bluetooth address of the device being targeted by directed advertising. */ + esp_ble_gap_ext_adv_data_status_t data_status; /*!< Data status. Indicates the status of the extended advertising data (e.g., complete, incomplete, truncated). */ + uint8_t adv_data_len; /*!< Extended advertising data length. The length of the advertising data in bytes. */ + uint8_t adv_data[251]; /*!< Extended advertising data. The actual data payload of the extended advertising packet, up to 251 bytes. */ } esp_ble_gap_ext_adv_report_t; /** -* @brief periodic adv report parameters -*/ + * @brief Periodic Advertising Report Parameters + * This structure is used to represent the information obtained from a periodic advertising report. + */ typedef struct { - uint16_t sync_handle; /*!< periodic advertising train handle */ - uint8_t tx_power; /*!< periodic advertising tx power*/ - int8_t rssi; /*!< periodic advertising rssi */ - esp_ble_gap_ext_adv_data_status_t data_status; /*!< periodic advertising data type*/ - uint8_t data_length; /*!< periodic advertising data length */ - uint8_t data[251]; /*!< periodic advertising data */ + uint16_t sync_handle; /*!< Periodic advertising synchronization handle. A handle used to identify the synchronization with a specific periodic advertising train. */ + uint8_t tx_power; /*!< Periodic advertising transmission power. The power level of the transmitted periodic advertising packets, measured in dBm. */ + int8_t rssi; /*!< Periodic advertising Received Signal Strength Indication (RSSI). The strength of the received periodic advertising signal, measured in dBm. */ + esp_ble_gap_ext_adv_data_status_t data_status; /*!< Data status. Indicates the status of the periodic advertising data (e.g., complete, incomplete, truncated). */ + uint8_t data_length; /*!< Periodic advertising data length. The length of the periodic advertising data in bytes. */ + uint8_t data[251]; /*!< Periodic advertising data. The actual data payload of the periodic advertising packet, up to 251 bytes. */ } esp_ble_gap_periodic_adv_report_t; /** -* @brief perodic adv sync establish parameters -*/ + * @brief Periodic Advertising Synchronization Establish Parameters + * This structure is used to represent the information obtained when a device successfully establishes synchronization with a periodic advertising train. + */ typedef struct { - uint8_t status; /*!< periodic advertising sync status */ - uint16_t sync_handle; /*!< periodic advertising train handle */ - uint8_t sid; /*!< periodic advertising sid */ - esp_ble_addr_type_t addr_type; /*!< periodic advertising address type */ - esp_bd_addr_t adv_addr; /*!< periodic advertising address */ - esp_ble_gap_phy_t adv_phy; /*!< periodic advertising adv phy type */ - uint16_t period_adv_interval; /*!< periodic advertising interval */ - uint8_t adv_clk_accuracy; /*!< periodic advertising clock accuracy */ + uint8_t status; /*!< Periodic advertising synchronization status. Indicates the result of the synchronization process. */ + uint16_t sync_handle; /*!< Periodic advertising train handle. A unique handle identifying the synchronized periodic advertising train. */ + uint8_t sid; /*!< Periodic advertising Signal Strength Indication. An identifier for the periodic advertising train, often used for filtering and synchronization. */ + esp_ble_addr_type_t addr_type; /*!< Periodic advertising address type. Specifies the type of Bluetooth address used by the advertiser (e.g., public or random). */ + esp_bd_addr_t adv_addr; /*!< Periodic advertising address. The Bluetooth address of the device that is broadcasting the periodic advertising packets. */ + esp_ble_gap_phy_t adv_phy; /*!< Periodic advertising Physical Layer type. Indicates the PHY used for the periodic advertising channel (e.g., 1M, 2M, coded). */ + uint16_t period_adv_interval; /*!< Periodic advertising interval. The interval at which the periodic advertising packets are broadcasted. */ + uint8_t adv_clk_accuracy; /*!< Periodic advertising clock accuracy. Indicates the accuracy of the advertiser??s clock, used to synchronize with the periodic advertising train. */ } esp_ble_gap_periodic_adv_sync_estab_t; /** -* @brief DTM TX parameters -*/ + * @brief Device Under Test Manager TX Parameters + * This structure is used to configure the parameters for transmitting test data in Bluetooth Low Energy tests. + */ typedef struct { - uint8_t tx_channel; /*!< channel for sending test data, tx_channel = (Frequency -2402)/2, tx_channel range:0x00-0x27, Frequency range: 2402 MHz to 2480 MHz */ - uint8_t len_of_data; /*!< length in bytes of payload data in each packet */ - esp_ble_dtm_pkt_payload_t pkt_payload; /*!< packet payload type. value range: 0x00-0x07 */ - esp_ble_gap_phy_t phy; /*!< the phy type used by the transmitter, coded phy with S=2:0x04 */ + uint8_t tx_channel; /*!< Channel for sending test data. Channel number is calculated as (Frequency - 2402) / 2. Range: 0x00 - 0x27, corresponding to frequencies from 2402 MHz to 2480 MHz. */ + uint8_t len_of_data; /*!< Length in bytes of payload data in each packet. Specifies the size of the test data payload. */ + esp_ble_dtm_pkt_payload_t pkt_payload; /*!< Packet payload type. Specifies the type of data payload used in the test packets. Range: 0x00 - 0x07. */ + esp_ble_gap_phy_t phy; /*!< Physical Layer type used by the transmitter. Indicates the PHY layer (e.g., 1M, 2M, coded with S=2). */ } esp_ble_dtm_enh_tx_t; /** -* @brief DTM RX parameters -*/ + * @brief Device Under Test Manager RX Parameters + * This structure is used to configure the parameters for receiving test data in Bluetooth Low Energy tests. + */ typedef struct { - uint8_t rx_channel; /*!< channel for test data reception, rx_channel = (Frequency -2402)/2, tx_channel range:0x00-0x27, Frequency range: 2402 MHz to 2480 MHz */ - esp_ble_gap_phy_t phy; /*!< the phy type used by the receiver, 1M phy: 0x01, 2M phy:0x02, coded phy:0x03 */ - uint8_t modulation_idx; /*!< modulation index, 0x00:standard modulation index, 0x01:stable modulation index */ + uint8_t rx_channel; /*!< Channel for test data reception. Channel number is calculated as (Frequency - 2402) / 2. Range: 0x00 - 0x27, corresponding to frequencies from 2402 MHz to 2480 MHz. */ + esp_ble_gap_phy_t phy; /*!< Physical Layer type used by the receiver. Indicates the PHY layer (e.g., 1M, 2M, coded). */ + uint8_t modulation_idx; /*!< Modulation index. Defines the modulation characteristics of the received signal. 0x00: standard modulation index, 0x01: stable modulation index. */ } esp_ble_dtm_enh_rx_t; -#endif //#if (BLE_50_FEATURE_SUPPORT == TRUE) +#endif// #if (BLE_50_FEATURE_SUPPORT == TRUE) +//@} +//@{ +/** if Bluetooth Low Energy Feature Periodic Advertising Synchronization Transfer Support + * Periodic advertising sync trans mode*/ #if (BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER == TRUE) -/// Periodic advertising sync trans mode -#define ESP_BLE_GAP_PAST_MODE_NO_SYNC_EVT (0x00) /*!< No attempt is made to sync and no periodic adv sync transfer received event */ -#define ESP_BLE_GAP_PAST_MODE_NO_REPORT_EVT (0x01) /*!< An periodic adv sync transfer received event and no periodic adv report events */ -#define ESP_BLE_GAP_PAST_MODE_DUP_FILTER_DISABLED (0x02) /*!< Periodic adv report events will be enabled with duplicate filtering disabled */ -#define ESP_BLE_GAP_PAST_MODE_DUP_FILTER_ENABLED (0x03) /*!< Periodic adv report events will be enabled with duplicate filtering enabled */ +/* + GAP Periodic Advertising Synchronization Transfer (PAST) Mode. + These macros define how periodic advertising synchronization and reporting are handled in BLE (Bluetooth Low Energy) GAP (Generic Access Profile). +*/ +#define ESP_BLE_GAP_PAST_MODE_NO_SYNC_EVT (0x00) /*!< No attempt is made to synchronization and no periodic advertising synchronization transfer received event. */ +#define ESP_BLE_GAP_PAST_MODE_NO_REPORT_EVT (0x01) /*!< A periodic advertising synchronization transfer received event is generated, but no periodic advertising report events are generated. */ +#define ESP_BLE_GAP_PAST_MODE_DUP_FILTER_DISABLED (0x02) /*!< Periodic advertising report events are generated with duplicate filtering disabled. */ +#define ESP_BLE_GAP_PAST_MODE_DUP_FILTER_ENABLED (0x03) /*!< Periodic advertising report events are generated with duplicate filtering enabled. */ typedef uint8_t esp_ble_gap_past_mode_t; /** -* @brief periodic adv sync transfer parameters -*/ + * @brief Periodic Advertising Synchronization Transfer Parameters + * This structure defines the parameters used for configuring periodic advertising synchronization transfer in Bluetooth Low Energy (BLE). + */ typedef struct { - esp_ble_gap_past_mode_t mode; /*!< periodic advertising sync transfer mode */ - uint16_t skip; /*!< the number of periodic advertising packets that can be skipped */ - uint16_t sync_timeout; /*!< synchronization timeout for the periodic advertising train */ - uint8_t cte_type; /*!< periodic advertising sync transfer CET type */ + esp_ble_gap_past_mode_t mode; /*!< The mode for periodic advertising synchronization transfer. */ + uint16_t skip; /*!< The maximum number of periodic advertising packets that can be skipped. + This value determines how many periodic advertising events can be missed before synchronization is considered lost or requires re-synchronization. */ + uint16_t sync_timeout; /*!< The timeout value for synchronization with the periodic advertising train. + This timeout specifies the maximum time duration to wait for periodic advertising packets before considering synchronization as lost or needing re-establishment. */ + + uint8_t cte_type; /*!< The Constant Tone Extension (CTE) type for periodic advertising synchronization transfer. + CTE is an extension to the advertising packets to provide better direction finding capabilities. + This parameter specifies the type of CTE that will be used for periodic advertising synchronization. + Values can vary based on the CTE types supported, such as `0` for no CTE, `1` for a specific CTE type, etc. */ } esp_ble_gap_past_params_t; -#endif // #if (BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER == TRUE) +#endif// #if (BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER == TRUE) +//@} +/** + * @brief Privacy Modes for Bluetooth Low Energy (BLE) + * This enumeration defines the different privacy modes that can be configured for a peer device in BLE. + */ typedef enum{ - ESP_BLE_NETWORK_PRIVACY_MODE = 0X00, /*!< Network Privacy Mode for peer device (default) */ - ESP_BLE_DEVICE_PRIVACY_MODE = 0X01, /*!< Device Privacy Mode for peer device */ + ESP_BLE_NETWORK_PRIVACY_MODE = 0X00, /*!< Network Privacy Mode for peer device. + In this mode, the peer device uses a network privacy approach, where the identity address of the peer device changes periodically for privacy purposes. This is the default privacy mode. */ + ESP_BLE_DEVICE_PRIVACY_MODE = 0X01, /*!< Device Privacy Mode for peer device. + In this mode, the peer device uses a device privacy approach, where its identity address changes for privacy, but it is managed at the device level, providing a higher level of privacy compared to network privacy mode. */ } esp_ble_privacy_mode_t; /** - * @brief Gap callback parameters union + * @brief Generic Access Profile (GAP) Callback Parameters Union + * This union encapsulates the parameters for various GAP callback events in BLE. Each structure within the union corresponds to a different event type, providing event-specific information. */ typedef union { /** * @brief ESP_GAP_BLE_GET_DEV_NAME_COMPLETE_EVT + * This event is triggered when the process of getting the Bluetooth device name is complete. */ struct ble_get_dev_name_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the get device name success status */ - char *name; /*!< Name of bluetooth device */ - } get_dev_name_cmpl; /*!< Event parameter of ESP_GAP_BLE_GET_DEV_NAME_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status indicating whether getting the device name was successful or not. + `ESP_BT_STATUS_SUCCESS` if successful. + Error status if failed. */ + char *name; /*!< The name of the Bluetooth device as a null-terminated string. + This name is the friendly name assigned to the device, which can be used for identification and display purposes. */ + } get_dev_name_cmpl; + +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_42_FEATURE_SUPPORT == TRUE) + /** - * @brief ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT + * @brief GAP Advertisement Data Set Complete Event Parameter + * This structure contains the parameters for the `ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT` event. + * It provides information about the completion status of the advertising data set operation. */ struct ble_adv_data_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the set advertising data operation success status */ - } adv_data_cmpl; /*!< Event parameter of ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success or failure of the set advertising data operation. */ + } adv_data_cmpl; /** - * @brief ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT + * @brief GAP Scan Response Data Set Complete Event Parameter + * This structure contains the parameters for the `ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT` event. + * It provides information about the completion status of the scan response data set operation. */ struct ble_scan_rsp_data_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the set scan response data operation success status */ - } scan_rsp_data_cmpl; /*!< Event parameter of ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success or failure of the set scan response data operation. */ + } scan_rsp_data_cmpl; /** - * @brief ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT + * @brief GAP Scan Parameters Set Complete Event Parameter + * This structure contains the parameters for the `ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT` event. + * It provides information about the completion status of the scan parameters set operation. */ struct ble_scan_param_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the set scan param operation success status */ - } scan_param_cmpl; /*!< Event parameter of ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT */ - /** + esp_bt_status_t status; /*!< Indicates the success or failure of the set scan parameters operation. */ + } scan_param_cmpl; + /** * @brief ESP_GAP_BLE_SCAN_RESULT_EVT + * Event parameter for the ESP_GAP_BLE_SCAN_RESULT_EVT event. + * This structure contains the parameters for the Bluetooth Low Energy (BLE) scan result event. */ struct ble_scan_result_evt_param { - esp_gap_search_evt_t search_evt; /*!< Search event type */ - esp_bd_addr_t bda; /*!< Bluetooth device address which has been searched */ - esp_bt_dev_type_t dev_type; /*!< Device type */ - esp_ble_addr_type_t ble_addr_type; /*!< Ble device address type */ - esp_ble_evt_type_t ble_evt_type; /*!< Ble scan result event type */ - int rssi; /*!< Searched device's RSSI */ - uint8_t ble_adv[ESP_BLE_ADV_DATA_LEN_MAX + ESP_BLE_SCAN_RSP_DATA_LEN_MAX]; /*!< Received EIR */ - int flag; /*!< Advertising data flag bit */ - int num_resps; /*!< Scan result number */ - uint8_t adv_data_len; /*!< Adv data length */ - uint8_t scan_rsp_len; /*!< Scan response length */ - uint32_t num_dis; /*!< The number of discard packets */ - } scan_rst; /*!< Event parameter of ESP_GAP_BLE_SCAN_RESULT_EVT */ + esp_gap_search_evt_t search_evt; /*!< The type of scan result event, such as device found, scan complete, etc. */ + esp_bd_addr_t bda; /*!< The Bluetooth device address of the discovered device. */ + esp_bt_dev_type_t dev_type; /*!< The type of the device (e.g., BR/EDR, BLE, or DUAL). */ + esp_ble_addr_type_t ble_addr_type; /*!< The address type of the BLE device (e.g., public, random). */ + esp_ble_evt_type_t ble_evt_type; /*!< The type of BLE scan result event (e.g., advertisement report). */ + int rssi; /*!< The Received Signal Strength Indication (RSSI) of the discovered device. */ + uint8_t ble_adv[ESP_BLE_ADV_DATA_LEN_MAX + ESP_BLE_SCAN_RSP_DATA_LEN_MAX]; /*!< The received advertisement and scan response data. */ + int flag; /*!< The advertising data flag bit, indicating the type of advertising data. */ + int num_resps; /*!< The number of responses received during the scan. */ + uint8_t adv_data_len; /*!< The length of the received advertising data. */ + uint8_t scan_rsp_len; /*!< The length of the received scan response data. */ + uint32_t num_dis; /*!< The number of discarded packets during the scan. */ + } scan_rst; /** * @brief ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT event. + * This structure contains the status of setting raw advertising data. */ struct ble_adv_data_raw_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the set raw advertising data operation success status */ - } adv_data_raw_cmpl; /*!< Event parameter of ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the set raw advertising data operation. */ + } adv_data_raw_cmpl; + /** * @brief ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT event. + * This structure contains the status of setting raw scan response data. */ struct ble_scan_rsp_data_raw_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the set raw advertising data operation success status */ - } scan_rsp_data_raw_cmpl; /*!< Event parameter of ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the set raw scan response data operation. */ + } scan_rsp_data_raw_cmpl; + /** * @brief ESP_GAP_BLE_ADV_START_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_ADV_START_COMPLETE_EVT event. + * This structure contains the status of starting advertising. */ struct ble_adv_start_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate advertising start operation success status */ - } adv_start_cmpl; /*!< Event parameter of ESP_GAP_BLE_ADV_START_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the advertising start operation. */ + } adv_start_cmpl; + /** * @brief ESP_GAP_BLE_SCAN_START_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_SCAN_START_COMPLETE_EVT event. + * This structure contains the status of starting a scan. */ struct ble_scan_start_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate scan start operation success status */ - } scan_start_cmpl; /*!< Event parameter of ESP_GAP_BLE_SCAN_START_COMPLETE_EVT */ -#endif //#if (BLE_42_FEATURE_SUPPORT == TRUE) - esp_ble_sec_t ble_security; /*!< ble gap security union type */ + esp_bt_status_t status; /*!< Indicates the success status of the scan start operation. */ + } scan_start_cmpl; +#endif// #if (BLE_42_FEATURE_SUPPORT == TRUE) +//@} + + esp_ble_sec_t ble_security; /*!< Bluetooth Low Energy Generic Access Profile security union type. */ + +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_42_FEATURE_SUPPORT == TRUE) /** * @brief ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT event. + * This structure contains the status of stopping a scan. */ struct ble_scan_stop_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate scan stop operation success status */ - } scan_stop_cmpl; /*!< Event parameter of ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the scan stop operation. */ + } scan_stop_cmpl; + /** * @brief ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT event. + * This structure contains the status of stopping advertising. */ struct ble_adv_stop_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate adv stop operation success status */ - } adv_stop_cmpl; /*!< Event parameter of ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the advertising stop operation. */ + } adv_stop_cmpl; + /** * @brief ESP_GAP_BLE_ADV_CLEAR_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_ADV_CLEAR_COMPLETE_EVT event. + * This structure contains the status of clearing advertising data. */ struct ble_adv_clear_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate adv clear operation success status */ - } adv_clear_cmpl; /*!< Event parameter of ESP_GAP_BLE_ADV_CLEAR_COMPLETE_EVT */ -#endif // #if (BLE_42_FEATURE_SUPPORT == TRUE) + esp_bt_status_t status; /*!< Indicates the success status of the advertising clear operation. */ + } adv_clear_cmpl; +#endif// #if (BLE_42_FEATURE_SUPPORT == TRUE) +//@} + /** * @brief ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT + * Event parameter for the ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT event. + * This event is triggered when the operation to set a static random address is complete. */ struct ble_set_rand_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate set static rand address operation success status */ - } set_rand_addr_cmpl; /*!< Event parameter of ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the operation to set a static random address. */ + } set_rand_addr_cmpl; + /** * @brief ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT + * Event parameter for the ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT event. + * This event is triggered when the connection parameters update operation is complete. */ struct ble_update_conn_params_evt_param { - esp_bt_status_t status; /*!< Indicate update connection parameters success status */ - esp_bd_addr_t bda; /*!< Bluetooth device address */ - uint16_t min_int; /*!< Min connection interval */ - uint16_t max_int; /*!< Max connection interval */ - uint16_t latency; /*!< Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3 */ - uint16_t conn_int; /*!< Current connection interval */ - uint16_t timeout; /*!< Supervision timeout for the LE Link. Range: 0x000A to 0x0C80. - Mandatory Range: 0x000A to 0x0C80 Time = N * 10 msec */ - } update_conn_params; /*!< Event parameter of ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the connection parameters update operation. */ + esp_bd_addr_t bda; /*!< Bluetooth Device Address (BD_ADDR) of the device for which the connection parameters were updated. */ + uint16_t min_int; /*!< Minimum connection interval in units of 1.25 milliseconds. */ + uint16_t max_int; /*!< Maximum connection interval in units of 1.25 milliseconds. */ + uint16_t latency; /*!< Connection latency in number of connection events. This value determines how many connection events the slave device can skip. */ + uint16_t conn_int; /*!< Current connection interval in units of 1.25 milliseconds. */ + uint16_t timeout; /*!< Supervision timeout for the connection in units of 10 milliseconds. This is the maximum time between consecutive connection events before the connection is considered lost. */ + } update_conn_params; + /** * @brief ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT event. + * This event is triggered when the operation to set the packet length is complete. */ struct ble_pkt_data_length_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the set pkt data length operation success status */ - esp_ble_pkt_data_length_params_t params; /*!< pkt data length value */ - } pkt_data_length_cmpl; /*!< Event parameter of ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the operation to set the packet data length. */ + esp_ble_pkt_data_length_params_t params; /*!< Contains the packet data length parameters such as maximum packet size and data length extension parameters. */ + } pkt_data_length_cmpl; + /** * @brief ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT event. + * This event is triggered when the operation to set local privacy is complete. */ struct ble_local_privacy_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the set local privacy operation success status */ - } local_privacy_cmpl; /*!< Event parameter of ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the operation to set local privacy. */ + } local_privacy_cmpl; + /** * @brief ESP_GAP_BLE_SET_RPA_TIMEOUT_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_SET_RPA_TIMEOUT_COMPLETE_EVT event. + * This event is triggered when the operation to set the Resolvable Private Address (RPA) timeout is complete. */ struct ble_rpa_timeout_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the set RPA timeout operation success status */ - } set_rpa_timeout_cmpl; /*!< Event parameter of ESP_GAP_BLE_SET_RPA_TIMEOUT_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the operation to set the RPA timeout. */ + } set_rpa_timeout_cmpl; + /** * @brief ESP_GAP_BLE_ADD_DEV_TO_RESOLVING_LIST_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_ADD_DEV_TO_RESOLVING_LIST_COMPLETE_EVT event. + * This event is triggered when the operation to add a device to the Resolving List is complete. */ struct ble_add_dev_to_resolving_list_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicates the success status of adding a device to the resolving list */ - } add_dev_to_resolving_list_cmpl; /*!< Event parameter of ESP_GAP_BLE_ADD_DEV_TO_RESOLVING_LIST_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the operation to add a device to the Resolving List. */ + } add_dev_to_resolving_list_cmpl; /** * @brief ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT event. + * This event is triggered when the operation to remove a bonded device is complete. */ struct ble_remove_bond_dev_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the remove bond device operation success status */ - esp_bd_addr_t bd_addr; /*!< The device address which has been remove from the bond list */ - } remove_bond_dev_cmpl; /*!< Event parameter of ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the operation to remove a bonded device. */ + esp_bd_addr_t bd_addr; /*!< Bluetooth Device Address (BD_ADDR) of the device that was removed from the bond list. */ + } remove_bond_dev_cmpl; + /** * @brief ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT event. + * This event is triggered when the operation to clear all bonded devices is complete. */ struct ble_clear_bond_dev_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the clear bond device operation success status */ - } clear_bond_dev_cmpl; /*!< Event parameter of ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the operation to clear all bonded devices. */ + } clear_bond_dev_cmpl; + /** * @brief ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT event. + * This event is triggered when the operation to get the bonded devices is complete. */ struct ble_get_bond_dev_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the get bond device operation success status */ - uint8_t dev_num; /*!< Indicate the get number device in the bond list */ - esp_ble_bond_dev_t *bond_dev; /*!< the pointer to the bond device Structure */ - } get_bond_dev_cmpl; /*!< Event parameter of ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the operation to get bonded devices. */ + uint8_t dev_num; /*!< Number of devices in the bond list. */ + esp_ble_bond_dev_t *bond_dev; /*!< Pointer to an array of bonded device structures. */ + } get_bond_dev_cmpl; + /** * @brief ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT event. + * This event is triggered when the operation to read the Received Signal Strength Indication (RSSI) is complete. */ struct ble_read_rssi_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the read adv tx power operation success status */ - int8_t rssi; /*!< The ble remote device rssi value, the range is from -127 to 20, the unit is dbm, - if the RSSI cannot be read, the RSSI metric shall be set to 127. */ - esp_bd_addr_t remote_addr; /*!< The remote device address */ - } read_rssi_cmpl; /*!< Event parameter of ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the RSSI read operation. */ + int8_t rssi; /*!< Received Signal Strength Indication (RSSI) value of the remote device. The range is from -127 to 20 dBm. If the RSSI cannot be read, it is set to 127. */ + esp_bd_addr_t remote_addr; /*!< Bluetooth Device Address (BD_ADDR) of the remote device whose RSSI was read. */ + } read_rssi_cmpl; + /** * @brief ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT event. + * This event is triggered when the operation to update the whitelist (add or remove addresses) is complete. */ struct ble_update_whitelist_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate the add or remove whitelist operation success status */ - esp_ble_wl_operation_t wl_operation; /*!< The value is ESP_BLE_WHITELIST_ADD if add address to whitelist operation success, ESP_BLE_WHITELIST_REMOVE if remove address from the whitelist operation success */ - } update_whitelist_cmpl; /*!< Event parameter of ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Indicates the success status of the whitelist update operation. */ + esp_ble_wl_operation_t wl_operation; /*!< Operation performed on the whitelist: ESP_BLE_WHITELIST_ADD for adding an address, ESP_BLE_WHITELIST_REMOVE for removing an address. */ + } update_whitelist_cmpl; + +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_42_FEATURE_SUPPORT == TRUE) /** * @brief ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT event. + * This event is triggered when the operation to update the duplicate exceptional list is complete. */ struct ble_update_duplicate_exceptional_list_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate update duplicate scan exceptional list operation success status */ - uint8_t subcode; /*!< Define in esp_bt_duplicate_exceptional_subcode_type_t */ - uint16_t length; /*!< The length of device_info */ - esp_duplicate_info_t device_info; /*!< device information, when subcode is ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_CLEAN, the value is invalid */ - } update_duplicate_exceptional_list_cmpl; /*!< Event parameter of ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT */ -#endif // #if (BLE_42_FEATURE_SUPPORT == TRUE) + esp_bt_status_t status; /*!< Indicates the success status of the operation to update the duplicate exceptional list. */ + uint8_t subcode; /*!< Defines the specific operation performed on the duplicate exceptional list. This value is defined in the esp_bt_duplicate_exceptional_subcode_type_t enumeration. */ + uint16_t length; /*!< The length of the `device_info` structure. This value is valid only if the subcode indicates an operation that involves device information. */ + esp_duplicate_info_t device_info; /*!< Device information related to the duplicate exceptional list. This field is valid only if the subcode is not `ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_CLEAN`. + If the subcode is `ESP_BLE_DUPLICATE_EXCEPTIONAL_LIST_CLEAN`, the value of this field is invalid. */ + } update_duplicate_exceptional_list_cmpl; +#endif// #if (BLE_42_FEATURE_SUPPORT == TRUE) +//@} + /** * @brief ESP_GAP_BLE_SET_CHANNELS_EVT - */ + * Event parameter for the ESP_GAP_BLE_SET_CHANNELS_EVT event. + * This event is triggered when the operation to set Bluetooth Low Energy (BLE) channels is complete. + */ struct ble_set_channels_evt_param { - esp_bt_status_t stat; /*!< BLE set channel status */ - } ble_set_channels; /*!< Event parameter of ESP_GAP_BLE_SET_CHANNELS_EVT */ + esp_bt_status_t stat; /*!< Indicates the status of the operation to set BLE channels. + This status value helps determine if the operation was successful or if an error occurred. */ + } ble_set_channels; +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_50_FEATURE_SUPPORT == TRUE) /** * @brief ESP_GAP_BLE_READ_PHY_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_READ_PHY_COMPLETE_EVT event. + * This event is triggered when the operation to read the Physical Layer (PHY) settings is complete. */ struct ble_read_phy_cmpl_evt_param { - esp_bt_status_t status; /*!< read phy complete status */ - esp_bd_addr_t bda; /*!< read phy address */ - esp_ble_gap_phy_t tx_phy; /*!< tx phy type */ - esp_ble_gap_phy_t rx_phy; /*!< rx phy type */ - } read_phy; /*!< Event parameter of ESP_GAP_BLE_READ_PHY_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the PHY read operation. Indicates whether the PHY read operation was successful or if an error occurred. */ + esp_bd_addr_t bda; /*!< Bluetooth Device Address of the device for which the PHY was read. */ + esp_ble_gap_phy_t tx_phy; /*!< Type of PHY used for transmission. */ + esp_ble_gap_phy_t rx_phy; /*!< Type of PHY used for reception. */ + } read_phy; + /** * @brief ESP_GAP_BLE_SET_PREFERRED_DEFAULT_PHY_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_SET_PREFERRED_DEFAULT_PHY_COMPLETE_EVT event. + * This event is triggered when the operation to set the default Physical Layer (PHY) is complete. */ struct ble_set_perf_def_phy_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate perf default phy set status */ - } set_perf_def_phy; /*!< Event parameter of ESP_GAP_BLE_SET_PREFERRED_DEFAULT_PHY_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the default PHY setting operation. Indicates whether the operation was successful or if an error occurred. */ + } set_perf_def_phy; + /** * @brief ESP_GAP_BLE_SET_PREFERRED_PHY_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_SET_PREFERRED_PHY_COMPLETE_EVT event. + * This event is triggered when the operation to set the preferred Physical Layer (PHY) is complete. */ struct ble_set_perf_phy_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate perf phy set status */ - } set_perf_phy; /*!< Event parameter of ESP_GAP_BLE_SET_PREFERRED_PHY_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the preferred PHY setting operation. Indicates whether the operation was successful or if an error occurred. */ + } set_perf_phy; + /** * @brief ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT event. + * This event is triggered when the operation to set a random address for extended advertising is complete. */ struct ble_ext_adv_set_rand_addr_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate extend advertising random address set status */ - } ext_adv_set_rand_addr; /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the extended advertising random address setting operation. Indicates whether the operation was successful or if an error occurred. */ + } ext_adv_set_rand_addr; + /** * @brief ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT event. + * This event is triggered when the operation to set parameters for extended advertising is complete. */ struct ble_ext_adv_set_params_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate extend advertising parameters set status */ - } ext_adv_set_params; /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the extended advertising parameters setting operation. Indicates whether the operation was successful or if an error occurred. */ + } ext_adv_set_params; + /** * @brief ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT event. + * This event is triggered when the operation to set extended advertising data is complete. */ - struct ble_ext_adv_data_set_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate extend advertising data set status */ - } ext_adv_data_set; /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT */ + struct ble_ext_adv_data_set_cmpl_evt_param { + esp_bt_status_t status; /*!< Status of the extended advertising data setting operation. Indicates whether the operation was successful or if an error occurred. */ + } ext_adv_data_set; + /** * @brief ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT event. + * This event is triggered when the operation to set extended scan response data is complete. */ struct ble_ext_adv_scan_rsp_set_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate extend advertising scan response data set status */ - } scan_rsp_set; /*!< Event parameter of ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the extended scan response data setting operation. Indicates whether the operation was successful or if an error occurred. */ + } scan_rsp_set; + /** * @brief ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT event. + * This event is triggered when the operation to start extended advertising is complete. */ struct ble_ext_adv_start_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate advertising start operation success status */ - } ext_adv_start; /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the extended advertising start operation. Indicates whether the operation was successful or if an error occurred. */ + } ext_adv_start; + /** * @brief ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT event. + * This event is triggered when the operation to stop extended advertising is complete. */ struct ble_ext_adv_stop_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate advertising stop operation success status */ - } ext_adv_stop; /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the extended advertising stop operation. Indicates whether the operation was successful or if an error occurred. */ + } ext_adv_stop; + /** * @brief ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT event. + * This event is triggered when the operation to remove an extended advertising set is complete. */ struct ble_ext_adv_set_remove_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate advertising stop operation success status */ - } ext_adv_remove; /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the extended advertising set removal operation. Indicates whether the operation was successful or if an error occurred. */ + } ext_adv_remove; + /** * @brief ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT event. + * This event is triggered when the operation to clear all extended advertising sets is complete. */ struct ble_ext_adv_set_clear_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate advertising stop operation success status */ - } ext_adv_clear; /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the extended advertising set clear operation. Indicates whether the operation was successful or if an error occurred. */ + } ext_adv_clear; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT event. + * This event is triggered when the operation to set parameters for periodic advertising is complete. */ struct ble_periodic_adv_set_params_cmpl_param { - esp_bt_status_t status; /*!< Indicate periodic advertisingparameters set status */ - } peroid_adv_set_params; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the periodic advertising parameters setting operation. Indicates whether the operation was successful or if an error occurred. */ + } peroid_adv_set_params; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT event. + * This event is triggered when the operation to set periodic advertising data is complete. */ struct ble_periodic_adv_data_set_cmpl_param { - esp_bt_status_t status; /*!< Indicate periodic advertising data set status */ - } period_adv_data_set; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the periodic advertising data setting operation. Indicates whether the operation was successful or if an error occurred. */ + } period_adv_data_set; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT event. + * This event is triggered when the operation to start periodic advertising is complete. */ struct ble_periodic_adv_start_cmpl_param { - esp_bt_status_t status; /*!< Indicate periodic advertising start status */ - } period_adv_start; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the periodic advertising start operation. Indicates whether the operation was successful or if an error occurred. */ + } period_adv_start; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT event. + * This event is triggered when the operation to stop periodic advertising is complete. */ struct ble_periodic_adv_stop_cmpl_param { - esp_bt_status_t status; /*!< Indicate periodic advertising stop status */ - } period_adv_stop; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the periodic advertising stop operation. Indicates whether the operation was successful or if an error occurred. */ + } period_adv_stop; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT event. + * This event is triggered when the operation to create a synchronization with periodic advertising is complete. */ struct ble_period_adv_create_sync_cmpl_param { - esp_bt_status_t status; /*!< Indicate periodic advertising create sync status */ - } period_adv_create_sync; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the periodic advertising synchronization creation operation. Indicates whether the operation was successful or if an error occurred. */ + } period_adv_create_sync; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT event. + * This event is triggered when the operation to cancel synchronization with periodic advertising is complete. */ struct ble_period_adv_sync_cancel_cmpl_param { - esp_bt_status_t status; /*!< Indicate periodic advertising sync cancel status */ - } period_adv_sync_cancel; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT */ - /** + esp_bt_status_t status; /*!< Status of the periodic advertising synchronization cancellation operation. Indicates whether the operation was successful or if an error occurred. */ + } period_adv_sync_cancel; + + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLETE_EVT event. + * This event is triggered when the operation to terminate synchronization with periodic advertising is complete. */ struct ble_period_adv_sync_terminate_cmpl_param { - esp_bt_status_t status; /*!< Indicate periodic advertising sync terminate status */ - } period_adv_sync_term; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_TERMINATE_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the periodic advertising synchronization termination operation. Indicates whether the operation was successful or if an error occurred. */ + } period_adv_sync_term; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT event. + * This event is triggered when the operation to add a device to the periodic advertising device list is complete. */ struct ble_period_adv_add_dev_cmpl_param { - esp_bt_status_t status; /*!< Indicate periodic advertising device list add status */ - } period_adv_add_dev; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_ADD_DEV_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the operation to add a device to the periodic advertising device list. Indicates whether the operation was successful or if an error occurred. */ + } period_adv_add_dev; /** * @brief ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT event. + * This event is triggered when the operation to remove a device from the periodic advertising device list is complete. */ struct ble_period_adv_remove_dev_cmpl_param { - esp_bt_status_t status; /*!< Indicate periodic advertising device list remove status */ - } period_adv_remove_dev; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_REMOVE_DEV_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the periodic advertising device list removal operation. Indicates whether the operation was successful or if an error occurred. */ + } period_adv_remove_dev; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT event. + * This event is triggered when the operation to clear all devices from the periodic advertising device list is complete. */ struct ble_period_adv_clear_dev_cmpl_param { - esp_bt_status_t status; /*!< Indicate periodic advertising device list clean status */ - } period_adv_clear_dev; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_CLEAR_DEV_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the periodic advertising device list clearing operation. Indicates whether the operation was successful or if an error occurred. */ + } period_adv_clear_dev; + /** * @brief ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETE_EVT event. + * This event is triggered when the operation to set parameters for extended scanning is complete. */ struct ble_set_ext_scan_params_cmpl_param { - esp_bt_status_t status; /*!< Indicate extend advertising parameters set status */ - } set_ext_scan_params; /*!< Event parameter of ESP_GAP_BLE_SET_EXT_SCAN_PARAMS_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the extended scan parameters setting operation. Indicates whether the operation was successful or if an error occurred. */ + } set_ext_scan_params; + /** * @brief ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT event. + * This event is triggered when the operation to start extended scanning is complete. */ struct ble_ext_scan_start_cmpl_param { - esp_bt_status_t status; /*!< Indicate extend advertising start status */ - } ext_scan_start; /*!< Event parameter of ESP_GAP_BLE_EXT_SCAN_START_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the extended scanning start operation. Indicates whether the operation was successful or if an error occurred. */ + } ext_scan_start; + /** * @brief ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT event. + * This event is triggered when the operation to stop extended scanning is complete. */ struct ble_ext_scan_stop_cmpl_param { - esp_bt_status_t status; /*!< Indicate extend advertising stop status */ - } ext_scan_stop; /*!< Event parameter of ESP_GAP_BLE_EXT_SCAN_STOP_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the extended scanning stop operation. Indicates whether the operation was successful or if an error occurred. */ + } ext_scan_stop; + /** * @brief ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETE_EVT event. + * This event is triggered when the operation to set preferred extended connection parameters is complete. */ struct ble_ext_conn_params_set_cmpl_param { - esp_bt_status_t status; /*!< Indicate extend connection parameters set status */ - } ext_conn_params_set; /*!< Event parameter of ESP_GAP_BLE_PREFER_EXT_CONN_PARAMS_SET_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the preferred extended connection parameters setting operation. Indicates whether the operation was successful or if an error occurred. */ + } ext_conn_params_set; + /** * @brief ESP_GAP_BLE_ADV_TERMINATED_EVT + * Event parameter for the ESP_GAP_BLE_ADV_TERMINATED_EVT event. + * This event is triggered when extended advertising terminates. */ struct ble_adv_terminate_param { - uint8_t status; /*!< Indicate adv terminate status */ - /* status 0x3c indicates that advertising for a fixed duration completed or, - for directed advertising, that advertising completed without a connection - being created; - status 0x00 indicates that advertising successfully ended with a connection being created. - */ - uint8_t adv_instance; /*!< extend advertising handle */ - uint16_t conn_idx; /*!< connection index */ - uint8_t completed_event; /*!< the number of completed extend advertising events */ - } adv_terminate; /*!< Event parameter of ESP_GAP_BLE_ADV_TERMINATED_EVT */ + uint8_t status; /*!< Status of the advertising termination. A status value of 0x3c indicates that advertising for a fixed duration completed or that directed advertising completed without creating a connection. A status value of 0x00 indicates that advertising successfully ended with a connection being created. */ + uint8_t adv_instance; /*!< Handle for the extended advertising instance. */ + uint16_t conn_idx; /*!< Connection index for the connection established during advertising. */ + uint8_t completed_event; /*!< Number of completed extended advertising events. */ + } adv_terminate; /** * @brief ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT + * Event parameter for the ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT event. + * This event is triggered when a scan request is received during extended advertising. */ struct ble_scan_req_received_param { - uint8_t adv_instance; /*!< extend advertising handle */ - esp_ble_addr_type_t scan_addr_type; /*!< scanner address type */ - esp_bd_addr_t scan_addr; /*!< scanner address */ - } scan_req_received; /*!< Event parameter of ESP_GAP_BLE_SCAN_REQ_RECEIVED_EVT */ + uint8_t adv_instance; /*!< Handle for the extended advertising instance. */ + esp_ble_addr_type_t scan_addr_type; /*!< Address type of the scanner. This indicates whether the scanner's address is public or random. */ + esp_bd_addr_t scan_addr; /*!< Address of the scanner that sent the scan request. */ + } scan_req_received; + /** * @brief ESP_GAP_BLE_CHANNEL_SELECT_ALGORITHM_EVT + * Event parameter for the ESP_GAP_BLE_CHANNEL_SELECT_ALGORITHM_EVT event. + * This event is triggered when the channel selection algorithm is updated for a connection. */ struct ble_channel_sel_alg_param { - uint16_t conn_handle; /*!< connection handle */ - uint8_t channel_sel_alg; /*!< channel selection algorithm */ - } channel_sel_alg; /*!< Event parameter of ESP_GAP_BLE_CHANNEL_SELECT_ALGORITHM_EVT */ + uint16_t conn_handle; /*!< Handle for the connection. Used to identify the connection for which the channel selection algorithm is being updated. */ + uint8_t channel_sel_alg; /*!< Channel selection algorithm used for the connection. This can indicate either the legacy or the new channel selection algorithm. */ + } channel_sel_alg; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT event. + * This event is triggered when synchronization with a periodic advertiser is lost. */ struct ble_periodic_adv_sync_lost_param { - uint16_t sync_handle; /*!< sync handle */ - } periodic_adv_sync_lost; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT */ + uint16_t sync_handle; /*!< Handle for the synchronization. Used to identify the synchronization that was lost. */ + } periodic_adv_sync_lost; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVT event. + * This event is triggered when synchronization with a periodic advertiser is established. */ struct ble_periodic_adv_sync_estab_param { - uint8_t status; /*!< periodic advertising sync status */ - uint16_t sync_handle; /*!< periodic advertising sync handle */ - uint8_t sid; /*!< periodic advertising sid */ - esp_ble_addr_type_t adv_addr_type; /*!< periodic advertising address type */ - esp_bd_addr_t adv_addr; /*!< periodic advertising address */ - esp_ble_gap_phy_t adv_phy; /*!< periodic advertising phy type */ - uint16_t period_adv_interval; /*!< periodic advertising interval */ - uint8_t adv_clk_accuracy; /*!< periodic advertising clock accuracy */ - } periodic_adv_sync_estab; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_ESTAB_EVT */ + uint8_t status; /*!< Status of the periodic advertising synchronization. A status value of 0 indicates successful synchronization, while other values indicate errors. */ + uint16_t sync_handle; /*!< Handle for the synchronization. Used to identify the established synchronization. */ + uint8_t sid; /*!< Service Identifier for the periodic advertising. Used to identify the type of service. */ + esp_ble_addr_type_t adv_addr_type; /*!< Address type of the periodic advertiser. Indicates whether the advertiser's address is public or random. */ + esp_bd_addr_t adv_addr; /*!< Address of the periodic advertiser. Used to identify the source of the periodic advertising. */ + esp_ble_gap_phy_t adv_phy; /*!< Physical Layer type for the periodic advertising. Indicates the PHY used for advertising. */ + uint16_t period_adv_interval; /*!< Interval between periodic advertising events. Specifies the period of the advertising interval. */ + uint8_t adv_clk_accuracy; /*!< Clock accuracy of the periodic advertiser. Indicates how accurate the advertiser's clock is for timing. */ + } periodic_adv_sync_estab; + /** * @brief ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT event. + * This event is triggered when the Physical Layer (PHY) update operation is complete for a connection. */ struct ble_phy_update_cmpl_param { - esp_bt_status_t status; /*!< phy update status */ - esp_bd_addr_t bda; /*!< address */ - esp_ble_gap_phy_t tx_phy; /*!< tx phy type */ - esp_ble_gap_phy_t rx_phy; /*!< rx phy type */ - } phy_update; /*!< Event parameter of ESP_GAP_BLE_PHY_UPDATE_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the PHY update operation. Indicates whether the update was successful or if an error occurred. */ + esp_bd_addr_t bda; /*!< Address of the device for which the PHY update was performed. */ + esp_ble_gap_phy_t tx_phy; /*!< Transmit PHY type after the update. Indicates the PHY used for transmitting data. */ + esp_ble_gap_phy_t rx_phy; /*!< Receive PHY type after the update. Indicates the PHY used for receiving data. */ + } phy_update; + /** * @brief ESP_GAP_BLE_EXT_ADV_REPORT_EVT + * Event parameter for the ESP_GAP_BLE_EXT_ADV_REPORT_EVT event. + * This event is triggered when an extended advertising report is received. */ struct ble_ext_adv_report_param { - esp_ble_gap_ext_adv_report_t params; /*!< extend advertising report parameters */ - } ext_adv_report; /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_REPORT_EVT */ + esp_ble_gap_ext_adv_report_t params; /*!< Parameters of the extended advertising report. Contains details about the extended advertising packet received. */ + } ext_adv_report; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT event. + * This event is triggered when a periodic advertising report is received. */ struct ble_periodic_adv_report_param { - esp_ble_gap_periodic_adv_report_t params; /*!< periodic advertising report parameters */ - } period_adv_report; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_REPORT_EVT */ -#endif // #if (BLE_50_FEATURE_SUPPORT == TRUE) -#if (BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER == TRUE) + esp_ble_gap_periodic_adv_report_t params; /*!< Parameters of the periodic advertising report. Contains details about the periodic advertising packet received. */ + } period_adv_report; +#endif// #if (BLE_50_FEATURE_SUPPORT == TRUE) +//@} + + +//@{ +/** if Bluetooth Low Energy Feature Periodic Advertising Synchronization Transfer Support */ +#if (BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER == TRUE) /** * @brief ESP_GAP_BLE_PERIODIC_ADV_RECV_ENABLE_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_RECV_ENABLE_COMPLETE_EVT event. + * This event is triggered when the periodic advertising receive enable operation completes. */ struct ble_periodic_adv_recv_enable_cmpl_param { - esp_bt_status_t status; /*!< Set periodic advertising receive enable status */ - } period_adv_recv_enable; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_RECV_ENABLE_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the periodic advertising receive enable operation. Indicates whether the operation was successful or if an error occurred. */ + } period_adv_recv_enable; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_SYNC_TRANS_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_SYNC_TRANS_COMPLETE_EVT event. + * This event is triggered when the periodic advertising synchronization transfer operation completes. */ struct ble_periodic_adv_sync_trans_cmpl_param { - esp_bt_status_t status; /*!< Periodic advertising sync transfer status */ - esp_bd_addr_t bda; /*!< The remote device address */ - } period_adv_sync_trans; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_TRANS_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the periodic advertising synchronization transfer operation. Indicates whether the transfer was successful or if an error occurred. */ + esp_bd_addr_t bda; /*!< Address of the remote device involved in the synchronization transfer. */ + } period_adv_sync_trans; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_SET_INFO_TRANS_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_SET_INFO_TRANS_COMPLETE_EVT event. + * This event is triggered when the periodic advertising set information transfer operation completes. */ struct ble_periodic_adv_set_info_trans_cmpl_param { - esp_bt_status_t status; /*!< Periodic advertising set info transfer status */ - esp_bd_addr_t bda; /*!< The remote device address */ - } period_adv_set_info_trans; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SET_INFO_TRANS_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the periodic advertising set information transfer operation. Indicates whether the transfer was successful or if an error occurred. */ + esp_bd_addr_t bda; /*!< Address of the remote device involved in the information transfer. */ + } period_adv_set_info_trans; + /** * @brief ESP_GAP_BLE_SET_PAST_PARAMS_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_SET_PAST_PARAMS_COMPLETE_EVT event. + * This event is triggered when the periodic advertising synchronization transfer parameters are set. */ struct ble_set_past_params_cmpl_param { - esp_bt_status_t status; /*!< Set periodic advertising sync transfer params status */ - esp_bd_addr_t bda; /*!< The remote device address */ - } set_past_params; /*!< Event parameter of ESP_GAP_BLE_SET_PAST_PARAMS_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the set periodic advertising synchronization transfer parameters operation. Indicates whether the operation was successful or if an error occurred. */ + esp_bd_addr_t bda; /*!< Address of the remote device involved in the parameter setting. */ + } set_past_params; + /** * @brief ESP_GAP_BLE_PERIODIC_ADV_SYNC_TRANS_RECV_EVT + * Event parameter for the ESP_GAP_BLE_PERIODIC_ADV_SYNC_TRANS_RECV_EVT event. + * This event is triggered when a periodic advertising synchronization transfer is received. */ struct ble_periodic_adv_sync_trans_recv_param { - esp_bt_status_t status; /*!< Periodic advertising sync transfer received status */ - esp_bd_addr_t bda; /*!< The remote device address */ - uint16_t service_data; /*!< The value provided by the peer device */ - uint16_t sync_handle; /*!< Periodic advertising sync handle */ - uint8_t adv_sid; /*!< Periodic advertising set id */ - uint8_t adv_addr_type; /*!< Periodic advertiser address type */ - esp_bd_addr_t adv_addr; /*!< Periodic advertiser address */ - esp_ble_gap_phy_t adv_phy; /*!< Periodic advertising PHY */ - uint16_t adv_interval; /*!< Periodic advertising interval */ - uint8_t adv_clk_accuracy; /*!< Periodic advertising clock accuracy */ - } past_received; /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SYNC_TRANS_RECV_EVT */ -#endif // #if (BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER == TRUE) + esp_bt_status_t status; /*!< Status of the received periodic advertising synchronization transfer. Indicates whether the reception was successful or if an error occurred. */ + esp_bd_addr_t bda; /*!< Address of the remote device that sent the synchronization transfer. */ + uint16_t service_data; /*!< Value provided by the peer device in the synchronization transfer. */ + uint16_t sync_handle; /*!< Handle for the periodic advertising synchronization. Used to identify the synchronization instance. */ + uint8_t adv_sid; /*!< Service Identifier for the periodic advertising set. Used to identify the type of periodic advertising service. */ + uint8_t adv_addr_type; /*!< Address type of the periodic advertiser. Indicates whether the advertiser's address is public or random. */ + esp_bd_addr_t adv_addr; /*!< Address of the periodic advertiser. Used to identify the source of the periodic advertising. */ + esp_ble_gap_phy_t adv_phy; /*!< Physical Layer type for the periodic advertising. Indicates the PHY used for periodic advertising. */ + uint16_t adv_interval; /*!< Interval between periodic advertising events. Specifies the period of the advertising interval. */ + uint8_t adv_clk_accuracy; /*!< Clock accuracy of the periodic advertiser. Indicates how accurate the advertiser's clock is for timing. */ + } past_received; +#endif// #if (BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER == TRUE) +//@} + /** * @brief ESP_GAP_BLE_DTM_TEST_UPDATE_EVT + * Event parameter for the ESP_GAP_BLE_DTM_TEST_UPDATE_EVT event. + * This event is triggered when the Direct Test Mode (DTM) state changes. */ struct ble_dtm_state_update_evt_param { - esp_bt_status_t status; /*!< Indicate DTM operation success status */ - esp_ble_dtm_update_evt_t update_evt; /*!< DTM state change event, 0x00: DTM TX start, 0x01: DTM RX start, 0x02:DTM end */ - uint16_t num_of_pkt; /*!< number of packets received, only valid if update_evt is DTM_TEST_STOP_EVT and shall be reported as 0 for a transmitter */ - } dtm_state_update; /*!< Event parameter of ESP_GAP_BLE_DTM_TEST_UPDATE_EVT */ + esp_bt_status_t status; /*!< Status of the Direct Test Mode operation, indicating whether the operation was successful or if an error occurred. */ + esp_ble_dtm_update_evt_t update_evt; /*!< Direct Test Mode state change event. Possible values are: + * 0x00: DTM TX start - Direct Test Mode transmitter started. + * 0x01: DTM RX start - Direct Test Mode receiver started. + * 0x02: DTM end - Direct Test Mode ended. */ + uint16_t num_of_pkt; /*!< Number of packets received, applicable only if update_evt is DTM_TEST_STOP_EVT (0x02). This field shall be reported as 0 for a transmitter. */ + } dtm_state_update; + /** * @brief ESP_GAP_BLE_VENDOR_CMD_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_VENDOR_CMD_COMPLETE_EVT event. + * This event is triggered when a vendor-specific Host Controller Interface (HCI) command completes. */ struct vendor_cmd_cmpl_evt_param { - uint16_t opcode; /*!< vendor hci command opcode */ - uint16_t param_len; /*!< The length of parameter buffer */ - uint8_t *p_param_buf; /*!< The point of parameter buffer */ - } vendor_cmd_cmpl; /*!< Event parameter of ESP_GAP_BLE_VENDOR_CMD_COMPLETE_EVT */ + uint16_t opcode; /*!< Vendor-specific Host Controller Interface (HCI) command opcode. Identifies the specific vendor command. */ + uint16_t param_len; /*!< Length of the parameter buffer associated with the command response. */ + uint8_t *p_param_buf; /*!< Pointer to the parameter buffer containing the command response data. */ + } vendor_cmd_cmpl; + /** * @brief ESP_GAP_BLE_SET_PRIVACY_MODE_COMPLETE_EVT + * Event parameter for the ESP_GAP_BLE_SET_PRIVACY_MODE_COMPLETE_EVT event. + * This event is triggered when the privacy mode setting operation completes. */ struct ble_set_privacy_mode_cmpl_evt_param { - esp_bt_status_t status; /*!< Indicate privacy mode set operation success status */ - } set_privacy_mode_cmpl; /*!< Event parameter of ESP_GAP_BLE_SET_PRIVACY_MODE_COMPLETE_EVT */ + esp_bt_status_t status; /*!< Status of the privacy mode set operation. Indicates whether the operation was successful or if an error occurred. */ + } set_privacy_mode_cmpl; } esp_ble_gap_cb_param_t; /** - * @brief GAP callback function type - * @param event : Event type - * @param param : Point to callback parameter, currently is union type + * @brief Generic Access Profile callback function type. + * + * This function type is used for handling BLE GAP events. + * + * @param event : Event type, an enumeration value indicating the specific GAP event that occurred. + * + * @param param : Pointer to callback parameter, currently a union type that holds different parameters for various events. */ typedef void (* esp_gap_ble_cb_t)(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param); /** - * @brief This function is called to occur gap event, such as scan result + * @brief This function is called to register a callback function for handling Generic Access Profile (GAP) events. * - * @param[in] callback: callback function + * @param[in] callback: Pointer to the callback function that handles GAP events. * * @return - * - ESP_OK : success - * - other : failed + * - ESP_OK : Success + * - Other : Failure * */ esp_err_t esp_ble_gap_register_callback(esp_gap_ble_cb_t callback); /** - * @brief This function is called to get the current gap callback + * @brief This function is called to get the current Generic Access Profile callback. * - * @return - * - esp_gap_ble_cb_t : callback function + * @return - esp_gap_ble_cb_t : The currently registered callback function for GAP events. * */ esp_gap_ble_cb_t esp_ble_gap_get_callback(void); +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_42_FEATURE_SUPPORT == TRUE) /** - * @brief This function is called to override the BTA default ADV parameters. - * - * @param[in] adv_data: Pointer to User defined ADV data structure. This - * memory space can not be freed until callback of config_adv_data - * is received. - * - * @return - * - ESP_OK : success - * - other : failed - * + * @brief This function is called to override the default advertising parameters of the Bluetooth Test Adapter. + * It configures the advertising data that the Bluetooth Low Energy (BLE) device will use for advertising. + * This function allows you to set up various advertising parameters including: + * - Device Name + * - Service UUIDs (Universally Unique Identifiers) + * - Manufacturer Data + * - Other Advertising Data Fields + * + * After calling this function, an event of type `ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT` will be triggered + * to indicate whether the configuration was successful or not. + * + * This function is crucial for customizing how your BLE device advertises itself to other devices. Properly + * configuring advertising data helps in identifying the device, providing service information, and enhancing + * device discoverability. + * + * @note Note: The `adv_data` structure should not be freed until the callback for `config_adv_data` is received, + * which indicates that the advertising data configuration process is complete. + * + * The function triggers the following event: + * - **ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT**: This event indicates the result of the advertising data configuration. + * It informs whether the configuration was successful or if there was an error. + * + * @param[in] adv_data: Pointer to User-defined advertising data structure (`esp_ble_adv_data_t`). + * This structure contains the various advertising data fields such as device name, service UUIDs, + * manufacturer data, and other related fields. + *. + * @return - ESP_OK : Success, advertising data configuration was successful. + * - other : Failed, advertising data configuration encountered an error. */ -esp_err_t esp_ble_gap_config_adv_data (esp_ble_adv_data_t *adv_data); - - - -/** - * @brief This function is called to set scan parameters - * - * @param[in] scan_params: Pointer to User defined scan_params data structure. This - * memory space can not be freed until callback of set_scan_params - * - * @return - * - ESP_OK : success - * - other : failed - * +esp_err_t esp_ble_gap_config_adv_data(esp_ble_adv_data_t *adv_data); + +/** + * @brief This function is called to set scan parameters for Bluetooth Low Energy (BLE) scanning. + * It configures the parameters that determine how the BLE device scans for nearby BLE devices. + * The scan parameters include: + * - Scan Interval: The time between the start of two consecutive scans. + * - Scan Window: The time during which the device listens for advertising packets. + * - Scan Mode: The mode of scanning (e.g., passive or active). + * + * After calling this function, an event of type `ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT` will be triggered + * to indicate whether the scan parameters configuration was successful or not. + * + * Proper configuration of scan parameters is essential for efficient scanning and power management. It helps + * in optimizing the scan duration and interval to balance between scanning performance and power consumption. + * + * @note Note: The `scan_params` structure should not be freed until the callback for `set_scan_params` is received, + * which indicates that the scan parameters configuration process is complete. + * + * The function triggers the following event: + * - **ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT**: This event indicates the result of the scan parameters configuration. + * It informs whether the configuration was successful or if there was an error. + * + * @param[in] scan_params: Pointer to User-defined scan parameters data structure (`esp_ble_scan_params_t`). + * This structure contains the scan interval, scan window, scan mode, and other related settings. + * + * @return - ESP_OK : Success, scan parameters configuration was successful. + * - other : Failed, scan parameters configuration encountered an error. */ esp_err_t esp_ble_gap_set_scan_params(esp_ble_scan_params_t *scan_params); /** - * @brief This procedure keep the device scanning the peer device which advertising on the air - * - * @param[in] duration: Keeping the scanning time, the unit is second. - * - * @return - * - ESP_OK : success - * - other : failed - * + * @brief This function starts a scanning procedure to search for Bluetooth Low Energy (BLE) devices + * that are advertising in the air. The scanning process will detect nearby BLE devices that are + * broadcasting advertising packets, allowing the device to discover available BLE devices in the vicinity. + * + * The scanning duration specifies how long the device should continue scanning for advertising packets. + * After calling this function: + * - Scanning will commence for the specified duration. + * - An event of type `ESP_GAP_BLE_SCAN_START_COMPLETE_EVT` will be triggered once the scanning procedure starts, + * indicating that the scanning has successfully begun. + * - An event of type `ESP_GAP_BLE_SCAN_RESULT_EVT` will be triggered for each detected BLE device during the scan. + * + * Proper configuration of the scanning duration is essential to balance between scan performance and power consumption. + * + * @note Note: For continuous scanning, specify a duration of 0 seconds. The device will continue scanning indefinitely + * until explicitly stopped. + * + * The function triggers the following events: + * - **ESP_GAP_BLE_SCAN_START_COMPLETE_EVT**: Indicates the result of starting the scanning procedure. + * It informs whether the scanning has started successfully or if there was an error. + * - **ESP_GAP_BLE_SCAN_RESULT_EVT**: Provides the result of each detected BLE device during the scan. + * This event contains details about the advertising packets received from the detected devices. + * + * @param[in] duration: The duration (in seconds) for which the device should keep scanning. A value of 0 indicates + * continuous scanning. The scanning will stop either when the specified duration elapses or when the scan is + * explicitly stopped. + * + * @return - ESP_OK : Success, scanning started successfully. + * - other : Failed, scanning could not be started. Refer to error codes for details. */ esp_err_t esp_ble_gap_start_scanning(uint32_t duration); /** - * @brief This function call to stop the device scanning the peer device which advertising on the air - * @return - * - ESP_OK : success - * - other : failed - * + * @brief This function stops the device from scanning for Bluetooth Low Energy (BLE) devices that are advertising. + * It halts the ongoing scanning procedure that was initiated by calling `esp_ble_gap_start_scanning()`. + * Once this function is called, the device will cease to listen for advertising packets from nearby BLE devices. + * + * After calling this function, an event of type `ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT` will be triggered + * to notify that the scanning procedure has been successfully stopped. + * + * Properly stopping scanning is important to manage power consumption and free up resources when scanning is no + * longer needed. + * + * @note Note: If scanning was not started or if scanning was already stopped, this function will still return + * `ESP_OK`, indicating that the request to stop scanning was processed correctly. + * + * The function triggers the following event: + * - **ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT**: This event indicates the result of stopping the scanning procedure. + * It informs whether the scanning was successfully stopped or if there was an error. + * + * @return - ESP_OK : Success, scanning was stopped successfully. + * - other : Failed, scanning could not be stopped. Refer to error codes for details. */ esp_err_t esp_ble_gap_stop_scanning(void); /** - * @brief This function is called to start advertising. - * - * @param[in] adv_params: pointer to User defined adv_params data structure. - - * @return - * - ESP_OK : success - * - other : failed - * + * @brief This function is called to start Bluetooth Low Energy (BLE) advertising. + * Advertising allows a BLE device to broadcast advertising packets to other nearby BLE devices. + * This function uses parameters defined in the `esp_ble_adv_params_t` structure to configure + * how the device advertises, including settings such as advertising interval, advertising type, + * and advertising channel map. Advertising enables other BLE devices to discover the device and + * initiate connections. + * + * After calling this function, an event of type `ESP_GAP_BLE_ADV_START_COMPLETE_EVT` will be triggered + * to indicate whether the advertising process was started successfully or if there was an error. + * + * Proper configuration of advertising parameters is essential for effective device discovery and connection + * establishment. It helps in optimizing advertising performance and managing power consumption. + * + * @note Note: Ensure that advertising parameters are correctly configured before starting advertising. + * The `adv_params` structure should not be freed until the callback for `start_advertising` is received, + * which indicates that the advertising start process is complete. + * + * The function triggers the following event: + * - **ESP_GAP_BLE_ADV_START_COMPLETE_EVT**: This event indicates the result of the advertising start operation. + * It informs whether the advertising was successfully started or if there was an error. + * + * @param[in] adv_params: Pointer to user-defined advertising parameters structure (`esp_ble_adv_params_t`). + * This structure contains various settings for advertising, including: + * - Advertising Interval: The time between consecutive advertising packets. + * - Advertising Type: The type of advertising (e.g., connectable, non-connectable). + * - Advertising Channel Map: The BLE channels used for advertising. + * + * @return - ESP_OK : Success, advertising started successfully. + * - other : Failed, advertising could not be started. Refer to error codes for details. */ -esp_err_t esp_ble_gap_start_advertising (esp_ble_adv_params_t *adv_params); - - - -/** - * @brief This function is called to stop advertising. - * - * @return - * - ESP_OK : success - * - other : failed - * +esp_err_t esp_ble_gap_start_advertising(esp_ble_adv_params_t *adv_params); + +/** + * @brief This function is called to stop Bluetooth Low Energy (BLE) advertising. + * This function halts the process of broadcasting advertising packets to other BLE devices, + * which were previously initiated by the `esp_ble_gap_start_advertising` function. + * Stopping advertising will prevent the device from being discoverable or establishing new connections + * based on the ongoing advertising packets. It is useful for controlling when the device should + * cease broadcasting its presence and stop responding to connection requests. + * + * After calling this function, an event of type `ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT` will be triggered + * to indicate whether the advertising stop operation was successful or if there was an error. + * + * Properly stopping advertising is important for managing power consumption and ensuring that + * the device is not unnecessarily discoverable. + * + * @note Note: Make sure to call this function when you want to stop advertising, such as when transitioning + * to a different operational mode or after a connection has been established. The function triggers + * the following event: + * - **ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT**: This event indicates the result of the advertising stop operation, + * informing whether the advertising was successfully stopped or if there was an error. + * + * @return - ESP_OK : Success, advertising stopped successfully. + * - other : Failed, advertising could not be stopped. Refer to error codes for details. */ esp_err_t esp_ble_gap_stop_advertising(void); -#endif // #if (BLE_42_FEATURE_SUPPORT == TRUE) - - -/** - * @brief Update connection parameters, can only be used when connection is up. - * - * @param[in] params - connection update parameters - * - * @return - * - ESP_OK : success - * - other : failed - * +#endif// #if (BLE_42_FEATURE_SUPPORT == TRUE) +//@} + +/** + * @brief Update the Bluetooth Low Energy (BLE) connection parameters for an existing connection. + * This function can only be used when a BLE connection is already established. + * It allows you to modify the connection parameters such as: + * - Connection Interval: The time between two consecutive connection events. + * - Slave Latency: The number of connection events that the slave device can skip. + * - Supervision Timeout: The maximum time between two successful connection events before the connection is considered lost. + * + * The function sends a request to the remote device to update these parameters. If the remote device accepts + * the request, the new parameters will be applied to the connection. + * + * After calling this function, an event of type `BLE_GAP_EVENT_CONN_UPDATE` will be triggered + * to indicate the result of the connection parameters update. + * + * Proper configuration of connection parameters is crucial for optimizing performance and power consumption. + * + * @note Note: Ensure that you call this function only when there is an active BLE connection. The function triggers + * the following event: + * - **BLE_GAP_EVENT_CONN_UPDATE**: This event indicates the result of the connection parameters update request. + * It informs whether the update was successful or if there was an error. + * + * @param[in] params - Pointer to the structure containing the new connection parameters, of type + * `esp_ble_conn_update_params_t`. This structure includes fields such as: + * - Connection Interval: The desired interval between connection events. + * - Slave Latency: The number of connection events that can be skipped. + * - Supervision Timeout: The timeout period for connection supervision. + * + * @return - ESP_OK : Success, connection parameters updated successfully. + * - other : Failed, connection parameters could not be updated. Refer to error codes for details. */ esp_err_t esp_ble_gap_update_conn_params(esp_ble_conn_update_params_t *params); /** - * @brief This function is to set maximum LE data packet size - * - * @return - * - ESP_OK : success - * - other : failed - * + * @brief This function sets the maximum data packet size for Bluetooth Low Energy (BLE) communication. + * The data packet size determines the maximum amount of data that can be transmitted in a single BLE + * data packet. This function allows you to specify the maximum payload size for outgoing data packets. + * + * Setting the data packet size is important to ensure efficient data transmission. Both the local device + * and the remote device must support the specified packet size for it to be effective. If the remote device + * does not support the specified size, the packet size may be adjusted to the maximum supported size. + * + * After calling this function, the new data packet size will be applied to the connection with the specified + * remote device. The function may trigger an event of type `ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT` + * to indicate the result of the data packet size configuration operation. + * + * @note Note: The `remote_device` parameter should be the Bluetooth device address (BD_ADDR) of the remote device. + * The `tx_data_length` should be within the range supported by the BLE specification. Ensure that both devices + * agree on the packet size to avoid potential issues with data transmission. + * + * The function triggers the following event: + * - **ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT**: This event indicates whether the data packet size configuration + * was successful or if there was an error. + * + * @param[in] remote_device: Address of the remote BLE device for which the data packet size is being set. + * This is an array of 6 bytes representing the Bluetooth device address (BD_ADDR). + * + * @param[in] tx_data_length: The maximum data length in bytes for the outgoing data packets. + * This value should be within the range specified by the BLE specification. + * + * @return - ESP_OK : Success, data packet size set successfully. + * - other : Failed, could not set data packet size. Refer to the error codes for details. */ esp_err_t esp_ble_gap_set_pkt_data_len(esp_bd_addr_t remote_device, uint16_t tx_data_length); /** - * @brief This function allows configuring either a Non-Resolvable Private Address or a Static Random Address - * - * @param[in] rand_addr: The address to be configured. Refer to the table below for possible address subtypes: - * - * | address [47:46] | Address Type | Corresponding API | - * |-----------------|-----------------------------|----------------------------------------| - * | 0b00 | Non-Resolvable Private | esp_ble_gap_addr_create_nrpa | - * | | Address (NRPA) | | - * |-----------------|-----------------------------|----------------------------------------| - * | 0b11 | Static Random Address | esp_ble_gap_addr_create_static | - * |-----------------|-----------------------------|----------------------------------------| - * - * @return - * - ESP_OK : success - * - other : failed - * + * @brief This function allows configuring either a Non-Resolvable Private Address (NRPA) or a Static Random Address. + * A Non-Resolvable Private Address is used to enhance privacy by preventing the device from being easily tracked, + * while a Static Random Address is a fixed, randomly generated address that does not change. This function + * sets the Bluetooth device address type to either NRPA or Static Random Address based on the format of the + * `rand_addr` parameter. + * + * After calling this function, the new address type will be applied to the Bluetooth device. The function + * may trigger an event of type `ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT` to indicate the result of the operation. + * + * Proper configuration of the address type is crucial for maintaining privacy and ensuring that the address + * meets the requirements for your specific use case. NRPA is useful for enhancing privacy by changing the address + * periodically, while Static Random Address provides a stable address for scenarios where a fixed address is needed. + * + * @note Note: The `rand_addr` parameter should be set according to the Bluetooth address type required. Refer to + * the address format and subtype table below for details on how to specify NRPA or Static Random Address. + * + * The function triggers the following event: + * - **ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT**: This event indicates whether the address configuration was + * successful or if there was an error. + * + * @param[in] rand_addr: The address to be configured. The address format and subtype are as follows: + * + * | address [47:46] | Address Type | Corresponding API | + * |-----------------|-----------------------------|----------------------------------------| + * | 0b00 | Non-Resolvable Private | esp_ble_gap_addr_create_nrpa | + * | | Address (NRPA) | | + * |-----------------|-----------------------------|----------------------------------------| + * | 0b11 | Static Random Address | esp_ble_gap_addr_create_static | + * |-----------------|-----------------------------|----------------------------------------| + * + * @return - ESP_OK : Success, address configured successfully. + * - other : Failed, could not configure the address. Refer to the error codes for details. */ esp_err_t esp_ble_gap_set_rand_addr(esp_bd_addr_t rand_addr); /** - * @brief Create a static device address + * @brief Create a static device address. + * A Static Random Address is a fixed, randomly generated address that does not change. + * This function generates a new static random address and stores it in the buffer provided by the user. + * The address is used to uniquely identify the Bluetooth device and does not change over time. + * This function may trigger the event `ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT` to indicate the result of the operation. + * + * @note Note: The buffer pointed to by `rand_addr` should be allocated by the user and must be large enough + * to hold a Bluetooth device address (BD_ADDR), which is 6 bytes. Ensure that this buffer remains valid + * until the callback for `esp_ble_gap_addr_create_static` is received, indicating that the static address + * creation process is complete. + * + * The function triggers the following event: + * - **ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT**: This event indicates whether the static device address creation + * was successful or if there was an error. + * * @param[out] rand_addr: Pointer to the buffer where the static device address will be stored. - * @return - ESP_OK : Success - * - Other : Failed + * This buffer should be large enough to hold the Bluetooth device address (BD_ADDR), which is 6 bytes. + * + * @return + * - ESP_OK : Success, static device address created and stored successfully. + * - Other : Failed, could not create static device address. Refer to the error codes for details. */ esp_err_t esp_ble_gap_addr_create_static(esp_bd_addr_t rand_addr); /** - * @brief Create a non-resolvable private address (NRPA) + * @brief Create a Non-Resolvable Private Address (NRPA). + * A Non-Resolvable Private Address (NRPA) is used to enhance privacy by preventing the device from being easily tracked. + * This function generates a new Non-Resolvable Private Address and stores it in the buffer provided by the user. + * The NRPA is a temporary address that changes periodically to avoid tracking by external parties. + * This function may trigger the event `ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT` to indicate the result of the operation. + * + * @note Note: The buffer pointed to by `rand_addr` should be allocated by the user and must be large enough + * to hold a Bluetooth device address (BD_ADDR), which is 6 bytes. Ensure that this buffer remains valid + * until the callback for `esp_ble_gap_addr_create_nrpa` is received, indicating that the NRPA creation + * process is complete. + * + * The function triggers the following event: + * - **ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT**: This event indicates whether the Non-Resolvable Private Address creation + * was successful or if there was an error. + * * @param[out] rand_addr: Pointer to the buffer where the NRPA will be stored. - * @return - ESP_OK : Success - * - Other : Failed + * This buffer should be large enough to hold the Bluetooth device address (BD_ADDR), which is 6 bytes. + * + * @return - ESP_OK : Success, NRPA created and stored successfully. + * - Other : Failed, could not create NRPA. Refer to the error codes for details. */ esp_err_t esp_ble_gap_addr_create_nrpa(esp_bd_addr_t rand_addr); /** - * @brief This function sets the length of time the Controller uses a Resolvable Private Address - * before generating and starting to use a new resolvable private address. + * @brief This function sets the length of time that the Bluetooth Controller uses a Resolvable Private Address (RPA) + * before generating and starting to use a new Resolvable Private Address. A Resolvable Private Address (RPA) + * is used to enhance privacy by allowing devices to periodically change their Bluetooth address while still + * being able to resolve the address back to the original device. This helps prevent tracking of devices. + * + * The timeout value specifies how long the current RPA should be used before the Controller switches to a new + * RPA. The timeout must be within the range specified by the Bluetooth Specification (0x0001 to 0x0E10), which + * corresponds to a time range of 1 second to 1 hour. The default timeout value is 0x0384 (900 seconds or 15 minutes). * * @note Note: This function is currently not supported on the ESP32 but will be enabled in a future update. * - * @param[in] rpa_timeout: The timeout duration in seconds for how long a Resolvable Private Address - * is used before a new one is generated. The value must be within the range specified by - * the Bluetooth specification (0x0001 to 0x0E10), which corresponds to a time range of - * 1 second to 1 hour. The default value is 0x0384 (900 seconds or 15 minutes). - * @return - * - ESP_OK : success - * - other : failed + * The function triggers the following event: + * - **ESP_GAP_BLE_SET_RPA_TIMEOUT_COMPLETE_EVT**: This event indicates that the operation to set the RPA timeout + * has completed. The event provides information about the success or failure of the operation. + * + * @param[in] rpa_timeout: The duration in seconds for how long the Resolvable Private Address (RPA) is used before a + * new RPA is generated. The value must be within the range specified by the Bluetooth Specification (0x0001 to 0x0E10). * + * @return - ESP_OK : Success, the RPA timeout has been set successfully. + * - Other : Failure, the RPA timeout could not be set. Refer to the error codes for details. */ esp_err_t esp_ble_gap_set_resolvable_private_address_timeout(uint16_t rpa_timeout); /** - * @brief This function adds a device to the resolving list used to generate and resolve Resolvable Private Addresses - * in the Controller. + * @brief This function adds a device to the resolving list used to generate and resolve Resolvable Private Addresses (RPAs) + * in the Bluetooth Controller. The resolving list is utilized to manage devices with which the Controller has + * previously exchanged Identity Resolving Keys (IRKs). The added device will be used to generate and resolve + * Resolvable Private Addresses during Bluetooth communication. * - * @note Note: This function shall not be used when address resolution is enabled in the Controller and: + * @note Note: This function should not be used when address resolution is enabled in the Controller and: * - Advertising (other than periodic advertising) is enabled, * - Scanning is enabled, or - * - an HCI_LE_Create_Connection, HCI_LE_Extended_Create_Connection, or HCI_LE_Periodic_Advertising_Create_Sync command is pending. + * - An HCI_LE_Create_Connection, HCI_LE_Extended_Create_Connection, or HCI_LE_Periodic_Advertising_Create_Sync + * command is pending. * This command may be used at any time when address resolution is disabled in the Controller. - * The added device shall be set to Network Privacy mode. + * The added device must be set to Network Privacy mode. * - * @param[in] peer_addr: The peer identity address of the device to be added to the resolving list. - * @param[in] addr_type: The address type of the peer identity address (BLE_ADDR_TYPE_PUBLIC or BLE_ADDR_TYPE_RANDOM). - * @param[in] peer_irk: The Identity Resolving Key (IRK) of the device. - * @return - * - ESP_OK : success - * - other : failed + * The function triggers the following event: + * - **ESP_GAP_BLE_RESOLVING_LIST_UPDATE_EVT**: This event indicates that the resolving list has been updated. + * It provides information about the result of adding the device to the list. + * + * @param[in] peer_addr: The peer identity address of the device to be added to the resolving list. This is a Bluetooth + * device address (BD_ADDR) that identifies the peer device. + * @param[in] addr_type: The address type of the peer identity address. It can be either `BLE_ADDR_TYPE_PUBLIC` for a public + * address or `BLE_ADDR_TYPE_RANDOM` for a random address. + * @param[in] peer_irk: The Identity Resolving Key (IRK) of the device. This key is used to generate and resolve Resolvable + * Private Addresses for the device. * + * @return - ESP_OK : Success, the device was added to the resolving list successfully. + * - Other : Failure, the device could not be added to the resolving list. Refer to the error codes for details. */ esp_err_t esp_ble_gap_add_device_to_resolving_list(esp_bd_addr_t peer_addr, uint8_t addr_type, uint8_t *peer_irk); + /** - * @brief This function clears the random address for the application - * - * @return - * - ESP_OK : success - * - other : failed - * + * @brief This function clears the random address that was previously set for the application. + * It removes the current random address configuration, which may have been used for + * privacy or other purposes. After calling this function, the Bluetooth device will + * no longer use the previously set random address. + * + * The function returns the result of the operation. If the address clearing was successful, + * the device will revert to using the default address or other address configuration. + * + * @note Note: Clearing the random address will not affect other Bluetooth settings or connections. + * It is important to configure a new address if needed before starting advertising or scanning + * operations again. + * + * @return - ESP_OK : Success, the random address was cleared successfully. + * - Other : Failure, the random address could not be cleared. Refer to the error codes for details. */ esp_err_t esp_ble_gap_clear_rand_addr(void); /** - * @brief Enable/disable privacy (including address resolution) on the local device - * - * @param[in] privacy_enable - enable/disable privacy on remote device. - * - * @return - * - ESP_OK : success - * - other : failed - * + * @brief This function enables or disables privacy features, including address resolution, on the local Bluetooth device. + * When privacy is enabled (`privacy_enable` set to `true`), the device will use a Resolvable Private Address (RPA) + * rather than a static or public address. This helps to enhance privacy by periodically changing the address + * while still allowing for address resolution. + * + * When privacy is disabled (`privacy_enable` set to `false`), the device will use its static or public address + * as usual, without employing RPA. This can be useful in scenarios where privacy is not a concern or when + * privacy-related operations are not required. + * + * @note Note: Enabling privacy can impact the device's discoverability and connection process, as other devices + * may need to resolve the RPA to establish a connection. Ensure that privacy settings align with your application's + * requirements. + * + * + * @param[in] privacy_enable: Boolean flag to enable or disable privacy on the local device. + * - `true` : Enable privacy using Resolvable Private Addresses (RPA). + * - `false` : Disable privacy and use static or public addresses. + * + * @return - ESP_OK : Success, privacy configuration applied successfully. + * - Other : Failure, privacy configuration could not be applied. Refer to the error codes for details. */ -esp_err_t esp_ble_gap_config_local_privacy (bool privacy_enable); +esp_err_t esp_ble_gap_config_local_privacy(bool privacy_enable); /** - * @brief set local gap appearance icon - * + * @brief This function sets the local Generic Access Profile (GAP) appearance icon. + * The appearance icon is used to provide a human-readable indication of the device's type or appearance + * in Bluetooth profiles and applications. This helps other devices or applications to identify or categorize + * the device based on its appearance. The values for the appearance icon are defined by the Bluetooth Special + * Interest Group (SIG). * - * @param[in] icon - External appearance value, these values are defined by the Bluetooth SIG, please refer to + * @param[in] icon - The appearance value to be set. These values are defined by the Bluetooth SIG and can be + * referenced in the Bluetooth Assigned Numbers document available at: * https://www.bluetooth.com/specifications/assigned-numbers/ + * + * @note Note: Ensure that the appearance value you set is valid and corresponds to a predefined value from the + * Bluetooth SIG specifications to ensure proper functionality and compatibility with other Bluetooth devices. * - * @return - * - ESP_OK : success - * - other : failed - * + * @return - ESP_OK : Success, the local appearance icon was set successfully. + * - Other : Failure, the local appearance icon could not be set. Refer to error codes for details. + */ +esp_err_t esp_ble_gap_config_local_icon(uint16_t icon); + +/** + * @brief Add or remove a device from the whitelist. + * The whitelist is a list of Bluetooth Low Energy (BLE) devices that are allowed or disallowed for + * connection or interaction. This function allows you to manage the whitelist by adding or removing + * devices based on their address. + * + * When `add_remove` is set to true, the specified device is added to the whitelist. When it is set to + * false, the specified device is removed from the whitelist. The `remote_bda` parameter specifies the + * Bluetooth device address (BD_ADDR) of the device to be added or removed, and `wl_addr_type` specifies + * the address type of the device. + * + * @param[in] add_remove: The action to be performed on the whitelist. Set to `true` to add the device to the + * whitelist, or `false` to remove the device from the whitelist. + * @param[in] remote_bda: The Bluetooth device address (BD_ADDR) of the device to be added or removed from the + * whitelist. This address uniquely identifies the device. + * @param[in] wl_addr_type: The address type of the device being added or removed. This can be either + * `BLE_ADDR_TYPE_PUBLIC` for a public address or `BLE_ADDR_TYPE_RANDOM` for a random address. + * + * @note Note: Managing the whitelist helps control which devices can connect to or interact with your BLE + * device. Ensure that you correctly specify the address type and address to avoid accidental removal or + * addition of unintended devices. + * + * The function triggers the following event: + * - **ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT**: This event indicates the result of the whitelist update + * operation. It provides information about whether the device was successfully added or removed from the + * whitelist. + * + * @return - ESP_OK : Success, the device was added to or removed from the whitelist successfully. + * - Other : Failure, the device could not be added to or removed from the whitelist. Refer to error codes + * for details. */ -esp_err_t esp_ble_gap_config_local_icon (uint16_t icon); - -/** -* @brief Add or remove device from white list -* -* @param[in] add_remove: the value is true if added the ble device to the white list, and false remove to the white list. -* @param[in] remote_bda: the remote device address add/remove from the white list. -* @param[in] wl_addr_type: whitelist address type -* @return -* - ESP_OK : success -* - other : failed -* -*/ esp_err_t esp_ble_gap_update_whitelist(bool add_remove, esp_bd_addr_t remote_bda, esp_ble_wl_addr_type_t wl_addr_type); /** -* @brief Clear all white list -* -* @return -* - ESP_OK : success -* - other : failed -* -*/ + * @brief Clear all entries from the whitelist. + * The whitelist is a list of Bluetooth Low Energy (BLE) devices that are allowed or disallowed for + * connection or interaction. This function removes all devices from the whitelist, effectively + * clearing the list of previously allowed or disallowed devices. + * + * After calling this function, the whitelist will be empty, and no devices will be on the list. + * This operation may be useful for resetting the device's connection policy or starting fresh + * with a new whitelist configuration. + * + * @note Note: Clearing the whitelist will affect the device's ability to connect to or interact with + * previously whitelisted devices. Ensure that you reconfigure the whitelist as needed after clearing it. + * + * @return - ESP_OK : Success, the whitelist was cleared successfully. + * - Other : Failure, the whitelist could not be cleared. Refer to error codes for details. + */ esp_err_t esp_ble_gap_clear_whitelist(void); /** -* @brief Get the whitelist size in the controller -* -* @param[out] length: the white list length. -* @return -* - ESP_OK : success -* - other : failed -* -*/ + * @brief Get the size of the whitelist in the controller. + * This function retrieves the current size of the whitelist, which indicates the number of entries + * that the whitelist can hold. The whitelist size defines how many devices can be added to or removed + * from the whitelist. This information is useful for understanding the capacity of the whitelist + * and managing device entries accordingly. + * + * @param[out] length: Pointer to a variable where the whitelist size will be stored. This variable will be + * updated with the current number of entries that the whitelist can accommodate. + * + * @return - ESP_OK : Success, the whitelist size was successfully retrieved. + * - Other : Failure, the whitelist size could not be retrieved. Refer to error codes for details. + */ esp_err_t esp_ble_gap_get_whitelist_size(uint16_t *length); + +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_42_FEATURE_SUPPORT == TRUE) /** -* @brief This function is called to set the preferred connection -* parameters when default connection parameter is not desired before connecting. -* This API can only be used in the master role. -* -* @param[in] bd_addr: BD address of the peripheral -* @param[in] min_conn_int: minimum preferred connection interval -* @param[in] max_conn_int: maximum preferred connection interval -* @param[in] slave_latency: preferred slave latency -* @param[in] supervision_tout: preferred supervision timeout -* -* @return -* - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to set the preferred connection parameters for a Bluetooth Low Energy (BLE) connection. + * This configuration is applied before initiating a connection to a peripheral device. It is applicable only + * when the device is in the master role. + * + * This function allows you to specify these parameters to optimize the connection based on your application's + * needs and to ensure compatibility with the peripheral device. + * + * After calling this function, the preferred connection parameters will be used when a connection is established + * with the specified peripheral device. + * + * @note Note: This function does not trigger an event directly. The connection parameters are applied when the connection + * is initiated. You can monitor the connection status and parameters through other events related to BLE connections. + * + * @param[in] bd_addr: The Bluetooth Device Address (BD_ADDR) of the peripheral device for which the preferred connection + * parameters are being set. + * @param[in] min_conn_int: Minimum preferred connection interval, in milliseconds. This defines the shortest time between + * two consecutive connection events. + * @param[in] max_conn_int: Maximum preferred connection interval, in milliseconds. This defines the longest time between + * two consecutive connection events. + * @param[in] slave_latency: Preferred slave latency. This is the number of connection events that the slave device is allowed + * to skip. + * @param[in] supervision_tout: Preferred supervision timeout, in milliseconds. This defines the time period within which + * the connection must be maintained to avoid disconnection. + * + * @return - ESP_OK : Success, the preferred connection parameters were set successfully. + * - Other : Failure, the preferred connection parameters could not be set. Refer to error codes for details. + */ esp_err_t esp_ble_gap_set_prefer_conn_params(esp_bd_addr_t bd_addr, - uint16_t min_conn_int, uint16_t max_conn_int, - uint16_t slave_latency, uint16_t supervision_tout); + uint16_t min_conn_int, uint16_t max_conn_int, + uint16_t slave_latency, uint16_t supervision_tout); #endif // #if (BLE_42_FEATURE_SUPPORT == TRUE) +//@} + /** - * @brief Set device name to the local device - * Note: This API don't affect the advertising data + * @brief Set the device name for the local Bluetooth Low Energy (BLE) device. + * This function allows you to set or update the device name that will be used for identification + * purposes. The device name is a human-readable string that can be displayed by other devices + * to identify your BLE device. + * + * @note This API only updates the device name in the local device's settings. It does not affect the + * advertising data or any other parameters related to BLE advertising. * - * @param[in] name - device name. - * - * @return - * - ESP_OK : success - * - other : failed + * @param[in] name: The device name to be set. This should be a null-terminated string. * + * @return - ESP_OK : Success, the device name was set successfully. + * - Other : Failure, the device name could not be set. Refer to error codes for details. */ esp_err_t esp_ble_gap_set_device_name(const char *name); /** - * @brief Get device name of the local device - * - * @return - * - ESP_OK : success - * - other : failed + * @brief Retrieve the device name of the local Bluetooth Low Energy (BLE) device. + * This function is used to get the current device name that has been assigned to the local BLE device. + * The device name is a human-readable string that identifies your BLE device and can be displayed + * by other BLE devices or applications to recognize it. + * + * @note Note: This function only retrieves the device name; it does not modify or set it. + * To set or update the device name, use the `esp_ble_gap_set_device_name` function. Ensure that + * the device name has been previously set using `esp_ble_gap_set_device_name` before calling this + * function to obtain it. * + * @return - ESP_OK : Success, the device name was retrieved successfully. + * - Other : Failure, the device name could not be retrieved. Refer to the error codes for details. */ esp_err_t esp_ble_gap_get_device_name(void); /** - * @brief This function is called to get local used address and address type. - * uint8_t *esp_bt_dev_get_address(void) get the public address + * @brief Retrieve the local Bluetooth Low Energy (BLE) device's currently used address and its type. + * This function provides the current address and address type that the local BLE device is using. + * The address can be either a public address or a random address, depending on the device's configuration. + * + * @note Note: The address type can indicate whether the address is public, random (static), or resolvable + * private. The function `esp_bt_dev_get_address` can be used to get the public address of the device. * - * @param[in] local_used_addr - current local used ble address (six bytes) - * @param[in] addr_type - ble address type - * - * @return - ESP_OK : success - * - other : failed + * @param[out] local_used_addr: Pointer to a buffer where the current local BLE address will be stored. This buffer + * should be large enough to hold the Bluetooth device address (BD_ADDR), which is 6 bytes. + * @param[out] addr_type: Pointer to a variable where the address type will be stored. This value indicates the type + * of the address (e.g., public or random). * + * @return - ESP_OK : Success, the local used address and address type were retrieved successfully. + * - Other : Failure, the local used address and address type could not be retrieved. Refer to the error + * codes for details. */ esp_err_t esp_ble_gap_get_local_used_addr(esp_bd_addr_t local_used_addr, uint8_t * addr_type); + /** - * @brief This function is called to get ADV data for a specific type. - * - * @param[in] adv_data - pointer of ADV data which to be resolved - * @param[in] type - finding ADV data type - * @param[out] length - return the length of ADV data not including type - * - * @return pointer of ADV data - * + * @brief Retrieve specific advertising data from a given advertising data buffer. + * This function processes the advertising data buffer to extract the data of a specific type. + * Advertising data in BLE (Bluetooth Low Energy) can contain various types of information such as + * device name, appearance, manufacturer data, etc. This function helps in extracting the required + * type of advertising data for further processing or analysis. + * + * @param[in] adv_data: Pointer to the buffer containing the complete advertising data. The buffer should include + * all the advertising data segments received from a BLE device. + * @param[in] type: The type of advertising data to find. BLE advertising data types are defined in the BLE + * specification and include various values such as `0x01` for flags, `0x09` for device name, etc. + * @param[out] length: Pointer to a variable where the length of the extracted advertising data (excluding the type) + * will be stored. This value will be updated with the length of the data found. + * + * @return Pointer to the extracted advertising data. If the specified type is found in the `adv_data`, + * this function returns a pointer to the start of that data. If the type is not found, it returns `NULL`. + * + * @note If the function returns `NULL`, it means the specified type of advertising data was not found in the + * provided buffer. */ uint8_t *esp_ble_resolve_adv_data(uint8_t *adv_data, uint8_t type, uint8_t *length); + +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_42_FEATURE_SUPPORT == TRUE) /** - * @brief This function is called to set raw advertising data. User need to fill - * ADV data by self. - * - * @param[in] raw_data : raw advertising data with the format: [Length 1][Data Type 1][Data 1][Length 2][Data Type 2][Data 2] ... - * @param[in] raw_data_len : raw advertising data length , less than 31 bytes - * - * @return - * - ESP_OK : success - * - other : failed - * + * @brief Configure raw advertising data for the local Bluetooth device. + * This function allows you to set custom raw advertising data that will be broadcasted by the device. + * The raw advertising data should be provided in a specific format, with each segment including + * a length field, a data type field, and the actual data. The total length of the raw data must be + * less than 31 bytes, which is the maximum allowed length for BLE (Bluetooth Low Energy) advertising data. + * + * @param[in] raw_data: Pointer to the buffer containing the raw advertising data. The format should be as follows: + * [Length 1][Data Type 1][Data 1][Length 2][Data Type 2][Data 2] ... + * Where: + * - [Length N]: Length of the advertising data segment N, including the data type byte. + * - [Data Type N]: Type of the advertising data segment N, as defined by the BLE specification. + * - [Data N]: Actual data for segment N. + * @param[in] raw_data_len: Length of the raw advertising data in bytes. The value must be less than 31 bytes. + * + * @return - ESP_OK : Success, raw advertising data configured successfully. + * - Other : Failure, raw advertising data could not be configured. Refer to error codes for details. */ esp_err_t esp_ble_gap_config_adv_data_raw(uint8_t *raw_data, uint32_t raw_data_len); /** - * @brief This function is called to set raw scan response data. User need to fill - * scan response data by self. + * @brief Configure raw scan response data for the local Bluetooth device. + * This function allows you to set custom raw scan response data that will be sent in response to + * scan requests from other BLE (Bluetooth Low Energy) devices. The raw scan response data should be + * provided in a specific format, with each segment including a length field, a data type field, and + * the actual data. The total length of the raw data must be less than 31 bytes, which is the maximum + * allowed length for BLE scan response data. * - * @param[in] raw_data : raw scan response data - * @param[in] raw_data_len : raw scan response data length , less than 31 bytes + * @param[in] raw_data: Pointer to the buffer containing the raw scan response data. The format should be as follows: + * [Length 1][Data Type 1][Data 1][Length 2][Data Type 2][Data 2] ... + * Where: + * - [Length N]: Length of the scan response data segment N, including the data type byte. + * - [Data Type N]: Type of the scan response data segment N, as defined by the BLE specification. + * - [Data N]: Actual data for segment N. + * @param[in] raw_data_len: Length of the raw scan response data in bytes. The value must be less than 31 bytes. * - * @return - * - ESP_OK : success - * - other : failed + * @return - ESP_OK : Success, raw scan response data configured successfully. + * - Other : Failure, raw scan response data could not be configured. Refer to error codes for details. */ esp_err_t esp_ble_gap_config_scan_rsp_data_raw(uint8_t *raw_data, uint32_t raw_data_len); #endif // #if (BLE_42_FEATURE_SUPPORT == TRUE) +//@} /** - * @brief This function is called to read the RSSI of remote device. - * The address of link policy results are returned in the gap callback function with - * ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT event. + * @brief Request to read the Received Signal Strength Indication (RSSI) of a remote Bluetooth device. + * The Received Signal Strength Indication is a measurement of the signal strength of the Bluetooth + * signal received from a remote device. This function triggers a request to read the RSSI value for + * the specified remote device address. Once the RSSI reading is complete, the result will be returned + * in the GAP (Generic Access Profile) callback function with the `ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT` event. * - * @param[in] remote_addr : The remote connection device address. + * @param[in] remote_addr: The Bluetooth Device Address (BD_ADDR) of the remote device whose RSSI value is to be read. + * This address uniquely identifies the remote device in the Bluetooth network. * - * @return - * - ESP_OK : success - * - other : failed + * @return - ESP_OK : Success, the RSSI reading request was initiated successfully. + * - Other : Failure, the RSSI reading request could not be initiated. Refer to error codes for details. + * + * @note The RSSI value can provide insight into the quality of the connection with the remote device. + * The function triggers the following event: + * - **ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT**: This event indicates that the RSSI reading request has completed. + * The event provides information about the RSSI value and the result of the operation. */ esp_err_t esp_ble_gap_read_rssi(esp_bd_addr_t remote_addr); + +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_42_FEATURE_SUPPORT == TRUE) /** - * @brief This function is called to add a device info into the duplicate scan exceptional list. - * - * - * @param[in] type: device info type, it is defined in esp_ble_duplicate_exceptional_info_type_t - * when type is MESH_BEACON_TYPE, MESH_PROV_SRV_ADV or MESH_PROXY_SRV_ADV , device_info is invalid. - * @param[in] device_info: the device information. - * @return - * - ESP_OK : success - * - other : failed + * @brief Add a device's information to the duplicate scan exceptional list. + * This function allows the user to add a specific device's information to a list of exceptions + * for duplicate scans. Devices in this list will be treated as exceptions, and their duplicate + * scan results will be handled according to the specified type. + * Note that for certain types (e.g., MESH_BEACON_TYPE, MESH_PROV_SRV_ADV, or MESH_PROXY_SRV_ADV), + * the `device_info` parameter is not used and should be considered invalid. + * + * @param[in] type: The type of device information to add. This is defined in the `esp_ble_duplicate_exceptional_info_type_t` enumeration. + * It determines the category of the device information and how it will be treated in the duplicate scan exceptional list. + * - `MESH_BEACON_TYPE`: Indicates the device is a mesh beacon. + * - `MESH_PROV_SRV_ADV`: Indicates the device is a mesh provisioning service advertiser. + * - `MESH_PROXY_SRV_ADV`: Indicates the device is a mesh proxy service advertiser. + * For these types, `device_info` is considered invalid. + * @param[in] device_info: The information of the device to be added to the exceptional list. + * This parameter is used to specify the device details except for the aforementioned types where it is invalid. + * + * @return - ESP_OK : Success, the device information was added to the duplicate scan exceptional list successfully. + * - Other : Failure, the device information could not be added to the list. Refer to error codes for details. */ esp_err_t esp_ble_gap_add_duplicate_scan_exceptional_device(esp_ble_duplicate_exceptional_info_type_t type, esp_duplicate_info_t device_info); /** - * @brief This function is called to remove a device info from the duplicate scan exceptional list. - * - * - * @param[in] type: device info type, it is defined in esp_ble_duplicate_exceptional_info_type_t - * when type is MESH_BEACON_TYPE, MESH_PROV_SRV_ADV or MESH_PROXY_SRV_ADV , device_info is invalid. - * @param[in] device_info: the device information. - * @return - * - ESP_OK : success - * - other : failed + * @brief Remove a device's information from the duplicate scan exceptional list. + * This function allows the user to remove a specific device's information from the list of exceptions + * for duplicate scans. Devices in this list are treated as exceptions during scanning, and this function + * will remove the specified device's information from that list. + * Note that for certain types (e.g., MESH_BEACON_TYPE, MESH_PROV_SRV_ADV, or MESH_PROXY_SRV_ADV), + * the `device_info` parameter is not used and should be considered invalid. + * + * @param[in] type: The type of device information to remove. This is defined in the `esp_ble_duplicate_exceptional_info_type_t` enumeration. + * It specifies the category of the device information to be removed from the exceptional list. + * - `MESH_BEACON_TYPE`: Indicates the device is a mesh beacon. + * - `MESH_PROV_SRV_ADV`: Indicates the device is a mesh provisioning service advertiser. + * - `MESH_PROXY_SRV_ADV`: Indicates the device is a mesh proxy service advertiser. + * For these types, `device_info` is considered invalid. + * @param[in] device_info: The information of the device to be removed from the exceptional list. + * This parameter specifies the device details to be removed from the list except for the types where it is invalid. + * + * @return - ESP_OK : Success, the device information was removed from the duplicate scan exceptional list successfully. + * - Other : Failure, the device information could not be removed from the list. Refer to error codes for details. */ esp_err_t esp_ble_gap_remove_duplicate_scan_exceptional_device(esp_ble_duplicate_exceptional_info_type_t type, esp_duplicate_info_t device_info); /** - * @brief This function is called to clean the duplicate scan exceptional list. - * This API will delete all device information in the duplicate scan exceptional list. - * + * @brief Clean the duplicate scan exceptional list. + * This function deletes all device information from the duplicate scan exceptional list. + * The exceptional list contains device information that is treated as exceptions during duplicate scanning. + * By calling this function, you clear all entries from this list. * - * @param[in] list_type: duplicate scan exceptional list type, the value can be one or more of esp_duplicate_scan_exceptional_list_type_t. + * @param[in] list_type: The type of duplicate scan exceptional list to clean. This parameter is defined in the + * `esp_duplicate_scan_exceptional_list_type_t` enumeration and can include one or more types: + * - `ESP_DUPLICATE_SCAN_EXCEPTIONAL_LIST_TYPE_BEACON`: For mesh beacon devices. + * - `ESP_DUPLICATE_SCAN_EXCEPTIONAL_LIST_TYPE_PROVISIONING`: For mesh provisioning service advertisers. + * - `ESP_DUPLICATE_SCAN_EXCEPTIONAL_LIST_TYPE_PROXY`: For mesh proxy service advertisers. + * The value can be a combination of these types, allowing you to specify which lists to clear. * - * @return - * - ESP_OK : success - * - other : failed + * @return - ESP_OK : Success, the duplicate scan exceptional list has been cleaned. + * - Other : Failure, the exceptional list could not be cleaned. Refer to error codes for details. */ esp_err_t esp_ble_gap_clean_duplicate_scan_exceptional_list(esp_duplicate_scan_exceptional_list_type_t list_type); -#endif // #if (BLE_42_FEATURE_SUPPORT == TRUE) +#endif// #if (BLE_42_FEATURE_SUPPORT == TRUE) +//@} +//@{ +/** if Security Manager Protocol Feature Support */ #if (SMP_INCLUDED == TRUE) /** -* @brief Set a GAP security parameter value. Overrides the default value. -* -* Secure connection is highly recommended to avoid some major -* vulnerabilities like 'Impersonation in the Pin Pairing Protocol' -* (CVE-2020-26555) and 'Authentication of the LE Legacy Pairing -* Protocol'. -* -* To accept only `secure connection mode`, it is necessary do as following: -* -* 1. Set bit `ESP_LE_AUTH_REQ_SC_ONLY` (`param_type` is -* `ESP_BLE_SM_AUTHEN_REQ_MODE`), bit `ESP_LE_AUTH_BOND` and bit -* `ESP_LE_AUTH_REQ_MITM` is optional as required. -* -* 2. Set to `ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_ENABLE` (`param_type` is -* `ESP_BLE_SM_ONLY_ACCEPT_SPECIFIED_SEC_AUTH`). -* -* @param[in] param_type : the type of the param which to be set -* @param[in] value : the param value -* @param[in] len : the length of the param value -* -* @return - ESP_OK : success -* - other : failed -* -*/ -esp_err_t esp_ble_gap_set_security_param(esp_ble_sm_param_t param_type, - void *value, uint8_t len); + * @brief Set a Generic Access Profile (GAP) security parameter value. Overrides the default value. + * Secure connection is highly recommended to avoid major vulnerabilities such as + * 'Impersonation in the Pin Pairing Protocol' (CVE-2020-26555) and 'Authentication of the Low Energy Legacy Pairing Protocol'. + * To accept only secure connection mode, follow these steps: + * + * 1. Set the bit `ESP_LE_AUTH_REQ_SC_ONLY` (param_type is `ESP_BLE_SM_AUTHEN_REQ_MODE`), + * and optionally set the bits `ESP_LE_AUTH_BOND` and `ESP_LE_AUTH_REQ_MITM` as required. + * + * 2. Set to `ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_ENABLE` (param_type is `ESP_BLE_SM_ONLY_ACCEPT_SPECIFIED_SEC_AUTH`). + * + * @param[in] param_type : The type of the parameter to be set. This is defined in the `esp_ble_sm_param_t` enumeration. + * @param[in] value : Pointer to the parameter value to be set. + * @param[in] len : The length of the parameter value. + * + * @return - ESP_OK : Success, the security parameter was set successfully. + * - Other : Failure, the security parameter could not be set. Refer to error codes for details. + */ +esp_err_t esp_ble_gap_set_security_param(esp_ble_sm_param_t param_type, void *value, uint8_t len); + /** -* @brief Grant security request access. -* -* @param[in] bd_addr : BD address of the peer -* @param[in] accept : accept the security request or not -* -* @return - ESP_OK : success -* - other : failed -* -*/ -esp_err_t esp_ble_gap_security_rsp(esp_bd_addr_t bd_addr, bool accept); + * @brief Grant or deny security request access from a peer Bluetooth device. + * + * This function is used to respond to a security request from a peer device. + * The security request typically involves pairing or encryption setup. + * + * @param[in] bd_addr : Bluetooth Device address of the peer. This is a 6-byte address that uniquely identifies the Bluetooth device. + * @param[in] accept : Set to `true` if thesecurity request, otherwise `false` if deny the security request. + * + * @return - ESP_OK : Success, the security request was responded to successfully. + * - Other : Failure, the security request could not be responded to. Refer to error codes for details. + * + * @note This function may trigger the following event: + * - `ESP_GAP_BLE_AUTH_CMPL_EVT`: Indicates that the authentication process has completed. + */ +esp_err_t esp_ble_gap_security_rsp(esp_bd_addr_t bd_addr, bool accept); + /** -* @brief Set a gap parameter value. Use this function to change -* the default GAP parameter values. -* -* @param[in] bd_addr : the address of the peer device need to encryption -* @param[in] sec_act : This is the security action to indicate -* what kind of BLE security level is required for -* the BLE link if the BLE is supported -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief Set a Generic Access Profile (GAP) security parameter value to enable encryption for a peer device. + * Use this function to change the default GAP security parameter values and initiate encryption. + * + * @param[in] bd_addr : The address of the peer Bluetooth device that needs encryption. This is a 6-byte address + * that uniquely identifies the Bluetooth device. + * @param[in] sec_act : The security action indicating the required Bluetooth Low Energy (BLE) security level for + * the BLE link. The available security actions are defined in `esp_ble_sec_act_t` and can include + * levels such as Just Works, Passkey Entry, Numeric Comparison, and Out of Band (OOB). + * + * @return - ESP_OK : Success, encryption was set successfully. + * - Other : Failure, encryption could not be set. Refer to the error codes for details. + */ esp_err_t esp_ble_set_encryption(esp_bd_addr_t bd_addr, esp_ble_sec_act_t sec_act); /** -* @brief Reply the key value to the peer device in the legacy connection stage. -* -* @param[in] bd_addr : BD address of the peer -* @param[in] accept : passkey entry successful or declined. -* @param[in] passkey : passkey value, must be a 6 digit number, -* can be lead by 0. -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief Reply with the passkey value to the peer device during the legacy pairing process. + * This function is used to respond to a passkey entry request from the peer device. + * + * @param[in] bd_addr : The Bluetooth Device address of the peer. This is a 6-byte address + * that uniquely identifies the Bluetooth device. + * @param[in] accept : Indicates whether the passkey entry was successful or declined. + * Set to `true` if the passkey entry was successful, otherwise `false` if declined. + * @param[in] passkey : The passkey value, which must be a 6-digit number (e.g., 000000 to 999999). + * Leading zeros are allowed. + * + * @return - ESP_OK : Success, the passkey reply was sent successfully. + * - Other : Failure, the passkey reply could not be sent. Refer to the error codes for details. + * + * @note This function may trigger the following event: + * - `ESP_GAP_BLE_AUTH_CMPL_EVT`: Indicates that the authentication process has completed, + * which may include the result of the passkey entry. + */ esp_err_t esp_ble_passkey_reply(esp_bd_addr_t bd_addr, bool accept, uint32_t passkey); /** -* @brief Reply the confirm value to the peer device in the secure connection stage. -* -* @param[in] bd_addr : BD address of the peer device -* @param[in] accept : numbers to compare are the same or different. -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief Reply with the confirmation value to the peer device during the secure connection stage. + * This function is used to respond to a numeric comparison request from the peer device. + * + * @param[in] bd_addr : The Bluetooth Device address of the peer device. This is a 6-byte address + * that uniquely identifies the Bluetooth device. + * @param[in] accept : Indicates whether the numbers to compare are the same or different. + * Set to `true` if the numbers are the same, otherwise `false` if they are different. + * + * @return - ESP_OK : Success, the confirmation reply was sent successfully. + * - Other : Failure, the confirmation reply could not be sent. Refer to the error codes for details. + */ esp_err_t esp_ble_confirm_reply(esp_bd_addr_t bd_addr, bool accept); /** -* @brief Removes a device from the security database list of -* peer device. It manages unpairing event while connected. -* -* @param[in] bd_addr : BD address of the peer device -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief Removes a device from the security database list of peer devices. + * This function manages the unpairing event while connected. + * It effectively unbonds the local device from the peer device, removing + * any stored security information such as keys and pairing status. + * + * @param[in] bd_addr : The Bluetooth Device address of the peer device. This is a 6-byte address + * that uniquely identifies the Bluetooth device. + * + * @return - ESP_OK : Success, the device was removed from the security database successfully. + * - Other : Failure, the device could not be removed. Refer to the error codes for details. + * + * @note This function may trigger the following event: + * - `ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT`: Indicates that the removal of the bonded device has been processed. + */ esp_err_t esp_ble_remove_bond_device(esp_bd_addr_t bd_addr); /** -* @brief Get the device number from the security database list of peer device. -* It will return the device bonded number immediately. -* -* @return - >= 0 : bonded devices number. -* - ESP_FAIL : failed -* -*/ + * @brief Get the number of devices from the security database list of peer devices. + * This function returns the number of bonded devices immediately. + * It queries the local security database and counts how many devices have been bonded with. + * + * @return - >= 0 : The number of bonded devices. + * - ESP_FAIL : Failure to retrieve the number of bonded devices. + */ int esp_ble_get_bond_device_num(void); /** -* @brief Get the device from the security database list of peer device. -* It will return the device bonded information immediately. -* @param[inout] dev_num: Indicate the dev_list array(buffer) size as input. -* If dev_num is large enough, it means the actual number as output. -* Suggest that dev_num value equal to esp_ble_get_bond_device_num(). -* -* @param[out] dev_list: an array(buffer) of `esp_ble_bond_dev_t` type. Use for storing the bonded devices address. -* The dev_list should be allocated by who call this API. -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief Get the list of bonded devices from the security database of peer devices. + * This function returns the bonded devices' information immediately. + * + * @param[inout] dev_num: Indicates the size of the `dev_list` array (buffer) as input. + * If `dev_num` is large enough, it returns the actual number of bonded devices as output. + * It is recommended that the `dev_num` value is equal to the value returned by `esp_ble_get_bond_device_num()`. + * + * @param[out] dev_list: An array (buffer) of `esp_ble_bond_dev_t` type used to store the bonded devices' addresses. + * The `dev_list` should be allocated by the caller of this API. + * + * @return - ESP_OK : Success + * - Other : Failure + */ esp_err_t esp_ble_get_bond_device_list(int *dev_num, esp_ble_bond_dev_t *dev_list); /** -* @brief This function is called to provide the OOB data for -* SMP in response to ESP_GAP_BLE_OOB_REQ_EVT +* @brief This function is called to provide the Out of Band (OOB) data for +* Security Manager Protocol (SMP) in response to `ESP_GAP_BLE_OOB_REQ_EVT` event. +* OOB data is used during pairing to ensure secure transmission of the Temporary Key (TK). * -* @param[in] bd_addr: BD address of the peer device. -* @param[in] TK: Temporary Key value, the TK value shall be a 128-bit random number -* @param[in] len: length of temporary key, should always be 128-bit +* @param[in] bd_addr: Bluetooth Device Address (BD_ADDR) of the peer device. +* @param[in] TK: Temporary Key (TK) value, which shall be a 128-bit random number. +* @param[in] len: Length of the Temporary Key. It should always be 128 bits (16 bytes). * -* @return - ESP_OK : success -* - other : failed +* @return - ESP_OK : Success +* - Other : Failure * +* @note This function is called in response to the `ESP_GAP_BLE_OOB_REQ_EVT` event. +* The `ESP_GAP_BLE_OOB_REQ_EVT` event indicates that the peer device is requesting OOB data. */ esp_err_t esp_ble_oob_req_reply(esp_bd_addr_t bd_addr, uint8_t *TK, uint8_t len); /** -* @brief This function is called to provide the OOB data for -* SMP in response to ESP_GAP_BLE_SC_OOB_REQ_EVT +* @brief This function is called to provide the Out of Band (OOB) data for +* Security Manager Protocol (SMP) in response to the `ESP_GAP_BLE_SC_OOB_REQ_EVT` event. +* OOB data is used during Secure Connections (SC) pairing to ensure secure transmission +* of the Confirmation value and the Random value. * -* @param[in] bd_addr: BD address of the peer device. -* @param[in] p_c: Confirmation value, it shall be a 128-bit random number -* @param[in] p_r: Randomizer value, it should be a 128-bit random number +* @param[in] bd_addr: Bluetooth Device Address (BD_ADDR) of the peer device. +* @param[in] p_c: Confirmation value, which shall be a 128-bit (16 bytes) random number. +* @param[in] p_r: Random value, which should be a 128-bit (16 bytes) random number. * -* @return - ESP_OK : success -* - other : failed +* @return - ESP_OK : Success +* - Other : Failure * +* @note This function is called in response to the `ESP_GAP_BLE_SC_OOB_REQ_EVT` event. +* The `ESP_GAP_BLE_SC_OOB_REQ_EVT` event indicates that the peer device is requesting +* Secure Connections OOB data. */ esp_err_t esp_ble_sc_oob_req_reply(esp_bd_addr_t bd_addr, uint8_t p_c[16], uint8_t p_r[16]); /** -* @brief This function is called to create the OOB data for -* SMP when secure connection -* -* @return - ESP_OK : success -* - other : failed +* @brief This function is called to create the Out of Band (OOB) data for +* Security Manager Protocol (SMP) during Secure Connections (SC). +* The OOB data generated by this function is used for pairing with devices +* using Secure Connections, providing an additional layer of security +* by allowing the exchange of cryptographic information out of the Bluetooth +* communication channel. * +* @return - ESP_OK : Success +* - Other : Failure */ esp_err_t esp_ble_create_sc_oob_data(void); -#endif /* #if (SMP_INCLUDED == TRUE) */ + +#endif// #if (SMP_INCLUDED == TRUE) +//@} /** -* @brief This function is to disconnect the physical connection of the peer device -* gattc may have multiple virtual GATT server connections when multiple app_id registered. -* esp_ble_gattc_close (esp_gatt_if_t gattc_if, uint16_t conn_id) only close one virtual GATT server connection. -* if there exist other virtual GATT server connections, it does not disconnect the physical connection. -* esp_ble_gap_disconnect(esp_bd_addr_t remote_device) disconnect the physical connection directly. -* -* +* @brief This function is used to disconnect the physical Bluetooth connection +* with a peer device. This function directly terminates the Bluetooth link +* between the local device and the specified peer device address. +* Unlike `esp_ble_gattc_close` which only closes one virtual GATT server +* connection (if multiple connections are established), this function +* ensures that the entire physical connection is disconnected. * -* @param[in] remote_device : BD address of the peer device +* @param[in] remote_device: The Bluetooth Device Address (BD_ADDR) of the peer device +* to be disconnected. This is a 6-byte address that uniquely identifies the +* peer device in Bluetooth communication. * -* @return - ESP_OK : success -* - other : failed +* @return - ESP_OK : Success, the physical connection was successfully disconnected. +* - Other : Failure, the disconnection attempt failed. Refer to the error codes +* for details on the failure. * +* @note This function is used to terminate the connection at the physical level, +* which means all virtual GATT server connections associated with the peer +* device will also be terminated. If there are multiple virtual GATT server +* connections, `esp_ble_gattc_close` can be used to close a specific GATT +* connection, but it does not affect the physical connection. */ esp_err_t esp_ble_gap_disconnect(esp_bd_addr_t remote_device); /** -* @brief This function is called to read the connection -* parameters information of the device +* @brief This function retrieves the current connection parameters of a Bluetooth device. +* It provides information about the connection parameters for a given peer device. +* Connection parameters include interval, latency, and supervision timeout, +* which are crucial for managing and optimizing Bluetooth connections. * -* @param[in] bd_addr: BD address of the peer device. -* @param[out] conn_params: the connection parameters information -* -* @return - ESP_OK : success -* - other : failed +* @param[in] bd_addr: The Bluetooth Device Address (BD_ADDR) of the peer device. +* This is a 6-byte address that uniquely identifies the peer device in Bluetooth communication. +* @param[out] conn_params: Pointer to an `esp_gap_conn_params_t` structure where the connection +* parameters information will be stored. The structure will be filled with the current +* connection parameters of the specified peer device. * +* @return - ESP_OK : Success, the connection parameters were successfully retrieved. +* - Other : Failure, the attempt to retrieve connection parameters failed. +* Refer to the error codes for details. */ esp_err_t esp_ble_get_current_conn_params(esp_bd_addr_t bd_addr, esp_gap_conn_params_t *conn_params); /** -* @brief BLE set channels +* @brief This function is used to set the channels for Bluetooth Low Energy (BLE) communication. +* The function allows configuring the link layer channel indices to indicate their status. +* Channels can be marked as "bad", "unknown", or reserved. * -* @param[in] channels : The n th such field (in the range 0 to 36) contains the value for the link layer channel index n. -* 0 means channel n is bad. -* 1 means channel n is unknown. -* The most significant bits are reserved and shall be set to 0. -* At least one channel shall be marked as unknown. +* @param[in] channels: A bit field where each bit represents the status of a BLE channel. +* - The n-th bit (in the range 0 to 36) represents the status of the link layer channel index n. +* - `0` means channel n is marked as "bad". +* - `1` means channel n is marked as "unknown". +* - The most significant bits are reserved and should be set to `0`. +* - At least one channel must be marked as "unknown". * -* @return - ESP_OK : success -* - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled -* - other : failed +* @return - ESP_OK : Success, channels were set successfully. +* - ESP_ERR_INVALID_STATE : Failure, Bluetooth stack is not yet enabled. +* - Other : Failure, the attempt to set channels failed. Refer to the error codes for details. * +* @note The function will not trigger any specific events. It directly configures the channels +* based on the provided `channels` bit field. +* It is essential that at least one channel is marked as "unknown" to ensure proper operation. +* Ensure that the Bluetooth stack is enabled before calling this function to avoid +* `ESP_ERR_INVALID_STATE` errors. */ esp_err_t esp_gap_ble_set_channels(esp_gap_ble_channels channels); /** -* @brief This function is called to authorized a link after Authentication(MITM protection) -* -* @param[in] bd_addr: BD address of the peer device. -* @param[out] authorize: Authorized the link or not. -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is called to authorize a link after authentication, providing Man-in-the-Middle (MITM) protection. + * Authorization determines whether a previously authenticated link should be allowed or not. + * + * @param[in] bd_addr: Bluetooth Device address of the peer device. + * @param[in] authorize: `true` if authorize the link, allowing it to proceed; otherwise `false` to deny authorization, + * preventing further communication with the peer device. + * + * @return - ESP_OK : Success, the authorization decision was processed successfully. + * - Other : Failure, the authorization decision could not be processed. Refer to the error codes for details. + */ esp_err_t esp_gap_ble_set_authorization(esp_bd_addr_t bd_addr, bool authorize); +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ #if (BLE_50_FEATURE_SUPPORT == TRUE) /** -* @brief This function is used to read the current transmitter PHY -* and receiver PHY on the connection identified by remote address. -* -* @param[in] bd_addr : BD address of the peer device -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to read the current Physical Layer (PHY) parameters + * for the transmitter and receiver on the connection identified by the Bluetooth + * Device Address (BD_ADDR) of the peer device. + * + * The Physical Layer (PHY) defines the radio frequency and modulation scheme used + * for communication. This function retrieves the PHY information that is currently + * being used for the connection, which includes details about the transmitter and receiver PHY. + * + * @param[in] bd_addr: The Bluetooth Device Address (BD_ADDR) of the peer device. This address + * identifies the connection for which PHY parameters are to be read. + * + * @return - ESP_OK : Success, the PHY parameters were read successfully. + * - Other : Failure, the PHY parameters could not be read. Refer to the error codes for details. + */ esp_err_t esp_ble_gap_read_phy(esp_bd_addr_t bd_addr); /** -* @brief This function is used to allows the Host to specify its preferred values -* for the transmitter PHY and receiver PHY to be used for all subsequent connections -* over the LE transport. -* -* @param[in] tx_phy_mask : indicates the transmitter PHYs that the Host prefers the Controller to use -* @param[in] rx_phy_mask : indicates the receiver PHYs that the Host prefers the Controller to use -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function allows the Host to specify its preferred values for the Physical Layer (PHY) + * parameters to be used for both transmitting and receiving data in all subsequent Bluetooth Low Energy (BLE) + * connections over the low energy transport. + * + * The Physical Layer (PHY) determines the radio frequency and modulation scheme used for Bluetooth communication. + * This function lets the Host indicate which PHY parameters it prefers for both transmitting and receiving data + * during BLE connections. The specified preferences will be considered by the Controller when establishing + * new BLE connections. + * + * @param[in] tx_phy_mask: Indicates the preferred Physical Layers for transmitting data. The mask is a bitfield + * where each bit represents a different PHY option. For example, `ESP_BLE_PHY_LE_1M` for 1 Mbps PHY, + * and `ESP_BLE_PHY_LE_2M` for 2 Mbps PHY. + * @param[in] rx_phy_mask: Indicates the preferred Physical Layers for receiving data. The mask is a bitfield + * similar to `tx_phy_mask` and represents the preferred PHY options for reception. + * + * @return - ESP_OK : Success, the preferred PHY parameters were set successfully. + * - Other : Failure, the preferred PHY parameters could not be set. Refer to the error codes for details. + */ esp_err_t esp_ble_gap_set_preferred_default_phy(esp_ble_gap_phy_mask_t tx_phy_mask, esp_ble_gap_phy_mask_t rx_phy_mask); + /** -* @brief This function is used to set the PHY preferences for the connection identified by the remote address. -* The Controller might not be able to make the change (e.g. because the peer does not support the requested PHY) -* or may decide that the current PHY is preferable. -* -* @param[in] bd_addr : remote address -* @param[in] all_phys_mask : a bit field that allows the Host to specify -* @param[in] tx_phy_mask : a bit field that indicates the transmitter PHYs that the Host prefers the Controller to use -* @param[in] rx_phy_mask : a bit field that indicates the receiver PHYs that the Host prefers the Controller to use -* @param[in] phy_options : a bit field that allows the Host to specify options for PHYs -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function sets the Physical Layer (PHY) preferences for a specific BLE connection identified by the remote address. + * The Controller will attempt to apply these preferences, but it may not always succeed if: + * - The peer device does not support the requested PHY options. + * - The Controller determines that the current PHY settings are preferable. + * + * Physical Layer (PHY) settings affect the radio frequency and modulation scheme used for Bluetooth communication. + * This function allows the Host to specify its preferred PHY parameters for transmitting and receiving data + * for a particular connection. The PHY options may include data rates, modulation schemes, and other related settings. + * + * @param[in] bd_addr: The Bluetooth Device Address of the remote peer device. This identifies the connection for which + * the PHY preferences are being set. + * @param[in] all_phys_mask: A bit field specifying which Physical Layers are available for preference. This allows + * the Host to specify which PHY options it wants the Controller to consider for both transmitting and receiving. + * @param[in] tx_phy_mask: A bit field indicating the preferred Physical Layers for transmitting data. This mask specifies + * which PHY options the Host prefers the Controller to use for sending data. + * @param[in] rx_phy_mask: A bit field indicating the preferred Physical Layers for receiving data. This mask specifies + * which PHY options the Host prefers the Controller to use for receiving data. + * @param[in] phy_options: A bit field allowing the Host to specify additional options for the Physical Layers, such as + * preference for low latency or higher throughput. + * + * @return - ESP_OK : Success, the PHY preferences were set successfully for the specified connection. + * - Other : Failure, the PHY preferences could not be set. Refer to the error codes for details. + */ esp_err_t esp_ble_gap_set_preferred_phy(esp_bd_addr_t bd_addr, esp_ble_gap_all_phys_t all_phys_mask, esp_ble_gap_phy_mask_t tx_phy_mask, @@ -2244,460 +3274,728 @@ esp_err_t esp_ble_gap_set_preferred_phy(esp_bd_addr_t bd_addr, esp_ble_gap_prefer_phy_options_t phy_options); /** -* @brief This function is used by the Host to set the random device address specified by the Random_Address parameter. -* -* @param[in] instance : Used to identify an advertising set -* @param[in] rand_addr : Random Device Address -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function sets the random device address for a specific advertising instance. + * The random address will be used during advertising operations for the specified instance. + * + * Random addresses enhance privacy by periodically changing the address, helping to prevent + * device tracking and improving anonymity. + * + * @param[in] instance : Identifies the advertising set for which the random address is being set. + * Each advertising set is identified by a unique instance number, allowing multiple sets to + * be managed independently. + * @param[in] rand_addr : The random device address to be set. This should be a valid 6-byte Bluetooth + * Device Address (BD_ADDR) in hexadecimal format. + * + * @return - ESP_OK : Success. The random address has been successfully set for the specified instance. + * - Other : Failure. An error occurred while setting the random address. + * + * @note Ensure that the Bluetooth stack is initialized and the instance identifier is valid before + * calling this function. If the random address format is incorrect or if the instance number + * is out of range, the function may return an error. + * + * After setting the random address, observe the following events: + * - `ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT`: May be related, signaling that the advertising data set is complete. + */ esp_err_t esp_ble_gap_ext_adv_set_rand_addr(uint8_t instance, esp_bd_addr_t rand_addr); /** -* @brief This function is used by the Host to set the advertising parameters. -* -* @param[in] instance : identifies the advertising set whose parameters are being configured. -* @param[in] params : advertising parameters -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used by the Host to configure the advertising parameters for a specific + * advertising instance. The parameters define how the advertising set will behave, including + * settings such as the advertising interval, type, and other configurations. + * + * Proper configuration of these parameters is essential for effective advertising and optimal + * performance of Bluetooth Low Energy (BLE) operations. + * + * @param[in] instance : Identifies the advertising set whose parameters are being configured. + * Each advertising set is identified by a unique instance number, allowing multiple sets to + * be managed independently. + * @param[in] params : Pointer to a structure containing the advertising parameters. The structure + * should be of type `esp_ble_gap_ext_adv_params_t`, which includes fields such as the advertising + * interval, advertising type, channel map, and other related settings. + * + * @return - ESP_OK : Success. The advertising parameters have been successfully set for the specified instance. + * - Other : Failure. An error occurred while setting the advertising parameters. + */ esp_err_t esp_ble_gap_ext_adv_set_params(uint8_t instance, const esp_ble_gap_ext_adv_params_t *params); /** -* @brief This function is used to set the data used in advertising PDUs that have a data field -* -* @param[in] instance : identifies the advertising set whose data are being configured -* @param[in] length : data length -* @param[in] data : data information -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used by the Host to configure the raw advertising data for a specific + * advertising instance. The data field in the advertising Protocol Data Units (PDUs) can be + * set with this function, allowing customization of the information broadcasted during + * advertising operations. + * + * The raw advertising data should be provided in the format specified by the Bluetooth + * specification, with the length and content properly defined to match the requirements of + * the intended advertising configuration. + * + * @param[in] instance : Identifies the advertising set whose data is being configured. This allows + * management of multiple advertising sets by specifying their unique instance numbers. + * @param[in] length : The length of the advertising data in bytes. It should be within the allowed + * range and match the length of the provided `data`. + * @param[in] data : Pointer to the raw advertising data. This data is used in the advertising PDUs + * and should be formatted according to the Bluetooth specification. + * + * @return - ESP_OK : Success. The raw advertising data has been successfully configured for the specified instance. + * - Other : Failure. An error occurred while setting the advertising data. + * + * @note Ensure that the `length` parameter matches the size of the `data` array. The Bluetooth stack + * must be initialized before calling this function, and the `instance` should refer to a valid + * advertising set. If the data length exceeds the allowed limit or the data format is incorrect, + * the function may return an error. + * + * After setting the advertising data, observe the following event: + * - `ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT`: Indicates that the advertising data has been successfully set. + */ esp_err_t esp_ble_gap_config_ext_adv_data_raw(uint8_t instance, uint16_t length, const uint8_t *data); /** -* @brief This function is used to provide scan response data used in scanning response PDUs -* -* @param[in] instance : identifies the advertising set whose response data are being configured. -* @param[in] length : responsedata length -* @param[in] scan_rsp_data : response data information -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to configure the raw scan response data for a specific advertising + * instance. The scan response data is used in scanning response Protocol Data Units (PDUs) + * to provide additional information to devices that are scanning for available advertising + * devices. + * + * By setting the scan response data, you can include extra details in the response to scanning + * requests, which may help in distinguishing your device or providing more information to + * potential connection requests. + * + * @param[in] instance : Identifies the advertising set whose scan response data is being configured. + * This allows management of multiple advertising sets by specifying their unique instance numbers. + * @param[in] length : The length of the scan response data in bytes. It should match the size of the + * provided `scan_rsp_data`. + * @param[in] scan_rsp_data : Pointer to the raw scan response data. This data is used in the scanning + * response PDUs and should be formatted according to the Bluetooth specification. + * + * @return - ESP_OK : Success. The scan response data has been successfully configured for the specified instance. + * - Other : Failure. An error occurred while setting the scan response data. + * + * @note Ensure that the `length` parameter corresponds to the size of the `scan_rsp_data` array. The + * Bluetooth stack must be initialized before calling this function, and the `instance` should + * refer to a valid advertising set. If the data length exceeds the allowed limit or the data + * format is incorrect, the function may return an error. + * + * After setting the scan response data, observe the following event: + * - `ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT`: Indicates that the scan response data has been successfully set. + */ esp_err_t esp_ble_gap_config_ext_scan_rsp_data_raw(uint8_t instance, uint16_t length, const uint8_t *scan_rsp_data); + /** -* @brief This function is used to request the Controller to enable one or more -* advertising sets using the advertising sets identified by the instance parameter. -* -* @param[in] num_adv : Number of advertising sets to enable or disable -* @param[in] ext_adv : adv parameters -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function requests the Controller to enable one or more advertising sets, which are identified + * by the `instance` parameter. It allows the Host to start advertising operations with the specified + * parameters for each advertising set. + * + * The function can be used to manage multiple advertising sets simultaneously, allowing for flexible + * and dynamic advertising strategies. It is useful in scenarios where different advertising sets may + * be required for various purposes, such as different advertising intervals, data types, or + * channels. + * + * @param[in] num_adv : The number of advertising sets to enable. This value specifies how many of the advertising + * sets identified in the `ext_adv` array should be started. + * @param[in] ext_adv : Pointer to an array of `esp_ble_gap_ext_adv_t` structures, each specifying the parameters + * for an advertising set. The array should have a length equal to `num_adv`, and each element in the + * array provides the configuration for one advertising set. + * + * @return - ESP_OK : Success. The advertising sets have been successfully started with the specified parameters. + * - Other : Failure. An error occurred while starting the advertising sets. + * + * @note Ensure that the `num_adv` parameter does not exceed the maximum number of supported advertising sets. + * The `ext_adv` array should be properly initialized and the Bluetooth stack must be enabled before + * calling this function. Each `esp_ble_gap_ext_adv_t` structure should be correctly configured with the + * desired advertising parameters. + * + * After starting the advertising sets, relevant events to monitor include: + * - `ESP_GAP_BLE_ADV_START_COMPLETE_EVT`: Indicates that the advertising has been successfully started for + * the specified advertising sets. + */ esp_err_t esp_ble_gap_ext_adv_start(uint8_t num_adv, const esp_ble_gap_ext_adv_t *ext_adv); /** -* @brief This function is used to request the Controller to disable one or more -* advertising sets using the advertising sets identified by the instance parameter. -* -* @param[in] num_adv : Number of advertising sets to enable or disable -* @param[in] ext_adv_inst : ext adv instance -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function requests the Controller to disable one or more advertising sets. The advertising sets + * are identified by the `ext_adv_inst` parameter, which provides the instance identifiers of the + * advertising sets to be stopped. + * + * The function allows the Host to stop advertising operations for specific advertising sets that + * were previously enabled. This is useful for managing and controlling advertising activity, such as + * when transitioning between different advertising strategies or when stopping advertising in response + * to specific conditions. + * + * @param[in] num_adv : The number of advertising sets to disable. This value specifies how many of the + * advertising instances identified in the `ext_adv_inst` array should be stopped. + * @param[in] ext_adv_inst : Pointer to an array of `uint8_t` values representing the instance identifiers of + * the advertising sets to be stopped. The array should have a length equal to `num_adv`. + * + * @return - ESP_OK : Success. The advertising sets have been successfully stopped as specified. + * - Other : Failure. An error occurred while stopping the advertising sets. + * + * @note Ensure that the `num_adv` parameter does not exceed the number of active advertising sets. The + * `ext_adv_inst` array should be properly initialized with valid instance identifiers, and the Bluetooth + * stack must be enabled before calling this function. + * + * After stopping the advertising sets, relevant events to monitor include: + * - `ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT`: Indicates that the advertising has been successfully stopped + * for the specified advertising sets. + */ esp_err_t esp_ble_gap_ext_adv_stop(uint8_t num_adv, const uint8_t *ext_adv_inst); /** -* @brief This function is used to remove an advertising set from the Controller. -* -* @param[in] instance : Used to identify an advertising set -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to remove an advertising set from the Controller. It effectively + * deletes the specified advertising set, freeing up resources associated with it and + * stopping any ongoing advertising operations related to that set. + * + * This function is useful when you want to clean up advertising sets that are no longer needed + * or to manage advertising resources dynamically. Removing an advertising set will stop its + * advertising activity and remove its configuration from the Controller. + * + * @param[in] instance : The identifier of the advertising set to be removed. This instance should + * correspond to a valid advertising set that was previously created and may be active. + * + * @return - ESP_OK : Success. The advertising set has been successfully removed. + * - Other : Failure. An error occurred while removing the advertising set. + * + * @note Before calling this function, ensure that the advertising set is no longer in use or is + * stopped using `esp_ble_gap_ext_adv_stop`. The Bluetooth stack must be properly initialized + * and the instance identifier should be valid. Removing an advertising set may affect any + * ongoing advertising operations or configurations. + * + * Relevant events to monitor after removing an advertising set include: + * - `ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT`: Indicates that the specified advertising set has + * been successfully removed from the Controller. + */ esp_err_t esp_ble_gap_ext_adv_set_remove(uint8_t instance); /** -* @brief This function is used to remove all existing advertising sets from the Controller. -* -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to remove all existing advertising sets from the Controller. It clears + * all advertising configurations and stops any ongoing advertising activities related to those + * sets, freeing up resources associated with them. + * + * This function is useful for resetting the advertising state or cleaning up all advertising + * configurations at once. After calling this function, no advertising sets will be active, and + * you will need to reconfigure and restart any advertising sets if needed. + * + * @return - ESP_OK : Success. All advertising sets have been successfully removed and resources freed. + * - Other : Failure. An error occurred while removing the advertising sets. + * + * @note Before calling this function, ensure that no critical advertising operations are ongoing + * or that they can be safely stopped. The Bluetooth stack must be properly initialized. + * Removing all advertising sets will affect any active advertising activities and may require + * reconfiguration of advertising parameters if needed. + * + * Relevant events to monitor after clearing advertising sets include: + * - `ESP_GAP_BLE_ADV_CLEAR_COMPLETE_EVT`: Indicates that all advertising sets have been + * successfully cleared from the Controller. + */ esp_err_t esp_ble_gap_ext_adv_set_clear(void); /** -* @brief This function is used by the Host to set the parameters for periodic advertising. -* -* @param[in] instance : identifies the advertising set whose periodic advertising parameters are being configured. -* @param[in] params : periodic adv parameters -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used by the Host to set the parameters for periodic advertising. + * Periodic advertising allows the device to periodically transmit data at a fixed interval, + * which can be used for broadcasting data in a continuous manner to be received by scanners + * or other devices. This function configures the parameters that control the periodic + * advertising behavior for a specified advertising instance. + * + * @param[in] instance : The identifier for the advertising set whose periodic advertising parameters + * are being configured. This allows distinguishing between multiple advertising sets + * that may be active simultaneously. + * @param[in] params : A pointer to a structure of type `esp_ble_gap_periodic_adv_params_t` that + * contains the periodic advertising parameters to be set. This structure includes settings + * such as the periodic advertising interval and other relevant configurations. + * + * @return - ESP_OK : Success. The periodic advertising parameters have been successfully set for the + * specified advertising instance. + * - Other : Failure. An error occurred while setting the periodic advertising parameters. + * Possible error codes may indicate issues such as invalid parameters, uninitialized state, + * or other failures. + * + * @note Ensure that the Bluetooth stack is properly initialized before calling this function. The + * specified `instance` must be valid and correctly correspond to an existing advertising set. + * Misconfiguration or invalid parameters may lead to failure. After setting the parameters, + * you may need to start periodic advertising using the appropriate function to activate the + * periodic advertising with the configured settings. + */ esp_err_t esp_ble_gap_periodic_adv_set_params(uint8_t instance, const esp_ble_gap_periodic_adv_params_t *params); #if (CONFIG_BT_BLE_FEAT_PERIODIC_ADV_ENH) /** -* @brief This function is used to set the data used in periodic advertising PDUs. -* -* @param[in] instance : identifies the advertising set whose periodic advertising parameters are being configured. -* @param[in] length : the length of periodic data -* @param[in] data : periodic data information -* @param[in] only_update_did : If true, only the Advertising DID of the periodic advertising will be updated, and the length and data parameters will be ignored. -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to set the data used in periodic advertising Protocol Data Units (PDUs). + * Periodic advertising allows a device to transmit periodic data at regular intervals, + * and this function configures the data that will be used for periodic advertising for a + * specified advertising instance. + * + * @param[in] instance : The identifier for the advertising set whose periodic advertising data + * is being configured. This allows distinguishing between multiple advertising sets + * that may be active simultaneously. + * @param[in] length : The length of the periodic advertising data. This specifies how many bytes + * of data are being provided in the `data` parameter. The length must be within the limits + * specified by the Bluetooth specification and the device's capabilities. + * @param[in] data : A pointer to the periodic advertising data. This is the data that will be + * included in the periodic advertising PDUs. The data should be formatted according to the + * Bluetooth specification and the application's requirements. + * @param[in] only_update_did : A boolean flag indicating whether to update only the Advertising DID (Device + * Identifier) of the periodic advertising. If set to `true`, only the Advertising DID will be updated, + * and the `length` and `data` parameters will be ignored. If set to `false`, the provided `length` + * and `data` parameters will be used to configure the periodic advertising data. + * + * @return - ESP_OK : Success. The periodic advertising data has been successfully set for the + * specified advertising instance. + * - Other : Failure. An error occurred while setting the periodic advertising data. + * Possible error codes may indicate issues such as invalid parameters, uninitialized state, + * or other failures. + * + * @note Ensure that the Bluetooth stack is properly initialized before calling this function. + * The specified `instance` must be valid and correctly correspond to an existing advertising + * set. If `only_update_did` is set to `true`, the `length` and `data` parameters will be ignored, + * and only the Advertising DID will be updated. Ensure that the periodic advertising data complies + * with the Bluetooth specifications and the device??s capabilities. + * + * Relevant events to monitor include: + * - `ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT`: Indicates that the periodic advertising + * data has been successfully set for the specified advertising instance. + */ esp_err_t esp_ble_gap_config_periodic_adv_data_raw(uint8_t instance, uint16_t length, - const uint8_t *data, bool only_update_did); + const uint8_t *data, bool only_update_did); + #else /** -* @brief This function is used to set the data used in periodic advertising PDUs. -* -* @param[in] instance : identifies the advertising set whose periodic advertising parameters are being configured. -* @param[in] length : the length of periodic data -* @param[in] data : periodic data information -* -* @return - ESP_OK : success -* - other : failed -* -*/ -esp_err_t esp_ble_gap_config_periodic_adv_data_raw(uint8_t instance, uint16_t length, - const uint8_t *data); + * @brief This function is used to set the data used in periodic advertising Protocol Data Units (PDUs). + * Periodic advertising allows devices to transmit data at regular intervals, and this function + * configures the data that will be used for periodic advertising for a specified advertising instance. + * + * @param[in] instance : Identifies the advertising set whose periodic advertising data is being configured. + * This parameter distinguishes between multiple advertising sets that may be active simultaneously. + * @param[in] length : The length of the periodic advertising data. This specifies the number of bytes + * in the `data` parameter. Ensure that the length does not exceed the maximum allowed by the Bluetooth specification. + * @param[in] data : A pointer to the periodic advertising data. This data will be included in the periodic advertising PDUs. + * The format and content of this data should adhere to the Bluetooth specification and application requirements. + * + * @return - ESP_OK : Success. The periodic advertising data has been successfully set for the specified advertising instance. + * - Other : Failure. An error occurred while setting the periodic advertising data. + * Possible error codes may indicate issues such as invalid parameters or an uninitialized state. + * + * @note Ensure that the Bluetooth stack is properly initialized before calling this function. The `instance` must + * be valid and correspond to an existing advertising set. Verify that the `length` and `data` parameters are + * correctly specified and within allowed limits. Proper handling of errors will help in managing unsuccessful + * attempts to set the periodic advertising data. + * + * Relevant events to monitor include: + * - `ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT`: Indicates that the periodic advertising data has been + * successfully set for the specified advertising instance. + */ +esp_err_t esp_ble_gap_config_periodic_adv_data_raw(uint8_t instance, uint16_t length, const uint8_t *data); #endif #if (CONFIG_BT_BLE_FEAT_PERIODIC_ADV_ENH) /** -* @brief This function is used to request the Controller to enable the periodic advertising for the advertising set specified -* -* @param[in] instance : Used to identify an advertising set -* @param[in] include_adi : If true, the ADI (Advertising Data Info) field will be included in AUX_SYNC_IND PDUs -* -* @return - ESP_OK : success -* - other : failed -* -*/ -esp_err_t esp_ble_gap_periodic_adv_start(uint8_t instance,bool include_adi); + * @brief This function is used to request the Controller to enable periodic advertising for the specified advertising set. + * Periodic advertising allows a device to periodically send advertising packets, which can be useful for + * applications that need to broadcast information at regular intervals. + * + * @param[in] instance : Identifies the advertising set for which periodic advertising is to be enabled. + * This parameter is used to distinguish between multiple advertising sets that may be active simultaneously. + * @param[in] include_adi: If true, the ADI (Advertising Data Info) field will be included in AUX_SYNC_IND PDUs. + * The ADI is used to provide additional information about the advertising data. When included, it can help + * with synchronization and identification of periodic advertising packets. + * + * @return - ESP_OK : Success. Periodic advertising has been successfully enabled for the specified advertising instance. + * - Other : Failure. An error occurred while enabling periodic advertising. Possible error codes may indicate + * issues such as invalid parameters or an uninitialized state. + * + * @note Ensure that the Bluetooth stack is properly initialized before calling this function. The `instance` must + * be valid and correspond to an existing advertising set. Verify that the `include_adi` parameter is set according + * to your application requirements. Proper error handling will help manage unsuccessful attempts to start periodic + * advertising. + * + * Relevant events to monitor include: + * - `ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT`: Indicates that the request to start periodic advertising has + * been processed. This event will provide details about the success or failure of the operation. + */ +esp_err_t esp_ble_gap_periodic_adv_start(uint8_t instance, bool include_adi); + #else /** -* @brief This function is used to request the Controller to enable the periodic advertising for the advertising set specified -* -* @param[in] instance : Used to identify an advertising set -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to request the Controller to enable periodic advertising for the specified advertising set. + * Periodic advertising allows a device to periodically send advertising packets, which can be useful for + * applications that need to broadcast information at regular intervals. + * + * @param[in] instance : Identifies the advertising set for which periodic advertising is to be enabled. + * This parameter is used to distinguish between multiple advertising sets that may be active simultaneously. + * + * @return - ESP_OK : Success. Periodic advertising has been successfully enabled for the specified advertising instance. + * - Other : Failure. An error occurred while enabling periodic advertising. Possible error codes may indicate + * issues such as invalid parameters or an uninitialized state. + * + * @note Ensure that the Bluetooth stack is properly initialized before calling this function. The `instance` must + * be valid and correspond to an existing advertising set. Proper error handling will help manage unsuccessful attempts + * to start periodic advertising. + * + * Relevant events to monitor include: + * - `ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT`: Indicates that the request to start periodic advertising has + * been processed. This event will provide details about the success or failure of the operation. + */ esp_err_t esp_ble_gap_periodic_adv_start(uint8_t instance); #endif /** -* @brief This function is used to request the Controller to disable the periodic advertising for the advertising set specified -* -* @param[in] instance : Used to identify an advertising set -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to request the Controller to disable periodic advertising for the specified advertising set. + * Disabling periodic advertising stops the periodic transmission of advertising packets for the given set, + * which can be useful for conserving resources or when periodic advertising is no longer needed. + * + * @param[in] instance : Identifies the advertising set for which periodic advertising is to be disabled. + * This parameter is used to distinguish between multiple advertising sets that may be active simultaneously. + * + * @return - ESP_OK : Success. Periodic advertising has been successfully disabled for the specified advertising instance. + * - Other : Failure. An error occurred while disabling periodic advertising. Possible error codes may indicate + * issues such as invalid parameters or an uninitialized state. + * + * @note Ensure that the Bluetooth stack is properly initialized before calling this function. The `instance` must + * be valid and correspond to an existing advertising set. Proper error handling will help manage unsuccessful attempts + * to stop periodic advertising. + * + * Relevant events to monitor include: + * - `ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT`: Indicates that the request to stop periodic advertising has + * been processed. This event will provide details about the success or failure of the operation. + */ esp_err_t esp_ble_gap_periodic_adv_stop(uint8_t instance); /** -* @brief This function is used to set the extended scan parameters to be used on the advertising channels. -* -* @param[in] params : scan parameters -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to set the extended scan parameters that define how the device will scan for advertising packets on the Bluetooth Low Energy (BLE) channels. + * Extended scanning parameters allow customization of the scanning behavior, including the scan interval, window, and type, which can impact the discovery of advertising devices and overall scan efficiency. + * + * @param[in] params : Pointer to a structure containing the extended scan parameters. This structure includes details such as scan interval, scan window, scan type, and other relevant parameters. + * The `esp_ble_ext_scan_params_t` structure should be properly initialized before passing it to this function. + * + * @return - ESP_OK : Success. The extended scan parameters have been successfully set. + * - Other : Failure. An error occurred while setting the scan parameters. Possible error codes may include invalid parameters or an uninitialized Bluetooth stack. + * + * @note Ensure that the Bluetooth stack is initialized and that the `params` structure is correctly populated with valid values. Setting the scan parameters will affect the scanning behavior of the device. + * + * Relevant events to monitor include: + * - `ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT`: Indicates that the scan parameters have been set successfully or failed. This event will provide details about the outcome of the parameter setting operation. + */ esp_err_t esp_ble_gap_set_ext_scan_params(const esp_ble_ext_scan_params_t *params); /** -* @brief This function is used to enable scanning. -* -* @param[in] duration Scan duration time, where Time = N * 10 ms. Range: 0x0001 to 0xFFFF. -* @param[in] period Time interval from when the Controller started its last Scan Duration until it begins the subsequent Scan Duration. -* Time = N * 1.28 sec. Range: 0x0001 to 0xFFFF. -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to enable extended scanning for Bluetooth Low Energy (BLE) devices. + * Extended scanning allows the device to search for advertising packets over a defined period and interval. + * The duration specifies how long the device will actively scan, while the period defines the time between successive scans. + * + * @param[in] duration : Scan duration time, where Time = N * 10 ms. + * The value must be in the range 0x0001 to 0xFFFF. A value of 0 indicates a continuous scan until explicitly stopped. + * @param[in] period : Time interval from when the Controller started its last Scan Duration until it begins the subsequent Scan Duration. + * Time = N * 1.28 sec. The value must be in the range 0x0001 to 0xFFFF. + * A value of 0 indicates no periodic scanning. + * + * @return - ESP_OK : Success. The extended scanning process has been successfully started. + * - Other : Failure. An error occurred while starting the scan. Possible issues could include invalid parameters or an uninitialized Bluetooth stack. + * + * @note Ensure that the Bluetooth stack is initialized before calling this function. The scan duration and period parameters must be within the valid ranges. + * + * Relevant events to monitor include: + * - `ESP_GAP_BLE_SCAN_START_COMPLETE_EVT`: Indicates that the extended scan has started successfully or failed. This event provides details about the outcome of the scan initiation. + */ esp_err_t esp_ble_gap_start_ext_scan(uint32_t duration, uint16_t period); /** -* @brief This function is used to disable scanning. -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to disable extended scanning. + * When called, it stops the ongoing extended scan process that was previously initiated with `esp_ble_gap_start_ext_scan`. + * + * @return - ESP_OK : Success. The extended scanning process has been successfully stopped. + * - Other : Failure. An error occurred while stopping the scan. Possible issues could include an uninitialized Bluetooth stack or an attempt to stop scanning when it is not active. + * + * @note Ensure that the Bluetooth stack is initialized before calling this function. It is important to handle the completion of scanning operations to ensure resources are properly freed. + * + * Relevant events to monitor include: + * - `ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT`: Indicates that the extended scan has been stopped successfully or failed. This event provides details about the outcome of the scan termination. + */ esp_err_t esp_ble_gap_stop_ext_scan(void); /** -* @brief This function is used to synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets. -* -* @param[in] params : sync parameters -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets. + * + * @param[in] params : Synchronization parameters used to define how the synchronization should occur. + * These parameters include details such as the advertiser's address, the synchronization interval, and other related settings. + * + * @return - ESP_OK : Success. The synchronization with the periodic advertising has been initiated. + * - Other : Failure. An error occurred while trying to synchronize with the periodic advertising. Possible issues could include incorrect parameters or an ongoing synchronization process. + * + * @note Ensure that the parameters provided are correctly configured to match the advertiser's periodic advertising data. + */ esp_err_t esp_ble_gap_periodic_adv_create_sync(const esp_ble_gap_periodic_adv_sync_params_t *params); /** -* @brief This function is used to cancel the LE_Periodic_Advertising_Create_Sync command while it is pending. -* -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to cancel the LE_Periodic_Advertising_Create_Sync command while it is pending. + * + * @return - ESP_OK : Success. The cancellation request was successfully processed, and any pending synchronization attempt will be aborted. + * - Other : Failure. An error occurred while attempting to cancel the synchronization request. This could occur if no synchronization request is pending or if there is an issue with the Bluetooth stack. + * + * @note This function should be used if you need to abort an ongoing synchronization request with periodic advertising before it completes. + * + * Relevant events to monitor include: + * - `ESP_GAP_BLE_PERIODIC_ADV_SYNC_CANCEL_COMPLETE_EVT`: Indicates that the synchronization cancel request has been processed, and provides details about the cancellation status. + */ esp_err_t esp_ble_gap_periodic_adv_sync_cancel(void); /** -* @brief This function is used to stop reception of the periodic advertising identified by the Sync Handle parameter. -* -* @param[in] sync_handle : identify the periodic advertiser -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to stop reception of the periodic advertising identified by the Synchronization Handle parameter. + * + * @param[in] sync_handle : A handle that identifies the periodic advertising synchronization to be terminated. This handle is obtained from the `esp_ble_gap_periodic_adv_create_sync` function when the synchronization was initially created. + * + * @return - ESP_OK : Success. The request to terminate the synchronization was successfully processed, and periodic advertising reception has been stopped. + * - Other : Failure. An error occurred while attempting to terminate the synchronization. This could occur if the `sync_handle` is invalid or if there is an issue with the Bluetooth stack. + * + * @note This function should be used if you need to stop receiving periodic advertising packets from a specific advertiser. It will terminate the synchronization process for the given handle. + */ esp_err_t esp_ble_gap_periodic_adv_sync_terminate(uint16_t sync_handle); /** -* @brief This function is used to add a single device to the Periodic Advertiser list stored in the Controller -* -* @param[in] addr_type : address type -* @param[in] addr : Device Address -* @param[in] sid : Advertising SID subfield in the ADI field used to identify the Periodic Advertising -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to add a single device to the Periodic Advertiser list stored in the Controller. + * + * @param[in] addr_type : Address type of the device to be added to the list. This specifies whether the address is public, random, etc. + * @param[in] addr : Device Address of the device to be added. This should be a valid 6-byte Bluetooth Device Address (BD_ADDR). + * @param[in] sid : Advertising Service Identifier (SID) used to identify the Periodic Advertising. This is a subfield in the Advertising Data Indicator field. + * + * @return - ESP_OK : Success. The device has been successfully added to the Periodic Advertiser list. + * - Other : Failure. An error occurred while attempting to add the device to the list. This could be due to an invalid address or SID, or if the Bluetooth stack encountered an issue. + * + * @note This function allows you to manage the Periodic Advertiser list by adding specific devices that you want to synchronize with. + * Adding a device to this list helps in filtering and processing periodic advertising data from that particular device. + */ esp_err_t esp_ble_gap_periodic_adv_add_dev_to_list(esp_ble_addr_type_t addr_type, - esp_bd_addr_t addr, - uint8_t sid); + esp_bd_addr_t addr, + uint8_t sid); /** -* @brief This function is used to remove one device from the list of Periodic Advertisers stored in the Controller. -* Removals from the Periodic Advertisers List take effect immediately. -* -* @param[in] addr_type : address type -* @param[in] addr : Device Address -* @param[in] sid : Advertising SID subfield in the ADI field used to identify the Periodic Advertising -* -* @return - ESP_OK : success -* - other : failed -* + * @brief This function is used to remove one device from the list of Periodic Advertisers stored in the Controller. + * Removals from the Periodic Advertisers List take effect immediately. + * + * @param[in] addr_type : Address type of the device to be removed from the list. This specifies whether the address is public, random, etc. + * @param[in] addr : Device Address of the device to be removed. This should be a valid 6-byte Bluetooth Device Address (BD_ADDR). + * @param[in] sid : Advertising Service Identifier (SID) used to identify the Periodic Advertising. This is a subfield in the Advertising Data Indicator field. + * + * @return - ESP_OK : Success. The device has been successfully removed from the Periodic Advertiser list. + * - Other : Failure. An error occurred while attempting to remove the device from the list. This could be due to an invalid address or SID, or if the Bluetooth stack encountered an issue. + * + * @note This function allows you to manage the Periodic Advertiser list by removing specific devices that you no longer wish to synchronize with. + * Removing a device from this list helps in filtering out periodic advertising data from that particular device. */ esp_err_t esp_ble_gap_periodic_adv_remove_dev_from_list(esp_ble_addr_type_t addr_type, - esp_bd_addr_t addr, - uint8_t sid); + esp_bd_addr_t addr, + uint8_t sid); + /** -* @brief This function is used to remove all devices from the list of Periodic Advertisers in the Controller. -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to remove all devices from the list of Periodic Advertisers in the Controller. + * + * @return - ESP_OK : Success. All devices have been successfully removed from the Periodic Advertiser list. + * - Other : Failure. An error occurred while attempting to clear the list. This could be due to issues with the Bluetooth stack or if no devices were in the list. + * + * @note This function clears the entire list of Periodic Advertisers, which means that no devices will be synchronized with periodic advertising data until new devices are added. + * This operation is useful when you need to reset the list or when you want to stop synchronization with all previously added periodic advertisers. + */ esp_err_t esp_ble_gap_periodic_adv_clear_dev(void); /** -* @brief This function is used to set aux connection parameters -* -* @param[in] addr : device address -* @param[in] phy_mask : indicates the PHY(s) on which the advertising packets should be received on the primary advertising channel and the PHYs for which connection parameters have been specified. -* @param[in] phy_1m_conn_params : Scan connectable advertisements on the LE 1M PHY. Connection parameters for the LE 1M PHY are provided. -* @param[in] phy_2m_conn_params : Connection parameters for the LE 2M PHY are provided. -* @param[in] phy_coded_conn_params : Scan connectable advertisements on the LE Coded PHY. Connection parameters for the LE Coded PHY are provided. -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to set Auxiliary connection parameters for extended advertising and scanning. + * + * @param[in] addr : Device address of the peer device for which the connection parameters are being set. + * @param[in] phy_mask : Indicates the Physical Layer(s) on which the advertising packets should be received and the Physical Layers for which connection parameters have been specified. + * @param[in] phy_1m_conn_params : Connection parameters for scanning and connecting on the low energy 1M Physical Layer. + * @param[in] phy_2m_conn_params : Connection parameters for scanning and connecting on the low energy 2M Physical Layer. + * @param[in] phy_coded_conn_params : Connection parameters for scanning and connecting on the LE Coded Physical Layer. + * + * @return - ESP_OK : Success. The connection parameters have been successfully set. + * - Other : Failure. An error occurred while setting the connection parameters. This could be due to invalid parameters or issues with the Bluetooth stack. + * + * @note This function allows you to specify different connection parameters for various Physical Layers (1M, 2M, and Coded) in extended advertising and scanning scenarios. + * The parameters provided will be used to establish a connection with the specified device, taking into account the preferred Physical Layers and their respective connection parameters. + */ esp_err_t esp_ble_gap_prefer_ext_connect_params_set(esp_bd_addr_t addr, esp_ble_gap_phy_mask_t phy_mask, const esp_ble_gap_conn_params_t *phy_1m_conn_params, const esp_ble_gap_conn_params_t *phy_2m_conn_params, const esp_ble_gap_conn_params_t *phy_coded_conn_params); -#endif //#if (BLE_50_FEATURE_SUPPORT == TRUE) +#endif// #if (BLE_50_FEATURE_SUPPORT == TRUE) +//@} +//@{ +/** if Bluetooth Low Energy Feature Periodic Advertising Synchronization Transfer Support */ #if (BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER == TRUE) /** -* @brief This function is used to set periodic advertising receive enable -* -* @param[in] sync_handle : Handle of periodic advertising sync -* @param[in] enable : Determines whether reporting and duplicate filtering are enabled or disabled -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to enable or disable the reception of periodic advertising data. + * + * @param[in] sync_handle : Handle of the periodic advertising synchronization. This handle is used to identify the specific periodic advertising sync instance. + * @param[in] enable : Determines whether periodic advertising data reporting and duplicate filtering should be enabled or disabled. + * - `1` to enable periodic advertising data reception. + * - `0` to disable periodic advertising data reception. + * + * @return - ESP_OK : Success. The periodic advertising receive settings have been successfully applied. + * - Other : Failure. An error occurred while setting the periodic advertising receive parameters. This could be due to invalid handle or other issues with the Bluetooth stack. + * + * @note Enabling periodic advertising data reception allows the device to start reporting and filtering received periodic advertising data based on the specified synchronization handle. + * Disabling reception stops reporting and filtering of periodic advertising data. Make sure the synchronization handle provided is valid and corresponds to an active periodic advertising sync instance. + * + * Relevant events to monitor include: + * - `ESP_GAP_BLE_PERIODIC_ADV_SYNC_LOST_EVT`: Indicates that the periodic advertising sync has been lost or terminated. + */ esp_err_t esp_ble_gap_periodic_adv_recv_enable(uint16_t sync_handle, uint8_t enable); /** -* @brief This function is used to transfer periodic advertising sync -* -* @param[in] addr : Peer device address -* @param[in] service_data : Service data used by Host -* @param[in] sync_handle : Handle of periodic advertising sync -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to transfer synchronization data for periodic advertising. + * + * @param[in] addr : The Bluetooth Device Address of the peer device. This address identifies the device with which periodic advertising synchronization data is being transferred. + * @param[in] service_data : Service data associated with the periodic advertising synchronization. This data is used by the Host for various purposes related to the service. + * @param[in] sync_handle : Handle of the periodic advertising synchronization instance. This handle identifies the specific sync instance for which the data is being transferred. + * + * @return - ESP_OK : Success. The synchronization data has been successfully transferred. + * - Other : Failure. An error occurred during the transfer process. This could be due to invalid handle, address issues, or other Bluetooth stack errors. + * + * @note Ensure that the synchronization handle is valid and corresponds to an active periodic advertising sync instance. The peer device address should be correct and match the intended device for synchronization. + */ esp_err_t esp_ble_gap_periodic_adv_sync_trans(esp_bd_addr_t addr, uint16_t service_data, uint16_t sync_handle); /** -* @brief This function is used to transfer periodic advertising set info -* -* @param[in] addr : Peer device address -* @param[in] service_data : Service data used by Host -* @param[in] adv_handle : Handle of advertising set -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to transfer periodic advertising set information. + * + * @param[in] addr : The Bluetooth Device Address of the peer device. This address identifies the device with which periodic advertising set information is being transferred. + * @param[in] service_data : Service data associated with the periodic advertising set. This data is used by the Host for various purposes related to the advertising set. + * @param[in] adv_handle : Handle of the advertising set. This handle identifies the specific advertising set for which the information is being transferred. + * + * @return - ESP_OK : Success. The advertising set information has been successfully transferred. + * - Other : Failure. An error occurred during the transfer process. This could be due to invalid handle, address issues, or other Bluetooth stack errors. + * + * @note Ensure that the advertising handle is valid and corresponds to an active advertising set. The peer device address should be correct and match the intended device for the transfer. + */ esp_err_t esp_ble_gap_periodic_adv_set_info_trans(esp_bd_addr_t addr, uint16_t service_data, uint8_t adv_handle); /** -* @brief This function is used to set periodic advertising sync transfer params -* -* @param[in] addr : Peer device address -* @param[in] params : Params of periodic advertising sync transfer -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to set the parameters for transferring periodic advertising synchronization. + * + * @param[in] addr : The Bluetooth Device Address of the peer device with which synchronization transfer is to be performed. This address identifies the target device for the synchronization. + * @param[in] params : Parameters for periodic advertising synchronization transfer. This structure should contain the specific configuration needed for synchronization. + * + * @return - ESP_OK : Success. The parameters for periodic advertising synchronization transfer have been successfully set. + * - Other : Failure. An error occurred while setting the parameters. Possible reasons could include invalid address or parameter issues. + * + * @note Ensure that the address is correct and that the parameters structure contains valid settings for synchronization transfer. This function is typically used in scenarios where the Host needs to configure or modify the synchronization settings for periodic advertising. + */ esp_err_t esp_ble_gap_set_periodic_adv_sync_trans_params(esp_bd_addr_t addr, const esp_ble_gap_past_params_t *params); -#endif //#if (BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER == TRUE) -#if (BLE_42_FEATURE_SUPPORT == TRUE) +#endif//#if (BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER == TRUE) +//@} +//@{ +/** if Bluetooth Low Energy 4.2 Feature Support */ +#if (BLE_42_FEATURE_SUPPORT == TRUE) /** -* @brief This function is used to start a test where the DUT generates reference packets -* at a fixed interval. -* -* @param[in] tx_params : DTM Transmitter parameters -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function starts a test where the Device Under Test (DUT) generates reference packets at a fixed interval. + * + * @param[in] tx_params : Parameters for Direct Test Mode (DTM) transmission. This structure should contain the configuration details for the transmitter, such as packet type, transmission frequency, and interval. + * + * @return - ESP_OK : Success. The Direct Test Mode transmitter has been started with the specified parameters. + * - Other : Failure. An error occurred while starting the transmitter. Possible reasons include invalid parameters or hardware issues. + * + * @note Ensure that the `tx_params` structure is correctly initialized with valid settings before calling this function. This function is typically used for testing and debugging purposes in BLE (Bluetooth Low Energy) scenarios. + */ esp_err_t esp_ble_dtm_tx_start(const esp_ble_dtm_tx_t *tx_params); /** -* @brief This function is used to start a test where the DUT receives test reference packets -* at a fixed interval. -* -* @param[in] rx_params : DTM Receiver parameters -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function starts a test where the Device Under Test (DUT) receives reference packets at a fixed interval. + * + * @param[in] rx_params : Parameters for Direct Test Mode (DTM) reception. This structure should contain the configuration details for the receiver, such as packet type, reception frequency, and interval. + * + * @return - ESP_OK : Success. The Direct Test Mode receiver has been started with the specified parameters. + * - Other : Failure. An error occurred while starting the receiver. Possible reasons include invalid parameters or hardware issues. + * + * @note Ensure that the `rx_params` structure is correctly initialized with valid settings before calling this function. This function is typically used for testing and debugging purposes in BLE (Bluetooth Low Energy) scenarios. + */ esp_err_t esp_ble_dtm_rx_start(const esp_ble_dtm_rx_t *rx_params); -#endif //#if (BLE_42_FEATURE_SUPPORT == TRUE) +#endif//#if (BLE_42_FEATURE_SUPPORT == TRUE) +//@} +//@{ +/** if Bluetooth Low Energy 5.0 Feature Support */ #if (BLE_50_FEATURE_SUPPORT == TRUE) /** -* @brief This function is used to start a test where the DUT generates reference packets -* at a fixed interval. -* -* @param[in] tx_params : DTM Transmitter parameters -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to start a test where the Device Under Test (DUT) generates reference packets + * at a fixed interval, using enhanced Direct Test Mode (DTM) transmitter parameters. + * + * @param[in] tx_params : Parameters for Direct Test Mode (DTM) enhanced transmitter. This structure should include the configuration details for the transmitter, such as packet type, transmission frequency, interval, and other relevant settings. + * + * @return - ESP_OK : Success. The Direct Test Mode transmitter has been started with the specified parameters. + * - Other : Failure. An error occurred while starting the transmitter. Possible issues include invalid parameters or hardware malfunctions. + * + * @note Ensure that the `tx_params` structure is properly initialized with valid settings before calling this function. This function is typically used for enhanced testing and debugging of BLE (Bluetooth Low Energy) functionalities. + */ esp_err_t esp_ble_dtm_enh_tx_start(const esp_ble_dtm_enh_tx_t *tx_params); /** -* @brief This function is used to start a test where the DUT receives test reference packets -* at a fixed interval. -* -* @param[in] rx_params : DTM Receiver parameters -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to start a test where the Device Under Test (DUT) receives test reference packets + * at a fixed interval, using enhanced Direct Test Mode (DTM) receiver parameters. + * + * @param[in] rx_params : Parameters for Direct Test Mode (DTM) enhanced receiver. This structure should include the configuration details for the receiver, such as packet type, reception frequency, and other relevant settings. + * + * @return - ESP_OK : Success. The Direct Test Mode receiver has been started with the specified parameters. + * - Other : Failure. An error occurred while starting the receiver. Possible issues include invalid parameters or hardware malfunctions. + * + * @note Ensure that the `rx_params` structure is properly initialized with valid settings before calling this function. This function is typically used for enhanced testing and debugging of BLE (Bluetooth Low Energy) functionalities. + */ esp_err_t esp_ble_dtm_enh_rx_start(const esp_ble_dtm_enh_rx_t *rx_params); -#endif // #if (BLE_50_FEATURE_SUPPORT == TRUE) +#endif //#if (BLE_50_FEATURE_SUPPORT == TRUE) +//@} /** -* @brief This function is used to stop any test which is in progress -* -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to stop any Direct Test Mode (DTM) test that is currently in progress. + * + * @return - ESP_OK : Success. The Direct Test Mode test has been successfully stopped. + * - Other : Failure. An error occurred while stopping the test. Possible reasons include no test in progress or hardware issues. + * + * @note This function can be called to halt any ongoing DTM test, whether it is transmitting or receiving. It is useful for stopping tests that are no longer needed or in cases where you need to reinitialize the test parameters. + */ esp_err_t esp_ble_dtm_stop(void); /** -* @brief This function is used to clear legacy advertising -* -* -* @return - ESP_OK : success -* - other : failed -* -*/ + * @brief This function is used to clear any legacy advertising configurations. + * + * @return - ESP_OK : Success. The legacy advertising configurations have been successfully cleared. + * - Other : Failure. An error occurred while clearing the advertising configurations. Possible reasons include no advertising configurations to clear or issues with the Bluetooth stack. + * + * @note This function is useful for resetting or removing legacy advertising settings that were previously configured. It can help in managing or updating advertising configurations as needed. + * + * Relevant events to monitor include: + * - `ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT`: Indicates that the advertising data has been set or cleared. This event can confirm whether the advertising data has been successfully cleared. + */ esp_err_t esp_ble_gap_clear_advertising(void); /** - * @brief This function is called to send vendor hci command. + * @brief This function is called to send a vendor-specific Host Controller Interface (HCI) command. * + * @param[in] vendor_cmd_param : Parameters for the vendor-specific HCI command. This includes the command opcode, parameters, and any other necessary data specific to the vendor's implementation. * + * @return - ESP_OK : Success. The vendor-specific HCI command was sent successfully. + * - Other : Failure. The command could not be sent. Possible reasons include invalid parameters or issues with the Bluetooth stack. * - * @param[in] vendor_cmd_param: vendor hci command parameters + * @note Vendor-specific HCI commands are used to access features or configurations that are not covered by standard Bluetooth commands. The exact behavior and parameters depend on the vendor's implementation and the specific command being sent. * - * @return - * - ESP_OK : success - * - other : failed + * Ensure that the `vendor_cmd_param` structure is correctly populated with valid data before calling this function. Refer to the vendor's documentation for details on supported commands and their parameters. */ esp_err_t esp_ble_gap_vendor_command_send(esp_ble_vendor_cmd_params_t *vendor_cmd_param); /** - * @brief This function set the privacy mode of the device in resolving list. + * @brief This function sets the privacy mode of the device in the resolving list. * * @note This feature is not supported on ESP32. * - * @param[in] addr_type: The address type of the peer identity address (BLE_ADDR_TYPE_PUBLIC or BLE_ADDR_TYPE_RANDOM). - * @param[in] addr: The peer identity address of the device. - * @param[in] mode: The privacy mode of the device. + * @param[in] addr_type: The address type of the peer identity address. It can be either `BLE_ADDR_TYPE_PUBLIC` or `BLE_ADDR_TYPE_RANDOM`. + * @param[in] addr: The peer identity address of the device. This should be a 6-byte Bluetooth Device Address (BD_ADDR). + * @param[in] mode: The privacy mode to be set for the device. This is specified by the `esp_ble_privacy_mode_t` enumeration. * - * @return - * - ESP_OK : success - * - other : failed + * @return - ESP_OK : Success. The privacy mode was successfully set. + * - Other : Failure. The privacy mode could not be set. This could be due to an unsupported feature or an invalid parameter. + * + * @note As indicated, this feature is not supported on ESP32, and calling this function on ESP32 may not have any effect. */ esp_err_t esp_ble_gap_set_privacy_mode(esp_ble_addr_type_t addr_type, esp_bd_addr_t addr, esp_ble_privacy_mode_t mode);