wehub/espressif--esp-idf
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 13:04:25 +08:00
commit 548b49ebc0
20937 changed files with 5455372 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/api-reference/bluetooth/bt_common.rst
+35
View File
@@ -0,0 +1,35 @@
Bluetooth\ :sup:`®` Common
===============================
:link_to_translation:`zh_CN:[中文]`
**Bluetooth Common** provides shared definitions and APIs used by both Bluetooth Classic and Bluetooth Low Energy (Bluetooth LE). It serves as a foundation for shared functionality across Bluetooth components, offering unified interfaces for Bluetooth initialization, configuration, and device management.
The Bluetooth Common API is organized into the following parts:
.. toctree::
:maxdepth: 1
Bluetooth Define <esp_bt_defs>
Provides shared definitions and data structures used by both Bluetooth Classic and Bluetooth LE.
.. toctree::
:maxdepth: 1
Bluetooth Main <esp_bt_main>
Provides core APIs for initializing, enabling/disabling, and managing the Bluetooth stack.
.. toctree::
:maxdepth: 1
Bluetooth Device <esp_bt_device>
Provides APIs for managing device-level properties such as address, name, visibility, and coexistence settings.
Each part typically includes the following sections:
- **Overview**: Summary of purpose, key functionality, and main interfaces
- **Application Examples**: Example projects demonstrating typical usage
- **API Reference**: Detailed API documentation, including header files, functions, structures, macros, type definitions, and enumerations
docs/en/api-reference/bluetooth/bt_le.rst
+44
View File
@@ -0,0 +1,44 @@
Bluetooth\ :sup:`®` Low Energy
====================================
:link_to_translation:`zh_CN:[中文]`
**Bluetooth Low Energy (Bluetooth LE)** provides low-power wireless communication for IoT devices such as wearables, sensors, and smart home products. This section documents the **Bluetooth LE API Reference**, covering APIs for device discovery, data exchange, and Wi-Fi provisioning over Bluetooth LE.
For usage concepts and tutorials, see :doc:`Bluetooth Low Energy <../../../api-guides/ble/index>` in **API Guides**.
The Bluetooth LE API in ESP-IDF is organized into the following parts:
- :doc:`Bluetooth Low Energy GAP <esp_gap_ble>`
Handles advertising, scanning, connection management, and security operations
- :doc:`Bluetooth Low Energy GATT Define <esp_gatt_defs>`
Common data types and constants for attributes, characteristics, and UUIDs used in GATT operations
- :doc:`Bluetooth Low Energy GATT Server <esp_gatts>`
Exposes services and characteristics to remote clients (peripheral role)
- :doc:`Bluetooth Low Energy GATT Client <esp_gattc>`
Discovers and accesses services on remote servers (central role)
.. only:: SOC_BLUFI_SUPPORTED
- :doc:`Bluetooth Low Energy BluFi <esp_blufi>`
Enables Wi-Fi provisioning and configuration via Bluetooth LE
Each part typically includes an **Overview**, **Application Examples**, and **API Reference**, covering purpose, main functionality, sample usage, and detailed API documentation.
.. toctree::
:maxdepth: 1
:hidden:
Bluetooth Low Energy GAP <esp_gap_ble>
Bluetooth Low Energy GATT Define <esp_gatt_defs>
Bluetooth Low Energy GATT Server <esp_gatts>
Bluetooth Low Energy GATT Client <esp_gattc>
:SOC_BLUFI_SUPPORTED: Bluetooth Low Energy BluFi <esp_blufi>
docs/en/api-reference/bluetooth/bt_vhci.rst
+380
View File
@@ -0,0 +1,380 @@
:orphan:
HCI Vendor-specific (VS) Commands
==========================================
:link_to_translation:`zh_CN:[中文]`
HCI VS Commands for Espressif's Bluetooth Host
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following HCI VS commands are exclusively for Espressif's Bluetooth Host (ESP-Bluedroid Host or ESP-NimBLE Host). If you are using a non-ESP host or HCI UART, these commands will remain disabled unless the initialization function is explicitly called from the application. Note, these init functions as well as these additional HCI VS commands are intended for Espressif's Bluetooth Host use only. Application developers **should not** call the init functions in their applications.
.. only:: esp32
.. doxygendefine:: ESP_BT_VS_COMMON_ECHO_OCF
.. doxygendefine:: ESP_BT_VS_SET_COEX_STATUS_OCF
.. doxygendefine:: ESP_BT_VS_CONFIG_DUP_EXC_LIST_OCF
.. doxygendefine:: ESP_BT_VS_SET_ADV_REPORT_FLOW_CTRL_OCF
.. doxygendefine:: ESP_BT_VS_UPD_ADV_REPORT_FLOW_CTRL_NUM_OCF
.. doxygendefine:: ESP_BT_VS_CLR_LEGACY_ADV_OCF
.. doxygendefine:: ESP_BT_VS_SET_MIN_ENC_KEY_SIZE_OCF
.. only:: esp32c3 or esp32s3
.. doxygendefine:: ESP_BT_VS_COMMON_ECHO_OCF
.. doxygendefine:: ESP_BT_VS_CONFIG_DUP_EXC_LIST_OCF
.. doxygendefine:: ESP_BT_VS_SET_ADV_REPORT_FLOW_CTRL_OCF
.. doxygendefine:: ESP_BT_VS_UPD_ADV_REPORT_FLOW_CTRL_NUM_OCF
.. doxygendefine:: ESP_BT_VS_CLR_LEGACY_ADV_OCF
.. doxygendefine:: ESP_BT_VS_ENABLE_CSA2_OCF
.. only:: esp32c2
.. doxygendefine:: ESP_BT_VS_SET_ADV_REPORT_FLOW_CTRL_OCF
.. doxygendefine:: ESP_BT_VS_UPD_ADV_REPORT_FLOW_CTRL_NUM_OCF
.. doxygendefine:: ESP_BT_VS_CLR_LEGACY_ADV_OCF
.. doxygendefine:: ESP_BT_VS_ENABLE_CSA2_OCF
.. doxygendefine:: ESP_BT_VS_SET_LE_VENDOR_EVTS_MASK_OCF
.. only:: esp32c5 or esp32c6 or esp32h2 or esp32h21 or esp32c61 or esp32h4 or esp32s31
.. doxygendefine:: ESP_BT_VS_CONFIG_DUP_EXC_LIST_OCF
.. doxygendefine:: ESP_BT_VS_SET_ADV_REPORT_FLOW_CTRL_OCF
.. doxygendefine:: ESP_BT_VS_UPD_ADV_REPORT_FLOW_CTRL_NUM_OCF
.. doxygendefine:: ESP_BT_VS_CLR_LEGACY_ADV_OCF
.. doxygendefine:: ESP_BT_VS_SET_DUP_LIST_PARAMS_OCF
.. doxygendefine:: ESP_BT_VS_ENABLE_DUP_EXC_LIST_OCF
.. doxygendefine:: ESP_BT_VS_ENABLE_ARRANGEMENT_OCF
.. doxygendefine:: ESP_BT_VS_SET_SCHED_ROLE_LEN_OCF
.. doxygendefine:: ESP_BT_VS_SET_PCL_RSSI_THRESH_OCF
.. doxygendefine:: ESP_BT_VS_ENABLE_CSA2_OCF
.. doxygendefine:: ESP_BT_VS_SET_LOG_PARAMS_OCF
.. doxygendefine:: ESP_BT_VS_SET_LE_VENDOR_EVTS_MASK_OCF
.. doxygendefine:: ESP_BT_VS_SET_CONST_PEER_SCA_OCF
HCI VS Events for Espressif's Bluetooth Host
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following HCI VS events are exclusively for Espressif's Bluetooth Host (ESP-Bluedroid Host or ESP-NimBLE Host). If you are using a non-ESP host or HCI UART, these events will remain disabled unless the initialization function is explicitly called from the application. Note, these init functions as well as these additional HCI VS events are intended for Espressif's Bluetooth Host use only. Application developers **should not** call the init functions in their applications.
.. only:: esp32
.. doxygendefine:: ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_LEGACY_REM_AUTH_EVT_SUBCODE
.. only:: esp32c3 or esp32s3
.. doxygendefine:: ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODE
.. only:: esp32c2
.. doxygendefine:: ESP_BT_VS_LE_CONN_SCAN_REQ_RXED_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_LE_CHAN_UPDATE_COMP_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_LE_SLEEP_WAKEUP_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODE
.. only:: esp32c6 or esp32h2 or esp32h21 or esp32c5 or esp32c61 or esp32h4
.. doxygendefine:: ESP_BT_VS_LE_CONN_SCAN_REQ_RXED_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_LE_CHAN_UPDATE_COMP_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_LE_SLEEP_WAKEUP_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODE
.. only:: esp32s31
.. doxygendefine:: ESP_BT_VS_LE_CONN_SCAN_REQ_RXED_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_LE_CHAN_UPDATE_COMP_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_LE_SLEEP_WAKEUP_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_LE_ADV_LOST_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_LEGACY_REM_AUTH_EVT_SUBCODE
HCI VS Commands for Espressif's Internal-Use Debugging
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following HCI VS debugging commands are implemented in Bluetooth Low Energy controller pre-compiled libraries. These commands are not linked into the application binary, unless the function `esp_ble_internalTestFeaturesEnable(true)` is called from the application. They are intended for Espressif's internal use only. Application developers **should not** call `esp_ble_internalTestFeaturesEnable(true)` in their applications.
.. only:: esp32
.. doxygendefine:: ESP_BT_VS_CFG_TEST_RELATED_OCF
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_ADV_DELAY_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_FOREVER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_EXPECTED_PEER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_ADV_TXED_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_SCAN_RXED_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_TXPWR_LVL_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_LVL_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_CLEAR_RAND_ADDR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_MAX_TXPWR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_RANGE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_AA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_ADV_AA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_CHAN_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_CTRL_STATUS_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_CTRL_COMPILE_VER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_RELATED_SUBCMD_MAX
The following HCI VS debugging commands are implemented in Bluetooth Classic controller pre-compiled libraries. These commands are not linked into the application binary, unless the corresponding initialization function is explicitly called from the application. They are intended for Espressif's internal use only. Application developers **should not** call in their applications.
.. doxygendefine:: ESP_BT_VS_WR_DM1_ENABLE_OCF
.. doxygendefine:: ESP_BT_VS_CLK_UPDATE_OCF
.. doxygendefine:: ESP_BT_VS_SET_AFH_OCF
.. doxygendefine:: ESP_BT_VS_SET_EVT_MASK_OCF
.. doxygendefine:: ESP_BT_VS_SET_AFH_REPORTING_MODE_OCF
.. doxygendefine:: ESP_BT_VS_MASK_RMT_CHANNEL_CLASSIFICATION_OCF
.. doxygendefine:: ESP_BT_VS_WR_AUTO_RATE_INIT_OCF
.. doxygendefine:: ESP_BT_VS_RD_ACL_REAL_RSSI_OCF
.. doxygendefine:: ESP_BT_VS_RD_NEW_CONN_TX_PWR_LVL_OCF
.. doxygendefine:: ESP_BT_VS_WR_NEW_CONN_TX_PWR_LVL_OCF
.. doxygendefine:: ESP_BT_VS_RD_PAGE_TX_PWR_LVL_OCF
.. doxygendefine:: ESP_BT_VS_WR_PAGE_TX_PWR_LVL_OCF
.. doxygendefine:: ESP_BT_VS_RD_PSCAN_TX_PWR_LVL_OCF
.. doxygendefine:: ESP_BT_VS_WR_PSCAN_TX_PWR_LVL_OCF
.. doxygendefine:: ESP_BT_VS_RD_INQ_TX_PWR_LVL_OCF
.. doxygendefine:: ESP_BT_VS_WR_ISCAN_TX_PWR_LVL_OCF
.. only:: esp32c3 or esp32s3
.. doxygendefine:: ESP_BT_VS_CFG_TEST_RELATED_OCF
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_ADV_DELAY_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_PREF_CODED_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_DEFAULT_PRIV_MODE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_FOREVER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_EXPECTED_PEER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_ADV_TXED_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_SCAN_RXED_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_TXPWR_LVL_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_LVL_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_TXPWR_LVL_ENH_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_LVL_ENH_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_CCA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_CLEAR_RAND_ADDR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_MAX_TXPWR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_RANGE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_AA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_ADV_AA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_CHAN_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_CTRL_STATUS_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_CTRL_COMPILE_VER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_AUX_ADV_OFFSET_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_AUX_OFFSET_THRESHOLD_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_RELATED_SUBCMD_MAX
.. only:: esp32c2
.. doxygendefine:: ESP_BT_VS_CFG_TEST_RELATED_OCF
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_ADV_DELAY_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_PREF_CODED_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_DEFAULT_PRIV_MODE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_FOREVER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_EXPECTED_PEER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_ADV_TXED_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_SCAN_RXED_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_TXPWR_LVL_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_LVL_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_TXPWR_LVL_ENH_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_LVL_ENH_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_IGNORE_WL_FOR_DIR_ADV_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_ADV_RXED_RSSI_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_CCA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_CCA_WIN_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_READ_CCA_DATA_SUBCM
.. doxygendefine:: ESP_BT_VS_CFG_TEST_CLEAR_RAND_ADDR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_MAX_TXPWR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_RANGE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_AA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_ADV_AA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_CHAN_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SKIP_LIGHT_SLEEP_CHECK_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_WAKEUP_OVERHEAD_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_ADV_MIN_ITVL_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_CTRL_STATUS_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_RECODE_RX_STATE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_RECODE_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_CLR_RECODE_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_CTRL_COMPILE_VER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_AUX_ADV_OFFSET_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_BACKOFF_UPLIMIT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_RXED_ADV_ADI_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_RX_SENS_THRESH_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_AGC_MAX_GAIN_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_RELATED_SUBCMD_MAX
.. only:: esp32c6 or esp32h2 or esp32h21 or esp32c5 or esp32c61 or esp32h4
.. doxygendefine:: ESP_BT_VS_CFG_TEST_RELATED_OCF
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_ADV_DELAY_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_PREF_CODED_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_DEFAULT_PRIV_MODE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_FOREVER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_EXPECTED_PEER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_ADV_TXED_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_SCAN_RXED_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_TXPWR_LVL_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_LVL_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_TXPWR_LVL_ENH_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_LVL_ENH_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_IGNORE_WL_FOR_DIR_ADV_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_ADV_RXED_RSSI_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_CCA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_CCA_WIN_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_READ_CCA_DATA_SUBCM
.. doxygendefine:: ESP_BT_VS_CFG_TEST_CLEAR_RAND_ADDR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_MAX_TXPWR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_RANGE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_AA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_ADV_AA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_CHAN_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SKIP_LIGHT_SLEEP_CHECK_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_WAKEUP_OVERHEAD_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_ADV_MIN_ITVL_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_CTRL_STATUS_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_CONN_PHY_TXPWR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_CONN_PHY_TXPWR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_RXBUF_EMPTY_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_RESTART_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_RECODE_RX_STATE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_RECODE_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_CLR_RECODE_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_CTRL_COMPILE_VER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_AUX_ADV_OFFSET_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_INIT_FLEXIBLE_MODE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_FLEXIBLE_MODE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_FLEXIBLE_CONN_ERR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_FLEXIBLE_ADV_ERR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_FLEXIBLE_SCAN_ERR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXED_CRCERR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_BACKOFF_UPLIMIT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_RXED_ADV_ADI_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCH_RAND_MODE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_RX_SENS_THRESH_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_CHECK_MSYS_BUF_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_UPDATE_BLE_TIMER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_UPDATE_BLE_RTC_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_LOCKED_MEM_NUM_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ALLOW_MEM_ALLOC_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCH_RAND_INFO_PTR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_DIAG_IO_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_AGC_MAX_GAIN_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_CHAN_ASSESS_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_BACKOFF_UPLIMIT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_CONN_TOP_PRIO_RESV_THRESH_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_TEST_EVT_MSK_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_WAKEUP_TIMEOUT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_RELATED_SUBCMD_MAX
.. only:: esp32s31
.. doxygendefine:: ESP_BT_VS_CFG_TEST_RELATED_OCF
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_ADV_DELAY_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_PREF_CODED_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_DEFAULT_PRIV_MODE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_FOREVER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_EXPECTED_PEER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_ADV_TXED_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_SCAN_RXED_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_TXPWR_LVL_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_LVL_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_TXPWR_LVL_ENH_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_LVL_ENH_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_IGNORE_WL_FOR_DIR_ADV_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_ADV_RXED_RSSI_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_CCA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_CCA_WIN_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_READ_CCA_DATA_SUBCM
.. doxygendefine:: ESP_BT_VS_CFG_TEST_CLEAR_RAND_ADDR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_MAX_TXPWR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXPWR_RANGE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_AA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_ADV_AA_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCAN_CHAN_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SKIP_LIGHT_SLEEP_CHECK_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_WAKEUP_OVERHEAD_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_ADV_MIN_ITVL_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_CTRL_STATUS_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_CONN_PHY_TXPWR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_CONN_PHY_TXPWR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_RXBUF_EMPTY_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_RESTART_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_RECODE_RX_STATE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_RECODE_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_CLR_RECODE_CNT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_CTRL_COMPILE_VER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_AUX_ADV_OFFSET_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_INIT_FLEXIBLE_MODE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_FLEXIBLE_MODE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_FLEXIBLE_CONN_ERR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_FLEXIBLE_ADV_ERR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_FLEXIBLE_SCAN_ERR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_TXED_CRCERR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_BACKOFF_UPLIMIT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_RXED_ADV_ADI_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCH_RAND_MODE_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_RX_SENS_THRESH_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_CHECK_MSYS_BUF_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_UPDATE_BLE_TIMER_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_UPDATE_BLE_RTC_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_LOCKED_MEM_NUM_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ALLOW_MEM_ALLOC_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_SCH_RAND_INFO_PTR_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_DIAG_IO_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_AGC_MAX_GAIN_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_ENABLE_CHAN_ASSESS_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_BACKOFF_UPLIMIT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_CONN_TOP_PRIO_RESV_THRESH_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_SET_TEST_EVT_MSK_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_GET_WAKEUP_TIMEOUT_SUBCMD
.. doxygendefine:: ESP_BT_VS_CFG_TEST_RELATED_SUBCMD_MAX
The following HCI VS debugging commands are implemented in Bluetooth Classic controller pre-compiled libraries. These commands are not linked into the application binary, unless the corresponding initialization function is explicitly called from the application. They are intended for Espressif's internal use only. Application developers **should not** call in their applications.
.. doxygendefine:: ESP_BT_VS_WR_DM1_ENABLE_OCF
.. doxygendefine:: ESP_BT_VS_CLK_UPDATE_OCF
.. doxygendefine:: ESP_BT_VS_PCA_OCF
.. doxygendefine:: ESP_BT_VS_SET_AFH_OCF
.. doxygendefine:: ESP_BT_VS_SET_EVT_MASK_OCF
.. doxygendefine:: ESP_BT_VS_SET_AFH_REPORTING_MODE_OCF
.. doxygendefine:: ESP_BT_VS_MASK_RMT_CHANNEL_CLASSIFICATION_OCF
.. doxygendefine:: ESP_BT_VS_DTM_TX_TEST_START_OCF
.. doxygendefine:: ESP_BT_VS_DTM_RX_TEST_START_OCF
.. doxygendefine:: ESP_BT_VS_DTM_TX_TEST_END_OCF
.. doxygendefine:: ESP_BT_VS_DTM_RX_TEST_END_OCF
HCI VS Events for Espressif's Internal-Use Debugging
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following HCI VS debugging events are implemented in Bluetooth controller pre-compiled libraries. These events are not linked into the application binary and are intended for Espressif's internal use only. Application developers **should not** call the corresponding initialization function in their applications.
.. only:: esp32
.. doxygendefine:: ESP_BT_VS_AFH_CHG_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_CH_CLASSIFICATION_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_CH_CLASSIFICATION_REPORTING_MODE_EVT_SUBCODE
.. only:: esp32c5 or esp32c6 or esp32c61 or esp32h2 or esp32h21 or esp32h4
.. doxygendefine:: ESP_BT_VS_LE_RUNNING_STATUS_EVT_SUBCODE
.. only:: esp32s31
.. doxygendefine:: ESP_BT_VS_LE_RUNNING_STATUS_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_AFH_CHG_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_CH_CLASSIFICATION_EVT_SUBCODE
.. doxygendefine:: ESP_BT_VS_CH_CLASSIFICATION_REPORTING_MODE_EVT_SUBCODE
docs/en/api-reference/bluetooth/classic_bt.rst
+79
View File
@@ -0,0 +1,79 @@
Bluetooth\ :sup:`®` Classic
===============================
:link_to_translation:`zh_CN:[中文]`
**Bluetooth Classic** provides APIs for implementing traditional Bluetooth functionalities, including audio streaming, device communication, and data exchange over the Serial Port Profile. It supports multiple Bluetooth profiles, allowing ESP devices to act as source or sink in scenarios like wireless audio, remote control, and data transmission.
The Bluetooth Classic API provides the following main features:
- Core protocol support (**GAP**, **L2CAP**, and **SDP**)
- Serial data communication (**SPP**)
- High-quality audio streaming (**A2DP**)
- Media playback control (**AVRCP**)
- Hands-free calling support (**HFP**)
- Input device connectivity (**HID** host and device roles)
----
The Bluetooth Classic API in ESP-IDF is organized into the following parts:
**Core Protocols**
- :doc:`Bluetooth GAP <esp_gap_bt>`
**Generic Access Profile (GAP):** Device discovery, pairing, and security management
- :doc:`Bluetooth L2CAP <esp_l2cap_bt>`
**Logical Link Control and Adaptation Protocol (L2CAP):** Data multiplexing and channel management
- :doc:`Bluetooth SDP <esp_sdp>`
**Service Discovery Protocol (SDP):** Discovers remote device services and attributes
**Communication Profile**
- :doc:`Bluetooth SPP <esp_spp>`
**Serial Port Profile (SPP):** Emulates a serial communication channel over Bluetooth for data exchange
**Audio and Media Profiles**
- :doc:`Bluetooth A2DP <esp_a2dp>`
**Advanced Audio Distribution Profile (A2DP):** High-quality audio streaming (source and sink)
- :doc:`Bluetooth AVRCP <esp_avrc>`
**Audio/Video Remote Control Profile (AVRCP):** Media playback control (play, pause, volume)
**Hands-Free Profile (HFP)**
- :doc:`Bluetooth HFP Define <esp_hf_defs>`: Core definitions shared by HFP roles
- :doc:`Bluetooth HFP Client <esp_hf_client>`: Implements the hands-free unit role (e.g., headset, car kit)
- :doc:`Bluetooth HFP AG <esp_hf_ag>`: Implements the audio gateway role (e.g., mobile phone)
**Human Interface Device (HID)**
- :doc:`Bluetooth HID Device <esp_hidd>`: Implements peripheral roles such as keyboard, mouse, or game controller
- :doc:`Bluetooth HID Host <esp_hidh>`: Implements the host role for connecting to remote HID devices
Each part typically includes an **Overview**, **Application Examples**, and **API Reference**, covering purpose, main functionality, sample usage, and detailed API documentation.
.. toctree::
:maxdepth: 1
:hidden:
Bluetooth GAP <esp_gap_bt>
Bluetooth L2CAP <esp_l2cap_bt>
Bluetooth SDP <esp_sdp>
Bluetooth SPP <esp_spp>
Bluetooth A2DP <esp_a2dp>
Bluetooth AVRCP <esp_avrc>
Bluetooth HFP Define <esp_hf_defs>
Bluetooth HFP Client <esp_hf_client>
Bluetooth HFP AG <esp_hf_ag>
Bluetooth HID Device <esp_hidd>
Bluetooth HID Host <esp_hidh>
docs/en/api-reference/bluetooth/controller_vhci.rst
+32
View File
@@ -0,0 +1,32 @@
Controller & HCI
==================================================
:link_to_translation:`zh_CN:[中文]`
.. only:: esp32 or esp32c3 or esp32s3
Application Examples
--------------------
.. only:: esp32
- :example:`bluetooth/hci/ble_adv_scan_combined` demonstrates how to use Bluetooth capabilities for advertising and scanning with a virtual Host Controller Interface (HCI). This example shows how to implement some host functionalities without a host and displays scanned advertising reports from other devices.
- :example:`bluetooth/hci/controller_hci_uart_esp32` demonstrates how to configure the Bluetooth LE Controller's HCI to communicate over UART on {IDF_TARGET_NAME}, enabling communication with an external Bluetooth host stack.
- :example:`bluetooth/hci/controller_vhci_ble_adv` demonstrates how to use the ESP-IDF VHCI ble_advertising app to perform advertising without a host and display received HCI events from the controller.
.. only:: esp32c3 or esp32s3
- :example:`bluetooth/hci/controller_hci_uart_esp32c3_and_esp32s3` demonstrates how to configure the Bluetooth LE Controller's HCI to communicate over UART on {IDF_TARGET_NAME}, enabling communication with an external Bluetooth host stack.
API Reference
-------------
.. include-build-file:: inc/esp_bt.inc
HCI Vendor-specific (VS) Commands
--------------------------------------
Espressif's HCI VS commands are exclusively designed for use with Espressif's Bluetooth Host stack or internal debugging purposes. Application developers **should not** initialize or invoke these VS commands in their applications. Please refer to :doc:`bt_vhci` for detailed information.
docs/en/api-reference/bluetooth/esp-ble-audio.rst
+243
View File
@@ -0,0 +1,243 @@
ESP-BLE-AUDIO
=============
ESP-BLE-AUDIO provides APIs for Bluetooth LE Audio, enabling time-synchronized audio over BLE using the Bluetooth Core Specification LE Audio architecture. Applications can implement unicast (one-to-one) and broadcast audio scenarios, including hearing aids, headsets, speakers, and broadcast sources/sinks.
The LE Audio stack is built on the **Bluetooth Core** and the **LC3** codec. The **generic audio framework** includes the Common Audio Profile (CAP), Common Audio Service (CAS), and the profiles and services below. **Use case specific profiles** (HAP, GMAP, TMAP, PBP) sit on top of the generic framework. LE Audio runs over the LE Isochronous Channels (CIS/BIS) supported by :doc:`esp-ble-iso`.
For conceptual background and architectural details, see the :doc:`Bluetooth LE Audio documentation <../../api-guides/esp-ble-audio/ble-audio-index>`, in particular the :doc:`ESP-BLE-AUDIO architecture <../../api-guides/esp-ble-audio/ble-audio-architecture-lea>`.
.. warning::
This is a **preview release**. The ESP-BLE-AUDIO APIs, data structures, and configuration parameters are subject to change in future releases. Breaking changes — such as renamed or restructured types, modified function signatures, or removed fields — may be introduced without prior notice.
**Generic audio framework**
* **Common Audio Profile (CAP)** — Top-level profile for coordinating audio procedures across single or multiple devices.
* **Common Audio Service (CAS)** — GATT service companion to CAP; used for coordinated set member announcement.
* **Basic Audio Profile (BAP)** — Unicast and broadcast stream setup, codec configuration, and stream control.
* **Published Audio Capabilities Service (PACS)** — Advertising and negotiating audio capabilities.
* **Audio Stream Control Service (ASCS)** — Exposes sink/source audio endpoints on a BAP Unicast Server; used by the Unicast Client to configure and control streams.
* **Broadcast Audio Scan Service (BASS)** — Allows a Broadcast Assistant to offload BIS scanning from a low-power Scan Delegator.
* **Volume Control Profile (VCP)** — Volume control (VCS, VOCS, AICS).
* **Volume Offset Control Service (VOCS)** — Per-output volume offset.
* **Audio Input Control Service (AICS)** — Audio input (microphone) state and gain.
* **Microphone Control Profile (MICP)** — Microphone mute and gain (MICS).
* **Coordinated Set Identification Profile (CSIP)** — Set member identification for coordinated sets (e.g., left/right earbuds).
* **Media Control Profile (MCP)** — Media control (MCS).
* **Media Control Service (MCS)** — Media control service.
* **Call Control Profile (CCP)** — Call/telephony control (TBS).
* **Telephone Bearer Service (TBS)** — Telephony bearer and in-call control.
* **Media Proxy** — Media proxy service (Zephyr implementation component; not a Bluetooth SIG specification).
**Use case specific profiles**
* **Hearing Access Profile (HAP)** — Hearing aid presets and presets control.
* **Gaming Audio Profile (GMAP)** — Gaming audio (e.g. Unicast Game Gateway/Terminal, Broadcast Game Sender/Receiver).
* **Telephony and Media Audio Profile (TMAP)** — Interoperability configurations for telephony and media audio use cases.
* **Public Broadcast Profile (PBP)** — Discovery and subscription to public broadcast streams.
Application Examples
--------------------
* **BAP (Basic Audio Profile)**
* :example:`bluetooth/esp_ble_audio/bap/broadcast_sink` demonstrates how to act as a BAP Broadcast Sink that synchronizes to a broadcast source and receives BIS audio streams.
* :example:`bluetooth/esp_ble_audio/bap/broadcast_source` demonstrates how to act as a BAP Broadcast Source that creates a BIG and sends broadcast audio over BIS.
* :example:`bluetooth/esp_ble_audio/bap/unicast_client` demonstrates how to discover and connect to a unicast server and establish BAP unicast streams.
* :example:`bluetooth/esp_ble_audio/bap/unicast_server` demonstrates how to advertise and accept unicast connections and serve BAP unicast streams.
* **CAP (Common Audio Profile)**
* :example:`bluetooth/esp_ble_audio/cap/acceptor` demonstrates how to act as a CAP Acceptor for unicast and broadcast flows.
* :example:`bluetooth/esp_ble_audio/cap/initiator` demonstrates how to act as a CAP Initiator for unicast and broadcast flows.
* **TMAP (Telephony and Media Audio Profile)**
* :example:`bluetooth/esp_ble_audio/tmap/bmr` demonstrates the TMAP Broadcast Media Receiver (BMR) role that receives broadcast audio from a BMS.
* :example:`bluetooth/esp_ble_audio/tmap/bms` demonstrates the TMAP Broadcast Media Sender (BMS) role that sends broadcast audio.
* :example:`bluetooth/esp_ble_audio/tmap/central` demonstrates the TMAP Call Gateway (CG) and Unicast Media Sender (UMS) roles.
* :example:`bluetooth/esp_ble_audio/tmap/peripheral` demonstrates the TMAP Call Terminal (CT) and Unicast Media Receiver (UMR) roles.
API Reference
-------------
ESP-BLE-AUDIO APIs are divided into the following parts:
* `Definitions <ESP-BLE-AUDIO Definitions_>`_
* `General Definitions`_
* `LC3 Codec Definitions`_
* `MCS Definitions`_
* `BAP LC3 Preset Definitions`_
* `GMAP LC3 Preset Definitions`_
* `API <ESP-BLE-AUDIO API_>`_
* `Common API`_
* `Codec API`_
* `Common Audio Profile (CAP)`_
* `Call Control Profile (CCP)`_
* `Basic Audio Profile (BAP)`_
* `Published Audio Capabilities (PACS)`_
* `Gaming Audio Profile (GMAP)`_
* `Volume Control Profile (VCP)`_
* `Volume Offset Control Service (VOCS)`_
* `Audio Input Control Service (AICS)`_
* `Microphone Control Profile (MICP)`_
* `Hearing Access Profile (HAP)`_
* `Coordinated Set Identification Profile (CSIP)`_
* `Telephone Bearer Service (TBS)`_
* `Media Control Client (MCC)`_
* `Media Proxy`_
* `Telephony and Media Audio Profile (TMAP)`_
* `Public Broadcast Profile (PBP)`_
ESP-BLE-AUDIO Definitions
-------------------------
This section contains common definitions, constants, and types used across LE Audio.
General Definitions
^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_defs.inc
LC3 Codec Definitions
^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_lc3_defs.inc
MCS Definitions
^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_mcs_defs.inc
BAP LC3 Preset Definitions
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_bap_lc3_preset_defs.inc
GMAP LC3 Preset Definitions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_gmap_lc3_preset_defs.inc
ESP-BLE-AUDIO API
-----------------
This section contains LE Audio APIs: common helpers, codec, Common Audio Profile (CAP), Call Control Profile (CCP), and all profile/service APIs.
Common API
^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_common_api.inc
Codec API
^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_codec_api.inc
Common Audio Profile (CAP)
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_cap_api.inc
Call Control Profile (CCP)
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_ccp_api.inc
Basic Audio Profile (BAP)
^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_bap_api.inc
Published Audio Capabilities (PACS)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_pacs_api.inc
Gaming Audio Profile (GMAP)
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_gmap_api.inc
Volume Control Profile (VCP)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_vcp_api.inc
Volume Offset Control Service (VOCS)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_vocs_api.inc
Audio Input Control Service (AICS)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_aics_api.inc
Microphone Control Profile (MICP)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_micp_api.inc
Hearing Access Profile (HAP)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_has_api.inc
Coordinated Set Identification Profile (CSIP)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_csip_api.inc
Telephone Bearer Service (TBS)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_tbs_api.inc
Media Control Client (MCC)
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_mcc_api.inc
Media Proxy
^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_media_proxy_api.inc
Telephony and Media Audio Profile (TMAP)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_tmap_api.inc
Public Broadcast Profile (PBP)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_audio_pbp_api.inc
docs/en/api-reference/bluetooth/esp-ble-iso.rst
+43
View File
@@ -0,0 +1,43 @@
ESP-BLE-ISO
===========
ESP-BLE-ISO provides APIs for Bluetooth LE Isochronous Channels, enabling time-synchronized, connection-oriented (CIS) and connectionless (BIS) streaming. The implementation is built on the Bluetooth controller ISO support and is intended for use with the :doc:`esp-ble-audio` component.
**Channel types**
* **Connected Isochronous Streams (CIS)** — Bidirectional isochronous links between two devices; requires a prior ACL connection to be established. Used for time-synchronized unicast audio (e.g., LE Audio).
* **Broadcast Isochronous Streams (BIS)** — Unidirectional isochronous streams from a Broadcaster to one or more Synchronized Receivers, without a prior connection. Used for broadcast audio and group listening.
With these APIs you can create or join Connected ISO Groups (CIG), create or synchronize to Broadcast ISO Groups (BIG), set up ISO data paths, and send or receive isochronous data (e.g., LC3 audio). For higher-level LE Audio profiles and codec APIs, see :doc:`esp-ble-audio`.
For an architectural overview and integration details, see the :doc:`Bluetooth LE Audio documentation <../../api-guides/esp-ble-audio/ble-audio-index>`, in particular the :doc:`ESP-BLE-ISO architecture <../../api-guides/esp-ble-audio/ble-audio-architecture-iso>`.
.. warning::
This is a **preview release**. The ESP-BLE-ISO APIs, data structures, and configuration parameters are subject to change in future releases. Breaking changes — such as renamed or restructured types, modified function signatures, or removed fields — may be introduced without prior notice.
Application Examples
--------------------
* **BIG (Broadcast Isochronous Group)**
- :example:`bluetooth/esp_ble_iso/big_broadcaster` demonstrates how to create a BIG and send isochronous data over BIS.
- :example:`bluetooth/esp_ble_iso/big_receiver` demonstrates how to synchronize to a BIG and receive isochronous data from BIS.
* **CIS (Connected Isochronous Stream)**
- :example:`bluetooth/esp_ble_iso/cis_central` demonstrates how to act as a CIS Central that creates a CIG/CIS and sends isochronous data.
- :example:`bluetooth/esp_ble_iso/cis_peripheral` demonstrates how to act as a CIS Peripheral that accepts a CIS and receives isochronous data.
API Reference
-------------
ESP-BLE-ISO APIs are divided into the following parts:
* `ESP-BLE-ISO Common API`_
ESP-BLE-ISO Common API
----------------------
This section contains macros, type definitions, and functions from ``esp_ble_iso_common_api.h``: BIS index and data path macros, controller delay and interval limits, CIG/BIG parameters and structures, ISO server and channel operations, data path setup, BIG create/sync/terminate, and GAP event types and ISO common initialization.
.. include-build-file:: inc/esp_ble_iso_common_api.inc
docs/en/api-reference/bluetooth/esp-ble-mesh.rst
+239
View File
@@ -0,0 +1,239 @@
ESP-BLE-MESH
============
.. note::
The current ESP-BLE-MESH v1.1 related code is a preview version, so the Mesh Protocol v1.1 related Structures, MACROs, and APIs involved in the code may be changed.
With various features of ESP-BLE-MESH, users can create a managed flooding mesh network for several scenarios, such as lighting, sensor and etc.
For an ESP32 to join and work on a ESP-BLE-MESH network, it must be provisioned firstly. By provisioning, the ESP32, as an unprovisioned device, will join the ESP-BLE-MESH network and become a ESP-BLE-MESH node, communicating with other nodes within or beyond the radio range.
Apart from ESP-BLE-MESH nodes, inside ESP-BLE-MESH network, there is also ESP32 that works as ESP-BLE-MESH provisioner, which could provision unprovisioned devices into ESP-BLE-MESH nodes and configure the nodes with various features.
For information how to start using ESP32 and ESP-BLE-MESH, please see the Section :ref:`getting-started-with-ble-mesh`. If you are interested in information on ESP-BLE-MESH architecture, including some details of software implementation, please see Section :doc:`../../api-guides/esp-ble-mesh/ble-mesh-architecture`.
Application Examples and Demos
------------------------------
Please refer to Sections :ref:`esp-ble-mesh-examples` and :ref:`esp-ble-mesh-demo-videos`.
API Reference
-------------
ESP-BLE-MESH APIs are divided into the following parts:
* `ESP-BLE-MESH Definitions`_
* `ESP-BLE-MESH Core API Reference`_
* `ESP-BLE-MESH Models API Reference`_
* `ESP-BLE-MESH (v1.1) Core API Reference`_
ESP-BLE-MESH Definitions
------------------------
This section contains only one header file, which lists the following items of ESP-BLE-MESH.
* ID of all the models and related message opcodes
* Structs of model, element and Composition Data
* Structs of used by ESP-BLE-MESH Node/Provisioner for provisioning
* Structs used to transmit/receive messages
* Event types and related event parameters
.. include-build-file:: inc/esp_ble_mesh_defs.inc
ESP-BLE-MESH Core API Reference
-------------------------------
This section contains ESP-BLE-MESH Core related APIs, which can be used to initialize ESP-BLE-MESH stack, provision, send/publish messages, etc.
This API reference covers six components:
* `ESP-BLE-MESH Stack Initialization`_
* `Reading of Local Data Information`_
* `Low Power Operation (Updating)`_
* `Send/Publish Messages, add Local AppKey, etc.`_
* `ESP-BLE-MESH Node/Provisioner Provisioning`_
* `ESP-BLE-MESH GATT Proxy Server`_
ESP-BLE-MESH Stack Initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_common_api.inc
Reading of Local Data Information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_local_data_operation_api.inc
Coexist with BLE
.. include-build-file:: inc/esp_ble_mesh_ble_api.inc
Low Power Operation (Updating)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_low_power_api.inc
Send/Publish Messages, Add Local AppKey, Etc.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_networking_api.inc
ESP-BLE-MESH Node/Provisioner Provisioning
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_provisioning_api.inc
ESP-BLE-MESH GATT Proxy Server
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_proxy_api.inc
ESP-BLE-MESH Models API Reference
---------------------------------
This section contains ESP-BLE-MESH Model related APIs, event types, event parameters, etc.
There are six categories of models:
* `Configuration Client/Server Models`_
* `Health Client/Server Models`_
* `Generic Client/Server Models`_
* `Sensor Client/Server Models`_
* `Time and Scenes Client/Server Models`_
* `Lighting Client/Server Models`_
.. note::
Definitions related to Server Models are being updated, and will be released soon.
Configuration Client/Server Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_config_model_api.inc
Health Client/Server Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_health_model_api.inc
Generic Client/Server Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_generic_model_api.inc
Sensor Client/Server Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_sensor_model_api.inc
Time and Scenes Client/Server Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_time_scene_model_api.inc
Lighting Client/Server Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_lighting_model_api.inc
ESP-BLE-MESH (v1.1) Core API Reference
--------------------------------------
.. note::
This section is a preview version, so the related structures, macros, and APIs may be changed.
This section contains ESP-BLE-MESH v1.1 Core related APIs, event types, event parameters, etc.
This API reference covers 10 components:
* `Remote Provisioning`_
* `Directed Forwarding`_
* `Subnet Bridge Configuration`_
* `Mesh Private Beacon`_
* `On-Demand Private Proxy`_
* `SAR Configuration`_
* `Solicitation PDU RPL Configuration`_
* `Opcodes Aggregator`_
* `Large Composition Data`_
* `Composition and Metadata`_
Remote Provisioning
^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_rpr_model_api.inc
Directed Forwarding
^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_df_model_api.inc
Subnet Bridge Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_brc_model_api.inc
Mesh Private Beacon
^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_prb_model_api.inc
On-Demand Private Proxy
^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_odp_model_api.inc
SAR Configuration
^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_sar_model_api.inc
Solicitation PDU RPL Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_srpl_model_api.inc
Opcodes Aggregator
^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_agg_model_api.inc
Large Composition Data
^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_lcd_model_api.inc
Composition and Metadata
^^^^^^^^^^^^^^^^^^^^^^^^
.. include-build-file:: inc/esp_ble_mesh_cm_data_api.inc
Device Firmware Update
.. include-build-file:: inc/esp_ble_mesh_dfu_model_api.inc
Device Firmware Slots
.. include-build-file:: inc/esp_ble_mesh_dfu_slot_api.inc
docs/en/api-reference/bluetooth/esp_a2dp.rst
+25
View File
@@ -0,0 +1,25 @@
Bluetooth® A2DP API
===================
Overview
--------
A2DP (Advanced Audio Distribution Profile) enables high-quality audio streaming from one device to another over Bluetooth. It is primarily used for streaming audio from source devices such as smartphones, computers, and media players to sink devices such as Bluetooth speakers, headphones, and car audio systems. Users can use the A2DP APIs to transmit or receive audio streams.
Application Examples
--------------------
- :example:`bluetooth/bluedroid/classic_bt/a2dp_sink_stream` demonstrates how to implement an audio sink device using the Advanced Audio Distribution Profile (A2DP) to receive audio streams. This example also shows how to use I2S for audio stream output.
- :example:`bluetooth/bluedroid/classic_bt/a2dp_source` demonstrates how to use A2DP APIs to transmit audio streams.
- :example:`bluetooth/bluedroid/classic_bt/a2dp_sink_stream_aac` demonstrates how to use the AAC codec in an A2DP sink.
- :example:`bluetooth/bluedroid/classic_bt/a2dp_source_aac` demonstrates how to use the AAC codec in an A2DP source.
- :example:`bluetooth/bluedroid/coex/a2dp_gatts_coex` demonstrates how to use the ESP-IDF A2DP-GATTS_COEX demo to create a GATT service and A2DP profile.
API Reference
-------------
.. include-build-file:: inc/esp_a2dp_api.inc
docs/en/api-reference/bluetooth/esp_avrc.rst
+23
View File
@@ -0,0 +1,23 @@
Bluetooth® AVRCP API
====================
Overview
--------
AVRCP (Audio/Video Remote Control Profile) enables remote control of audio and video devices over Bluetooth, allowing users to manage playback (play, pause, next/previous track), adjust volume, and retrieve media metadata.
Application Examples
--------------------
- :example:`bluetooth/bluedroid/classic_bt/avrcp_absolute_volume` demonstrates how to implement Audio/Video Remote Control Profile to control absolute volume.
- :example:`bluetooth/bluedroid/classic_bt/avrcp_ct_metadata` demonstrates how to implement Audio/Video Remote Control Profile to get metadata.
- :example:`bluetooth/bluedroid/classic_bt/avrcp_ct_cover_art` demonstrates how to implement Audio/Video Remote Control Profile to get and display cover art image.
API Reference
-------------
.. include-build-file:: inc/esp_avrc_api.inc
docs/en/api-reference/bluetooth/esp_blufi.rst
+22
View File
@@ -0,0 +1,22 @@
BluFi API
=========
Overview
--------
BluFi is a profile based GATT to config ESP32 Wi-Fi to connect/disconnect AP or setup a softap and etc.
Use should concern these things:
1. The event sent from profile. Then you need to do something as the event indicate.
2. Security reference. You can write your own Security functions such as symmetrical encryption/decryption and checksum functions. Even you can define the "Key Exchange/Negotiation" procedure.
Application Examples
--------------------
- :example:`bluetooth/blufi` how to use the Blufi function to configure the Wi-Fi connection to an AP via a Bluetooth channel on {IDF_TARGET_NAME}.
API Reference
-------------
.. include-build-file:: inc/esp_blufi_api.inc
docs/en/api-reference/bluetooth/esp_bt_defs.rst
+8
View File
@@ -0,0 +1,8 @@
Bluetooth® Generic Defines
==========================
API Reference
-------------
.. include-build-file:: inc/esp_bt_defs.inc
docs/en/api-reference/bluetooth/esp_bt_device.rst
+19
View File
@@ -0,0 +1,19 @@
Bluetooth® Device APIs
======================
Overview
--------
Bluetooth device reference APIs.
.. only:: esp32
Application Examples
--------------------
- :example:`bluetooth/bluedroid/classic_bt/bt_spp_vfs_acceptor` demonstrates how to use Serial Port Protocol (SPP) APIs to create an SPP acceptor that acts as a server and registers into the VFS. It also shows how to implement Secure Simple Pairing (SSP) in your own applications.
API Reference
-------------
.. include-build-file:: inc/esp_bt_device.inc
docs/en/api-reference/bluetooth/esp_bt_main.rst
+9
View File
@@ -0,0 +1,9 @@
Bluetooth® Main API
===================
API Reference
-------------
.. include-build-file:: inc/esp_bt_main.inc
docs/en/api-reference/bluetooth/esp_gap_ble.rst
+16
View File
@@ -0,0 +1,16 @@
GAP API
=======
:link_to_translation:`zh_CN:[中文]`
Application Examples
--------------------
- :example:`bluetooth/bluedroid/ble/gatt_security_client` demonstrates how to use ESP BLE security APIs on {IDF_TARGET_NAME} to establish a secure connection and encrypt communication with peer devices while acting as a GATT client.
- :example:`bluetooth/bluedroid/ble/gatt_security_server` demonstrates how to use ESP BLE security APIs on {IDF_TARGET_NAME} to establish a secure connection and encrypt communication with peer devices while acting as a GATT server.
API Reference
-------------
.. include-build-file:: inc/esp_gap_ble_api.inc
docs/en/api-reference/bluetooth/esp_gap_bt.rst
+17
View File
@@ -0,0 +1,17 @@
Bluetooth® Classic GAP API
==========================
Overview
--------
The Bluetooth Classic GAP (Generic Access Profile) API provides interfaces for device discovery, pairing, and security management, allowing applications to control visibility, initiate connections, and configure authentication and encryption for Bluetooth Classic links.
Application Examples
--------------------
- :example:`bluetooth/bluedroid/classic_bt/bt_discovery` demonstrates how to use APIs to search for a target device with a Major device type of "Phone" or "Audio/Video" in the Class of Device field, and then perform a service discovery via the Service Discovery Protocol.
API Reference
-------------
.. include-build-file:: inc/esp_gap_bt_api.inc
docs/en/api-reference/bluetooth/esp_gatt_defs.rst
+9
View File
@@ -0,0 +1,9 @@
GATT Defines
============
API Reference
-------------
.. include-build-file:: inc/esp_gatt_defs.inc
docs/en/api-reference/bluetooth/esp_gattc.rst
+17
View File
@@ -0,0 +1,17 @@
GATT Client API
===============
Application Examples
--------------------
- :example:`bluetooth/bluedroid/ble/gatt_client` demonstrates how to create a GATT Client that connects to a GATT server, enabling the server's notification function to discover its service.
- :example:`bluetooth/bluedroid/ble/gattc_multi_connect` demonstrates how to create a GATT Client that connects to multiple GATT servers, enabling their notification functions to discover their services.
- :example:`bluetooth/bluedroid/coex/gattc_gatts_coex` demonstrates the coexistence of GATT client and GATT server by creating a GATT service, starting ADV, and exchanging data between a GATT client and device.
API Reference
-------------
.. include-build-file:: inc/esp_gattc_api.inc
docs/en/api-reference/bluetooth/esp_gatts.rst
+16
View File
@@ -0,0 +1,16 @@
GATT Server API
===============
:link_to_translation:`zh_CN:[中文]`
Application Examples
--------------------
- :example:`bluetooth/bluedroid/ble/gatt_server_service_table` demonstrates how to create a GATT service using an attribute table, releasing the user from adding attributes individually.
- :example:`bluetooth/bluedroid/ble/gatt_server` demonstrates how to create a GATT service by adding attributes individually and then starts advertising so that a GATT client can connect and exchange data.
API Reference
-------------
.. include-build-file:: inc/esp_gatts_api.inc
docs/en/api-reference/bluetooth/esp_hf_ag.rst
+17
View File
@@ -0,0 +1,17 @@
Bluetooth® HFP AG API
=====================
Overview
--------
HFP (Hands-Free Profile) AG API provides functions for a Bluetooth device to act as an Audio Gateway (AG), enabling communication with HFP Client devices such as headsets or car kits. It supports connection management, call handling, volume control, and other hands-free operations.
Application Examples
--------------------
- :example:`bluetooth/bluedroid/classic_bt/hfp_ag` demonstrates how to use the Hands-Free Audio Gateway (HF-AG) component to communicate with a device that implements Hands-Free Client Role, such as a headphone set. It provides commands for configuring the project, establishing connections, controlling volume, and answering or rejecting calls.
API Reference
-------------
.. include-build-file:: inc/esp_hf_ag_api.inc
docs/en/api-reference/bluetooth/esp_hf_client.rst
+17
View File
@@ -0,0 +1,17 @@
Bluetooth® HFP Client API
=========================
Overview
--------
HFP (Hands-Free Profile) Client API provides functions to enable a Bluetooth device to act as an HFP Client, allowing communication with an Audio Gateway (AG) device, such as a smartphone, to handle voice calls, volume control, and other hands-free operations.
Application Examples
--------------------
- :example:`bluetooth/bluedroid/classic_bt/hfp_hf` demonstrates how to use the Hands-Free Client Component to communicate with a device that implements Hands-Free Audio Gateway (HF-AG), such as a smartphone.
API Reference
-------------
.. include-build-file:: inc/esp_hf_client_api.inc
docs/en/api-reference/bluetooth/esp_hf_defs.rst
+21
View File
@@ -0,0 +1,21 @@
Bluetooth® HFP Defines
======================
Overview
--------
This file contains definitions for constants, enumerations, and structures used in the Bluetooth Hands-Free Profile (HFP), enabling features like call management, audio control, and network status reporting.
Application Examples
--------------------
- :example:`bluetooth/bluedroid/classic_bt/hfp_hf` demonstrates how to use the Hands-Free Client Component to communicate with a device that implements Hands-Free Audio Gateway (HF-AG), such as a smartphone.
- :example:`bluetooth/bluedroid/classic_bt/hfp_ag` demonstrates how to use the Hands-Free Audio Gateway (HF-AG) component to communicate with a device that implements Hands-Free Client Role, such as a headphone set. It provides commands for configuring the project, establishing connections, controlling volume, and answering or rejecting calls.
API Reference
-------------
.. include-build-file:: inc/esp_hf_defs.inc
docs/en/api-reference/bluetooth/esp_hidd.rst
+19
View File
@@ -0,0 +1,19 @@
Bluetooth® HID Device API
=========================
Overview
--------
A Bluetooth HID device is a device providing the service of human or other data input and output to and from a Bluetooth HID Host. Users can use the Bluetooth HID Device APIs to make devices like keyboards, mice, joysticks and so on.
Application Examples
--------------------
- :example:`bluetooth/bluedroid/classic_bt/bt_hid_mouse_device` demonstrates how to implement a Bluetooth HID device by simulating a Bluetooth HID mouse device that periodically sends reports to a remote Bluetooth HID host.
- :example:`bluetooth/esp_hid_device` demonstrates how to create a Bluetooth Classic or Bluetooth LE HID device, which can function as a mouse or a remote control, depending on the mode set by the user.
API Reference
-------------
.. include-build-file:: inc/esp_hidd_api.inc
docs/en/api-reference/bluetooth/esp_hidh.rst
+17
View File
@@ -0,0 +1,17 @@
Bluetooth® HID Host API
========================
Overview
--------
A Bluetooth HID host is a device or software that is capable of connecting and communicating with Bluetooth HID devices, such as keyboards, mice. Users can use the Bluetooth HID Host APIs to send output data or control commands to the HID devices, enabling them to control the behavior or settings of the devices.
Application Examples
--------------------
- :example:`bluetooth/esp_hid_host` demonstrates how to use the ESP-IDF Bluetooth HID Host APIs to create a Bluetooth Classic, Bluetooth LE, or Bluetooth dual-mode HID host that scans and connects to the most recently discovered Bluetooth HID device, dumps the HID device information, and receives data sent by the HID device.
API Reference
-------------
.. include-build-file:: inc/esp_hidh_api.inc
docs/en/api-reference/bluetooth/esp_l2cap_bt.rst
+19
View File
@@ -0,0 +1,19 @@
Bluetooth® Classic L2CAP API
============================
Overview
--------
Bluetooth Classic L2CAP (Logical Link Control and Adaptation Layer Protocol) API provides functions for data transmission between Bluetooth devices. It supports both client and server roles, allowing the creation of L2CAP connections for reliable, high-throughput communication.
Application Examples
--------------------
- :example:`bluetooth/bluedroid/classic_bt/bt_l2cap_server` demonstrates how to use Logical Link Control and Adaptation Layer Protocol (L2CAP) APIs to create an L2CAP server, and wait to be discovered and connected by a remote device L2CAP client.
- :example:`bluetooth/bluedroid/classic_bt/bt_l2cap_client` demonstrates how to use L2CAP APIs to create an L2CAP client.
API Reference
-------------
.. include-build-file:: inc/esp_l2cap_bt_api.inc
docs/en/api-reference/bluetooth/esp_sdp.rst
+21
View File
@@ -0,0 +1,21 @@
Bluetooth® SDP API
==================
Overview
--------
SDP (Service Discovery Protocol) API enables devices to discover services and service attributes offered by remote Bluetooth devices. It supports service search, service attribute retrieval, and the establishment of service connections.
Application Examples
--------------------
- :example:`bluetooth/bluedroid/classic_bt/bt_l2cap_client` demonstrates how to use SDP APIs to search for services on remote Bluetooth devices. It shows how to register SDP callbacks, initialize SDP, perform service discovery using ``esp_sdp_search_record()``, and retrieve the L2CAP PSM (Protocol/Service Multiplexer) value from the search results to establish an L2CAP connection.
- :example:`bluetooth/bluedroid/classic_bt/bt_l2cap_server` demonstrates how to use SDP APIs to create and publish service records. It shows how to register SDP callbacks, initialize SDP, create an SDP record using ``esp_sdp_create_record()`` with L2CAP PSM information, making the service discoverable by remote clients.
API Reference
-------------
.. include-build-file:: inc/esp_sdp_api.inc
docs/en/api-reference/bluetooth/esp_spp.rst
+21
View File
@@ -0,0 +1,21 @@
Bluetooth® SPP API
==================
Overview
--------
SPP (Serial Port Profile) enables serial communication between Bluetooth devices, allowing them to exchange data over a virtual serial link. SPP API provides functionality to create both SPP initiators (clients) and acceptors (servers), enabling operation under different security requirements.
Application Examples
--------------------
- :example:`bluetooth/bluedroid/classic_bt/bt_spp_acceptor` demonstrates how to use Bluetooth capabilities to create a Serial Port Protocol (SPP) acceptor that acts as a server and integrate Secure Simple Pairing (SSP). This example also includes a demo for communicating with an SPP initiator that acts as a client.
- :example:`bluetooth/bluedroid/classic_bt/bt_spp_initiator` demonstrates how to use Bluetooth capabilities to create an SPP initiator that performs as a client and integrate SSP. This example also includes a demo for communicating with an SPP acceptor that acts as a server.
- :example:`bluetooth/bluedroid/classic_bt/bt_spp_vfs_initiator` demonstrates how to use SPP APIs to create an SPP initiator that acts as a client and communicates with an SPP acceptor, using Virtual File System (VFS) interface to send and receive data.
API Reference
-------------
.. include-build-file:: inc/esp_spp_api.inc
docs/en/api-reference/bluetooth/index.rst
+114
View File
@@ -0,0 +1,114 @@
Bluetooth\ :sup:`®` API
*****************************
:link_to_translation:`zh_CN:[中文]`
This section provides the API reference for Bluetooth components supported in ESP-IDF. ESP-IDF supports two host stacks: **Bluedroid** and **NimBLE**.
- **Bluedroid** (the default stack): Supports both Bluetooth Classic and Bluetooth LE. Recommended for applications that require both technologies.
- **NimBLE**: A lightweight stack for Bluetooth LE only. Ideal for resource-constrained applications due to smaller code size and memory usage.
Use the navigation links below to explore API documentation and application examples.
----
**Controller Interface API**
The low-level interface between the Bluetooth host stack and the controller.
.. toctree::
:maxdepth: 1
controller_vhci
**Bluedroid Stack API**
The default host stack in ESP-IDF, supporting both Bluetooth Classic and Bluetooth LE.
.. toctree::
:maxdepth: 1
bt_common
:SOC_BT_CLASSIC_SUPPORTED: classic_bt
bt_le
For architecture and feature overviews, refer to the following documents in API Guides:
.. only:: SOC_BT_CLASSIC_SUPPORTED
:doc:`../../api-guides/bt-architecture/index`, :doc:`../../api-guides/classic-bt/index`, :doc:`../../api-guides/ble/index`
.. only:: not SOC_BT_CLASSIC_SUPPORTED
:doc:`../../api-guides/bt-architecture/index`, :doc:`../../api-guides/ble/index`
**NimBLE Stack API**
A lightweight host stack for Bluetooth LE.
.. toctree::
:maxdepth: 1
nimble/index
For additional details and API reference from the upstream documentation, refer to `Apache Mynewt NimBLE User Guide <https://mynewt.apache.org/latest/network/index.html>`_.
.. only:: SOC_BLE_MESH_SUPPORTED
**ESP-BLE-MESH API**
Implements Bluetooth LE Mesh networking.
.. toctree::
:maxdepth: 1
esp-ble-mesh
.. only:: SOC_BLE_ISO_SUPPORTED
**ESP-BLE-ISO API**
Bluetooth LE Isochronous Channels (CIS/BIS) for LE Audio and time-synchronized streaming.
.. toctree::
:maxdepth: 1
esp-ble-iso
.. only:: SOC_BLE_AUDIO_SUPPORTED
**ESP-BLE-AUDIO API**
Bluetooth LE Audio profiles and services (BAP, PACS, VCP, HAS, CSIP, etc.).
.. toctree::
:maxdepth: 1
esp-ble-audio
----
Examples and Tutorials
----------------------
Explore examples and tutorials in the ESP-IDF examples directory:
- **Bluedroid**: :example:`bluetooth/bluedroid`
- **NimBLE**: :example:`bluetooth/nimble`
- **BLE UART Service** (turnkey serial-over-BLE peripheral on top of NimBLE or Bluedroid, exposing the BLE UART Service GATT layout): :example:`bluetooth/ble_uart_service`
Step-by-step tutorials for developing with the Bluedroid stack:
* :example_file:`GATT Client Example Walkthrough <bluetooth/bluedroid/ble/gatt_client/tutorial/Gatt_Client_Example_Walkthrough.md>`
* :example_file:`GATT Server Service Table Example Walkthrough <bluetooth/bluedroid/ble/gatt_server_service_table/tutorial/Gatt_Server_Service_Table_Example_Walkthrough.md>`
* :example_file:`GATT Server Example Walkthrough <bluetooth/bluedroid/ble/gatt_server/tutorial/Gatt_Server_Example_Walkthrough.md>`
* :example_file:`GATT Security Client Example Walkthrough <bluetooth/bluedroid/ble/gatt_security_client/tutorial/Gatt_Security_Client_Example_Walkthrough.md>`
* :example_file:`GATT Security Server Example Walkthrough <bluetooth/bluedroid/ble/gatt_security_server/tutorial/Gatt_Security_Server_Example_Walkthrough.md>`
* :example_file:`GATT Client Multi-connection Example Walkthrough <bluetooth/bluedroid/ble/gattc_multi_connect/tutorial/Gatt_Client_Multi_Connection_Example_Walkthrough.md>`
Step-by-step tutorials for developing with the NimBLE stack:
* :example_file:`Bluetooth LE Central Example Walkthrough <bluetooth/nimble/blecent/tutorial/blecent_walkthrough.md>`
* :example_file:`Bluetooth LE Heart Rate Example Walkthrough <bluetooth/nimble/blehr/tutorial/blehr_walkthrough.md>`
* :example_file:`Bluetooth LE Peripheral Example Walkthrough <bluetooth/nimble/bleprph/tutorial/bleprph_walkthrough.md>`
docs/en/api-reference/bluetooth/nimble/index.rst
+44
View File
@@ -0,0 +1,44 @@
NimBLE-based Host APIs
**********************
Overview
========
Apache MyNewt NimBLE is a highly configurable and Bluetooth® SIG qualifiable Bluetooth Low Energy (Bluetooth LE) stack providing both host and controller functionalities. ESP-IDF supports NimBLE host stack which is specifically ported for ESP32 platform and FreeRTOS. The underlying controller is still the same (as in case of Bluedroid) providing VHCI interface. Refer to `NimBLE user guide <https://mynewt.apache.org/latest/network/index.html>`_ for a complete list of features and additional information on NimBLE stack. Most features of NimBLE including Bluetooth Low Energy Mesh are supported by ESP-IDF. The porting layer is kept cleaner by maintaining all the existing APIs of NimBLE along with a single ESP-NimBLE API for initialization, making it simpler for the application developers.
Architecture
============
Currently, NimBLE host and controller support different transports such as UART and RAM between them. However, RAM transport cannot be used as is in case of ESP as ESP controller supports VHCI interface and buffering schemes used by NimBLE host is incompatible with that used by ESP controller. Therefore, a new transport between NimBLE host and ESP controller has been added. This is depicted in the figure below. This layer is responsible for maintaining pool of transport buffers and formatting buffers exchanges between host and controller as per the requirements.
.. figure:: ../../../../_static/esp32_nimble_stack.png
:align: center
:alt: ESP NimBLE Stack.
:scale: 50
ESP NimBLE Stack
Threading Model
===============
The NimBLE host can run inside the application thread or can have its own independent thread. This flexibility is inherently provided by NimBLE design. By default, a thread is spawned by the porting function ``nimble_port_freertos_init``. This behavior can be changed by overriding the same function. For Bluetooth Low Energy Mesh, additional thread (advertising thread) is used which keeps on feeding advertisement events to the main thread.
Programming Sequence
====================
To begin with, make sure that the NimBLE stack is enabled from menuconfig :ref:`choose NimBLE for the Bluetooth host <CONFIG_BT_HOST>`.
Typical programming sequence with NimBLE stack consists of the following steps:
* Initialize NVS flash using :cpp:func:`nvs_flash_init` API. This is because ESP controller uses NVS during initialization.
* Initialize the host and controller stack using ``nimble_port_init``.
* Initialize the required NimBLE host configuration parameters and callbacks
* Perform application specific tasks/initialization
* Run the thread for host stack using ``nimble_port_freertos_init``
This documentation does not cover NimBLE APIs. Refer to `NimBLE tutorial <https://mynewt.apache.org/latest/network/index.html#ble-user-guide>`_ for more details on the programming sequence/NimBLE APIs for different scenarios.
API Reference
=============
.. include-build-file:: inc/esp_nimble_hci.inc