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 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #include <stdint.h> 22 #include <stddef.h> 23 #include <stdbool.h> 24 #include <stdio.h> 25 26 /* HID Report Map Values */ 27 #define HID_RM_INPUT 0x80 28 #define HID_RM_OUTPUT 0x90 29 #define HID_RM_FEATURE 0xb0 30 #define HID_RM_COLLECTION 0xa0 31 #define HID_RM_END_COLLECTION 0xc0 32 #define HID_RM_USAGE_PAGE 0x04 33 #define HID_RM_LOGICAL_MINIMUM 0x14 34 #define HID_RM_LOGICAL_MAXIMUM 0x24 35 #define HID_RM_PHYSICAL_MINIMUM 0x34 36 #define HID_RM_PHYSICAL_MAXIMUM 0x44 37 #define HID_RM_UNIT_EXPONENT 0x54 38 #define HID_RM_UNIT 0x64 39 #define HID_RM_REPORT_SIZE 0x74 40 #define HID_RM_REPORT_ID 0x84 41 #define HID_RM_REPORT_COUNT 0x94 42 #define HID_RM_PUSH 0xa4 43 #define HID_RM_POP 0xb4 44 #define HID_RM_USAGE 0x08 45 #define HID_RM_USAGE_MINIMUM 0x18 46 #define HID_RM_USAGE_MAXIMUM 0x28 47 #define HID_RM_DESIGNATOR_INDEX 0x38 48 #define HID_RM_DESIGNATOR_MINIMUM 0x48 49 #define HID_RM_DESIGNATOR_MAXIMUM 0x58 50 #define HID_RM_STRING_INDEX 0x78 51 #define HID_RM_STRING_MINIMUM 0x88 52 #define HID_RM_STRING_MAXIMUM 0x98 53 #define HID_RM_DELIMITER 0xa8 54 55 /* HID Usage Pages and Usages */ 56 #define HID_USAGE_PAGE_GENERIC_DESKTOP 0x01 57 #define HID_USAGE_KEYBOARD 0x06 58 #define HID_USAGE_MOUSE 0x02 59 #define HID_USAGE_JOYSTICK 0x04 60 #define HID_USAGE_GAMEPAD 0x05 61 62 #define HID_USAGE_PAGE_CONSUMER_DEVICE 0x0C 63 #define HID_USAGE_CONSUMER_CONTROL 0x01 64 65 /* HID BT COD Peripheral Min Values Main Role */ 66 #define ESP_HID_COD_MIN_KEYBOARD 0x10 67 #define ESP_HID_COD_MIN_MOUSE 0x20 68 69 /* HID BLE Appearances */ 70 #define ESP_HID_APPEARANCE_GENERIC 0x03C0 71 #define ESP_HID_APPEARANCE_KEYBOARD 0x03C1 72 #define ESP_HID_APPEARANCE_MOUSE 0x03C2 73 #define ESP_HID_APPEARANCE_JOYSTICK 0x03C3 74 #define ESP_HID_APPEARANCE_GAMEPAD 0x03C4 75 76 /* HID Report Types */ 77 #define ESP_HID_REPORT_TYPE_INPUT 1 78 #define ESP_HID_REPORT_TYPE_OUTPUT 2 79 #define ESP_HID_REPORT_TYPE_FEATURE 3 80 81 /* HID Protocol Modes */ 82 #define ESP_HID_PROTOCOL_MODE_BOOT 0x00 // Boot Protocol Mode 83 #define ESP_HID_PROTOCOL_MODE_REPORT 0x01 // Report Protocol Mode 84 85 /* HID information flags */ 86 #define ESP_HID_FLAGS_REMOTE_WAKE 0x01 // RemoteWake 87 #define ESP_HID_FLAGS_NORMALLY_CONNECTABLE 0x02 // NormallyConnectable 88 89 /* Control point commands */ 90 #define ESP_HID_CONTROL_SUSPEND 0x00 // Suspend 91 #define ESP_HID_CONTROL_EXIT_SUSPEND 0x01 // Exit Suspend 92 93 /* Client Characteristic Configuration values */ 94 #define ESP_HID_CCC_NOTIFICATIONS_ENABLED 0x01 // Notifications enabled 95 #define ESP_HID_CCC_INDICATIONS_ENABLED 0x02 // Indications enabled 96 97 /* HID Transports */ 98 typedef enum { 99 ESP_HID_TRANSPORT_BT, 100 ESP_HID_TRANSPORT_BLE, 101 ESP_HID_TRANSPORT_USB, 102 ESP_HID_TRANSPORT_MAX 103 } esp_hid_transport_t; 104 105 /* HID Usage Types */ 106 typedef enum { 107 ESP_HID_USAGE_GENERIC = 0, 108 ESP_HID_USAGE_KEYBOARD = 1, 109 ESP_HID_USAGE_MOUSE = 2, 110 ESP_HID_USAGE_JOYSTICK = 4, 111 ESP_HID_USAGE_GAMEPAD = 8, 112 ESP_HID_USAGE_TABLET = 16, 113 ESP_HID_USAGE_CCONTROL = 32, 114 ESP_HID_USAGE_VENDOR = 64 115 } esp_hid_usage_t; 116 117 /* HID BT COD Peripheral Min Values. Mask of (keyboard|mouse|ESP_HIDH_COD_*) */ 118 typedef enum { 119 ESP_HID_COD_MIN_GENERIC, 120 ESP_HID_COD_MIN_JOYSTICK, 121 ESP_HID_COD_MIN_GAMEPAD, 122 ESP_HID_COD_MIN_REMOTE, 123 ESP_HID_COD_MIN_SENSOR, 124 ESP_HID_COD_MIN_TABLET, 125 ESP_HID_COD_MIN_CARD_READER, 126 ESP_HID_COD_MIN_MAX 127 } esp_hid_cod_min_t; 128 129 /* HID transaction Types */ 130 typedef enum { 131 ESP_HID_TRANS_HANDSHAKE = 0, 132 ESP_HID_TRANS_CONTROL = 1, 133 ESP_HID_TRANS_GET_REPORT = 4, 134 ESP_HID_TRANS_SET_REPORT = 5, 135 ESP_HID_TRANS_GET_PROTOCOL = 6, 136 ESP_HID_TRANS_SET_PROTOCOL = 7, 137 ESP_HID_TRANS_GET_IDLE = 8, 138 ESP_HID_TRANS_SET_IDLE = 9, 139 ESP_HID_TRANS_DATA = 10, 140 ESP_HID_TRANS_DATAC = 11, 141 ESP_HID_TRANS_MAX 142 } esp_hid_trans_type_t; 143 144 /** 145 * @brief HID report item structure 146 */ 147 typedef struct { 148 uint8_t map_index; /*!< HID report map index */ 149 uint8_t report_id; /*!< HID report id */ 150 uint8_t report_type; /*!< HID report type */ 151 uint8_t protocol_mode; /*!< HID protocol mode */ 152 esp_hid_usage_t usage; /*!< HID usage type */ 153 uint16_t value_len; /*!< HID report length in bytes */ 154 } esp_hid_report_item_t; 155 156 /** 157 * @brief HID parsed report map structure 158 */ 159 typedef struct { 160 esp_hid_usage_t usage; /*!< Dominant HID usage. (keyboard > mouse > joystick > gamepad > generic) */ 161 uint16_t appearance; /*!< Calculated HID Appearance based on the dominant usage */ 162 uint8_t reports_len; /*!< Number of reports discovered in the report map */ 163 esp_hid_report_item_t *reports; /*!< Reports discovered in the report map */ 164 } esp_hid_report_map_t; 165 166 /** 167 * @brief HID raw report map structure 168 */ 169 typedef struct { 170 const uint8_t *data; /*!< Pointer to the HID report map data */ 171 uint16_t len; /*!< HID report map data length */ 172 } esp_hid_raw_report_map_t; 173 174 /** 175 * @brief HID device config structure 176 */ 177 typedef struct { 178 uint16_t vendor_id; /*!< HID Vendor ID */ 179 uint16_t product_id; /*!< HID Product ID */ 180 uint16_t version; /*!< HID Product Version */ 181 const char *device_name; /*!< HID Device Name */ 182 const char *manufacturer_name; /*!< HID Manufacturer */ 183 const char *serial_number; /*!< HID Serial Number */ 184 esp_hid_raw_report_map_t *report_maps; /*!< Array of the raw HID report maps */ 185 uint8_t report_maps_len; /*!< number of raw report maps in the array */ 186 } esp_hid_device_config_t; 187 188 /* 189 * @brief Parse RAW HID report map 190 * It is a responsibility of the user to free the parsed report map, 191 * when it's no longer needed. Use esp_hid_free_report_map 192 * @param hid_rm : pointer to the hid report map data 193 * @param hid_rm_len : length to the hid report map data 194 * 195 * @return: pointer to the parsed report map 196 */ 197 esp_hid_report_map_t *esp_hid_parse_report_map(const uint8_t *hid_rm, size_t hid_rm_len); 198 199 /* 200 * @brief Free parsed HID report map 201 * @param map : pointer to the parsed hid report map 202 */ 203 void esp_hid_free_report_map(esp_hid_report_map_t *map); 204 205 /** 206 * @brief Calculate the HID Device usage type from the BLE Apperance 207 * @param appearance : BLE Apperance value 208 * 209 * @return: the hid usage type 210 */ 211 esp_hid_usage_t esp_hid_usage_from_appearance(uint16_t appearance); 212 213 /** 214 * @brief Calculate the HID Device usage type from the BT CoD 215 * @param cod : BT CoD value 216 * 217 * @return: the hid usage type 218 */ 219 esp_hid_usage_t esp_hid_usage_from_cod(uint32_t cod); 220 221 /** 222 * @brief Convert device usage type to string 223 * @param usage : The HID usage type to convert 224 * 225 * @return: a pointer to the string or NULL 226 */ 227 const char *esp_hid_usage_str(esp_hid_usage_t usage); 228 229 /** 230 * @brief Convert HID protocol mode to string 231 * @param protocol_mode : The HID protocol mode to convert 232 * BOOT/REPORT 233 * 234 * @return: a pointer to the string or NULL 235 */ 236 const char *esp_hid_protocol_mode_str(uint8_t protocol_mode); 237 238 /** 239 * @brief Convert HID report type to string 240 * @param report_type : The HID report type to convert 241 * INPUT/OUTPUT/FEATURE 242 * 243 * @return: a pointer to the string or NULL 244 */ 245 const char *esp_hid_report_type_str(uint8_t report_type); 246 247 /** 248 * @brief Convert BT CoD major to string 249 * @param cod_major : The CoD major value to convert 250 * 251 * @return: a pointer to the string or NULL 252 */ 253 const char *esp_hid_cod_major_str(uint8_t cod_major); 254 255 /** 256 * @brief Print BT CoD minor value 257 * @param cod_min : The CoD minor value to print 258 * @param fp : pointer to the output file 259 */ 260 void esp_hid_cod_minor_print(uint8_t cod_min, FILE *fp); 261 262 /** 263 * @brief Convert BLE disconnect reason to string 264 * @param reason : The value of the reason 265 * 266 * @return: a pointer to the string or NULL 267 */ 268 const char *esp_hid_disconnect_reason_str(esp_hid_transport_t transport, int reason); 269 270 #ifdef __cplusplus 271 } 272 #endif 273
