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