Bluetooth® A2DP API

Application Examples

API Reference

Header File

  • components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h

  • This header file can be included with:

    #include "esp_a2dp_api.h"

  • This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

    REQUIRES bt

    or

    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::[anonymous] 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

Was this page helpful?