Bluetooth A2DP API

Overview

Instructions

Application Example

Check bluetooth/bluedroid/classic_bt folder in ESP-IDF examples, which contains the following application:

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

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_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 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
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 type

  • 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.

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

Provide feedback about this document