1 // Copyright 2017-2019 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 #pragma once 16 17 #include "sdkconfig.h" 18 #include "esp_err.h" 19 #include "esp_log.h" 20 #include "esp_event.h" 21 #include "esp_hid_common.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /** 28 * @brief HIDH structure forward declaration 29 */ 30 struct esp_hidh_dev_s; 31 typedef struct esp_hidh_dev_s esp_hidh_dev_t; 32 33 ESP_EVENT_DECLARE_BASE(ESP_HIDH_EVENTS); 34 35 /** 36 * @brief HIDH callback events enum 37 */ 38 typedef enum { 39 ESP_HIDH_ANY_EVENT = ESP_EVENT_ANY_ID, /*!< HID device any event */ 40 ESP_HIDH_OPEN_EVENT = 0, /*!< HID device opened */ 41 ESP_HIDH_BATTERY_EVENT, /*!< HID device battery level changed */ 42 ESP_HIDH_INPUT_EVENT, /*!< Received HID device INPUT report */ 43 ESP_HIDH_FEATURE_EVENT, /*!< Received HID device FEATURE report */ 44 ESP_HIDH_CLOSE_EVENT, /*!< HID device closed */ 45 ESP_HIDH_START_EVENT, /*!< HID host stack started, used only for Classic Bluetooth */ 46 ESP_HIDH_STOP_EVENT, /*!< HID host stack stopped, used only for Classic Bluetooth */ 47 ESP_HIDH_MAX_EVENT, /*!< HID events end marker */ 48 } esp_hidh_event_t; 49 50 /** 51 * @brief HIDH callback parameters union 52 */ 53 typedef union { 54 /** 55 * @brief ESP_HIDH_START_EVENT 56 * @note Used only for Classic Bluetooth. 57 */ 58 struct { 59 esp_err_t status; /*!< HID host operation status */ 60 } start; /*!< HID callback param of ESP_HIDH_START_EVENT */ 61 62 /** 63 * @brief ESP_HIDH_STOP_EVENT 64 * @note Used only for Classic Bluetooth. 65 */ 66 struct { 67 esp_err_t status; /*!< HID host operation status */ 68 } stop; /*!< HID callback param of ESP_HIDH_STOP_EVENT */ 69 70 /** 71 * @brief ESP_HIDH_OPEN_EVENT 72 */ 73 struct { 74 esp_hidh_dev_t *dev; /*!< HID Remote bluetooth device */ 75 esp_err_t status; /*!< HID host operation status, used only for Classic Bluetooth */ 76 } open; /*!< HID callback param of ESP_HIDH_OPEN_EVENT */ 77 78 /** 79 * @brief ESP_HIDH_CLOSE_EVENT 80 */ 81 struct { 82 esp_hidh_dev_t *dev; /*!< HID Remote bluetooth device. */ 83 int reason; /*!< Reason why the connection was closed. BLE Only */ 84 esp_err_t status; /*!< HID host operation status, used only for Classic Bluetooth */ 85 } close; /*!< HID callback param of ESP_HIDH_CLOSE_EVENT */ 86 87 /** 88 * @brief ESP_HIDH_BATTERY_EVENT 89 */ 90 struct { 91 esp_hidh_dev_t *dev; /*!< HID Remote bluetooth device */ 92 uint8_t level; /*!< Battery Level (0-100%) */ 93 esp_err_t status; /*!< HID host operation status */ 94 } battery; /*!< HID callback param of ESP_HIDH_BATTERY_EVENT */ 95 96 /** 97 * @brief ESP_HIDH_INPUT_EVENT 98 */ 99 struct { 100 esp_hidh_dev_t *dev; /*!< HID Remote bluetooth device */ 101 esp_hid_usage_t usage; /*!< HID report usage */ 102 uint16_t report_id; /*!< HID report index */ 103 uint16_t length; /*!< HID data length */ 104 uint8_t *data; /*!< The pointer to the HID data */ 105 uint8_t map_index; /*!< HID report map index */ 106 } input; /*!< HID callback param of ESP_HIDH_INPUT_EVENT */ 107 108 /** 109 * @brief ESP_HIDH_FEATURE_EVENT 110 */ 111 struct { 112 esp_hidh_dev_t *dev; /*!< HID Remote bluetooth device */ 113 esp_hid_usage_t usage; /*!< HID report usage */ 114 uint16_t report_id; /*!< HID report index */ 115 uint16_t length; /*!< HID data length */ 116 uint8_t *data; /*!< The pointer to the HID data */ 117 uint8_t map_index; /*!< HID report map index */ 118 esp_err_t status; /*!< HID host operation status, used only for Classic Bluetooth */ 119 esp_hid_trans_type_t trans_type; /*!< HID host feature transaction type, used only for Classic Bluetooth */ 120 } feature; /*!< HID callback param of ESP_HIDH_FEATURE_EVENT */ 121 122 } esp_hidh_event_data_t; 123 124 typedef struct { 125 esp_event_handler_t callback; 126 uint16_t event_stack_size; 127 void *callback_arg; 128 } esp_hidh_config_t; 129 130 /** 131 * @brief Initialize the HID Host component 132 * @param config : pointer to esp_hidh_config_t structure 133 * 134 * @return: ESP_OK on success 135 */ 136 esp_err_t esp_hidh_init(const esp_hidh_config_t *config); 137 138 /** 139 * @brief De-initialize the HID Host component 140 * 141 * @return: ESP_OK on success 142 */ 143 esp_err_t esp_hidh_deinit(void); 144 145 /** 146 * @brief Close HID Device 147 * @param dev : pointer to the device 148 * 149 * @return: ESP_OK on success 150 */ 151 esp_err_t esp_hidh_dev_close(esp_hidh_dev_t *dev); 152 153 /** 154 * @brief Free HID Device Memory 155 * This function MUST be called when handling ESP_HIDH_CLOSE_EVENT 156 * Only then all memory used for the device will be freed. 157 * @param dev : pointer to the device 158 * 159 * @return: ESP_OK on success 160 */ 161 esp_err_t esp_hidh_dev_free(esp_hidh_dev_t *dev); 162 163 /** 164 * @brief Check if the device still exists. 165 * @param dev : pointer to the device 166 * 167 * @return: true if exists 168 */ 169 bool esp_hidh_dev_exists(esp_hidh_dev_t *dev); 170 171 /** 172 * @brief Send an OUTPUT report to the device 173 * @param dev : pointer to the device 174 * @param map_index : index of the device report map 175 * @param report_id : id of the HID OUTPUT report 176 * @param data : pointer to the data to send 177 * @param length : length of the data to send 178 * 179 * @return: ESP_OK on success 180 */ 181 esp_err_t esp_hidh_dev_output_set(esp_hidh_dev_t *dev, size_t map_index, size_t report_id, uint8_t *data, size_t length); 182 183 /** 184 * @brief Send a FEATURE report to the device 185 * @param dev : pointer to the device 186 * @param map_index : index of the device report map 187 * @param report_id : id of the HID FEATURE report 188 * @param data : pointer to the data to send 189 * @param length : length of the data to send 190 * 191 * @return: ESP_OK on success 192 */ 193 esp_err_t esp_hidh_dev_feature_set(esp_hidh_dev_t *dev, size_t map_index, size_t report_id, uint8_t *data, size_t length); 194 195 /** 196 * @brief Get the value a FEATURE report from the device 197 * @param dev : pointer to the device 198 * @param map_index : index of the device report map 199 * @param report_id : id of the HID FEATURE report 200 * @param max_len : size of the buffer that will hold the data 201 * @param data : pointer to the data buffer 202 * @param length : pointer to the value that will be set to the number of bytes received 203 * 204 * @return: ESP_OK on success 205 */ 206 esp_err_t esp_hidh_dev_feature_get(esp_hidh_dev_t *dev, size_t map_index, size_t report_id, size_t max_len, uint8_t *data, size_t *length); 207 208 /** 209 * @brief Set_Report command. 210 * @note For now, this function used only for Classic Bluetooth. 211 * 212 * @param dev : pointer to the device 213 * @param map_index : index of the device report map 214 * @param report_id : id of the HID FEATURE report 215 * @param report_type : report type, defines in `esp_hid_common.h` 216 * @param data : pointer to the data to send 217 * @param length : length of the data to send 218 * 219 * @return: ESP_OK on success 220 */ 221 esp_err_t esp_hidh_dev_set_report(esp_hidh_dev_t *dev, size_t map_index, size_t report_id, int report_type, 222 uint8_t *data, size_t length); 223 224 /** 225 * @brief Get_Report command. 226 * @note For now, this function used only for Classic Bluetooth. 227 * 228 * @param dev : pointer to the device 229 * @param map_index : index of the device report map 230 * @param report_id : id of the HID FEATURE report 231 * @param report_type : report type, defines in `esp_hid_common.h` 232 * @param max_len : size of the buffer that will hold the data 233 * 234 * @return: ESP_OK on success 235 */ 236 esp_err_t esp_hidh_dev_get_report(esp_hidh_dev_t *dev, size_t map_index, size_t report_id, int report_type, 237 size_t max_len); 238 239 /** 240 * @brief Get_Idle Command. 241 * @note For now, this function used only for Classic Bluetooth. 242 * 243 * @param dev : pointer to the device 244 * 245 * @return: ESP_OK on success 246 */ 247 esp_err_t esp_hidh_dev_get_idle(esp_hidh_dev_t *dev); 248 249 /** 250 * @brief Set_Idle Command. 251 * @note For now, this function used only for Classic Bluetooth. 252 * 253 * @param dev : pointer to the device 254 * @param idle_time : idle_time 255 * 256 * @return: ESP_OK on success 257 */ 258 esp_err_t esp_hidh_dev_set_idle(esp_hidh_dev_t *dev, uint8_t idle_time); 259 260 /** 261 * @brief Get_Protocol Command. 262 * @note For now, this function used only for Classic Bluetooth. 263 * 264 * @param dev : pointer to the device 265 * 266 * @return: ESP_OK on success 267 */ 268 esp_err_t esp_hidh_dev_get_protocol(esp_hidh_dev_t *dev); 269 270 /** 271 * @brief Set_Protocol Command. 272 * @note For now, this function used only for Classic Bluetooth. 273 * 274 * @param dev : pointer to the device 275 * @param protocol_mode : protocol_mode 276 * 277 * @return: ESP_OK on success 278 */ 279 esp_err_t esp_hidh_dev_set_protocol(esp_hidh_dev_t *dev, uint8_t protocol_mode); 280 281 /** 282 * @brief Dump the properties of HID Device to UART 283 * @param dev : pointer to the HID Device 284 * @param fp : pointer to the output file 285 */ 286 void esp_hidh_dev_dump(esp_hidh_dev_t *dev, FILE *fp); 287 288 /** 289 * @brief Get the BT Device Address of a HID Device 290 * @param dev : pointer to the HID Device 291 * 292 * @return: pointer to the BDA byte array or NULL 293 */ 294 const uint8_t *esp_hidh_dev_bda_get(esp_hidh_dev_t *dev); 295 296 /** 297 * @brief Get the HID Device Transport 298 * @param dev : pointer to the HID Device 299 * 300 * @return: the transport of the connected device or ESP_HID_TRANSPORT_MAX 301 */ 302 esp_hid_transport_t esp_hidh_dev_transport_get(esp_hidh_dev_t *dev); 303 304 /** 305 * @brief Get the HID Device Cofiguration 306 * @param dev : pointer to the HID Device 307 * 308 * @return: pointer to the config structure or NULL 309 */ 310 const esp_hid_device_config_t *esp_hidh_dev_config_get(esp_hidh_dev_t *dev); 311 312 /** 313 * @brief Get the name of a HID Device 314 * @param dev : pointer to the HID Device 315 * 316 * @return: pointer to the character array or NULL 317 */ 318 const char *esp_hidh_dev_name_get(esp_hidh_dev_t *dev); 319 320 /** 321 * @brief Get the manufacturer of a HID Device 322 * @param dev : pointer to the HID Device 323 * 324 * @return: pointer to the character array 325 */ 326 const char *esp_hidh_dev_manufacturer_get(esp_hidh_dev_t *dev); 327 328 /** 329 * @brief Get the serial number of a HID Device 330 * @param dev : pointer to the HID Device 331 * 332 * @return: pointer to the character array or NULL 333 */ 334 const char *esp_hidh_dev_serial_get(esp_hidh_dev_t *dev); 335 336 /** 337 * @brief Get the VID of a HID Device 338 * @param dev : pointer to the HID Device 339 * 340 * @return: the VID value 341 */ 342 uint16_t esp_hidh_dev_vendor_id_get(esp_hidh_dev_t *dev); 343 344 /** 345 * @brief Get the PID of a HID Device 346 * @param dev : pointer to the HID Device 347 * 348 * @return: the PID value 349 */ 350 uint16_t esp_hidh_dev_product_id_get(esp_hidh_dev_t *dev); 351 352 /** 353 * @brief Get the version HID Device 354 * @param dev : pointer to the HID Device 355 * 356 * @return: the version value 357 */ 358 uint16_t esp_hidh_dev_version_get(esp_hidh_dev_t *dev); 359 360 /** 361 * @brief Get the appearance of BLE HID Device 362 * @param dev : pointer to the BLE HID Device 363 * 364 * @return: the appearance value 365 */ 366 uint16_t esp_hidh_dev_appearance_get(esp_hidh_dev_t *dev); //BLE Only 367 368 /** 369 * @brief Get the calculated HID Device usage type 370 * @param dev : pointer to the HID Device 371 * 372 * @return: the hid usage type 373 */ 374 esp_hid_usage_t esp_hidh_dev_usage_get(esp_hidh_dev_t *dev); 375 376 /** 377 * @brief Get an array of all reports found on a device 378 * @param dev : pointer to the device 379 * @param num_reports : pointer to the value that will be set to the number of reports 380 * @param reports : location to set to the pointer of the reports array 381 * 382 * @return: ESP_OK on success 383 */ 384 esp_err_t esp_hidh_dev_reports_get(esp_hidh_dev_t *dev, size_t *num_reports, esp_hid_report_item_t **reports); 385 386 /** 387 * @brief Get an array of the report maps found on a device 388 * @param dev : pointer to the device 389 * @param num_maps : pointer to the value that will be set to the number of report maps found 390 * @param maps : location to set to the pointer of the report maps array 391 * 392 * @return: ESP_OK on success 393 */ 394 esp_err_t esp_hidh_dev_report_maps_get(esp_hidh_dev_t *dev, size_t *num_maps, esp_hid_raw_report_map_t **maps); 395 396 #include "esp_hidh_transport.h" 397 398 #ifdef __cplusplus 399 } 400 #endif 401
