Bluetooth A2DP API¶
Overview¶
Application Example¶
Check bluetooth/bluedroid/classic_bt folder in ESP-IDF examples, which contains the following application:
- This is a A2DP sink client demo. This demo can be discovered and connected by A2DP source device and receive the audio stream from remote device - bluetooth/bluedroid/classic_bt/a2dp_sink
API Reference¶
Functions¶
-
esp_err_t
esp_a2d_register_callback
(esp_a2d_cb_t callback)¶ Register application callback function to A2DP module. This function should be called only after esp_bluedroid_enable() completes successfully, used by both A2DP source and sink.
- Return
- ESP_OK: success
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: if callback is a NULL function pointer
- Parameters
callback
: A2DP event callback function
-
esp_err_t
esp_a2d_sink_register_data_callback
(esp_a2d_sink_data_cb_t callback)¶ Register A2DP sink data output function; For now the output is PCM data stream decoded from SBC format. This function should be called only after esp_bluedroid_enable() completes successfully, used only by A2DP sink. The callback is invoked in the context of A2DP sink task whose stack size is configurable through menuconfig.
- Return
- ESP_OK: success
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: if callback is a NULL function pointer
- Parameters
callback
: A2DP sink data callback function
-
esp_err_t
esp_a2d_sink_init
(void)¶ Initialize the bluetooth A2DP sink module. This function should be called after esp_bluedroid_enable() completes successfully.
- Return
- ESP_OK: if the initialization request is sent successfully
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
-
esp_err_t
esp_a2d_sink_deinit
(void)¶ De-initialize for A2DP sink module. This function should be called only after esp_bluedroid_enable() completes successfully.
- Return
- ESP_OK: success
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
-
esp_err_t
esp_a2d_sink_connect
(esp_bd_addr_t remote_bda)¶ Connect to remote bluetooth A2DP source device, must after esp_a2d_sink_init()
- Return
- ESP_OK: connect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_bda
: remote bluetooth device address
-
esp_err_t
esp_a2d_sink_disconnect
(esp_bd_addr_t remote_bda)¶ Disconnect from the remote A2DP source device.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_bda
: remote bluetooth device address
-
esp_err_t
esp_a2d_media_ctrl
(esp_a2d_media_ctrl_t ctrl)¶ media control commands; this API can be used for both A2DP sink and source
- Return
- ESP_OK: control command is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
ctrl
: control commands for A2DP data channel
-
esp_err_t
esp_a2d_source_init
(void)¶ Initialize the bluetooth A2DP source module. This function should be called after esp_bluedroid_enable() completes successfully.
- Return
- ESP_OK: if the initialization request is sent successfully
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
-
esp_err_t
esp_a2d_source_deinit
(void)¶ De-initialize for A2DP source module. This function should be called only after esp_bluedroid_enable() completes successfully.
- Return
- ESP_OK: success
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
-
esp_err_t
esp_a2d_source_register_data_callback
(esp_a2d_source_data_cb_t callback)¶ Register A2DP source data input function; For now the input is PCM data stream. This function should be called only after esp_bluedroid_enable() completes successfully. The callback is invoked in the context of A2DP source task whose stack size is configurable through menuconfig.
- Return
- ESP_OK: success
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: if callback is a NULL function pointer
- Parameters
callback
: A2DP source data callback function
-
esp_err_t
esp_a2d_source_connect
(esp_bd_addr_t remote_bda)¶ Connect to remote A2DP sink device, must after esp_a2d_source_init()
- Return
- ESP_OK: connect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_bda
: remote bluetooth device address
-
esp_err_t
esp_a2d_source_disconnect
(esp_bd_addr_t remote_bda)¶ Disconnect from the remote A2DP sink device.
- Return
- ESP_OK: disconnect request is sent to lower layer
- ESP_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
- Parameters
remote_bda
: remote bluetooth device address
Unions¶
-
union
esp_a2d_cb_param_t
¶ - #include <esp_a2dp_api.h>
A2DP state callback parameters.
Public Members
-
struct esp_a2d_cb_param_t::a2d_conn_stat_param
conn_stat
¶ A2DP connection status
-
struct esp_a2d_cb_param_t::a2d_audio_stat_param
audio_stat
¶ audio stream playing state
-
struct esp_a2d_cb_param_t::a2d_audio_cfg_param
audio_cfg
¶ media codec configuration information
-
struct esp_a2d_cb_param_t::media_ctrl_stat_param
media_ctrl_stat
¶ status in acknowledgement to media control commands
-
struct
a2d_audio_cfg_param
¶ - #include <esp_a2dp_api.h>
ESP_A2D_AUDIO_CFG_EVT.
Public Members
-
esp_bd_addr_t
remote_bda
¶ remote bluetooth device address
-
esp_a2d_mcc_t
mcc
¶ A2DP media codec capability information
-
esp_bd_addr_t
-
struct
a2d_audio_stat_param
¶ - #include <esp_a2dp_api.h>
ESP_A2D_AUDIO_STATE_EVT.
Public Members
-
esp_a2d_audio_state_t
state
¶ one of the values from esp_a2d_audio_state_t
-
esp_bd_addr_t
remote_bda
¶ remote bluetooth device address
-
esp_a2d_audio_state_t
-
struct
a2d_conn_stat_param
¶ - #include <esp_a2dp_api.h>
ESP_A2D_CONNECTION_STATE_EVT.
Public Members
-
esp_a2d_connection_state_t
state
¶ one of values from esp_a2d_connection_state_t
-
esp_bd_addr_t
remote_bda
¶ remote bluetooth device address
-
esp_a2d_disc_rsn_t
disc_rsn
¶ reason of disconnection for “DISCONNECTED”
-
esp_a2d_connection_state_t
-
struct
media_ctrl_stat_param
¶ - #include <esp_a2dp_api.h>
ESP_A2D_MEDIA_CTRL_ACK_EVT.
Public Members
-
esp_a2d_media_ctrl_t
cmd
¶ media control commands to acknowledge
-
esp_a2d_media_ctrl_ack_t
status
¶ acknowledgement to media control commands
-
esp_a2d_media_ctrl_t
-
struct esp_a2d_cb_param_t::a2d_conn_stat_param
Structures¶
-
struct
esp_a2d_mcc_t
¶ A2DP media codec capabilities union.
Public Members
-
esp_a2d_mct_t
type
¶ A2DP media codec type
-
union esp_a2d_mcc_t::[anonymous]
cie
¶ A2DP codec information element
-
esp_a2d_mct_t
Macros¶
-
ESP_A2D_MCT_SBC
¶ Media codec types supported by A2DP.
SBC
-
ESP_A2D_MCT_M12
¶ MPEG-1, 2 Audio
-
ESP_A2D_MCT_M24
¶ MPEG-2, 4 AAC
-
ESP_A2D_MCT_ATRAC
¶ ATRAC family
-
ESP_A2D_MCT_NON_A2DP
¶
-
ESP_A2D_CIE_LEN_SBC
¶
-
ESP_A2D_CIE_LEN_M12
¶
-
ESP_A2D_CIE_LEN_M24
¶
-
ESP_A2D_CIE_LEN_ATRAC
¶
Type Definitions¶
-
typedef uint8_t
esp_a2d_mct_t
¶
-
typedef void (*
esp_a2d_cb_t
)(esp_a2d_cb_event_t event, esp_a2d_cb_param_t *param)¶ A2DP profile callback function type.
- Parameters
event
: : Event typeparam
: : Pointer to callback parameter
-
typedef void (*
esp_a2d_sink_data_cb_t
)(const uint8_t *buf, uint32_t len)¶ A2DP profile data callback function.
- Parameters
buf
: : data received from A2DP source device and is PCM format decoder from SBC decoder; buf references to a static memory block and can be overwritten by upcoming datalen
: : size(in bytes) in buf
-
typedef int32_t (*
esp_a2d_source_data_cb_t
)(uint8_t *buf, int32_t len)¶ A2DP source data read callback function.
- Return
- size of bytes read successfully, if the argument len is -1, this value is ignored.
- Parameters
buf
: : buffer to be filled with PCM data stream from higher layerlen
: : size(in bytes) of data block to be copied to buf. -1 is an indication to user that data buffer shall be flushed
Enumerations¶
-
enum
esp_a2d_connection_state_t
¶ Bluetooth A2DP connection states.
Values:
-
ESP_A2D_CONNECTION_STATE_DISCONNECTED
= 0¶ connection released
-
ESP_A2D_CONNECTION_STATE_CONNECTING
¶ connecting remote device
-
ESP_A2D_CONNECTION_STATE_CONNECTED
¶ connection established
-
ESP_A2D_CONNECTION_STATE_DISCONNECTING
¶ disconnecting remote device
-
-
enum
esp_a2d_disc_rsn_t
¶ Bluetooth A2DP disconnection reason.
Values:
-
ESP_A2D_DISC_RSN_NORMAL
= 0¶ Finished disconnection that is initiated by local or remote device
-
ESP_A2D_DISC_RSN_ABNORMAL
¶ Abnormal disconnection caused by signal loss
-
-
enum
esp_a2d_audio_state_t
¶ Bluetooth A2DP datapath states.
Values:
-
ESP_A2D_AUDIO_STATE_REMOTE_SUSPEND
= 0¶ audio stream datapath suspended by remote device
-
ESP_A2D_AUDIO_STATE_STOPPED
¶ audio stream datapath stopped
-
ESP_A2D_AUDIO_STATE_STARTED
¶ audio stream datapath started
-
-
enum
esp_a2d_media_ctrl_ack_t
¶ A2DP media control command acknowledgement code.
Values:
-
ESP_A2D_MEDIA_CTRL_ACK_SUCCESS
= 0¶ media control command is acknowledged with success
-
ESP_A2D_MEDIA_CTRL_ACK_FAILURE
¶ media control command is acknowledged with failure
-
ESP_A2D_MEDIA_CTRL_ACK_BUSY
¶ media control command is rejected, as previous command is not yet acknowledged
-
-
enum
esp_a2d_media_ctrl_t
¶ A2DP media control commands.
Values:
-
ESP_A2D_MEDIA_CTRL_NONE
= 0¶ dummy command
-
ESP_A2D_MEDIA_CTRL_CHECK_SRC_RDY
¶ check whether AVDTP is connected, only used in A2DP source
-
ESP_A2D_MEDIA_CTRL_START
¶ command to set up media transmission channel
-
ESP_A2D_MEDIA_CTRL_STOP
¶ command to stop media transmission
-
ESP_A2D_MEDIA_CTRL_SUSPEND
¶ command to suspend media transmission
-
-
enum
esp_a2d_cb_event_t
¶ A2DP callback events.
Values:
-
ESP_A2D_CONNECTION_STATE_EVT
= 0¶ connection state changed event
-
ESP_A2D_AUDIO_STATE_EVT
¶ audio stream transmission state changed event
-
ESP_A2D_AUDIO_CFG_EVT
¶ audio codec is configured, only used for A2DP SINK
-
ESP_A2D_MEDIA_CTRL_ACK_EVT
¶ acknowledge event in response to media control commands
-