1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD 2 // Copyright 2019 Blake Felt 3 // 4 // Licensed under the Apache License, Version 2.0 (the "License"); 5 // you may not use this file except in compliance with the License. 6 // You may obtain a copy of the License at 7 8 // http://www.apache.org/licenses/LICENSE-2.0 9 // 10 // Unless required by applicable law or agreed to in writing, software 11 // distributed under the License is distributed on an "AS IS" BASIS, 12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 // See the License for the specific language governing permissions and 14 // limitations under the License. 15 16 #ifndef __ESP_HIDH_API_H__ 17 #define __ESP_HIDH_API_H__ 18 19 #include "esp_bt_defs.h" 20 #include "esp_err.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 #define BTHH_MAX_DSC_LEN 884 27 28 /** 29 * @brief HID host connection state 30 */ 31 typedef enum { 32 ESP_HIDH_CONN_STATE_CONNECTED = 0, /*!< connected state */ 33 ESP_HIDH_CONN_STATE_CONNECTING, /*!< connecting state */ 34 ESP_HIDH_CONN_STATE_DISCONNECTED, /*!< disconnected state */ 35 ESP_HIDH_CONN_STATE_DISCONNECTING, /*!< disconnecting state */ 36 ESP_HIDH_CONN_STATE_UNKNOWN /*!< unknown state(initial state) */ 37 } esp_hidh_connection_state_t; 38 39 typedef enum { 40 ESP_HIDH_OK, 41 ESP_HIDH_HS_HID_NOT_READY, /*!< handshake error : device not ready */ 42 ESP_HIDH_HS_INVALID_RPT_ID, /*!< handshake error : invalid report ID */ 43 ESP_HIDH_HS_TRANS_NOT_SPT, /*!< handshake error : transaction not spt */ 44 ESP_HIDH_HS_INVALID_PARAM, /*!< handshake error : invalid paremter */ 45 ESP_HIDH_HS_ERROR, /*!< handshake error : unspecified HS error */ 46 ESP_HIDH_ERR, /*!< general ESP HH error */ 47 ESP_HIDH_ERR_SDP, /*!< SDP error */ 48 ESP_HIDH_ERR_PROTO, /*!< SET_Protocol error, 49 only used in ESP_HIDH_OPEN_EVT callback */ 50 51 ESP_HIDH_ERR_DB_FULL, /*!< device database full error, used in 52 ESP_HIDH_OPEN_EVT/ESP_HIDH_ADD_DEV_EVT */ 53 ESP_HIDH_ERR_TOD_UNSPT, /*!< type of device not supported */ 54 ESP_HIDH_ERR_NO_RES, /*!< out of system resources */ 55 ESP_HIDH_ERR_AUTH_FAILED, /*!< authentication fail */ 56 ESP_HIDH_ERR_HDL, /*!< connection handle error */ 57 ESP_HIDH_ERR_SEC, /*!< encryption error */ 58 // self_defined 59 ESP_HIDH_BUSY, /*!< Temporarily can not handle this request. */ 60 ESP_HIDH_NO_DATA, /*!< No data. */ 61 ESP_HIDH_NEED_INIT, /*!< HIDH module shall init first */ 62 ESP_HIDH_NEED_DEINIT, /*!< HIDH module shall deinit first */ 63 ESP_HIDH_NO_CONNECTION, /*!< connection may have been closed */ 64 } esp_hidh_status_t; 65 66 /** 67 * @brief HID host protocol modes 68 */ 69 typedef enum { 70 ESP_HIDH_BOOT_MODE = 0x00, /*!< boot protocol mode */ 71 ESP_HIDH_REPORT_MODE = 0x01, /*!< report protocol mode */ 72 ESP_HIDH_UNSUPPORTED_MODE = 0xff /*!< unsupported protocol mode */ 73 } esp_hidh_protocol_mode_t; 74 75 /** 76 * @brief HID host report types 77 */ 78 typedef enum { 79 ESP_HIDH_REPORT_TYPE_OTHER = 0, /*!< unsupported report type */ 80 ESP_HIDH_REPORT_TYPE_INPUT, /*!< input report type */ 81 ESP_HIDH_REPORT_TYPE_OUTPUT, /*!< output report type */ 82 ESP_HIDH_REPORT_TYPE_FEATURE, /*!< feature report type */ 83 } esp_hidh_report_type_t; 84 85 /** 86 * @brief HID host callback function events 87 */ 88 typedef enum { 89 ESP_HIDH_INIT_EVT = 0, /*!< When HID host is inited, the event comes */ 90 ESP_HIDH_DEINIT_EVT, /*!< When HID host is deinited, the event comes */ 91 ESP_HIDH_OPEN_EVT, /*!< When HID host connection opened, the event comes */ 92 ESP_HIDH_CLOSE_EVT, /*!< When HID host connection closed, the event comes */ 93 ESP_HIDH_GET_RPT_EVT, /*!< When Get_Report command is called, the event comes */ 94 ESP_HIDH_SET_RPT_EVT, /*!< When Set_Report command is called, the event comes */ 95 ESP_HIDH_GET_PROTO_EVT, /*!< When Get_Protocol command is called, the event comes */ 96 ESP_HIDH_SET_PROTO_EVT, /*!< When Set_Protocol command is called, the event comes */ 97 ESP_HIDH_GET_IDLE_EVT, /*!< When Get_Idle command is called, the event comes */ 98 ESP_HIDH_SET_IDLE_EVT, /*!< When Set_Idle command is called, the event comes */ 99 ESP_HIDH_GET_DSCP_EVT, /*!< When HIDH is inited, the event comes */ 100 ESP_HIDH_ADD_DEV_EVT, /*!< When a device is added, the event comes */ 101 ESP_HIDH_RMV_DEV_EVT, /*!< When a device is removed, the event comes */ 102 ESP_HIDH_VC_UNPLUG_EVT, /*!< When virtually unplugged, the event comes */ 103 ESP_HIDH_DATA_EVT, /*!< When send data on interrupt channel, the event comes */ 104 ESP_HIDH_DATA_IND_EVT, /*!< When receive data on interrupt channel, the event comes */ 105 ESP_HIDH_SET_INFO_EVT /*!< When set the HID device descriptor, the event comes */ 106 } esp_hidh_cb_event_t; 107 108 typedef struct { 109 int attr_mask; 110 uint8_t sub_class; 111 uint8_t app_id; 112 int vendor_id; 113 int product_id; 114 int version; 115 uint8_t ctry_code; 116 int dl_len; 117 uint8_t dsc_list[BTHH_MAX_DSC_LEN]; 118 } esp_hidh_hid_info_t; 119 120 /** 121 * @brief HID host callback parameters union 122 */ 123 typedef union { 124 /** 125 * @brief ESP_HIDH_INIT_EVT 126 */ 127 struct hidh_init_evt_param { 128 esp_hidh_status_t status; /*!< status */ 129 } init; /*!< HIDH callback param of ESP_HIDH_INIT_EVT */ 130 131 /** 132 * @brief ESP_HIDH_DEINIT_EVT 133 */ 134 struct hidh_uninit_evt_param { 135 esp_hidh_status_t status; /*!< status */ 136 } deinit; /*!< HIDH callback param of ESP_HIDH_DEINIT_EVT */ 137 138 /** 139 * @brief ESP_HIDH_OPEN_EVT 140 */ 141 struct hidh_open_evt_param { 142 esp_hidh_status_t status; /*!< operation status */ 143 esp_hidh_connection_state_t conn_status; /*!< connection status */ 144 bool is_orig; /*!< indicate if host intiate the connection */ 145 uint8_t handle; /*!< device handle */ 146 esp_bd_addr_t bd_addr; /*!< device address */ 147 } open; /*!< HIDH callback param of ESP_HIDH_OPEN_EVT */ 148 149 /** 150 * @brief ESP_HIDH_CLOSE_EVT 151 */ 152 struct hidh_close_evt_param { 153 esp_hidh_status_t status; /*!< operation status */ 154 uint8_t reason; /*!< lower layer failed reason(ref hiddefs.h) */ 155 esp_hidh_connection_state_t conn_status; /*!< connection status */ 156 uint8_t handle; /*!< device handle */ 157 } close; /*!< HIDH callback param of ESP_HIDH_CLOSE_EVT */ 158 159 /** 160 * @brief ESP_HIDH_VC_UNPLUG_EVT 161 */ 162 struct hidh_unplug_evt_param { 163 esp_hidh_status_t status; /*!< operation status */ 164 esp_hidh_connection_state_t conn_status; /*!< connection status */ 165 uint8_t handle; /*!< device handle */ 166 } unplug; /*!< HIDH callback param of ESP_HIDH_VC_UNPLUG_EVT */ 167 168 /** 169 * @brief ESP_HIDH_GET_PROTO_EVT 170 */ 171 struct hidh_get_proto_evt_param { 172 esp_hidh_status_t status; /*!< operation status */ 173 uint8_t handle; /*!< device handle */ 174 esp_hidh_protocol_mode_t proto_mode; /*!< protocol mode */ 175 } get_proto; /*!< HIDH callback param of ESP_HIDH_GET_PROTO_EVT */ 176 177 /** 178 * @brief ESP_HIDH_SET_PROTO_EVT 179 */ 180 struct hidh_set_proto_evt_param { 181 esp_hidh_status_t status; /*!< operation status */ 182 uint8_t handle; /*!< device handle */ 183 } set_proto; /*!< HIDH callback param of ESP_HIDH_SET_PROTO_EVT */ 184 185 /** 186 * @brief ESP_HIDH_GET_RPT_EVT 187 */ 188 struct hidh_get_rpt_evt_param { 189 esp_hidh_status_t status; /*!< operation status */ 190 uint8_t handle; /*!< device handle */ 191 uint16_t len; /*!< data length */ 192 uint8_t *data; /*!< data pointer */ 193 } get_rpt; /*!< HIDH callback param of ESP_HIDH_GET_RPT_EVT */ 194 195 /** 196 * @brief ESP_HIDH_SET_RPT_EVT 197 */ 198 struct hidh_set_rpt_evt_param { 199 esp_hidh_status_t status; /*!< operation status */ 200 uint8_t handle; /*!< device handle */ 201 } set_rpt; /*!< HIDH callback param of ESP_HIDH_SET_RPT_EVT */ 202 203 /** 204 * @brief ESP_HIDH_DATA_EVT 205 */ 206 struct hidh_send_data_evt_param { 207 esp_hidh_status_t status; /*!< operation status */ 208 uint8_t handle; /*!< device handle */ 209 uint8_t reason; /*!< lower layer failed reason(ref hiddefs.h) */ 210 } send_data; /*!< HIDH callback param of ESP_HIDH_DATA_EVT */ 211 212 /** 213 * @brief ESP_HIDH_GET_IDLE_EVT 214 */ 215 struct hidh_get_idle_evt_param { 216 esp_hidh_status_t status; /*!< operation status */ 217 uint8_t handle; /*!< device handle */ 218 uint8_t idle_rate; /*!< idle rate */ 219 } get_idle; /*!< HIDH callback param of ESP_HIDH_GET_IDLE_EVT */ 220 221 /** 222 * @brief ESP_HIDH_SET_IDLE_EVT 223 */ 224 struct hidh_set_idle_evt_param { 225 esp_hidh_status_t status; /*!< operation status */ 226 uint8_t handle; /*!< device handle */ 227 } set_idle; /*!< HIDH callback param of ESP_HIDH_SET_IDLE_EVT */ 228 229 /** 230 * @brief ESP_HIDH_DATA_IND_EVT 231 */ 232 struct hidh_data_ind_evt_param { 233 esp_hidh_status_t status; /*!< operation status */ 234 uint8_t handle; /*!< device handle */ 235 esp_hidh_protocol_mode_t proto_mode; /*!< protocol mode */ 236 uint16_t len; /*!< data length */ 237 uint8_t *data; /*!< data pointer */ 238 } data_ind; /*!< HIDH callback param of ESP_HIDH_DATA_IND_EVT */ 239 240 /** 241 * @brief ESP_HIDH_ADD_DEV_EVT 242 */ 243 struct hidh_add_dev_evt_param { 244 esp_hidh_status_t status; /*!< operation status */ 245 uint8_t handle; /*!< device handle */ 246 esp_bd_addr_t bd_addr; /*!< device address */ 247 } add_dev; /*!< HIDH callback param of ESP_HIDH_ADD_DEV_EVT */ 248 249 /** 250 * @brief ESP_HIDH_RMV_DEV_EVT 251 */ 252 struct hidh_rmv_dev_evt_param { 253 esp_hidh_status_t status; /*!< operation status */ 254 uint8_t handle; /*!< device handle */ 255 esp_bd_addr_t bd_addr; /*!< device address */ 256 } rmv_dev; /*!< HIDH callback param of ESP_HIDH_RMV_DEV_EVT */ 257 258 /** 259 * @brief ESP_HIDH_GET_DSCP_EVT 260 */ 261 struct hidh_get_dscp_evt_param { 262 esp_hidh_status_t status; /*!< operation status */ 263 uint8_t handle; /*!< device handle */ 264 bool added; /*!< Indicate if added */ 265 uint16_t vendor_id; /*!< Vendor ID */ 266 uint16_t product_id; /*!< Product ID */ 267 uint16_t version; /*!< Version */ 268 uint16_t ssr_max_latency; /*!< SSR max latency */ 269 uint16_t ssr_min_tout; /*!< SSR min timeout */ 270 uint8_t ctry_code; /*!< Country Code */ 271 uint16_t dl_len; /*!< Device descriptor length */ 272 uint8_t *dsc_list; /*!< Device descriptor pointer */ 273 } dscp; /*!< HIDH callback param of ESP_HIDH_GET_DSCP_EVT */ 274 275 /** 276 * @brief ESP_HIDH_SET_INFO_EVT 277 */ 278 struct hidh_set_info_evt_param { 279 esp_hidh_status_t status; /*!< operation status */ 280 uint8_t handle; /*!< device handle */ 281 esp_bd_addr_t bd_addr; /*!< device address */ 282 } set_info; /*!< HIDH callback param of ESP_HIDH_SET_INFO_EVT */ 283 } esp_hidh_cb_param_t; 284 285 /** 286 * @brief HID host callback function type 287 * @param event: Event type 288 * @param param: Point to callback parameter, currently is union type 289 */ 290 typedef void (esp_hh_cb_t)(esp_hidh_cb_event_t event, esp_hidh_cb_param_t *param); 291 292 /** 293 * @brief This function is called to init callbacks with HID host module. 294 * 295 * @param[in] callback: pointer to the init callback function. 296 * 297 * @return 298 * - ESP_OK: success 299 * - other: failed 300 */ 301 esp_err_t esp_bt_hid_host_register_callback(esp_hh_cb_t callback); 302 303 /** 304 * @brief This function initializes HID host. This function should be called after esp_bluedroid_enable() and 305 * esp_blueroid_init() success, and should be called after esp_bt_hid_host_register_callback(). 306 * When the operation is complete the callback function will be called with ESP_HIDH_INIT_EVT. 307 * 308 * @return 309 * - ESP_OK: success 310 * - other: failed 311 */ 312 esp_err_t esp_bt_hid_host_init(void); 313 314 /** 315 * @brief Closes the interface. This function should be called after esp_bluedroid_enable() and 316 * esp_blueroid_init() success, and should be called after esp_bt_hid_host_init(). 317 * When the operation is complete the callback function will be called with ESP_HIDH_DEINIT_EVT. 318 * 319 * @return - ESP_OK: success 320 * - other: failed 321 */ 322 esp_err_t esp_bt_hid_host_deinit(void); 323 324 /** 325 * @brief Connect to hid device. When the operation is complete the callback 326 * function will be called with ESP_HIDH_OPEN_EVT. 327 * 328 * @param[in] bd_addr: Remote device bluetooth device address. 329 * 330 * @return - ESP_OK: success 331 * - other: failed 332 */ 333 esp_err_t esp_bt_hid_host_connect(esp_bd_addr_t bd_addr); 334 335 /** 336 * @brief Disconnect from hid device. When the operation is complete the callback 337 * function will be called with ESP_HIDH_CLOSE_EVT. 338 * 339 * @param[in] bd_addr: Remote device bluetooth device address. 340 * 341 * @return - ESP_OK: success 342 * - other: failed 343 */ 344 esp_err_t esp_bt_hid_host_disconnect(esp_bd_addr_t bd_addr); 345 346 /** 347 * @brief Virtual UnPlug (VUP) the specified HID device. When the operation is complete the callback 348 * function will be called with ESP_HIDH_VC_UNPLUG_EVT. 349 * 350 * @param[in] bd_addr: Remote device bluetooth device address. 351 * 352 * @return - ESP_OK: success 353 * - other: failed 354 */ 355 esp_err_t esp_bt_hid_host_virtual_cable_unplug(esp_bd_addr_t bd_addr); 356 357 /** 358 * @brief Set the HID device descriptor for the specified HID device. When the operation is complete the callback 359 * function will be called with ESP_HIDH_SET_INFO_EVT. 360 * 361 * @param[in] bd_addr: Remote device bluetooth device address. 362 * @param[in] hid_info: HID device descriptor structure. 363 * 364 * @return - ESP_OK: success 365 * - other: failed 366 */ 367 esp_err_t esp_bt_hid_host_set_info(esp_bd_addr_t bd_addr, esp_hidh_hid_info_t *hid_info); 368 369 /** 370 * @brief Get the HID proto mode. When the operation is complete the callback 371 * function will be called with ESP_HIDH_GET_PROTO_EVT. 372 * 373 * @param[in] bd_addr: Remote device bluetooth device address. 374 * 375 * @return 376 * - ESP_OK: success 377 * - other: failed 378 */ 379 esp_err_t esp_bt_hid_host_get_protocol(esp_bd_addr_t bd_addr); 380 381 /** 382 * @brief Set the HID proto mode. When the operation is complete the callback 383 * function will be called with ESP_HIDH_SET_PROTO_EVT. 384 * 385 * @param[in] bd_addr: Remote device bluetooth device address. 386 * @param[in] protocol_mode: Protocol mode type. 387 * 388 * @return 389 * - ESP_OK: success 390 * - other: failed 391 */ 392 esp_err_t esp_bt_hid_host_set_protocol(esp_bd_addr_t bd_addr, esp_hidh_protocol_mode_t protocol_mode); 393 394 /** 395 * @brief Get the HID Idle Time. When the operation is complete the callback 396 * function will be called with ESP_HIDH_GET_IDLE_EVT. 397 * 398 * @param[in] bd_addr: Remote device bluetooth device address. 399 * 400 * @return 401 * - ESP_OK: success 402 * - other: failed 403 */ 404 esp_err_t esp_bt_hid_host_get_idle(esp_bd_addr_t bd_addr); 405 406 /** 407 * @brief Set the HID Idle Time. When the operation is complete the callback 408 * function will be called with ESP_HIDH_SET_IDLE_EVT. 409 * 410 * @param[in] bd_addr: Remote device bluetooth device address. 411 * @param[in] idle_time: Idle time rate 412 * 413 * @return - ESP_OK: success 414 * - other: failed 415 */ 416 esp_err_t esp_bt_hid_host_set_idle(esp_bd_addr_t bd_addr, uint16_t idle_time); 417 418 /** 419 * @brief Send a GET_REPORT to HID device. When the operation is complete the callback 420 * function will be called with ESP_HIDH_GET_RPT_EVT. 421 * 422 * @param[in] bd_addr: Remote device bluetooth device address. 423 * @param[in] report_type: Report type 424 * @param[in] report_id: Report id 425 * @param[in] buffer_size: Buffer size 426 * 427 * @return - ESP_OK: success 428 * - other: failed 429 */ 430 esp_err_t esp_bt_hid_host_get_report(esp_bd_addr_t bd_addr, esp_hidh_report_type_t report_type, uint8_t report_id, 431 int buffer_size); 432 433 /** 434 * @brief Send a SET_REPORT to HID device. When the operation is complete the callback 435 * function will be called with ESP_HIDH_SET_RPT_EVT. 436 * 437 * @param[in] bd_addr: Remote device bluetooth device address. 438 * @param[in] report_type: Report type 439 * @param[in] report: Report data pointer 440 * @param[in] len: Report data length 441 * 442 * @return - ESP_OK: success 443 * - other: failed 444 */ 445 esp_err_t esp_bt_hid_host_set_report(esp_bd_addr_t bd_addr, esp_hidh_report_type_t report_type, uint8_t *report, 446 size_t len); 447 448 /** 449 * @brief Send data to HID device. When the operation is complete the callback 450 * function will be called with ESP_HIDH_DATA_EVT. 451 * 452 * @param[in] bd_addr: Remote device bluetooth device address. 453 * @param[in] data: Data pointer 454 * @param[in] len: Data length 455 * 456 * @return - ESP_OK: success 457 * - other: failed 458 */ 459 esp_err_t esp_bt_hid_host_send_data(esp_bd_addr_t bd_addr, uint8_t *data, size_t len); 460 461 #ifdef __cplusplus 462 } 463 #endif 464 465 #endif 466
