Bluetooth A2DP API¶
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
[in] 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
[in] 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, and ESP_A2D_PROF_STATE_EVT with ESP_A2D_INIT_SUCCESS will reported to the APP layer. Note: A2DP can work independently. If you want to use AVRC together, you should initiate AVRC first. 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, and ESP_A2D_PROF_STATE_EVT with ESP_A2D_DEINIT_SUCCESS will reported to APP layer.
- Return
ESP_OK: if the deinitialization request is sent successfully
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. This API must be called after esp_a2d_sink_init() and before esp_a2d_sink_deinit().
- Return
ESP_OK: connect request is sent to lower layer successfully
ESP_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others
- Parameters
[in] 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. This API must be called after esp_a2d_sink_init() and before esp_a2d_sink_deinit().
- Return
ESP_OK: disconnect request is sent to lower layer successfully
ESP_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others
- Parameters
[in] 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 and must be called after esp_a2d_sink_init() and before esp_a2d_sink_deinit().
- Return
ESP_OK: control command is sent to lower layer successfully
ESP_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others
- Parameters
[in] ctrl
: control commands for A2DP data channel
-
esp_err_t
esp_a2d_source_init
(void)¶ Initialize the bluetooth A2DP source module. A2DP can work independently. If you want to use AVRC together, you should initiate AVRC first. This function should be called after esp_bluedroid_enable() completes successfully, and ESP_A2D_PROF_STATE_EVT with ESP_A2D_INIT_SUCCESS will reported to the APP layer. Note: A2DP can work independently. If you want to use AVRC together, you should initiate AVRC first.
- Return
ESP_OK: if the initialization request is sent to lower layer 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, and ESP_A2D_PROF_STATE_EVT with ESP_A2D_DEINIT_SUCCESS will reported to APP layer.
- 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 shoule be 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
[in] 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. This API must be called after esp_a2d_source_init() and before esp_a2d_source_deinit().
- Return
ESP_OK: connect request is sent to lower layer successfully
ESP_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others
- Parameters
[in] 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. This API must be called after esp_a2d_source_init() and before esp_a2d_source_deinit().
- Return
ESP_OK: disconnect request is sent to lower layer
ESP_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others
- Parameters
[in] 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 esp_a2d_cb_param_t::a2d_prof_stat_param
a2d_prof_stat
¶ status to indicate a2d prof init or deinit
-
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
a2d_prof_stat_param
¶ - #include <esp_a2dp_api.h>
ESP_A2D_PROF_STATE_EVT.
Public Members
-
esp_a2d_init_state_t
init_state
¶ a2dp profile state param
-
esp_a2d_init_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
-
uint8_t
sbc
[ESP_A2D_CIE_LEN_SBC
]¶ SBC codec capabilities
-
uint8_t
m12
[ESP_A2D_CIE_LEN_M12
]¶ MPEG-1,2 audio codec capabilities
-
uint8_t
m24
[ESP_A2D_CIE_LEN_M24
]¶ MPEG-2, 4 AAC audio codec capabilities
-
uint8_t
atrac
[ESP_A2D_CIE_LEN_ATRAC
]¶ ATRAC family codec capabilities
-
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 sink data callback function.
- Parameters
[in] buf
: : pointer to the data received from A2DP source device and is PCM format decoded from SBC decoder; buf references to a static memory block and can be overwritten by upcoming data[in] len
: : 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
[in] buf
: : buffer to be filled with PCM data stream from higher layer[in] len
: : 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¶ Not for application use, use inside stack only.
-
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_init_state_t
¶ Bluetooth A2DP Initiation states.
Values:
-
ESP_A2D_DEINIT_SUCCESS
= 0¶ A2DP profile deinit successful event
-
ESP_A2D_INIT_SUCCESS
¶ A2DP profile deinit successful event
-
-
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
-
ESP_A2D_PROF_STATE_EVT
¶ indicate a2dp init&deinit complete
-