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
Header File
This header file can be included with:
#include "esp_a2dp_api.h"
- This header file is a part of the API provided by the
btcomponent. To declare that your component depends onbt, add the following to your CMakeLists.txt:
REQUIRES btor
> PRIV_REQUIRES bt
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.
Parameters
callback -- [in] A2DP event callback function
Returns
ESP_OK: success
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: if callback is a NULL function pointer
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.
Parameters
callback -- [in] A2DP sink data callback function
Returns
ESP_OK: success
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: if callback is a NULL function pointer
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.
Returns
ESP_OK: if the initialization request is sent successfully
ESP_ERR_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.
Returns
ESP_OK: if the deinitialization request is sent successfully
ESP_ERR_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().
Parameters
remote_bda -- [in] remote bluetooth device address
Returns
ESP_OK: connect request is sent to lower layer successfully
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others
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().
Parameters
remote_bda -- [in] remote bluetooth device address
Returns
ESP_OK: disconnect request is sent to lower layer successfully
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others
esp_err_t esp_a2d_sink_set_delay_value(uint16_t delay_value)
Set delay reporting value. The delay value of sink is caused by buffering (including protocol stack and application layer), decoding and rendering. The default delay value is 120ms, if the set value is less than 120ms, the setting will fail. This API must be called after esp_a2d_sink_init() and before esp_a2d_sink_deinit().
Parameters
delay_value -- [in] reporting value is in 1/10 millisecond
Returns
ESP_OK: delay value is sent to lower layer successfully
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others
esp_err_t esp_a2d_sink_get_delay_value(void)
Get delay reporting value. This API must be called after esp_a2d_sink_init() and before esp_a2d_sink_deinit().
Returns
ESP_OK: if the request is sent successfully
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others
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().
Parameters
ctrl -- [in] control commands for A2DP data channel
Returns
ESP_OK: control command is sent to lower layer successfully
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others
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.
Returns
ESP_OK: if the initialization request is sent to lower layer successfully
ESP_ERR_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.
Returns
ESP_OK: success
ESP_ERR_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.
Parameters
callback -- [in] A2DP source data callback function
Returns
ESP_OK: success
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: if callback is a NULL function pointer
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().
Parameters
remote_bda -- [in] remote bluetooth device address
Returns
ESP_OK: connect request is sent to lower layer successfully
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others
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().
Parameters
remote_bda -- [in] remote bluetooth device address
Returns
ESP_OK: disconnect request is sent to lower layer
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others
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 esp_a2d_cb_param_t::a2d_psc_cfg_param a2d_psc_cfg_stat
status to indicate protocol service capabilities configured
struct esp_a2d_cb_param_t::a2d_set_stat_param a2d_set_delay_value_stat
A2DP sink set delay report value status
struct esp_a2d_cb_param_t::a2d_get_stat_param a2d_get_delay_value_stat
A2DP sink get delay report value status
struct esp_a2d_cb_param_t::a2d_report_delay_stat_param a2d_report_delay_value_stat
A2DP source received sink report value status
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
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
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"
struct a2d_get_stat_param
#include <esp_a2dp_api.h>
ESP_A2D_SNK_GET_DELAY_VALUE_EVT.
Public Members
uint16_t delay_value
delay report value
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
struct a2d_psc_cfg_param
#include <esp_a2dp_api.h>
ESP_A2D_SNK_PSC_CFG_EVT.
Public Members
esp_a2d_psc_t psc_mask
protocol service capabilities configured
struct a2d_report_delay_stat_param
#include <esp_a2dp_api.h>
ESP_A2D_REPORT_SNK_DELAY_VALUE_EVT.
Public Members
uint16_t delay_value
delay report value
struct a2d_set_stat_param
#include <esp_a2dp_api.h>
ESP_A2D_SNK_SET_DELAY_VALUE_EVT.
Public Members
esp_a2d_set_delay_value_state_t set_state
a2dp profile state param
uint16_t delay_value
delay report value
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
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 cie
A2DP codec information element
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
NON-A2DP
ESP_A2D_PSC_DELAY_RPT
Protocol service capabilities. This value is a mask.
Delay Report
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 uint16_t esp_a2d_psc_t
typedef void (*esp_a2d_cb_t)(esp_a2d_cb_event_t event, esp_a2d_cb_param_t *param)
A2DP profile callback function type.
Param event
: Event type
Param param
: Pointer to callback parameter
typedef void (*esp_a2d_sink_data_cb_t)(const uint8_t *buf, uint32_t len)
A2DP sink data callback function.
Param buf
[in] : 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
Param len
[in] : 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.
Param buf
[in] : buffer to be filled with PCM data stream from higher layer
Param len
[in] : size(in bytes) of data block to be copied to buf. -1 is an indication to user that data buffer shall be flushed
Return
size of bytes read successfully, if the argument len is -1, this value is ignored.
Enumerations
enum esp_a2d_connection_state_t
Bluetooth A2DP connection states.
Values:
enumerator ESP_A2D_CONNECTION_STATE_DISCONNECTED
connection released
enumerator ESP_A2D_CONNECTION_STATE_CONNECTING
connecting remote device
enumerator ESP_A2D_CONNECTION_STATE_CONNECTED
connection established
enumerator ESP_A2D_CONNECTION_STATE_DISCONNECTING
disconnecting remote device
enum esp_a2d_disc_rsn_t
Bluetooth A2DP disconnection reason.
Values:
enumerator ESP_A2D_DISC_RSN_NORMAL
Finished disconnection that is initiated by local or remote device
enumerator ESP_A2D_DISC_RSN_ABNORMAL
Abnormal disconnection caused by signal loss
enum esp_a2d_audio_state_t
Bluetooth A2DP datapath states.
Values:
enumerator ESP_A2D_AUDIO_STATE_SUSPEND
audio stream datapath suspended by remote device
enumerator ESP_A2D_AUDIO_STATE_STARTED
audio stream datapath started
enumerator ESP_A2D_AUDIO_STATE_STOPPED
Note
Deprecated
enumerator ESP_A2D_AUDIO_STATE_REMOTE_SUSPEND
Note
Deprecated
enum esp_a2d_media_ctrl_ack_t
A2DP media control command acknowledgement code.
Values:
enumerator ESP_A2D_MEDIA_CTRL_ACK_SUCCESS
media control command is acknowledged with success
enumerator ESP_A2D_MEDIA_CTRL_ACK_FAILURE
media control command is acknowledged with failure
enumerator 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:
enumerator ESP_A2D_MEDIA_CTRL_NONE
Not for application use, use inside stack only.
enumerator ESP_A2D_MEDIA_CTRL_CHECK_SRC_RDY
check whether AVDTP is connected, only used in A2DP source
enumerator ESP_A2D_MEDIA_CTRL_START
command to set up media transmission channel
enumerator ESP_A2D_MEDIA_CTRL_SUSPEND
command to suspend media transmission
enumerator ESP_A2D_MEDIA_CTRL_STOP
Note
Deprecated, Please use ESP_A2D_MEDIA_CTRL_SUSPEND
enum esp_a2d_init_state_t
Bluetooth A2DP Initiation states.
Values:
enumerator ESP_A2D_DEINIT_SUCCESS
A2DP profile deinit successful event
enumerator ESP_A2D_INIT_SUCCESS
A2DP profile deinit successful event
enum esp_a2d_set_delay_value_state_t
Bluetooth A2DP set delay report value states.
Values:
enumerator ESP_A2D_SET_SUCCESS
A2DP profile set delay report value successful
enumerator ESP_A2D_SET_INVALID_PARAMS
A2DP profile set delay report value is invalid parameter
enum esp_a2d_cb_event_t
A2DP callback events.
Values:
enumerator ESP_A2D_CONNECTION_STATE_EVT
connection state changed event
enumerator ESP_A2D_AUDIO_STATE_EVT
audio stream transmission state changed event
enumerator ESP_A2D_AUDIO_CFG_EVT
audio codec is configured, only used for A2DP SINK
enumerator ESP_A2D_MEDIA_CTRL_ACK_EVT
acknowledge event in response to media control commands
enumerator ESP_A2D_PROF_STATE_EVT
indicate a2dp init&deinit complete
enumerator ESP_A2D_SNK_PSC_CFG_EVT
protocol service capabilities configured，only used for A2DP SINK
enumerator ESP_A2D_SNK_SET_DELAY_VALUE_EVT
indicate a2dp sink set delay report value complete, only used for A2DP SINK
enumerator ESP_A2D_SNK_GET_DELAY_VALUE_EVT
indicate a2dp sink get delay report value complete, only used for A2DP SINK
enumerator ESP_A2D_REPORT_SNK_DELAY_VALUE_EVT
report delay value, only used for A2DP SRC