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_event.h" 20 #include "esp_hid_common.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 #include "esp_hidd_transport.h" 27 28 ESP_EVENT_DECLARE_BASE(ESP_HIDD_EVENTS); // Declare the event base for HID device 29 30 /** 31 * @brief HIDD callback events enum 32 */ 33 typedef enum { 34 ESP_HIDD_ANY_EVENT = ESP_EVENT_ANY_ID, /*!< HID device any event */ 35 ESP_HIDD_START_EVENT = 0, /*!< HID device stack started */ 36 ESP_HIDD_CONNECT_EVENT, /*!< HID device connected */ 37 ESP_HIDD_PROTOCOL_MODE_EVENT, /*!< HID device protocol mode change */ 38 ESP_HIDD_CONTROL_EVENT, /*!< HID device control request */ 39 ESP_HIDD_OUTPUT_EVENT, /*!< HID device output report event */ 40 ESP_HIDD_FEATURE_EVENT, /*!< HID device feature report event */ 41 ESP_HIDD_DISCONNECT_EVENT, /*!< HID device disconnected */ 42 ESP_HIDD_STOP_EVENT, /*!< HID device stack stopped */ 43 ESP_HIDD_MAX_EVENT, /*!< HID events end marker */ 44 } esp_hidd_event_t; 45 46 /** 47 * @brief HIDD structure forward declaration 48 */ 49 struct esp_hidd_dev_s; 50 typedef struct esp_hidd_dev_s esp_hidd_dev_t; 51 52 /** 53 * @brief HIDD callback parameters union 54 */ 55 typedef union { 56 /** 57 * @brief ESP_HIDD_START_EVENT 58 * @note Used only for Classic Bluetooth. 59 */ 60 struct { 61 esp_err_t status; /*!< HID device operation status */ 62 } start; /*!< HID callback param of ESP_HIDD_START_EVENT */ 63 64 /** 65 * @brief ESP_HIDD_STOP_EVENT 66 * @note Used only for Classic Bluetooth. 67 */ 68 struct { 69 esp_err_t status; /*!< HID device operation status */ 70 } stop; /*!< HID callback param of ESP_HIDD_STOP_EVENT */ 71 72 /** 73 * @brief ESP_HIDD_CONNECT_EVENT 74 */ 75 struct { 76 esp_hidd_dev_t *dev; /*!< HID device structure */ 77 esp_err_t status; /*!< HID device operation status, used only for Classic Bluetooth */ 78 } connect; /*!< HID callback param of ESP_HIDD_CONNECT_EVENT */ 79 80 /** 81 * @brief ESP_HIDD_DISCONNECT_EVENT 82 */ 83 struct { 84 esp_hidd_dev_t *dev; /*!< HID device structure */ 85 int reason; /*!< Indicate the reason of disconnection */ 86 esp_err_t status; /*!< HID device operation status, used only for Classic Bluetooth */ 87 } disconnect; /*!< HID callback param of ESP_HIDD_DISCONNECT_EVENT */ 88 89 /** 90 * @brief ESP_HIDD_OUTPUT_EVENT 91 */ 92 struct { 93 esp_hidd_dev_t *dev; /*!< HID device structure */ 94 esp_hid_usage_t usage; /*!< HID report usage */ 95 uint16_t report_id; /*!< HID report index */ 96 uint16_t length; /*!< data length */ 97 uint8_t *data; /*!< The pointer to the data */ 98 uint8_t map_index; /*!< HID config report map index */ 99 } output; /*!< HID callback param of ESP_HIDD_OUTPUT_EVENT */ 100 101 /** 102 * @brief ESP_HIDD_FEATURE_EVENT 103 */ 104 struct { 105 esp_hidd_dev_t *dev; /*!< HID device structure */ 106 esp_hid_usage_t usage; /*!< HID report usage */ 107 uint16_t report_id; /*!< HID report index */ 108 uint16_t length; /*!< data length */ 109 uint8_t *data; /*!< The pointer to the data */ 110 uint8_t map_index; /*!< HID config report map index */ 111 uint8_t trans_type; /*!< HID device feature transaction type, used only for Classic Bluetooth */ 112 uint8_t report_type; /*!< HID device feature report type, used only for Classic Bluetooth */ 113 } feature; /*!< HID callback param of ESP_HIDD_FEATURE_EVENT */ 114 115 /** 116 * @brief ESP_HIDD_PROTOCOL_MODE_EVENT 117 */ 118 struct { 119 esp_hidd_dev_t *dev; /*!< HID device structure */ 120 uint8_t protocol_mode; /*!< HID Protocol Mode */ 121 uint8_t map_index; /*!< HID config report map index */ 122 } protocol_mode; /*!< HID callback param of ESP_HIDD_PROTOCOL_MODE_EVENT */ 123 124 /** 125 * @brief ESP_HIDD_CONTROL_EVENT 126 */ 127 struct { 128 esp_hidd_dev_t *dev; /*!< HID device structure */ 129 uint8_t control; /*!< HID Control Point */ 130 uint8_t map_index; /*!< HID config report map index */ 131 } control; /*!< HID callback param of ESP_HIDD_CONTROL_EVENT */ 132 133 } esp_hidd_event_data_t; 134 135 /** 136 * @brief Init HID Device 137 * @param config : configuration for the device 138 * @param transport: protocol that the device will use (ESP_HID_TRANSPORT_BLE/BT/USB) 139 * @param callback : function to call when events for this device are generated. 140 * Can be NULL, but will miss the START event. 141 * @param[out] dev : location to return the pointer to the device structure 142 * 143 * @return: ESP_OK on success 144 */ 145 esp_err_t esp_hidd_dev_init(const esp_hid_device_config_t *config, esp_hid_transport_t transport, esp_event_handler_t callback, esp_hidd_dev_t **dev); 146 147 /** 148 * @brief Deinit HID Device 149 * @param dev : pointer to the device to deinit 150 * 151 * @return: ESP_OK on success 152 */ 153 esp_err_t esp_hidd_dev_deinit(esp_hidd_dev_t *dev); 154 155 /** 156 * @brief Get the HID Device Transport 157 * @param dev : pointer to the HID Device 158 * 159 * @return: the transport of the connected device or ESP_HID_TRANSPORT_MAX 160 */ 161 esp_hid_transport_t esp_hidd_dev_transport_get(esp_hidd_dev_t *dev); 162 163 /** 164 * @brief Check if HID Device is connected 165 * @param dev : pointer to the device 166 * 167 * @return: true if the device is connected 168 */ 169 bool esp_hidd_dev_connected(esp_hidd_dev_t *dev); 170 171 /** 172 * @brief Set the battery level reported by the HID Device 173 * @param dev : pointer to the device 174 * @param level : battery level (0-100) 175 * 176 * @return: ESP_OK on success 177 */ 178 esp_err_t esp_hidd_dev_battery_set(esp_hidd_dev_t *dev, uint8_t level); 179 180 /** 181 * @brief Send an INPUT report to the host 182 * @param dev : pointer to the device 183 * @param map_index : index of the device report map in the init config 184 * @param report_id : id of the HID INPUT report 185 * @param data : pointer to the data to send 186 * @param length : length of the data to send 187 * 188 * @return: ESP_OK on success 189 */ 190 esp_err_t esp_hidd_dev_input_set(esp_hidd_dev_t *dev, size_t map_index, size_t report_id, uint8_t *data, size_t length); 191 192 /** 193 * @brief Send a FEATURE report to the host 194 * @param dev : pointer to the device 195 * @param map_index : index of the device report map in the init config 196 * @param report_id : id of the HID FEATURE report 197 * @param data : pointer to the data to send 198 * @param length : length of the data to send 199 * 200 * @return: ESP_OK on success 201 */ 202 esp_err_t esp_hidd_dev_feature_set(esp_hidd_dev_t *dev, size_t map_index, size_t report_id, uint8_t *data, size_t length); 203 204 /** 205 * @brief Register function to listen for device events 206 * @param dev : pointer to the device 207 * @param callback : event handler function 208 * @param event : event to listen for (ESP_HIDD_ANY_EVENT for all) 209 * 210 * @return: ESP_OK on success 211 */ 212 esp_err_t esp_hidd_dev_event_handler_register(esp_hidd_dev_t *dev, esp_event_handler_t callback, esp_hidd_event_t event); 213 214 /** 215 * @brief Unregister function that is listening for device events 216 * @param dev : pointer to the device 217 * @param callback : event handler function 218 * @param event : event that is listening for (ESP_HIDD_ANY_EVENT for all) 219 * 220 * @return: ESP_OK on success 221 */ 222 esp_err_t esp_hidd_dev_event_handler_unregister(esp_hidd_dev_t *dev, esp_event_handler_t callback, esp_hidd_event_t event); 223 224 #ifdef __cplusplus 225 } 226 #endif 227
