The Audio/Video Remote Control Profile (AVRCP) defines the features and procedures to ensure interoperability between Bluetooth devices with audio/video functions. More...

Overview

The Audio/Video Remote Control Profile (AVRCP) defines the features and procedures to ensure interoperability between Bluetooth devices with audio/video functions.

The AVRCP API only supports controller role (CT) in the specification of Audio/Video remote control profile V1.6.0.

Terms and Acronyms

Terms	Details
CT	Controller role or the device playing the Controller role.
TG	Target role or the device playing the Target role.
PDU	Protocol Data Unit. In AVRCP, it indicates the data unit for Metadata transfer data.
AV/C	The Audio/Video Digital Interface Command set. For more information, please refer to AV/C Digital Interface Command Set.
SDP	Service Discovery Protocol. For more information, please refer to SDP in Wikipedia.

How to use this module

Step 1. Mandatory, implement the function bt_app_event_callback() to handle the AVRCP events, such as connect, disconnect, send pass through, register notification, etc.
- Sample code:
  void bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buff)
  {
  switch (msg)
  {
  case BT_AVRCP_CONNECT_CNF:
  {
  bt_avrcp_connect_cnf_t *params = (bt_avrcp_connect_cnf_t *)buff;
  // Save the params->handle if params->result is BT_STATUS_SUCCESS.
  break;
  }
  case BT_AVRCP_DISCONNECT_IND:
  {
  bt_avrcp_disconnect_ind_t *params = (bt_avrcp_disconnect_ind_t *)buff;
  // The AVRCP disconnect handler to clear the application state, context or other items.
  break;
  }
  case BT_AVRCP_PASS_THROUGH_CNF:
  {
  bt_avrcp_pass_through_cnf_t *cnf = (bt_avrcp_pass_through_cnf_t *)buff;
  if (status == BT_STATUS_SUCCESS)
  {
  // Send a key release pass through command if the key press command confirmation is received.
  if (cnf->op_state == BT_AVRCP_OPERATION_STATE_PUSH)
  {
  bt_avrcp_send_pass_through_command(cnf->conn_id, cnf->key_code, BT_AVRCP_OPERATION_STATE_RELEASED);
  // Keep the current AVRCP application state and context until the BT_AVRCP_OPERATION_STATE_RELEASED event is confirmed.
  }
  }
  break;
  }
  case BT_AVRCP_EVENT_NOTIFICATION_IND:
  {
  bt_avrcp_event_notification_t *cnf = (bt_avrcp_event_notification_t *)buff;
  if (status == BT_STATUS_AVRCP_INTERIM)
  {
  // Do something.
  } else if (status == BT_STATUS_SUCCESS)
  // Response to a successfully registered notification.
  // The registered notification is changed.
  // An additional NOTIFY command is expected to be sent.
  // Handle the notification.
  } else {
  // Error handing.
  }
  break;
  }
  default:
  break;
  }
  }
Step 2. Mandatory, connect to the remote device, as shown in the figure titled as "AVRCP connection establishment" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
- Sample code:
  // Connect to the remote device with a remote address and connection handle given as input parameters.
  // The event BT_AVRCP_CONNECT_CNF is in bt_avrcp_common_callback().
  ret = bt_avrcp_connect(&handle, &dev_addr);
Step 3. Mandatory, disconnect from the remote device, as shown in the figure titled as "AVRCP connection release" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
- Sample code:
  // Disconnect the remote device, with a given connection handle.
  ret = bt_avrcp_disconnect(handle);
Step 4. Mandatory, in the CT role, register notification and send pass through command after the AVRCP connection is established, as shown in the figure titled as "AV/C command procedure" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
- Sample code:
  // Pass through command.
  // Send a pass through command, pass the connection handle, operation ID and operation state,
  // then handle the event BT_AVRCP_PASS_THROUGH_CNF in #bt_app_event_callback().
  ret = bt_avrcp_send_pass_through_command(handle, BT_AVRCP_OPERATION_ID_PLAY, BT_AVRCP_OPERATION_STATE_PUSH);
  // Register a notification event.
  // Register a notification event, pass the connection handle, event ID and interval, then
  // handle the event BT_AVRCP_EVENT_NOTIFICATION_IND in #bt_app_event_callback().
  // Note, according to the AVRCP specification, interval is applicable only for BT_AVRCP_EVENT_PLAYBACK_POS_CHANGED.
  ret = bt_avrcp_register_notification(handle, BT_AVRCP_EVENT_PLAYBACK_STATUS_CHANGED, 255);
Step 5. Optional, list player application setting attributes, get or set the player application setting values, as shown in the figure titled as "AV/C command procedure" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
- Sample code:
  // A command to list the player application setting attributes.
  // Send a list player application setting attributes command, pass the connection handle
  // then handle the event BT_AVRCP_LIST_APP_SETTING_ATTRIBUTES_CNF in #bt_app_event_callback().
  ret = bt_avrcp_list_app_setting_attributes(handle);
  // A command to get the player application setting values.
  // Send a get player application setting values command, pass the connection handle and list of attribute IDs
  // then handle the event BT_AVRCP_GET_APP_SETTING_VALUE_CNF in #bt_app_event_callback().
  ret = bt_avrcp_get_app_setting_value(handle, atrribute_list_len, &attributes_id_list);
Step 6. Optional, play element attributes, as shown in the figure titled as "AV/C command procedure" in the Bluetooth developer's guide under the [sdk_root]/doc folder.
- Sample code:
  // A command to get the element attributes.
  // Send a get element attributes command, passing connection handle and media attribute IDs
  // then handle the event BT_AVRCP_GET_ELEMENT_ATTRIBUTES_CNF in #bt_app_event_callback().
  ret = bt_avrcp_get_element_attributes(conn_id, attribute_list_len, &attribute_id_list);

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

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

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

bt_status_t	bt_avrcp_send_pass_through_command (uint32_t handle, bt_avrcp_operation_id_t op_id, bt_avrcp_operation_state_t op_state)
	This function sends pass through command to the specified TG device. More...

bt_status_t	bt_avrcp_send_pass_through_response (uint32_t handle, bt_avrcp_response_t response, bt_avrcp_operation_id_t op_id, bt_avrcp_operation_state_t op_state)
	This function sends pass through response after receiving pass through command from the remote CT device. More...

bt_status_t	bt_avrcp_list_app_setting_attributes (uint32_t handle)
	This function gets player application attributes supported at TG device. More...

bt_status_t	bt_avrcp_get_app_setting_value (uint32_t handle, uint16_t attribute_size, bt_avrcp_get_app_setting_value_t *attribute_list)
	This function gets the player application setting values for specified attribute ID at the TG device. More...

bt_status_t	bt_avrcp_set_app_setting_value (uint32_t handle, uint16_t attribute_size, bt_avrcp_app_setting_value_t *attribute_value_list)
	This function sets the player application setting values to specified attribute ID at the TG device. More...

bt_status_t	bt_avrcp_get_element_attributes (uint32_t handle, uint16_t attribute_size, bt_avrcp_get_element_attributes_t *attribute_list)
	This function obtains the detailed information on a particular media file playing currently at the TG device. More...

bt_status_t	bt_avrcp_register_notification (uint32_t handle, bt_avrcp_event_t event_id, uint32_t play_back_interval)
	This function sends a register notification command to the TG device. More...

bt_status_t	bt_avrcp_request_continuing_response (uint32_t handle, bt_avrcp_pdu_id_t pdu_id)
	This function requests TG device to send continuing response packet for current PDU command. More...

bt_status_t	bt_avrcp_abort_continuing_response (uint32_t handle, bt_avrcp_pdu_id_t pdu_id)
	This function requests TG device to abort continuing response packet for current PDU command. More...

bt_status_t	bt_avrcp_set_absolute_volume (uint32_t handle, uint8_t volume)
	This function sets the volume in percentage for the rendering device. More...

bt_status_t	bt_avrcp_send_set_absoulte_volume_response (uint32_t handle, uint8_t volume)
	This function sends the response after receiving set absolute volume command from CT device. More...

bt_status_t	bt_avrcp_send_register_notification_response (uint32_t handle, bt_avrcp_send_register_notification_response_t *rsp_data)
	This function sends the register notification response to the CT device. More...

void	bt_avrcp_init (bt_avrcp_init_struct *bt_role)
	This function initializes the AVRCP context with CT or Target role. More...

void	bt_avrcp_deinit (void)
	This function removes the role from the AVRCP context.

bt_status_t	bt_avrcp_media_send_play_status_response (uint32_t handle, bt_avrcp_media_play_status_notification_t *data)
	This function sends notification to the remote device for currenct status of playing media, including SongLength, SongPosition and more. More...

bt_status_t	bt_avrcp_send_abort_data_response (uint32_t handle)
	This function sends response for the abort continuation pdu. More...

bt_status_t	bt_avrcp_element_metadata_attributes_response (uint32_t handle, bt_avrcp_get_element_attributes_response_t *rsp_data)
	This function provides metadata attributes to the remote device for some specific element(s). More...

bt_status_t	bt_avrcp_send_capability_response (uint32_t handle, void *response_data_t, bt_avrcp_capability_types_t type)
	This function sends device/profile capability to the remote device. More...

Modules
	Define

	Struct

Function Documentation

bt_status_t bt_avrcp_abort_continuing_response	(	uint32_t	handle,
		bt_avrcp_pdu_id_t	pdu_id
	)

This function requests TG device to abort continuing response packet for current PDU command.

The function should be called when the packet type of metadata response is start or continue. BT_AVRCP_ABORT_CONTINUING_CNF is sent to the upper layer with the request.

Parameters

[in]	handle	is the AVRCP handle for the specified remote device.
[in]	pdu_id	is the current PDU id for the corresponding command.

Returns: BT_STATUS_SUCCESS, the abort continuing command is sent successfully. BT_STATUS_AVRCP_BUSY, the last command did not receive any response. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle is NULL. BT_STATUS_OUT_OF_MEMORY, the TX memory is not enough.

bt_status_t bt_avrcp_connect	(	uint32_t *	handle,
		const bt_bd_addr_t *	address
	)

This function connects to the specified remote device.

The BT_AVRCP_CONNECT_CNF event is sent to the upper layer with the connection request result.

Parameters

[out]	handle	is the connection handle of the specified remote device. The handle is only valid when the return value is BT_STATUS_SUCCESS.
[in]	address	is a pointer to the remote device's address.

Returns: BT_STATUS_SUCCESS, the connection request started successfully. BT_STATUS_OUT_OF_MEMORY, not enough memory allocated for the AVRCP. BT_STATUS_AVRCP_LINK_ALREADY_EXISTED, the AVRCP channel already exists.

bt_status_t bt_avrcp_connect_response	(	uint32_t	handle,
		bool	accept
	)

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

The function should be called after BT_AVRCP_CONNECT_IND is received. The BT_AVRCP_CONNECT_CNF event is sent to the upper layer with the connection request result.

Parameters

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

Returns: BT_STATUS_SUCCESS, successfully responded to the connection request. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle or address is NULL.

bt_status_t bt_avrcp_disconnect ( uint32_t handle )

This function disconnects the specified remote device.

Parameters

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

Returns: BT_STATUS_SUCCESS, the disconnect request completed successfully. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle is NULL.

bt_status_t bt_avrcp_element_metadata_attributes_response	(	uint32_t	handle,
		bt_avrcp_get_element_attributes_response_t *	rsp_data
	)

This function provides metadata attributes to the remote device for some specific element(s).

// bt_avrcp_media_attribute_t : 0x01 : Title, 0x02 : Artist Name, 0x3 : Album Name etc.

Parameters

[in]	handle	is the AVRCP connection handle for the specified remote device.
[in]	rsp_data	metadata attributes to transfer/send to the remote device:

Returns: BT_STATUS_SUCCESS, successfully responded to the connection request. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle or address is NULL.

bt_status_t bt_avrcp_get_app_setting_value	(	uint32_t	handle,
		uint16_t	attribute_size,
		bt_avrcp_get_app_setting_value_t *	attribute_list
	)

This function gets the player application setting values for specified attribute ID at the TG device.

BT_AVRCP_GET_APP_SETTING_VALUE_CNF event is sent to the upper layer with the request result.

Parameters

[in]	handle	is the AVRCP handle for the specified remote device.
[in]	attribute_size	is the total size of the list of attribute ID.
[in]	attribute_list	is the list of specified attribute ID.

Returns: BT_STATUS_SUCCESS, the get app setting command is sent successfully. BT_STATUS_AVRCP_BUSY, the last command did not receive any response. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle is NULL. BT_STATUS_OUT_OF_MEMORY, the TX memory is not enough.

bt_status_t bt_avrcp_get_element_attributes	(	uint32_t	handle,
		uint16_t	attribute_size,
		bt_avrcp_get_element_attributes_t *	attribute_list
	)

This function obtains the detailed information on a particular media file playing currently at the TG device.

The event BT_AVRCP_GET_ELEMENT_ATTRIBUTES_CNF is sent to the upper layer with the request result.

Parameters

[in]	handle	is the AVRCP handle for the specified remote device.
[in]	attribute_size	is the total size of the list of media attribute ID.
[in]	attribute_list	is the list of media attribute ID.

Returns: BT_STATUS_SUCCESS, the get element attributes command is sent successfully. BT_STATUS_AVRCP_BUSY, the last command did not receive any response. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle is NULL. BT_STATUS_OUT_OF_MEMORY, the TX memory is not enough.

void bt_avrcp_init ( bt_avrcp_init_struct * bt_role )

This function initializes the AVRCP context with CT or Target role.

Parameters

[in] bt_role is the role.

bt_status_t bt_avrcp_list_app_setting_attributes ( uint32_t handle )

This function gets player application attributes supported at TG device.

BT_AVRCP_LIST_APP_SETTING_ATTRIBUTES_CNF event is sent to the upper layer with the request result.

Parameters

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

Returns: BT_STATUS_SUCCESS, the list app setting command is sent successfully. BT_STATUS_AVRCP_BUSY, the last command did not receive any response. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle is NULL. BT_STATUS_OUT_OF_MEMORY, the TX memory is not enough.

bt_status_t bt_avrcp_media_send_play_status_response	(	uint32_t	handle,
		bt_avrcp_media_play_status_notification_t *	data
	)

This function sends notification to the remote device for currenct status of playing media, including SongLength, SongPosition and more.

The function should be called after BT_AVRCP_CONNECT_IND is received. The BT_AVRCP_CONNECT_CNF event is sent to the upper layer with the connection request result.

Parameters

[in]	handle	is the AVRCP connection handle for the specified remote device.
[in]	data	notification data to be transfered to the remote device:

Returns: BT_STATUS_SUCCESS, successfully responded to the connection request. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle or address is NULL.

bt_status_t bt_avrcp_register_notification	(	uint32_t	handle,
		bt_avrcp_event_t	event_id,
		uint32_t	play_back_interval
	)

This function sends a register notification command to the TG device.

BT_AVRCP_EVENT_NOTIFICATION_IND event is sent to the upper layer with the request result.

Parameters

[in]	handle	is the AVRCP handle for the specified remote device.
[in]	event_id	is the related AVRCP event ID.
[in]	play_back_interval	is the time interval (in seconds) at which the change in playback position is noticed.

Returns: BT_STATUS_SUCCESS, the register command is sent successfully. BT_STATUS_AVRCP_BUSY, the last command did not receive any response. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle is NULL. BT_STATUS_OUT_OF_MEMORY, the TX memory is not enough.

bt_status_t bt_avrcp_request_continuing_response	(	uint32_t	handle,
		bt_avrcp_pdu_id_t	pdu_id
	)

This function requests TG device to send continuing response packet for current PDU command.

The function should be called when the packet type of metadata response is start or continue. The response of current PDU command is sent to the upper layer with the request.

Parameters

[in]	handle	is the AVRCP handle for the specified remote device.
[in]	pdu_id	is the current PDU id for the corresponding command.

Returns: BT_STATUS_SUCCESS, the request continuing command is sent successfully. BT_STATUS_AVRCP_BUSY, the last command did not receive any response. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle is NULL. BT_STATUS_OUT_OF_MEMORY, the TX memory is not enough.

bt_status_t bt_avrcp_send_abort_data_response ( uint32_t handle )

This function sends response for the abort continuation pdu.

Parameters

[in] handle is the AVRCP connection handle for the specified remote device.

Returns: BT_STATUS_SUCCESS, successfully responded to the connection request. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle or address is NULL.

bt_status_t bt_avrcp_send_capability_response	(	uint32_t	handle,
		void *	response_data_t,
		bt_avrcp_capability_types_t	type
	)

This function sends device/profile capability to the remote device.

bt_avrcp_capability_types_t

Parameters

[in]	handle	is the AVRCP connection handle for the specified remote device.
[in]	rsp_data	device/profile capability attributes to transfer/send to the remote device:

Returns: BT_STATUS_SUCCESS, successfully responded to the connection request. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle or address is NULL.

bt_status_t bt_avrcp_send_pass_through_command	(	uint32_t	handle,
		bt_avrcp_operation_id_t	op_id,
		bt_avrcp_operation_state_t	op_state
	)

This function sends pass through command to the specified TG device.

BT_AVRCP_PASS_THROUGH_CNF event is sent to the upper layer with the request result.

Parameters

[in]	handle	is the AVRCP handle for the specified remote device.
[in]	op_id	is the operation ID.
[in]	op_state	is the operation state.

Returns: BT_STATUS_SUCCESS, the pass through command is sent successfully. BT_STATUS_AVRCP_BUSY, the last command did not receive any response. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle is NULL. BT_STATUS_OUT_OF_MEMORY, the TX memory is not enough.

bt_status_t bt_avrcp_send_pass_through_response	(	uint32_t	handle,
		bt_avrcp_response_t	response,
		bt_avrcp_operation_id_t	op_id,
		bt_avrcp_operation_state_t	op_state
	)

This function sends pass through response after receiving pass through command from the remote CT device.

The function should only be called after BT_AVRCP_PASS_THROUGH_COMMAND_IND is received.

Parameters

[in]	handle	is the AVRCP handle of the remote device.
[in]	response	is the type of response. BT_AVRCP_RESPONSE_NOT_IMPLEMENTED or BT_AVRCP_RESPONSE_ACCEPTED or BT_AVRCP_RESPONSE_REJECTED.
[in]	op_id	is the corresponding operation ID.
[in]	op_state	is the corresponding operation state. BT_AVRCP_OPERATION_STATE_PUSH or #BT_AVRCP_OPERATION_STATE_RELEASE.

Returns: BT_STATUS_SUCCESS, the pass through command is sent successfully. BT_STATUS_AVRCP_INVALID_PARAMETER, the handel is NULL. BT_STATUS_OUT_OF_MEMORY, the TX memory is not enough.

bt_status_t bt_avrcp_send_register_notification_response	(	uint32_t	handle,
		bt_avrcp_send_register_notification_response_t *	rsp_data
	)

This function sends the register notification response to the CT device.

The function should only be called in the following two cases:

Register notification command BT_AVRCP_REGISTER_NOTIFICATION_IND is received with valid parameters.
The register notification command has received and the corresponding registered event happenes.

Parameters

[in]	handle	is the AVRCP handle of the remote device.
[in]	rsp_data	is the pointer to the register notification response parameters.

Returns: BT_STATUS_SUCCESS, the register notification response is sent successfully. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle is NULL. BT_STATUS_OUT_OF_MEMORY, the TX memory is not enough.

bt_status_t bt_avrcp_send_set_absoulte_volume_response	(	uint32_t	handle,
		uint8_t	volume
	)

This function sends the response after receiving set absolute volume command from CT device.

The function should only be called after BT_AVRCP_SET_ABSOLUTE_VOLUME_COMMAND_IND is received.

Parameters

[in]	handle	is the AVRCP handle of the remote device.
[in]	volume	is the actual volume to set in percentage. TG can accept the assigned volume in #BT_AVRCP_SET_ABSOLUTE_COMMAND_IND command or return the actual set volume value.

Returns: BT_STATUS_SUCCESS, the set absolute volume response is sent successfully. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle is NULL. BT_STATUS_OUT_OF_MEMORY, the TX memory is not enough.

bt_status_t bt_avrcp_set_absolute_volume	(	uint32_t	handle,
		uint8_t	volume
	)

This function sets the volume in percentage for the rendering device.

Note that the actual volume level set in the rendering device is returned through the volume field of bt_avrcp_set_absolute_volume_response_t in the event BT_AVRCP_SET_ABSOLUTE_VOLUME_CNF.

Parameters

[in]	handle	is the AVRCP handle of the remote device.
[in]	volume	is the volume to set in percentage. The top bit (bit 7) is reserved. Values ranging from 0x00 to 0x7F specify 0% to 100% of volume. Other values are invalid.

Returns: BT_STATUS_SUCCESS, the set absolute volume command is sent successfully. BT_STATUS_AVRCP_BUSY, the last command did not receive any response. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle is NULL. #BT_STATUS_OUT_OF_MOMORY, the TX memory is not enough.

bt_status_t bt_avrcp_set_app_setting_value	(	uint32_t	handle,
		uint16_t	attribute_size,
		bt_avrcp_app_setting_value_t *	attribute_value_list
	)

This function sets the player application setting values to specified attribute ID at the TG device.

BT_AVRCP_SET_APP_SETTING_VALUE_CNF event is sent to upper layer with the request result.

Parameters

[in]	handle	is the AVRCP handle for the specified remote device.
[in]	attribute_size	is the total size of the list of attribute value and corresponding attribute ID.
[in]	attribute_value_list	is the list of attribute value and corresponding attribute ID.

Returns: BT_STATUS_SUCCESS, the set app setting command is sent successfully. BT_STATUS_AVRCP_BUSY, the last command did not receive any response. BT_STATUS_AVRCP_INVALID_PARAMETER, the handle is NULL. BT_STATUS_OUT_OF_MEMORY, the TX memory is not enough.

Overview

Terms and Acronyms

How to use this module

Functions

Modules

Function Documentation