This section introduces the Advanced Audio Distribution Profile (A2DP) APIs including terms, supported features and details on how to use the APIs to set up a Bluetooth Audio instance. More...

Overview

This section introduces the Advanced Audio Distribution Profile (A2DP) APIs including terms, supported features and details on how to use the APIs to set up a Bluetooth Audio instance.

The A2DP defines the protocol to implement distribution of high-quality audio content in mono or stereo on ACL channels.

Terms and Acronyms

Terms	Details
SBC	The Low Complexity Subband Coding (SBC) is an audio subband codec specified by the Bluetooth Special Interest Group (SIG) for the Advanced Audio Distribution Profile (A2DP). SBC is a digital audio encoder and decoder used to transfer data to Bluetooth audio output devices like headphones or loudspeakers. For more information, please refer to Wikipedia.
AAC	Advanced Audio Coding (AAC) is an audio coding standard for lossy digital audio compression. For more information, please refer to Wikipedia.
SEID	Stream End Point Identifier (SEID) is a SEP identifier.
SEP	Stream End Point (SEP) is a concept to expose available Transport Services and AV capabilities of the Application in order to negotiate a stream.
SNK	Sink. A device is the SNK when it acts as a sink of a digital audio stream delivered from the SRC on the same piconet.
SRC	Source. A device is the SRC when it acts as a source of a digital audio stream that is delivered to the SNK of the piconet.
Piconet	A piconet is a computer network which links a wireless user group of devices using Bluetooth technology protocols. For more information, please refer to Wikipedia.

How to use this module

The A2DP confirmation/indication notifies the upper layer that the process has finished or an indication is received. BT_A2DP_XXX_CNF represents the events that a procedure has finished. BT_A2DP_XXX_IND represents the events that an indication has been received.
The A2DP confirmation/indication structures provide related information to the upper layer. The data is obtained from the events parameter.
- 1. Mandatory, implement bt_a2dp_get_init_params() to set the initial configuration (device role, SEP number, SEP detail, etc). This is a user-defined API, which is invoked when the Bluetooth is powered on. It should be implemented by the application.
  - Sample code:
    bt_status_t bt_a2dp_get_init_params(bt_a2dp_init_params_t *params)
    {
    static bt_a2dp_codec_capability_t init_codec;
    // Fill codec infomation into init_codec.
    params->codec_number = 1;
    params->codec_list = &init_codec;
    return BT_STATUS_SUCCESS;
    }
- 2. Mandatory, implement bt_app_event_callback() to handle the A2DP events, such as connect, disconnect, streaming start indication, media data received, etc.
  - Sample code:
    void bt_app_event_callback(bt_msg_type_t msg_id, bt_status_t status, void *buff)
    {
    switch (msg_id)
    {
    case BT_A2DP_CONNECT_CNF:
    {
    bt_a2dp_connect_cnf_t *params = (bt_a2dp_connect_cnf_t *)buff;
    // Check connection result and save handle if connection is successful.
    break;
    }
    case BT_A2DP_DISCONNECT_CNF:
    {
    bt_a2dp_disconnect_cnf_t *params = (bt_a2dp_disconnect_cnf_t *)buff;
    // Check disconnection result and clear the A2DP context.
    break;
    }
    default:
    break;
    }
    }
- 3. Optional, initiate a connection to a remote device, as shown in the figure titled as "The A2DP connection establishment message sequence" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
  - Sample code:
    // A BT_A2DP_CONNECT_CNF event notifies the function bt_app_event_callback() once the device is connected.
    ret = bt_a2dp_connect(&a2dp_handle, address, role);
- 4. Mandatory, similar to sink, handles the events in bt_app_event_callback().
  - Sample code:
    void bt_app_event_callback(bt_msg_type_t msg_id, bt_status_t status, void *buff)
    {
    switch (msg_id)
    {
    case BT_A2DP_START_STREAMING_IND:
    {
    bt_a2dp_start_streaming_ind_t *params = (bt_a2dp_start_streaming_ind_t *)buff;
    // Must accept the request by sending the response with either true or false.
    bt_a2dp_start_streaming_response(params->handle, true);
    // Open sink codec (initialize the audio driver).
    handle = bt_codec_a2dp_open(callback, codec_a2dp);
    break;
    }
    case BT_A2DP_SUSPEND_STREAMING_IND:
    {
    bt_a2dp_suspend_streaming_ind_t *params = (bt_a2dp_suspend_streaming_ind_t *)buff;
    // Must accept the request by sending the response with either true or false.
    bt_a2dp_suspend_streaming_response(params->handle, true);
    break;
    }
    case BT_A2DP_RECONFIGURE_IND:
    {
    bt_a2dp_reconfigure_ind_t *params = (bt_a2dp_reconfigure_ind_t *)buff;
    // Must accept the request by sending the response with either true or false.
    bt_a2dp_reconfigure_response(params->handle, true);
    break;
    }
    default:
    break;
    }
    }
- 5. Mandatory, handle media event and write data to audio driver using bt_app_event_callback().
  - Sample code:
    void bt_app_event_callback(bt_msg_type_t msg_id, bt_status_t status, void *buff)
    {
    switch (msg_id)
    {
    case BT_A2DP_STREAMING_RECEIVED_IND:
    {
    bt_a2dp_streaming_received_ind_t *params = (bt_a2dp_streaming_received_ind_t *)buff;
    // Hold the received data node to prevent the node from being released before it is consumed.
    // Remember that bt_a2dp_release_media_data_node() must be called after the data node is consumed.
    bt_a2dp_hold_media_data_node(params->data_node);
    break;
    }
    default:
    break;
    }
    }
- 6. Optional, initiate the disconnection from a remote device, as shown in the figure titled as "The A2DP connection release message sequence" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
  - Sample code:
    // A BT_A2DP_DISCONNECT_CNF event notifies the function bt_app_event_callback() once the device is disconnected.
    ret = bt_a2dp_disconnect(handle);

Functions
bt_status_t	bt_a2dp_connect (uint32_t handle, const bt_bd_addr_t address, bt_a2dp_role_t role)
	This function connects to the specified remote device. More...

bt_status_t	bt_a2dp_start_streaming (uint32_t handle)
	This function starts streaming with the specified remote device. More...

bt_status_t	bt_a2dp_suspend_streaming (uint32_t handle)
	This function suspends the current streaming with the specified remote device. More...

bt_status_t	bt_a2dp_reconfigure_stream (uint32_t handle, bt_a2dp_codec_capability_t *codec_cap)
	This function reconfigures the already configured stream and the API needs to be called only in stream open state not in streaming state More...

bt_status_t	bt_a2dp_send_media_data (uint32_t handle, uint8_t *buffer, uint32_t payload_size, uint32_t timestamp)
	This function sends media data to the remote device. More...

uint32_t	bt_a2dp_get_mtu_size (uint32_t handle)
	This function returns the maximum A2DP payload data value in bytes so that the app can send data less than this value. More...

bt_status_t	bt_a2dp_abort_streaming (uint32_t handle)
	This function aborts the current connection channel with the specified remote device. More...

bt_status_t	bt_a2dp_connect_response (uint32_t handle, bool accept)
	This function responds to the specified remote device's incoming connection. More...

bt_status_t	bt_a2dp_disconnect (uint32_t handle)
	This function disconnects from the specified remote device. More...

bt_status_t	bt_a2dp_start_streaming_response (uint32_t handle, bool accept)
	This function responds to the incoming streaming from the specified remote device. More...

bt_status_t	bt_a2dp_suspend_streaming_response (uint32_t handle, bool accept)
	This function responds to suspended streaming from the specified remote device. More...

bt_status_t	bt_a2dp_reconfigure_response (uint32_t handle, bool accept)
	This function responds to the reconfiguration of the specified remote device. More...

bt_status_t	bt_a2dp_get_init_params (bt_a2dp_init_params_t *param)
	This function is A2DP initialization API. More...

void	bt_a2dp_hold_media_data_node (uint8_t *data_node)
	This function holds a media packet from A2DP, preventing from that the packet is released before consumed. More...

void	bt_a2dp_release_media_data_node (uint8_t *data_node)
	This function releases a media packet after it is consumed. More...

Modules
	Define

	Struct

Function Documentation

bt_status_t bt_a2dp_abort_streaming ( uint32_t handle )

This function aborts the current connection channel with the specified remote device.

The BT_A2DP_DISCONNECT_IND event will be sent to the upper layer.

Parameters

[in] handle is the connection handle of the specified remote device.

Returns: BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_a2dp_connect	(	uint32_t *	handle,
		const bt_bd_addr_t *	address,
		bt_a2dp_role_t	role
	)

This function connects to the specified remote device.

The BT_A2DP_CONNECT_CNF event will be sent to the upper layer with connection request result.

Parameters

[out]	handle	is the connection handle of the specified remote device. The handle can be used to abort the connection before BT_A2DP_CONNECT_CNF arrives.
[in]	address	is the Bluetooth address of a remote device.
[in]	role	is local device's A2DP role.

Returns: BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_a2dp_connect_response	(	uint32_t	handle,
		bool	accept
	)

This function responds to the specified remote device's incoming connection.

The BT_A2DP_CONNECT_CNF event will be sent to the upper layer with connection request result.

Parameters

[in]	handle	is the A2DP handle for the specified remote device.
[in]	accept	defines whether accept or reject remote device's connection request.

Returns: BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed.

bt_status_t bt_a2dp_disconnect ( uint32_t handle )

This function disconnects from the specified remote device.

The BT_A2DP_DISCONNECT_CNF event will be sent to the upper layer with disconnection request result.

Parameters

[in] handle is the A2DP handle for the specified remote device.

Returns: BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_a2dp_get_init_params ( bt_a2dp_init_params_t * param )

This function is A2DP initialization API.

Implementation is required.

Parameters

[out] param is the initialization parameter. The value is provided once it is called by A2DP.

Returns: BT_STATUS_SUCCESS, A2DP is enabled successfully. BT_STATUS_FAIL, A2DP is enabled failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

uint32_t bt_a2dp_get_mtu_size ( uint32_t handle )

This function returns the maximum A2DP payload data value in bytes so that the app can send data less than this value.

Parameters

[in] handle is the connection handle of the specified remote device.

Returns: value of the MTU.

void bt_a2dp_hold_media_data_node ( uint8_t * data_node )

This function holds a media packet from A2DP, preventing from that the packet is released before consumed.

Parameters

[in] data_node is media packet node which needs to be kept, preventing that it is released before it is consumed.

Returns: None.

bt_status_t bt_a2dp_reconfigure_response	(	uint32_t	handle,
		bool	accept
	)

This function responds to the reconfiguration of the specified remote device.

Parameters

[in]	handle	is the A2DP handle for the specified remote device.
[in]	accept	defines whether to accept or reject the reconfiguration request.

Returns: BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_a2dp_reconfigure_stream	(	uint32_t	handle,
		bt_a2dp_codec_capability_t *	codec_cap
	)

This function reconfigures the already configured stream and the API needs to be called only in stream open state not in streaming state

The BT_A2DP_RECONFIGURE_CNF event will be sent to the upper layer with reconfigured stream result.

Parameters

[in]	handle	is the connection handle of the specified remote device.
[in]	codec_cap	is the codec capabilities to renegotiate with the remote device.

Returns: BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

void bt_a2dp_release_media_data_node ( uint8_t * data_node )

This function releases a media packet after it is consumed.

Parameters

[in] data_node is media packet node which needs be released after it is consumed.

Returns: None.

bt_status_t bt_a2dp_send_media_data	(	uint32_t	handle,
		uint8_t *	buffer,
		uint32_t	payload_size,
		uint32_t	timestamp
	)

This function sends media data to the remote device.

Parameters

[in]	handle	is the connection handle of the specified remote device.
[in]	buffer	is the media payload data for the remote device.
[in]	payload_size	is the size of media payload data.
[in]	timestamp	is the timestamp value to add in the media header.

Returns: BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_a2dp_start_streaming ( uint32_t handle )

This function starts streaming with the specified remote device.

The BT_A2DP_START_STREAMING_CNF event will be sent to the upper layer with Suspend streaming status.

Parameters

[in] handle is the connection handle of the specified remote device.

Returns: BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_a2dp_start_streaming_response	(	uint32_t	handle,
		bool	accept
	)

This function responds to the incoming streaming from the specified remote device.

Parameters

[in]	handle	is the A2DP handle for the specified remote device.
[in]	accept	defines whether to accept or reject the streaming request.

Returns: BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed.

bt_status_t bt_a2dp_suspend_streaming ( uint32_t handle )

This function suspends the current streaming with the specified remote device.

The BT_A2DP_SUSPEND_STREAMING_CNF event will be sent to the upper layer with Suspend streaming status.

Parameters

[in] handle is the connection handle of the specified remote device.

Returns: BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

bt_status_t bt_a2dp_suspend_streaming_response	(	uint32_t	handle,
		bool	accept
	)

This function responds to suspended streaming from the specified remote device.

Parameters

[in]	handle	is the A2DP handle for the specified remote device.
[in]	accept	defines whether to accept or reject the suspension request.

Returns: BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory.

Overview

Terms and Acronyms

How to use this module

Functions

Modules

Function Documentation