Merge branch 'docs/update_bt_api_ref_v6.0' into 'release/v6.0'

docs(bt): update Classic Bluetooth api reference(v6.0) See merge request espressif/esp-idf!44993
2026-10-02 03:00:34 +03:00 · 2026-01-28 19:05:49 +08:00
parent 2761bd1889 74fa9f7945
commit 8f8730d673
26 changed files with 366 additions and 280 deletions
@@ -1,6 +1,11 @@
 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
 --------------------

@@ -1,10 +1,10 @@
-Bluetooth® AVRCP APIs
-=====================
+Bluetooth® AVRCP API
+====================

 Overview
 --------

-Bluetooth AVRCP reference APIs.
+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
 --------------------
@@ -1,6 +1,11 @@
-Classic Bluetooth® GAP API
+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
 --------------------

@@ -1,5 +1,10 @@
-HFP AG API
-==============
+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
 --------------------
@@ -1,5 +1,10 @@
-HFP Client API
-==============
+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
 --------------------
@@ -1,5 +1,17 @@
-HFP Defines
-===========
+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
 -------------
@@ -1,6 +1,11 @@
-Classic Bluetooth® L2CAP API
+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
 --------------------

@@ -1,10 +1,17 @@
-Bluetooth® SDP APIs
-===================
+Bluetooth® SDP API
+==================

 Overview
 --------

-Bluetooth SDP reference APIs.
+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
 -------------
@@ -1,5 +1,10 @@
-SPP API
-=======
+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
 --------------------
@@ -48,3 +48,5 @@ Bluedroid
        - Field ``ESP_A2D_MEDIA_CTRL_STOP`` is removed in structure ``esp_a2d_media_ctrl_t``, and is replaced by ``ESP_A2D_MEDIA_CTRL_SUSPEND``.

        - Field ``sbc, m12, m24 and atrac`` is removed and replaced by ``sbc_info, m12_info, m24_info and atrc_info`` in structure ``esp_a2d_mcc_t``.
+
+        - Macro ``ESP_A2D_SBC_CIE_ALLOC_MTHD_SRN`` is renamed to ``ESP_A2D_SBC_CIE_ALLOC_MTHD_SNR``. The old macro is kept for backward compatibility, but it is deprecated and will emit a compile-time warning.