1 /* 2 * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef __ESP_AVRC_API_H__ 8 #define __ESP_AVRC_API_H__ 9 10 #include <stdint.h> 11 #include <stdbool.h> 12 #include "esp_err.h" 13 #include "esp_bt_defs.h" 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 #define ESP_AVRC_TRANS_LABEL_MAX 15 /*!< max transaction label */ 20 21 /// AVRC feature bit mask 22 typedef enum { 23 ESP_AVRC_FEAT_RCTG = 0x0001, /*!< remote control target */ 24 ESP_AVRC_FEAT_RCCT = 0x0002, /*!< remote control controller */ 25 ESP_AVRC_FEAT_VENDOR = 0x0008, /*!< remote control vendor dependent commands */ 26 ESP_AVRC_FEAT_BROWSE = 0x0010, /*!< use browsing channel */ 27 ESP_AVRC_FEAT_META_DATA = 0x0040, /*!< remote control metadata transfer command/response */ 28 ESP_AVRC_FEAT_ADV_CTRL = 0x0200, /*!< remote control advanced control command/response */ 29 } esp_avrc_features_t; 30 31 /// AVRC supported features flag retrieved in SDP record 32 typedef enum { 33 ESP_AVRC_FEAT_FLAG_CAT1 = 0x0001, /*!< category 1 */ 34 ESP_AVRC_FEAT_FLAG_CAT2 = 0x0002, /*!< category 2 */ 35 ESP_AVRC_FEAT_FLAG_CAT3 = 0x0004, /*!< category 3 */ 36 ESP_AVRC_FEAT_FLAG_CAT4 = 0x0008, /*!< category 4 */ 37 ESP_AVRC_FEAT_FLAG_BROWSING = 0x0040, /*!< browsing */ 38 ESP_AVRC_FEAT_FLAG_COVER_ART_GET_IMAGE_PROP = 0x0080, /*!< Cover Art GetImageProperties */ 39 ESP_AVRC_FEAT_FLAG_COVER_ART_GET_IMAGE = 0x0100, /*!< Cover Art GetImage */ 40 ESP_AVRC_FEAT_FLAG_COVER_ART_GET_LINKED_THUMBNAIL = 0x0200, /*!< Cover Art GetLinkedThumbnail */ 41 } esp_avrc_feature_flag_t; 42 43 /// AVRC passthrough command code 44 typedef enum { 45 ESP_AVRC_PT_CMD_SELECT = 0x00, /*!< select */ 46 ESP_AVRC_PT_CMD_UP = 0x01, /*!< up */ 47 ESP_AVRC_PT_CMD_DOWN = 0x02, /*!< down */ 48 ESP_AVRC_PT_CMD_LEFT = 0x03, /*!< left */ 49 ESP_AVRC_PT_CMD_RIGHT = 0x04, /*!< right */ 50 ESP_AVRC_PT_CMD_RIGHT_UP = 0x05, /*!< right-up */ 51 ESP_AVRC_PT_CMD_RIGHT_DOWN = 0x06, /*!< right-down */ 52 ESP_AVRC_PT_CMD_LEFT_UP = 0x07, /*!< left-up */ 53 ESP_AVRC_PT_CMD_LEFT_DOWN = 0x08, /*!< left-down */ 54 ESP_AVRC_PT_CMD_ROOT_MENU = 0x09, /*!< root menu */ 55 ESP_AVRC_PT_CMD_SETUP_MENU = 0x0A, /*!< setup menu */ 56 ESP_AVRC_PT_CMD_CONT_MENU = 0x0B, /*!< contents menu */ 57 ESP_AVRC_PT_CMD_FAV_MENU = 0x0C, /*!< favorite menu */ 58 ESP_AVRC_PT_CMD_EXIT = 0x0D, /*!< exit */ 59 ESP_AVRC_PT_CMD_0 = 0x20, /*!< 0 */ 60 ESP_AVRC_PT_CMD_1 = 0x21, /*!< 1 */ 61 ESP_AVRC_PT_CMD_2 = 0x22, /*!< 2 */ 62 ESP_AVRC_PT_CMD_3 = 0x23, /*!< 3 */ 63 ESP_AVRC_PT_CMD_4 = 0x24, /*!< 4 */ 64 ESP_AVRC_PT_CMD_5 = 0x25, /*!< 5 */ 65 ESP_AVRC_PT_CMD_6 = 0x26, /*!< 6 */ 66 ESP_AVRC_PT_CMD_7 = 0x27, /*!< 7 */ 67 ESP_AVRC_PT_CMD_8 = 0x28, /*!< 8 */ 68 ESP_AVRC_PT_CMD_9 = 0x29, /*!< 9 */ 69 ESP_AVRC_PT_CMD_DOT = 0x2A, /*!< dot */ 70 ESP_AVRC_PT_CMD_ENTER = 0x2B, /*!< enter */ 71 ESP_AVRC_PT_CMD_CLEAR = 0x2C, /*!< clear */ 72 ESP_AVRC_PT_CMD_CHAN_UP = 0x30, /*!< channel up */ 73 ESP_AVRC_PT_CMD_CHAN_DOWN = 0x31, /*!< channel down */ 74 ESP_AVRC_PT_CMD_PREV_CHAN = 0x32, /*!< previous channel */ 75 ESP_AVRC_PT_CMD_SOUND_SEL = 0x33, /*!< sound select */ 76 ESP_AVRC_PT_CMD_INPUT_SEL = 0x34, /*!< input select */ 77 ESP_AVRC_PT_CMD_DISP_INFO = 0x35, /*!< display information */ 78 ESP_AVRC_PT_CMD_HELP = 0x36, /*!< help */ 79 ESP_AVRC_PT_CMD_PAGE_UP = 0x37, /*!< page up */ 80 ESP_AVRC_PT_CMD_PAGE_DOWN = 0x38, /*!< page down */ 81 ESP_AVRC_PT_CMD_POWER = 0x40, /*!< power */ 82 ESP_AVRC_PT_CMD_VOL_UP = 0x41, /*!< volume up */ 83 ESP_AVRC_PT_CMD_VOL_DOWN = 0x42, /*!< volume down */ 84 ESP_AVRC_PT_CMD_MUTE = 0x43, /*!< mute */ 85 ESP_AVRC_PT_CMD_PLAY = 0x44, /*!< play */ 86 ESP_AVRC_PT_CMD_STOP = 0x45, /*!< stop */ 87 ESP_AVRC_PT_CMD_PAUSE = 0x46, /*!< pause */ 88 ESP_AVRC_PT_CMD_RECORD = 0x47, /*!< record */ 89 ESP_AVRC_PT_CMD_REWIND = 0x48, /*!< rewind */ 90 ESP_AVRC_PT_CMD_FAST_FORWARD = 0x49, /*!< fast forward */ 91 ESP_AVRC_PT_CMD_EJECT = 0x4A, /*!< eject */ 92 ESP_AVRC_PT_CMD_FORWARD = 0x4B, /*!< forward */ 93 ESP_AVRC_PT_CMD_BACKWARD = 0x4C, /*!< backward */ 94 ESP_AVRC_PT_CMD_ANGLE = 0x50, /*!< angle */ 95 ESP_AVRC_PT_CMD_SUBPICT = 0x51, /*!< subpicture */ 96 ESP_AVRC_PT_CMD_F1 = 0x71, /*!< F1 */ 97 ESP_AVRC_PT_CMD_F2 = 0x72, /*!< F2 */ 98 ESP_AVRC_PT_CMD_F3 = 0x73, /*!< F3 */ 99 ESP_AVRC_PT_CMD_F4 = 0x74, /*!< F4 */ 100 ESP_AVRC_PT_CMD_F5 = 0x75, /*!< F5 */ 101 ESP_AVRC_PT_CMD_VENDOR = 0x7E, /*!< vendor unique */ 102 } esp_avrc_pt_cmd_t; 103 104 /// AVRC passthrough command filter 105 typedef enum { 106 ESP_AVRC_PSTH_FILTER_ALLOWED_CMD = 0, /*!< all of the PASSTHROUGH commands that can possibly be used, immutable */ 107 ESP_AVRC_PSTH_FILTER_SUPPORTED_CMD = 1, /*!< PASSTHROUGH commands selectively supported according to the current configuration */ 108 ESP_AVRC_PSTH_FILTER_SUPPORT_MAX, 109 } esp_avrc_psth_filter_t; 110 111 /// AVRC passthrough command bit mask 112 typedef struct { 113 uint16_t bits[8]; /*!< bit mask representation of PASSTHROUGH commands */ 114 } esp_avrc_psth_bit_mask_t; 115 116 typedef enum { 117 ESP_AVRC_BIT_MASK_OP_TEST = 0, /*!< operation code to test a specific bit */ 118 ESP_AVRC_BIT_MASK_OP_SET = 1, /*!< operation code to set a specific bit */ 119 ESP_AVRC_BIT_MASK_OP_CLEAR = 2, /*!< operation code to clear a specific bit */ 120 } esp_avrc_bit_mask_op_t; 121 122 /// AVRC passthrough command state 123 typedef enum { 124 ESP_AVRC_PT_CMD_STATE_PRESSED = 0, /*!< key pressed */ 125 ESP_AVRC_PT_CMD_STATE_RELEASED = 1 /*!< key released */ 126 } esp_avrc_pt_cmd_state_t; 127 128 /// AVRC Controller callback events 129 typedef enum { 130 ESP_AVRC_CT_CONNECTION_STATE_EVT = 0, /*!< connection state changed event */ 131 ESP_AVRC_CT_PASSTHROUGH_RSP_EVT = 1, /*!< passthrough response event */ 132 ESP_AVRC_CT_METADATA_RSP_EVT = 2, /*!< metadata response event */ 133 ESP_AVRC_CT_PLAY_STATUS_RSP_EVT = 3, /*!< play status response event */ 134 ESP_AVRC_CT_CHANGE_NOTIFY_EVT = 4, /*!< notification event */ 135 ESP_AVRC_CT_REMOTE_FEATURES_EVT = 5, /*!< feature of remote device indication event */ 136 ESP_AVRC_CT_GET_RN_CAPABILITIES_RSP_EVT = 6, /*!< supported notification events capability of peer device */ 137 ESP_AVRC_CT_SET_ABSOLUTE_VOLUME_RSP_EVT = 7, /*!< set absolute volume response event */ 138 } esp_avrc_ct_cb_event_t; 139 140 /// AVRC Target callback events 141 typedef enum { 142 ESP_AVRC_TG_CONNECTION_STATE_EVT = 0, /*!< connection state changed event */ 143 ESP_AVRC_TG_REMOTE_FEATURES_EVT = 1, /*!< feature of remote device indication event */ 144 ESP_AVRC_TG_PASSTHROUGH_CMD_EVT = 2, /*!< passthrough command event */ 145 ESP_AVRC_TG_SET_ABSOLUTE_VOLUME_CMD_EVT = 3, /*!< set absolute volume command from remote device */ 146 ESP_AVRC_TG_REGISTER_NOTIFICATION_EVT = 4, /*!< register notification event */ 147 ESP_AVRC_TG_SET_PLAYER_APP_VALUE_EVT = 5, /*!< set application attribute value, attribute refer to esp_avrc_ps_attr_ids_t */ 148 } esp_avrc_tg_cb_event_t; 149 150 /// AVRC metadata attribute mask 151 typedef enum { 152 ESP_AVRC_MD_ATTR_TITLE = 0x1, /*!< title of the playing track */ 153 ESP_AVRC_MD_ATTR_ARTIST = 0x2, /*!< track artist */ 154 ESP_AVRC_MD_ATTR_ALBUM = 0x4, /*!< album name */ 155 ESP_AVRC_MD_ATTR_TRACK_NUM = 0x8, /*!< track position on the album */ 156 ESP_AVRC_MD_ATTR_NUM_TRACKS = 0x10, /*!< number of tracks on the album */ 157 ESP_AVRC_MD_ATTR_GENRE = 0x20, /*!< track genre */ 158 ESP_AVRC_MD_ATTR_PLAYING_TIME = 0x40 /*!< total album playing time in miliseconds */ 159 } esp_avrc_md_attr_mask_t; 160 161 /// AVRC event notification ids 162 typedef enum { 163 ESP_AVRC_RN_PLAY_STATUS_CHANGE = 0x01, /*!< track status change, eg. from playing to paused */ 164 ESP_AVRC_RN_TRACK_CHANGE = 0x02, /*!< new track is loaded */ 165 ESP_AVRC_RN_TRACK_REACHED_END = 0x03, /*!< current track reached end */ 166 ESP_AVRC_RN_TRACK_REACHED_START = 0x04, /*!< current track reached start position */ 167 ESP_AVRC_RN_PLAY_POS_CHANGED = 0x05, /*!< track playing position changed */ 168 ESP_AVRC_RN_BATTERY_STATUS_CHANGE = 0x06, /*!< battery status changed */ 169 ESP_AVRC_RN_SYSTEM_STATUS_CHANGE = 0x07, /*!< system status changed */ 170 ESP_AVRC_RN_APP_SETTING_CHANGE = 0x08, /*!< application settings changed */ 171 ESP_AVRC_RN_NOW_PLAYING_CHANGE = 0x09, /*!< now playing content changed */ 172 ESP_AVRC_RN_AVAILABLE_PLAYERS_CHANGE = 0x0a, /*!< available players changed */ 173 ESP_AVRC_RN_ADDRESSED_PLAYER_CHANGE = 0x0b, /*!< the addressed player changed */ 174 ESP_AVRC_RN_UIDS_CHANGE = 0x0c, /*!< UIDs changed */ 175 ESP_AVRC_RN_VOLUME_CHANGE = 0x0d, /*!< volume changed locally on TG */ 176 ESP_AVRC_RN_MAX_EVT 177 } esp_avrc_rn_event_ids_t; 178 179 /// AVRC target notification event notification capability 180 typedef enum { 181 ESP_AVRC_RN_CAP_ALLOWED_EVT = 0, /*!< all of the notification events that can possibly be supported, immutable */ 182 ESP_AVRC_RN_CAP_SUPPORTED_EVT = 1, /*!< notification events selectively supported according to the current configuration */ 183 ESP_AVRC_RN_CAP_MAX, 184 } esp_avrc_rn_evt_cap_t; 185 186 /// AVRC target notification event capability bit mask 187 typedef struct { 188 uint16_t bits; /*!< bit mask representation of PASSTHROUGH commands */ 189 } esp_avrc_rn_evt_cap_mask_t; 190 191 /// AVRC notification response type 192 typedef enum { 193 ESP_AVRC_RN_RSP_INTERIM = 13, /*!< initial response to RegisterNotification, should be sent T_mtp(1000ms) from receiving the command */ 194 ESP_AVRC_RN_RSP_CHANGED = 15, /*!< final response to RegisterNotification command */ 195 } esp_avrc_rn_rsp_t; 196 197 /// AVRC player setting ids 198 typedef enum { 199 ESP_AVRC_PS_EQUALIZER = 0x01, /*!< equalizer, on or off */ 200 ESP_AVRC_PS_REPEAT_MODE = 0x02, /*!< repeat mode */ 201 ESP_AVRC_PS_SHUFFLE_MODE = 0x03, /*!< shuffle mode */ 202 ESP_AVRC_PS_SCAN_MODE = 0x04, /*!< scan mode on or off */ 203 ESP_AVRC_PS_MAX_ATTR 204 } esp_avrc_ps_attr_ids_t; 205 206 /// AVRC equalizer modes 207 typedef enum { 208 ESP_AVRC_PS_EQUALIZER_OFF = 0x1, /*!< equalizer OFF */ 209 ESP_AVRC_PS_EQUALIZER_ON = 0x2 /*!< equalizer ON */ 210 } esp_avrc_ps_eq_value_ids_t; 211 212 /// AVRC repeat modes 213 typedef enum { 214 ESP_AVRC_PS_REPEAT_OFF = 0x1, /*!< repeat mode off */ 215 ESP_AVRC_PS_REPEAT_SINGLE = 0x2, /*!< single track repeat */ 216 ESP_AVRC_PS_REPEAT_GROUP = 0x3 /*!< group repeat */ 217 } esp_avrc_ps_rpt_value_ids_t; 218 219 220 /// AVRC shuffle modes 221 typedef enum { 222 ESP_AVRC_PS_SHUFFLE_OFF = 0x1, /*<! shuffle off */ 223 ESP_AVRC_PS_SHUFFLE_ALL = 0x2, /*<! shuffle all tracks */ 224 ESP_AVRC_PS_SHUFFLE_GROUP = 0x3 /*<! group shuffle */ 225 } esp_avrc_ps_shf_value_ids_t; 226 227 /// AVRC scan modes 228 typedef enum { 229 ESP_AVRC_PS_SCAN_OFF = 0x1, /*!< scan off */ 230 ESP_AVRC_PS_SCAN_ALL = 0x2, /*!< all tracks scan */ 231 ESP_AVRC_PS_SCAN_GROUP = 0x3 /*!< group scan */ 232 } esp_avrc_ps_scn_value_ids_t; 233 234 /// AVCTP response codes 235 typedef enum { 236 ESP_AVRC_RSP_NOT_IMPL = 8, /*!< not implemented */ 237 ESP_AVRC_RSP_ACCEPT = 9, /*!< accept */ 238 ESP_AVRC_RSP_REJECT = 10, /*!< reject */ 239 ESP_AVRC_RSP_IN_TRANS = 11, /*!< in transition */ 240 ESP_AVRC_RSP_IMPL_STBL = 12, /*!< implemented/stable */ 241 ESP_AVRC_RSP_CHANGED = 13, /*!< changed */ 242 ESP_AVRC_RSP_INTERIM = 15, /*!< interim */ 243 } esp_avrc_rsp_t; 244 245 /// AVRCP battery status 246 typedef enum { 247 ESP_AVRC_BATT_NORMAL = 0, /*!< normal state */ 248 ESP_AVRC_BATT_WARNING = 1, /*!< unable to operate soon */ 249 ESP_AVRC_BATT_CRITICAL = 2, /*!< cannot operate any more */ 250 ESP_AVRC_BATT_EXTERNAL = 3, /*!< plugged to external power supply */ 251 ESP_AVRC_BATT_FULL_CHARGE = 4, /*!< when completely charged from external power supply */ 252 } esp_avrc_batt_stat_t; 253 254 /// AVRCP current status of playback 255 typedef enum { 256 ESP_AVRC_PLAYBACK_STOPPED = 0, /*!< stopped */ 257 ESP_AVRC_PLAYBACK_PLAYING = 1, /*!< playing */ 258 ESP_AVRC_PLAYBACK_PAUSED = 2, /*!< paused */ 259 ESP_AVRC_PLAYBACK_FWD_SEEK = 3, /*!< forward seek */ 260 ESP_AVRC_PLAYBACK_REV_SEEK = 4, /*!< reverse seek */ 261 ESP_AVRC_PLAYBACK_ERROR = 0xFF, /*!< error */ 262 } esp_avrc_playback_stat_t; 263 264 /// AVRCP notification parameters 265 typedef union 266 { 267 uint8_t volume; /*!< response data for ESP_AVRC_RN_VOLUME_CHANGE, ranges 0..127 */ 268 esp_avrc_playback_stat_t playback; /*!< response data for ESP_AVRC_RN_PLAY_STATUS_CHANGE */ 269 uint8_t elm_id[8]; /*!< response data for ESP_AVRC_RN_TRACK_CHANGE */ 270 uint32_t play_pos; /*!< response data for ESP_AVRC_RN_PLAY_POS_CHANGED, in millisecond */ 271 esp_avrc_batt_stat_t batt; /*!< response data for ESP_AVRC_RN_BATTERY_STATUS_CHANGE */ 272 } esp_avrc_rn_param_t; 273 274 /// AVRCP set app value parameters 275 typedef struct { 276 uint8_t attr_id; /*!< player application attribute id */ 277 uint8_t attr_val; /*!< player application attribute value */ 278 } esp_avrc_set_app_value_param_t; 279 280 /// AVRC controller callback parameters 281 typedef union { 282 /** 283 * @brief ESP_AVRC_CT_CONNECTION_STATE_EVT 284 */ 285 struct avrc_ct_conn_stat_param { 286 bool connected; /*!< whether AVRC connection is set up */ 287 esp_bd_addr_t remote_bda; /*!< remote bluetooth device address */ 288 } conn_stat; /*!< AVRC connection status */ 289 290 /** 291 * @brief ESP_AVRC_CT_PASSTHROUGH_RSP_EVT 292 */ 293 struct avrc_ct_psth_rsp_param { 294 uint8_t tl; /*!< transaction label, 0 to 15 */ 295 uint8_t key_code; /*!< passthrough command code */ 296 uint8_t key_state; /*!< 0 for PRESSED, 1 for RELEASED */ 297 esp_avrc_rsp_t rsp_code; /*!< response code */ 298 } psth_rsp; /*!< passthrough command response */ 299 300 /** 301 * @brief ESP_AVRC_CT_METADATA_RSP_EVT 302 */ 303 struct avrc_ct_meta_rsp_param { 304 uint8_t attr_id; /*!< id of metadata attribute */ 305 uint8_t *attr_text; /*!< attribute itself */ 306 int attr_length; /*!< attribute character length */ 307 } meta_rsp; /*!< metadata attributes response */ 308 309 /** 310 * @brief ESP_AVRC_CT_CHANGE_NOTIFY_EVT 311 */ 312 struct avrc_ct_change_notify_param { 313 uint8_t event_id; /*!< id of AVRC event notification */ 314 esp_avrc_rn_param_t event_parameter; /*!< event notification parameter */ 315 } change_ntf; /*!< notifications */ 316 317 /** 318 * @brief ESP_AVRC_CT_REMOTE_FEATURES_EVT 319 */ 320 struct avrc_ct_rmt_feats_param { 321 uint32_t feat_mask; /*!< AVRC feature mask of remote device */ 322 uint16_t tg_feat_flag; /*!< feature flag of remote device as TG */ 323 esp_bd_addr_t remote_bda; /*!< remote bluetooth device address */ 324 } rmt_feats; /*!< AVRC features discovered from remote SDP server */ 325 326 /** 327 * @brief ESP_AVRC_CT_GET_RN_CAPABILITIES_RSP_EVT 328 */ 329 struct avrc_ct_get_rn_caps_rsp_param { 330 uint8_t cap_count; /*!< number of items provided in event or company_id according to cap_id used */ 331 esp_avrc_rn_evt_cap_mask_t evt_set; /*!< supported event_ids represented in bit-mask */ 332 } get_rn_caps_rsp; /*!< get supported event capabilities response from AVRCP target */ 333 334 /** 335 * @brief ESP_AVRC_CT_SET_ABSOLUTE_VOLUME_RSP_EVT 336 */ 337 struct avrc_ct_set_volume_rsp_param { 338 uint8_t volume; /*!< the volume which has actually been set, range is 0 to 0x7f, means 0% to 100% */ 339 } set_volume_rsp; /*!< set absolute volume response event */ 340 } esp_avrc_ct_cb_param_t; 341 342 /// AVRC target callback parameters 343 typedef union { 344 /** 345 * @brief ESP_AVRC_TG_CONNECTION_STATE_EVT 346 */ 347 struct avrc_tg_conn_stat_param { 348 bool connected; /*!< whether AVRC connection is set up */ 349 esp_bd_addr_t remote_bda; /*!< remote bluetooth device address */ 350 } conn_stat; /*!< AVRC connection status */ 351 352 /** 353 * @brief ESP_AVRC_TG_REMOTE_FEATURES_EVT 354 */ 355 struct avrc_tg_rmt_feats_param { 356 uint32_t feat_mask; /*!< AVRC feature mask of remote device */ 357 uint16_t ct_feat_flag; /*!< feature flag of remote device as CT */ 358 esp_bd_addr_t remote_bda; /*!< remote bluetooth device address */ 359 } rmt_feats; /*!< AVRC features discovered through SDP */ 360 361 /** 362 * @brief ESP_AVRC_TG_PASSTHROUGH_CMD_EVT 363 */ 364 struct avrc_tg_psth_cmd_param { 365 uint8_t key_code; /*!< passthrough command code */ 366 uint8_t key_state; /*!< 0 for PRESSED, 1 for RELEASED */ 367 } psth_cmd; /*!< passthrough command */ 368 369 /** 370 * @brief ESP_AVRC_TG_SET_ABSOLUTE_VOLUME_CMD_EVT 371 */ 372 struct avrc_tg_set_abs_vol_param { 373 uint8_t volume; /*!< volume ranges from 0 to 127 */ 374 } set_abs_vol; /*!< set absolute volume command targeted on audio sink */ 375 376 /** 377 * @brief ESP_AVRC_TG_REGISTER_NOTIFICATION_EVT 378 */ 379 struct avrc_tg_reg_ntf_param { 380 uint8_t event_id; /*!< event id of AVRC RegisterNotification */ 381 uint32_t event_parameter; /*!< event notification parameter */ 382 } reg_ntf; /*!< register notification */ 383 384 /** 385 * @brief ESP_AVRC_TG_SET_PLAYER_APP_VALUE_EVT 386 */ 387 struct avrc_tg_set_app_value_param { 388 uint8_t num_val; /*!< attribute num */ 389 esp_avrc_set_app_value_param_t *p_vals; /*!< point to the id and value of player application attribute */ 390 } set_app_value; /*!< set player application value */ 391 392 } esp_avrc_tg_cb_param_t; 393 394 /** 395 * @brief AVRCP controller callback function type 396 * 397 * @param event : Event type 398 * 399 * @param param : Pointer to callback parameter union 400 */ 401 typedef void (* esp_avrc_ct_cb_t)(esp_avrc_ct_cb_event_t event, esp_avrc_ct_cb_param_t *param); 402 403 /** 404 * @brief AVRCP target callback function type 405 * 406 * @param event : Event type 407 * 408 * @param param : Pointer to callback parameter union 409 */ 410 typedef void (* esp_avrc_tg_cb_t)(esp_avrc_tg_cb_event_t event, esp_avrc_tg_cb_param_t *param); 411 412 413 /** 414 * @brief Register application callbacks to AVRCP module. This function should be 415 * called after esp_bluedroid_enable() completes successfully. 416 * 417 * @param[in] callback: AVRCP controller callback function 418 * 419 * @return 420 * - ESP_OK: success 421 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 422 * - ESP_FAIL: others 423 * 424 */ 425 esp_err_t esp_avrc_ct_register_callback(esp_avrc_ct_cb_t callback); 426 427 /** 428 * 429 * @brief Initialize the bluetooth AVRCP controller module, This function should be called 430 * after esp_bluedroid_enable() completes successfully. Note: AVRC cannot work independently, 431 * AVRC should be used along with A2DP and AVRC should be initialized before A2DP. 432 * 433 * @return 434 * - ESP_OK: success 435 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 436 * - ESP_FAIL: others 437 * 438 */ 439 esp_err_t esp_avrc_ct_init(void); 440 441 /** 442 * 443 * @brief De-initialize AVRCP controller module. This function should be called after 444 * after esp_bluedroid_enable() completes successfully. Note: AVRC cannot work independently, 445 * AVRC should be used along with A2DP and AVRC should be deinitialized before A2DP. 446 * 447 * @return 448 * - ESP_OK: success 449 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 450 * - ESP_FAIL: others 451 */ 452 esp_err_t esp_avrc_ct_deinit(void); 453 454 /** 455 * 456 * @brief Send player application settings command to AVRCP target. This function should be called 457 * after ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established. 458 * 459 * @param[in] tl : transaction label, 0 to 15, consecutive commands should use different values 460 * 461 * @param[in] attr_id : player application setting attribute IDs from one of esp_avrc_ps_attr_ids_t 462 * 463 * @param[in] value_id : attribute value defined for the specific player application setting attribute 464 * 465 * @return 466 * - ESP_OK: success 467 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 468 * - ESP_FAIL: others 469 */ 470 esp_err_t esp_avrc_ct_send_set_player_value_cmd(uint8_t tl, uint8_t attr_id, uint8_t value_id); 471 472 /** 473 * @brief Send GetCapabilities PDU to AVRCP target to retrieve remote device's supported 474 * notification event_ids. This function should be called after 475 * ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established. 476 * 477 * @param[in] tl : transaction label, 0 to 15, consecutive commands should use different values 478 * 479 * @return 480 * - ESP_OK: success 481 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 482 * - ESP_FAIL: others 483 */ 484 esp_err_t esp_avrc_ct_send_get_rn_capabilities_cmd(uint8_t tl); 485 486 /** 487 * @brief Send register notification command to AVRCP target. This function should be called after 488 * ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established. 489 * 490 * @param[in] tl : transaction label, 0 to 15, consecutive commands should use different values. 491 * 492 * @param[in] event_id : id of events, e.g. ESP_AVRC_RN_PLAY_STATUS_CHANGE, ESP_AVRC_RN_TRACK_CHANGE, etc. 493 * 494 * @param[in] event_parameter : playback interval for ESP_AVRC_RN_PLAY_POS_CHANGED; 495 * For other events , value of this parameter is ignored. 496 * @return 497 * - ESP_OK: success 498 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 499 * - ESP_ERR_NOT_SUPPORTED: if the event_id is not supported in current implementation 500 * - ESP_FAIL: others 501 */ 502 esp_err_t esp_avrc_ct_send_register_notification_cmd(uint8_t tl, uint8_t event_id, uint32_t event_parameter); 503 504 /** 505 * @brief Send set absolute volume command to AVRCP target. This function should be called after 506 * ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established. 507 * 508 * @param[in] tl : transaction label, 0 to 15, consecutive commands should use different values 509 * 510 * @param[in] volume : volume, 0 to 0x7f, means 0% to 100% 511 * 512 * @return 513 * - ESP_OK: success 514 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 515 * - ESP_ERR_NOT_SUPPORTED: if the event_id is not supported in current implementation 516 * - ESP_FAIL: others 517 */ 518 esp_err_t esp_avrc_ct_send_set_absolute_volume_cmd(uint8_t tl, uint8_t volume); 519 520 /** 521 * @brief Send metadata command to AVRCP target. This function should be called after 522 * ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established. 523 * 524 * @param[in] tl : transaction label, 0 to 15, consecutive commands should use different values. 525 * 526 * @param[in] attr_mask : mask of attributes, e.g. ESP_AVRC_MD_ATTR_ID_TITLE | ESP_AVRC_MD_ATTR_ID_ARTIST. 527 * 528 * @return 529 * - ESP_OK: success 530 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 531 * - ESP_FAIL: others 532 */ 533 esp_err_t esp_avrc_ct_send_metadata_cmd(uint8_t tl, uint8_t attr_mask); 534 535 536 /** 537 * @brief Send passthrough command to AVRCP target. This function should be called after 538 * ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established. 539 * 540 * @param[in] tl : transaction label, 0 to 15, consecutive commands should use different values. 541 * 542 * @param[in] key_code : passthrough command code, e.g. ESP_AVRC_PT_CMD_PLAY, ESP_AVRC_PT_CMD_STOP, etc. 543 * 544 * @param[in] key_state : passthrough command key state, ESP_AVRC_PT_CMD_STATE_PRESSED or 545 * ESP_AVRC_PT_CMD_STATE_RELEASED 546 * 547 * @return 548 * - ESP_OK: success 549 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 550 * - ESP_FAIL: others 551 */ 552 esp_err_t esp_avrc_ct_send_passthrough_cmd(uint8_t tl, uint8_t key_code, uint8_t key_state); 553 554 555 /** 556 * @brief Register application callbacks to AVRCP target module. This function should be 557 * called after esp_bluedroid_enable() completes successfully. 558 * 559 * @param[in] callback: AVRCP target callback function 560 * 561 * @return 562 * - ESP_OK: success 563 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 564 * - ESP_FAIL: others 565 * 566 */ 567 esp_err_t esp_avrc_tg_register_callback(esp_avrc_tg_cb_t callback); 568 569 /** 570 * 571 * @brief Initialize the bluetooth AVRCP target module, This function should be called 572 * after esp_bluedroid_enable() completes successfully. Note: AVRC cannot work independently, 573 * AVRC should be used along with A2DP and AVRC should be initialized before A2DP. 574 * 575 * @return 576 * - ESP_OK: success 577 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 578 * - ESP_FAIL: others 579 * 580 */ 581 esp_err_t esp_avrc_tg_init(void); 582 583 /** 584 * 585 * @brief De-initialize AVRCP target module. This function should be called after 586 * after esp_bluedroid_enable() completes successfully. Note: AVRC cannot work independently, 587 * AVRC should be used along with A2DP and AVRC should be deinitialized before A2DP. 588 * 589 * @return 590 * - ESP_OK: success 591 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 592 * - ESP_FAIL: others 593 */ 594 esp_err_t esp_avrc_tg_deinit(void); 595 596 /** 597 * 598 * @brief Get the current filter of remote passthrough commands on AVRC target. Filter is given by 599 * filter type and bit mask for the passthrough commands. This function should be called 600 * after esp_avrc_tg_init(). 601 * For filter type ESP_AVRC_PSTH_FILTER_ALLOWED_CMD, the retrieved command set is constant and 602 * it covers all of the passthrough commands that can possibly be supported. 603 * For filter type ESP_AVRC_PSTH_FILTER_SUPPORT_COMMANDS, the retrieved command set covers the 604 * passthrough commands selected to be supported according to current configuration. The 605 * configuration can be changed using esp_avrc_tg_set_psth_cmd_filter(). 606 * 607 * @return 608 * - ESP_OK: success 609 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled or AVRC TG is not initialized 610 * - ESP_ERR_INVALID_ARG: if filter type is invalid or cmd_set is NULL 611 * - ESP_FAIL: otherwise 612 */ 613 esp_err_t esp_avrc_tg_get_psth_cmd_filter(esp_avrc_psth_filter_t filter, esp_avrc_psth_bit_mask_t *cmd_set); 614 615 /** 616 * 617 * @brief Set the filter of remote passthrough commands on AVRC target. Filter is given by 618 * filter type and bit mask for the passthrough commands. This function should be called 619 * after esp_avrc_tg_init(). 620 * 621 * If filter type is ESP_AVRC_PSTH_FILTER_SUPPORT_CMD, the passthrough commands which 622 * are set "1" as given in cmd_set will generate ESP_AVRC_CT_PASSTHROUGH_RSP_EVT callback 623 * event and are auto-accepted in the protocol stack, other commands are replied with response 624 * type "NOT IMPLEMENTED" (8). The set of supported commands should be a subset of allowed 625 * command set. The allowed command set can be retrieved using esp_avrc_tg_get_psth_cmd_filter() 626 * with filter type "ESP_AVRC_PSTH_FILTER_ALLOWED_CMD". 627 * 628 * Filter type "ESP_AVRC_PSTH_FILTER_ALLOWED_CMD" does not apply to this function. 629 * 630 * @return 631 * - ESP_OK: success 632 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled 633 * - ESP_ERR_INVALID_ARG: if filter type is invalid or cmd_set is NULL 634 * - ESP_ERR_NOT_SUPPORTED:: if filter type is ESP_AVRC_PSTH_FILTER_ALLOWED_CMD, or cmd_set 635 * includes commands that are not allowed 636 * 637 */ 638 esp_err_t esp_avrc_tg_set_psth_cmd_filter(esp_avrc_psth_filter_t filter, const esp_avrc_psth_bit_mask_t *cmd_set); 639 640 /** 641 * @brief Operate on the type esp_avrc_psth_bit_mask_t with regard to a specific PASSTHROUGH command. 642 * 643 * @param[in] op: operation requested on the bit mask field 644 * 645 * @param[in] psth: pointer to passthrough command bit mask structure 646 * 647 * @param[in] cmd: passthrough command code 648 * 649 * @return For operation ESP_AVRC_BIT_MASK_OP_SET or ESP_AVRC_BIT_MASK_OP_CLEAR, return 650 * true for a successful operation, otherwise return false. 651 * For operation ESP_AVRC_BIT_MASK_OP_TEST, return true if the corresponding bit 652 * is set, otherwise false. 653 * 654 */ 655 bool esp_avrc_psth_bit_mask_operation(esp_avrc_bit_mask_op_t op, esp_avrc_psth_bit_mask_t *psth, esp_avrc_pt_cmd_t cmd); 656 657 /** 658 * 659 * @brief Get the requested event notification capabilies on local AVRC target. The capability is returned 660 * in a bit mask representation in evt_set. This function should be called after esp_avrc_tg_init(). 661 * 662 * For capability type "ESP_AVRC_RN_CAP_ALLOWED_EVT, the retrieved event set is constant and 663 * it covers all of the notifcation events that can possibly be supported with current 664 * implementation. 665 * 666 * For capability type ESP_AVRC_RN_CAP_SUPPORTED_EVT, the event set covers the notification 667 * events selected to be supported under current configuration, The configuration can be 668 * changed using esp_avrc_tg_set_rn_evt_cap(). 669 * 670 * @return 671 * - ESP_OK: success 672 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled or AVRC TG is not initialized 673 * - ESP_ERR_INVALID_ARG: if cap is invalid or evt_set is NULL 674 * - ESP_FAIL: otherwise 675 */ 676 esp_err_t esp_avrc_tg_get_rn_evt_cap(esp_avrc_rn_evt_cap_t cap, esp_avrc_rn_evt_cap_mask_t *evt_set); 677 678 /** 679 * 680 * @brief Set the event notification capabilities on local AVRCP target. The capability is given in a 681 * bit mask representation in evt_set and must be a subset of allowed event IDs with current 682 * implementation. This function should be called after esp_avrc_tg_init(). 683 * 684 * @return 685 * - ESP_OK: success 686 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled 687 * - ESP_ERR_INVALID_ARG: if evt_set is NULL 688 * 689 */ 690 esp_err_t esp_avrc_tg_set_rn_evt_cap(const esp_avrc_rn_evt_cap_mask_t *evt_set); 691 692 /** 693 * @brief Operate on the type esp_avrc_rn_evt_cap_mask_t with regard to a specific event. 694 * 695 * @param[in] op: operation requested on the bit mask field 696 * 697 * @param[in] events: pointer to event notification capability bit mask structure 698 * 699 * @param[in] event_id: notification event code 700 * 701 * @return For operation ESP_AVRC_BIT_MASK_OP_SET or ESP_AVRC_BIT_MASK_OP_CLEAR, return 702 * true for a successful operation, otherwise return false. 703 * 704 * For operation ESP_AVRC_BIT_MASK_OP_TEST, return true if the corresponding bit 705 * is set, otherwise false. 706 * 707 */ 708 bool esp_avrc_rn_evt_bit_mask_operation(esp_avrc_bit_mask_op_t op, esp_avrc_rn_evt_cap_mask_t *events, 709 esp_avrc_rn_event_ids_t event_id); 710 711 /** 712 * 713 * @brief Send RegisterNotification Response to remote AVRCP controller. Local event notification 714 * capability can be set using esp_avrc_tg_set_rn_evt_cap(), in a bit mask representation 715 * in evt_set. This function should be called after esp_avrc_tg_init(). 716 * 717 * @param[in] event_id: notification event ID that remote AVRCP CT registers 718 * 719 * @param[in] rsp: notification response code 720 * 721 * @param[in] param: parameters included in the specific notification 722 * 723 * @return 724 * - ESP_OK: success 725 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled or AVRC TG is not initialized 726 * - ESP_ERR_INVALID_ARG: if evt_set is NULL 727 * 728 */ 729 esp_err_t esp_avrc_tg_send_rn_rsp(esp_avrc_rn_event_ids_t event_id, esp_avrc_rn_rsp_t rsp, 730 esp_avrc_rn_param_t *param); 731 732 #ifdef __cplusplus 733 } 734 #endif 735 736 #endif /* __ESP_AVRC_API_H__ */ 737
