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_HIDD_API_H__ 17 #define __ESP_HIDD_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 /* sub_class of hid device */ 27 #define ESP_HID_CLASS_UNKNOWN (0x00<<2) 28 #define ESP_HID_CLASS_JOS (0x01<<2) /* joy stick */ 29 #define ESP_HID_CLASS_GPD (0x02<<2) /* game pad */ 30 #define ESP_HID_CLASS_RMC (0x03<<2) /* remote control */ 31 #define ESP_HID_CLASS_SED (0x04<<2) /* sensing device */ 32 #define ESP_HID_CLASS_DGT (0x05<<2) /* Digitizer tablet */ 33 #define ESP_HID_CLASS_CDR (0x06<<2) /* card reader */ 34 #define ESP_HID_CLASS_KBD (0x10<<2) /* keyboard */ 35 #define ESP_HID_CLASS_MIC (0x20<<2) /* pointing device */ 36 #define ESP_HID_CLASS_COM (0x30<<2) /* Combo keyboard/pointing */ 37 38 /** 39 * @brief HIDD handshake error 40 */ 41 typedef enum { 42 ESP_HID_PAR_HANDSHAKE_RSP_SUCCESS = 0, 43 ESP_HID_PAR_HANDSHAKE_RSP_NOT_READY = 1, 44 ESP_HID_PAR_HANDSHAKE_RSP_ERR_INVALID_REP_ID = 2, 45 ESP_HID_PAR_HANDSHAKE_RSP_ERR_UNSUPPORTED_REQ = 3, 46 ESP_HID_PAR_HANDSHAKE_RSP_ERR_INVALID_PARAM = 4, 47 ESP_HID_PAR_HANDSHAKE_RSP_ERR_UNKNOWN = 14, 48 ESP_HID_PAR_HANDSHAKE_RSP_ERR_FATAL = 15 49 } esp_hidd_handshake_error_t; 50 51 /** 52 * @brief HIDD report types 53 */ 54 typedef enum { 55 ESP_HIDD_REPORT_TYPE_OTHER = 0, 56 ESP_HIDD_REPORT_TYPE_INPUT, 57 ESP_HIDD_REPORT_TYPE_OUTPUT, 58 ESP_HIDD_REPORT_TYPE_FEATURE, 59 // special value for reports to be sent on INTR(INPUT is assumed) 60 ESP_HIDD_REPORT_TYPE_INTRDATA 61 } esp_hidd_report_type_t; 62 63 /** 64 * @brief HIDD connection state 65 */ 66 typedef enum { 67 ESP_HIDD_CONN_STATE_CONNECTED, 68 ESP_HIDD_CONN_STATE_CONNECTING, 69 ESP_HIDD_CONN_STATE_DISCONNECTED, 70 ESP_HIDD_CONN_STATE_DISCONNECTING, 71 ESP_HIDD_CONN_STATE_UNKNOWN 72 } esp_hidd_connection_state_t; 73 74 /** 75 * @brief HID device protocol modes 76 */ 77 typedef enum { 78 ESP_HIDD_REPORT_MODE = 0x00, 79 ESP_HIDD_BOOT_MODE = 0x01, 80 ESP_HIDD_UNSUPPORTED_MODE = 0xff 81 } esp_hidd_protocol_mode_t; 82 83 84 /** 85 * @brief HIDD characteristics for SDP report 86 */ 87 typedef struct { 88 const char *name; 89 const char *description; 90 const char *provider; 91 uint8_t subclass; 92 uint8_t *desc_list; 93 int desc_list_len; 94 } esp_hidd_app_param_t; 95 96 /** 97 * @brief HIDD Quality of Service parameters 98 */ 99 typedef struct { 100 uint8_t service_type; 101 uint32_t token_rate; 102 uint32_t token_bucket_size; 103 uint32_t peak_bandwidth; 104 uint32_t access_latency; 105 uint32_t delay_variation; 106 } esp_hidd_qos_param_t; 107 108 /** 109 * @brief HID device callback function events 110 */ 111 typedef enum { 112 ESP_HIDD_INIT_EVT = 0, /*!< When HID device is inited, the event comes */ 113 ESP_HIDD_DEINIT_EVT, /*!< When HID device is deinited, the event comes */ 114 ESP_HIDD_REGISTER_APP_EVT, /*!< When HID device application registered, the event comes */ 115 ESP_HIDD_UNREGISTER_APP_EVT, /*!< When HID device application unregistered, the event comes */ 116 ESP_HIDD_OPEN_EVT, /*!< When HID device connection to host opened, the event comes */ 117 ESP_HIDD_CLOSE_EVT, /*!< When HID device connection to host closed, the event comes */ 118 ESP_HIDD_SEND_REPORT_EVT, /*!< When HID device send report to lower layer, the event comes */ 119 ESP_HIDD_REPORT_ERR_EVT, /*!< When HID device report handshanke error to lower layer, the event comes */ 120 ESP_HIDD_GET_REPORT_EVT, /*!< When HID device receives GET_REPORT request from host, the event comes */ 121 ESP_HIDD_SET_REPORT_EVT, /*!< When HID device receives SET_REPORT request from host, the event comes */ 122 ESP_HIDD_SET_PROTOCOL_EVT, /*!< When HID device receives SET_PROTOCOL request from host, the event comes */ 123 ESP_HIDD_INTR_DATA_EVT, /*!< When HID device receives DATA from host on intr, the event comes */ 124 ESP_HIDD_VC_UNPLUG_EVT, /*!< When HID device initiates Virtual Cable Unplug, the event comes */ 125 ESP_HIDD_API_ERR_EVT /*!< When HID device has API error, the event comes */ 126 } esp_hidd_cb_event_t; 127 128 typedef enum { 129 ESP_HIDD_SUCCESS, 130 ESP_HIDD_ERROR, /*!< general ESP HD error */ 131 ESP_HIDD_NO_RES, /*!< out of system resources */ 132 ESP_HIDD_BUSY, /*!< Temporarily can not handle this request. */ 133 ESP_HIDD_NO_DATA, /*!< No data. */ 134 ESP_HIDD_NEED_INIT, /*!< HIDD module shall init first */ 135 ESP_HIDD_NEED_DEINIT, /*!< HIDD module shall deinit first */ 136 ESP_HIDD_NEED_REG, /*!< HIDD module shall register first */ 137 ESP_HIDD_NEED_DEREG, /*!< HIDD module shall deregister first */ 138 ESP_HIDD_NO_CONNECTION, /*!< connection may have been closed */ 139 } esp_hidd_status_t; 140 141 /** 142 * @brief HID device callback parameters union 143 */ 144 typedef union { 145 /** 146 * @brief ESP_HIDD_INIT_EVT 147 */ 148 struct hidd_init_evt_param { 149 esp_hidd_status_t status; /*!< operation status */ 150 } init; /*!< HIDD callback param of ESP_HIDD_INIT_EVT */ 151 152 /** 153 * @brief ESP_HIDD_DEINIT_EVT 154 */ 155 struct hidd_deinit_evt_param { 156 esp_hidd_status_t status; /*!< operation status */ 157 } deinit; /*!< HIDD callback param of ESP_HIDD_DEINIT_EVT */ 158 159 /** 160 * @brief ESP_HIDD_REGISTER_APP_EVT 161 */ 162 struct hidd_register_app_evt_param { 163 esp_hidd_status_t status; /*!< operation status */ 164 bool in_use; /*!< indicate whether use virtual cable plug host address */ 165 esp_bd_addr_t bd_addr; /*!< host address */ 166 } register_app; /*!< HIDD callback param of ESP_HIDD_REGISTER_APP_EVT */ 167 168 /** 169 * @brief ESP_HIDD_UNREGISTER_APP_EVT 170 */ 171 struct hidd_unregister_app_evt_param { 172 esp_hidd_status_t status; /*!< operation status */ 173 } unregister_app; /*!< HIDD callback param of ESP_HIDD_UNREGISTER_APP_EVT */ 174 175 /** 176 * @brief ESP_HIDD_OPEN_EVT 177 */ 178 struct hidd_open_evt_param { 179 esp_hidd_status_t status; /*!< operation status */ 180 esp_hidd_connection_state_t conn_status; /*!< connection status */ 181 esp_bd_addr_t bd_addr; /*!< host address */ 182 } open; /*!< HIDD callback param of ESP_HIDD_OPEN_EVT */ 183 184 /** 185 * @brief ESP_HIDD_CLOSE_EVT 186 */ 187 struct hidd_close_evt_param { 188 esp_hidd_status_t status; /*!< operation status */ 189 esp_hidd_connection_state_t conn_status; /*!< connection status */ 190 } close; /*!< HIDD callback param of ESP_HIDD_CLOSE_EVT */ 191 192 /** 193 * @brief ESP_HIDD_SEND_REPORT_EVT 194 */ 195 struct hidd_send_report_evt_param { 196 esp_hidd_status_t status; /*!< operation status */ 197 uint8_t reason; /*!< lower layer failed reason(ref hiddefs.h) */ 198 esp_hidd_report_type_t report_type; /*!< report type */ 199 uint8_t report_id; /*!< report id */ 200 } send_report; /*!< HIDD callback param of ESP_HIDD_SEND_REPORT_EVT */ 201 202 /** 203 * @brief ESP_HIDD_REPORT_ERR_EVT 204 */ 205 struct hidd_report_err_evt_param { 206 esp_hidd_status_t status; /*!< operation status */ 207 uint8_t reason; /*!< lower layer failed reason(ref hiddefs.h) */ 208 } report_err; /*!< HIDD callback param of ESP_HIDD_REPORT_ERR_EVT */ 209 210 /** 211 * @brief ESP_HIDD_GET_REPORT_EVT 212 */ 213 struct hidd_get_report_evt_param { 214 esp_hidd_report_type_t report_type; /*!< report type */ 215 uint8_t report_id; /*!< report id */ 216 uint16_t buffer_size; /*!< buffer size */ 217 } get_report; /*!< HIDD callback param of ESP_HIDD_GET_REPORT_EVT */ 218 219 /** 220 * @brief ESP_HIDD_SET_REPORT_EVT 221 */ 222 struct hidd_set_report_evt_param { 223 esp_hidd_report_type_t report_type; /*!< report type */ 224 uint8_t report_id; /*!< report id */ 225 uint16_t len; /*!< set_report data length */ 226 uint8_t *data; /*!< set_report data pointer */ 227 } set_report; /*!< HIDD callback param of ESP_HIDD_SET_REPORT_EVT */ 228 229 /** 230 * @brief ESP_HIDD_SET_PROTOCOL_EVT 231 */ 232 struct hidd_set_protocol_evt_param { 233 esp_hidd_protocol_mode_t protocol_mode; /*!< protocol mode */ 234 } set_protocol; /*!< HIDD callback param of ESP_HIDD_SET_PROTOCOL_EVT */ 235 236 /** 237 * @brief ESP_HIDD_INTR_DATA_EVT 238 */ 239 struct hidd_intr_data_evt_param { 240 uint8_t report_id; /*!< interrupt channel report id */ 241 uint16_t len; /*!< interrupt channel report data length */ 242 uint8_t *data; /*!< interrupt channel report data pointer */ 243 } intr_data; /*!< HIDD callback param of ESP_HIDD_INTR_DATA_EVT */ 244 245 /** 246 * @brief ESP_HIDD_VC_UNPLUG_EVT 247 */ 248 struct hidd_vc_unplug_param { 249 esp_hidd_status_t status; /*!< operation status */ 250 esp_hidd_connection_state_t conn_status; /*!< connection status */ 251 } vc_unplug; /*!< HIDD callback param of ESP_HIDD_VC_UNPLUG_EVT */ 252 } esp_hidd_cb_param_t; 253 254 /** 255 * @brief HID device callback function type. 256 * @param event: Event type 257 * @param param: Point to callback parameter, currently is union type 258 */ 259 typedef void (esp_hd_cb_t)(esp_hidd_cb_event_t event, esp_hidd_cb_param_t *param); 260 261 /** 262 * @brief This function is called to init callbacks with HID device module. 263 * 264 * @param[in] callback: pointer to the init callback function. 265 * 266 * @return 267 * - ESP_OK: success 268 * - other: failed 269 */ 270 esp_err_t esp_bt_hid_device_register_callback(esp_hd_cb_t callback); 271 272 /** 273 * @brief This function initializes HIDD. This function should be called after esp_bluedroid_enable and 274 * esp_blueroid_init success, and should be called after esp_bt_hid_device_register_callback. 275 * When the operation is complete the callback function will be called with ESP_HIDD_INIT_EVT. 276 * 277 * @return 278 * - ESP_OK: success 279 * - other: failed 280 */ 281 esp_err_t esp_bt_hid_device_init(void); 282 283 /** 284 * @brief This function de-initializes HIDD interface. This function should be called after esp_bluedroid_enable() and 285 * esp_blueroid_init() success, and should be called after esp_bt_hid_device_init(). When the operation is complete the callback 286 * function will be called with ESP_HIDD_DEINIT_EVT. 287 * 288 * @return - ESP_OK: success 289 * - other: failed 290 */ 291 esp_err_t esp_bt_hid_device_deinit(void); 292 293 /** 294 * @brief Registers HIDD parameters with SDP and sets l2cap Quality of Service. This function should be called after 295 * esp_bluedroid_enable and esp_blueroid_init success, and must be done after esp_bt_hid_device_init. When the operation is complete the callback 296 * function will be called with ESP_HIDD_REGISTER_APP_EVT. 297 * 298 * @param[in] app_param: HIDD parameters 299 * @param[in] in_qos: incoming QoS parameters 300 * @param[in] out_qos: outgoing QoS parameters 301 * 302 * @return - ESP_OK: success 303 * - other: failed 304 */ 305 esp_err_t esp_bt_hid_device_register_app(esp_hidd_app_param_t *app_param, esp_hidd_qos_param_t *in_qos, 306 esp_hidd_qos_param_t *out_qos); 307 308 /** 309 * @brief Removes HIDD parameters from SDP and resets l2cap Quality of Service. This function should be called after esp_bluedroid_enable and 310 * esp_blueroid_init success, and should be called after esp_bt_hid_device_init. When the operation is complete the callback 311 * function will be called with ESP_HIDD_UNREGISTER_APP_EVT. 312 * 313 * @return - ESP_OK: success 314 * - other: failed 315 */ 316 esp_err_t esp_bt_hid_device_unregister_app(void); 317 318 /** 319 * @brief This function connects HIDD interface to connected bluetooth device, if not done already. When the operation is complete the callback 320 * function will be called with ESP_HIDD_OPEN_EVT. 321 * 322 * @param[in] bd_addr: Remote host bluetooth device address. 323 * 324 * @return 325 * - ESP_OK: success 326 * - other: failed 327 */ 328 esp_err_t esp_bt_hid_device_connect(esp_bd_addr_t bd_addr); 329 330 /** 331 * @brief This function disconnects HIDD interface. When the operation is complete the callback 332 * function will be called with ESP_HIDD_CLOSE_EVT. 333 * 334 * @return 335 * - ESP_OK: success 336 * - other: failed 337 */ 338 esp_err_t esp_bt_hid_device_disconnect(void); 339 340 /** 341 * @brief Send HIDD report. When the operation is complete the callback 342 * function will be called with ESP_HIDD_SEND_REPORT_EVT. 343 * 344 * @param[in] type: type of report 345 * @param[in] id: report id as defined by descriptor 346 * @param[in] len: length of report 347 * @param[in] data: report data 348 * 349 * @return 350 * - ESP_OK: success 351 * - other: failed 352 */ 353 esp_err_t esp_bt_hid_device_send_report(esp_hidd_report_type_t type, uint8_t id, uint16_t len, uint8_t *data); 354 355 /** 356 * @brief Sends HIDD handshake with error info for invalid set_report. When the operation is complete the callback 357 * function will be called with ESP_HIDD_REPORT_ERR_EVT. 358 * 359 * @param[in] error: type of error 360 * 361 * @return - ESP_OK: success 362 * - other: failed 363 */ 364 esp_err_t esp_bt_hid_device_report_error(esp_hidd_handshake_error_t error); 365 366 /** 367 * @brief Unplug virtual cable of HIDD. When the operation is complete the callback 368 * function will be called with ESP_HIDD_VC_UNPLUG_EVT. 369 * 370 * @return - ESP_OK: success 371 * - other: failed 372 */ 373 esp_err_t esp_bt_hid_device_virtual_cable_unplug(void); 374 375 #ifdef __cplusplus 376 } 377 #endif 378 379 #endif 380
