BT AVRCP APIs

Overview

Bluetooth AVRCP reference APIs.

Instructions

Application Example

Instructions

API Reference

Functions

esp_err_t esp_avrc_ct_register_callback(esp_avrc_ct_cb_t callback)

Register application callbacks to AVRCP module; for now only AVRCP Controller role is supported. This function should be called after esp_bluedroid_enable() completes successfully.

Return

  • ESP_OK: success

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

Parameters

  • [in] callback: AVRCP controller callback function

esp_err_t esp_avrc_ct_init(void)

Initialize the bluetooth AVRCP controller module, This function should be called after esp_bluedroid_enable() completes successfully.

Return

  • ESP_OK: success

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_avrc_ct_deinit(void)

De-initialize AVRCP controller module. This function should be called after after esp_bluedroid_enable() completes successfully.

Return

  • ESP_OK: success

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

esp_err_t esp_avrc_ct_send_set_player_value_cmd(uint8_t tl, uint8_t attr_id, uint8_t value_id)

Send player application settings command to AVRCP target. This function should be called after ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established.

Return

  • ESP_OK: success

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

Parameters

  • [in] tl: : transaction label, 0 to 15, consecutive commands should use different values.

  • [in] attr_id: : player application setting attribute IDs from one of esp_avrc_ps_attr_ids_t

  • [in] value_id: : attribute value defined for the specific player application setting attribute

esp_err_t esp_avrc_ct_send_register_notification_cmd(uint8_t tl, uint8_t event_id, uint32_t event_parameter)

Send register notification command to AVRCP target, This function should be called after ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established.

Return

  • ESP_OK: success

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

Parameters

  • [in] tl: : transaction label, 0 to 15, consecutive commands should use different values.

  • [in] event_id: : id of events, e.g. ESP_AVRC_RN_PLAY_STATUS_CHANGE, ESP_AVRC_RN_TRACK_CHANGE, etc.

  • [in] event_parameter: : special parameters, eg. playback interval for ESP_AVRC_RN_PLAY_POS_CHANGED

esp_err_t esp_avrc_ct_send_metadata_cmd(uint8_t tl, uint8_t attr_mask)

Send metadata command to AVRCP target, This function should be called after ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established.

Return

  • ESP_OK: success

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

Parameters

  • [in] tl: : transaction label, 0 to 15, consecutive commands should use different values.

  • [in] attr_mask: : mask of attributes, e.g. ESP_AVRC_MD_ATTR_ID_TITLE | ESP_AVRC_MD_ATTR_ID_ARTIST.

esp_err_t esp_avrc_ct_send_passthrough_cmd(uint8_t tl, uint8_t key_code, uint8_t key_state)

Send passthrough command to AVRCP target, This function should be called after ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established.

Return

  • ESP_OK: success

  • ESP_INVALID_STATE: if bluetooth stack is not yet enabled

  • ESP_FAIL: others

Parameters

  • [in] tl: : transaction label, 0 to 15, consecutive commands should use different values.

  • [in] key_code: : passthrough command code, e.g. ESP_AVRC_PT_CMD_PLAY, ESP_AVRC_PT_CMD_STOP, etc.

  • [in] key_state: : passthrough command key state, ESP_AVRC_PT_CMD_STATE_PRESSED or ESP_AVRC_PT_CMD_STATE_RELEASED

Unions

union esp_avrc_ct_cb_param_t
#include <esp_avrc_api.h>

AVRC controller callback parameters.

Public Members

struct esp_avrc_ct_cb_param_t::avrc_ct_conn_stat_param conn_stat

AVRC connection status

struct esp_avrc_ct_cb_param_t::avrc_ct_psth_rsp_param psth_rsp

passthrough command response

struct esp_avrc_ct_cb_param_t::avrc_ct_meta_rsp_param meta_rsp

metadata attributes response

struct esp_avrc_ct_cb_param_t::avrc_ct_change_notify_param change_ntf

notifications

struct esp_avrc_ct_cb_param_t::avrc_ct_rmt_feats_param rmt_feats

AVRC features discovered from remote SDP server

struct avrc_ct_change_notify_param
#include <esp_avrc_api.h>

ESP_AVRC_CT_CHANGE_NOTIFY_EVT.

Public Members

uint8_t event_id

id of AVRC event notification

uint32_t event_parameter

event notification parameter

struct avrc_ct_conn_stat_param
#include <esp_avrc_api.h>

ESP_AVRC_CT_CONNECTION_STATE_EVT.

Public Members

bool connected

whether AVRC connection is set up

esp_bd_addr_t remote_bda

remote bluetooth device address

struct avrc_ct_meta_rsp_param
#include <esp_avrc_api.h>

ESP_AVRC_CT_METADATA_RSP_EVT.

Public Members

uint8_t attr_id

id of metadata attribute

uint8_t *attr_text

attribute itself

int attr_length

attribute character length

struct avrc_ct_psth_rsp_param
#include <esp_avrc_api.h>

ESP_AVRC_CT_PASSTHROUGH_RSP_EVT.

Public Members

uint8_t tl

transaction label, 0 to 15

uint8_t key_code

passthrough command code

uint8_t key_state

0 for PRESSED, 1 for RELEASED

struct avrc_ct_rmt_feats_param
#include <esp_avrc_api.h>

ESP_AVRC_CT_REMOTE_FEATURES_EVT.

Public Members

uint32_t feat_mask

AVRC feature mask of remote device

esp_bd_addr_t remote_bda

remote bluetooth device address

Type Definitions

typedef void (*esp_avrc_ct_cb_t)(esp_avrc_ct_cb_event_t event, esp_avrc_ct_cb_param_t *param)

AVRCP controller callback function type.

Parameters

  • event: : Event type

  • param: : Pointer to callback parameter union

Enumerations

enum esp_avrc_features_t

AVRC feature bit mask.

Values:

ESP_AVRC_FEAT_RCTG = 0x0001

remote control target

ESP_AVRC_FEAT_RCCT = 0x0002

remote control controller

ESP_AVRC_FEAT_VENDOR = 0x0008

remote control vendor dependent commands

ESP_AVRC_FEAT_BROWSE = 0x0010

use browsing channel

ESP_AVRC_FEAT_META_DATA = 0x0040

remote control metadata transfer command/response

ESP_AVRC_FEAT_ADV_CTRL = 0x0200

remote control advanced control commmand/response

enum esp_avrc_pt_cmd_t

AVRC passthrough command code.

Values:

ESP_AVRC_PT_CMD_PLAY = 0x44

play

ESP_AVRC_PT_CMD_STOP = 0x45

stop

ESP_AVRC_PT_CMD_PAUSE = 0x46

pause

ESP_AVRC_PT_CMD_FORWARD = 0x4B

forward

ESP_AVRC_PT_CMD_BACKWARD = 0x4C

backward

ESP_AVRC_PT_CMD_REWIND = 0x48

rewind

ESP_AVRC_PT_CMD_FAST_FORWARD = 0x49

fast forward

enum esp_avrc_pt_cmd_state_t

AVRC passthrough command state.

Values:

ESP_AVRC_PT_CMD_STATE_PRESSED = 0

key pressed

ESP_AVRC_PT_CMD_STATE_RELEASED = 1

key released

enum esp_avrc_ct_cb_event_t

AVRC Controller callback events.

Values:

ESP_AVRC_CT_CONNECTION_STATE_EVT = 0

connection state changed event

ESP_AVRC_CT_PASSTHROUGH_RSP_EVT = 1

passthrough response event

ESP_AVRC_CT_METADATA_RSP_EVT = 2

metadata response event

ESP_AVRC_CT_PLAY_STATUS_RSP_EVT = 3

play status response event

ESP_AVRC_CT_CHANGE_NOTIFY_EVT = 4

notification event

ESP_AVRC_CT_REMOTE_FEATURES_EVT = 5

feature of remote device indication event

enum esp_avrc_md_attr_mask_t

AVRC metadata attribute mask.

Values:

ESP_AVRC_MD_ATTR_TITLE = 0x1

title of the playing track

ESP_AVRC_MD_ATTR_ARTIST = 0x2

track artist

ESP_AVRC_MD_ATTR_ALBUM = 0x4

album name

ESP_AVRC_MD_ATTR_TRACK_NUM = 0x8

track position on the album

ESP_AVRC_MD_ATTR_NUM_TRACKS = 0x10

number of tracks on the album

ESP_AVRC_MD_ATTR_GENRE = 0x20

track genre

ESP_AVRC_MD_ATTR_PLAYING_TIME = 0x40

total album playing time in miliseconds

enum esp_avrc_rn_event_ids_t

AVRC event notification ids.

Values:

ESP_AVRC_RN_PLAY_STATUS_CHANGE = 0x01

track status change, eg. from playing to paused

ESP_AVRC_RN_TRACK_CHANGE = 0x02

new track is loaded

ESP_AVRC_RN_TRACK_REACHED_END = 0x03

current track reached end

ESP_AVRC_RN_TRACK_REACHED_START = 0x04

current track reached start position

ESP_AVRC_RN_PLAY_POS_CHANGED = 0x05

track playing position changed

ESP_AVRC_RN_BATTERY_STATUS_CHANGE = 0x06

battery status changed

ESP_AVRC_RN_SYSTEM_STATUS_CHANGE = 0x07

system status changed

ESP_AVRC_RN_APP_SETTING_CHANGE = 0x08

application settings changed

ESP_AVRC_RN_MAX_EVT
enum esp_avrc_ps_attr_ids_t

AVRC player setting ids.

Values:

ESP_AVRC_PS_EQUALIZER = 0x01

equalizer, on or off

ESP_AVRC_PS_REPEAT_MODE = 0x02

repeat mode

ESP_AVRC_PS_SHUFFLE_MODE = 0x03

shuffle mode

ESP_AVRC_PS_SCAN_MODE = 0x04

scan mode on or off

ESP_AVRC_PS_MAX_ATTR
enum esp_avrc_ps_eq_value_ids_t

AVRC equalizer modes.

Values:

ESP_AVRC_PS_EQUALIZER_OFF = 0x1

equalizer OFF

ESP_AVRC_PS_EQUALIZER_ON = 0x2

equalizer ON

enum esp_avrc_ps_rpt_value_ids_t

AVRC repeat modes.

Values:

ESP_AVRC_PS_REPEAT_OFF = 0x1

repeat mode off

ESP_AVRC_PS_REPEAT_SINGLE = 0x2

single track repeat

ESP_AVRC_PS_REPEAT_GROUP = 0x3

group repeat

enum esp_avrc_ps_shf_value_ids_t

AVRC shuffle modes.

Values:

ESP_AVRC_PS_SHUFFLE_OFF = 0x1
ESP_AVRC_PS_SHUFFLE_ALL = 0x2
ESP_AVRC_PS_SHUFFLE_GROUP = 0x3
enum esp_avrc_ps_scn_value_ids_t

AVRC scan modes.

Values:

ESP_AVRC_PS_SCAN_OFF = 0x1

scan off

ESP_AVRC_PS_SCAN_ALL = 0x2

all tracks scan

ESP_AVRC_PS_SCAN_GROUP = 0x3

group scan