1 /** 2 ******************************************************************************* 3 * 4 * @file hids.h 5 * 6 * @brief Human Interface Device Service API 7 * 8 ******************************************************************************* 9 * @attention 10 #####Copyright (c) 2019 GOODIX 11 All rights reserved. 12 13 Redistribution and use in source and binary forms, with or without 14 modification, are permitted provided that the following conditions are met: 15 * Redistributions of source code must retain the above copyright 16 notice, this list of conditions and the following disclaimer. 17 * Redistributions in binary form must reproduce the above copyright 18 notice, this list of conditions and the following disclaimer in the 19 documentation and/or other materials provided with the distribution. 20 * Neither the name of GOODIX nor the names of its contributors may be used 21 to endorse or promote products derived from this software without 22 specific prior written permission. 23 24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE 28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34 POSSIBILITY OF SUCH DAMAGE. 35 ***************************************************************************************** 36 */ 37 38 /** 39 * @addtogroup BLE_SRV BLE Services 40 * @{ 41 * @brief Definitions and prototypes for the BLE Service interface. 42 */ 43 44 /** 45 * @defgroup BLE_SDK_HIDS Human Input Device Service (HIDS) 46 * @{ 47 * @brief Definitions and prototypes for the HIDS interface. 48 * 49 * @details The HID Service exposes data and associated formatting for HID Devices 50 * and HID Hosts. This module implements the HID Service with HID Information 51 * characteristic, HID Control Point characteristic, Report Map characteristic, 52 * Input/Output/Feature Report characteristics, Boot Keyboard Input characteristic, 53 * Boot Keyboard Output characteristic, Boot Mouse Input Report characteristic. 54 * 55 * After \ref hids_init_t variable is initialized, the application must call \ref hids_service_init() 56 * to add the HID Service and the characteristics to the BLE Stack database. However 57 * the array of Report map locates in user space, application must make sure the 58 * array is available. 59 * 60 * If Notify is enabled, the value of Input Report characteristic is sent to the 61 * peer when application calls \ref hids_input_rep_send() function. The application is reponsible 62 * for encoding Input Report data as “USB HID Spec”. If an event hanlder is provided by the application, 63 * HID Service will pass HIDS events to the application, e.g. Output Report characteristic is written. 64 */ 65 66 #ifndef __HIDS_H__ 67 #define __HIDS_H__ 68 69 #include <stdint.h> 70 #include "ble_prf_utils.h" 71 #include "gr55xx_sys.h" 72 #include "custom_config.h" 73 74 /** 75 * @defgroup HIDS_MACRO Defines 76 * @{ 77 */ 78 79 #define HIDS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ? \ 80 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of Heart Rate Service connections. */ 81 82 #define HIDS_REPORT_MAX_SIZE 20 /**< Maximum length of report. */ 83 #define HIDS_REPORT_MAP_MAX_SIZE 512 /**< Limitation of length, as per Section 2.6.1 in HIDS Spec, version 1.0 */ 84 85 /** 86 * @defgroup HIDS_REPORT_TYPE Report Type values 87 * @{ 88 * @brief HIDS Report Type values define. 89 */ 90 #define HIDS_REP_TYPE_INPUT 1 /**< The input report type. */ 91 #define HIDS_REP_TYPE_OUTPUT 2 /**< The output report type. */ 92 #define HIDS_REP_TYPE_FEATURE 3 /**< The feature report type. */ 93 /** @} */ 94 95 /** 96 * @defgroup HIDS_INFOR_FLAGS Information Flags 97 * @{ 98 * @brief HIDS Information Flags define. 99 */ 100 #define HID_INFO_FLAG_REMOTE_WAKE_MSK 0x01 /**< Bit mask of Remote Wake flag in HIDS information. */ 101 #define HID_INFO_FLAG_NORMALLY_CONNECTABLE_MSK 0x02 /**< Bit mask of Normally Connectable flag in HIDS information. */ 102 /** @} */ 103 /** @} */ 104 105 106 /** 107 * @defgroup HIDS_ENUM Enumerations 108 * @{ 109 */ 110 111 /**@brief HID Service event type. */ 112 typedef enum { 113 HIDS_EVT_INVALID, /**< Invalid event. */ 114 HIDS_EVT_IN_REP_NOTIFY_ENABLED, /**< Input report notification enabled event. */ 115 HIDS_EVT_IN_REP_NOTIFY_DISABLED, /**< Input report notification disabled event. */ 116 HIDS_EVT_HOST_SUSP, /**< Suspend command received. */ 117 HIDS_EVT_HOST_EXIT_SUSP, /**< Exit suspend command received. */ 118 HIDS_EVT_BOOT_MODE_ENTERED, /**< Boot mode entered */ 119 HIDS_EVT_REPORT_MODE_ENTERED, /**< Report mode entered */ 120 HIDS_EVT_REP_CHAR_WRITE, /**< New value has been written to a report characteristic */ 121 } hids_evt_type_t; 122 123 124 /**@brief HID Service write report type. */ 125 typedef enum { 126 HIDS_REPORT_TYPE_RESERVED, /**< The reserved report type. */ 127 HIDS_REPORT_TYPE_IN1, /**< The input report1 type. */ 128 HIDS_REPORT_TYPE_IN2, /**< The input report2 type. */ 129 HIDS_REPORT_TYPE_IN3, /**< The input report3 type. */ 130 HIDS_REPORT_TYPE_OUT, /**< The output report type. */ 131 HIDS_REPORT_TYPE_FEATURE, /**< The feature report type. */ 132 HIDS_REPORT_TYPE_KB_IN, /**< The boot keyboard input report type. */ 133 HIDS_REPORT_TYPE_KB_OUT, /**< The boot keyboard output report type. */ 134 HIDS_REPORT_TYPE_MOUSE_IN, /**< The boot mouse inputreport type. */ 135 } hids_report_type_t; 136 /** @} */ 137 138 139 /** 140 * @defgroup HIDS_TYPEDEF Typedefs 141 * @{ 142 */ 143 144 /**@brief HID Service event. */ 145 typedef struct { 146 hids_evt_type_t evt_type; /**< Type of event. */ 147 uint8_t conn_idx; /**< Connect index. */ 148 hids_report_type_t report_type; /**< Type of report, see @ref hids_report_type_t. */ 149 uint16_t offset; /**< Offset for the write operation. */ 150 uint16_t len; /**< Length of the incoming data. */ 151 uint8_t const * data; /**< Incoming data, variable length */ 152 } hids_evt_t; 153 154 /**@brief HID Information characteristic value. */ 155 typedef struct { 156 uint16_t 157 bcd_hid; /**< 16-bit unsigned integer representing version number of base USB HID Specification \ 158 implemented by HID Device */ 159 uint8_t 160 b_country_code; /**< Identifies which country the hardware is localized for. \ 161 Most hardware is not localized and thus this value would be zero (0). */ 162 uint8_t 163 flags; /**< See http://developer.bluetooth.org/gatt/characteristics/Pages/ \ 164 CharacteristicViewer.aspx?u=org.bluetooth.characteristic.hid_information.xml */ 165 } hids_hid_info_t; 166 167 168 /**@brief Value of a Report Reference descriptor. 169 * 170 * @details This is mapping information that maps the parent characteristic to the Report ID(s) and 171 * Report Type(s) defined within a Report Map characteristic. 172 */ 173 typedef struct { 174 uint8_t report_id; /**< Non-zero value if there is more than one instance of the same Report Type */ 175 uint8_t report_type; /**< Type of Report characteristic (see @ref HIDS_REPORT_TYPE) */ 176 } hids_report_ref_t; 177 178 179 /**@brief HID Service Report characteristic define. */ 180 typedef struct { 181 uint16_t value_len; /**< Length of characteristic value. */ 182 hids_report_ref_t 183 ref; /**< Value of a Report Reference descriptor, see @ref hids_report_ref_t. */ 184 } hids_report_int_t; 185 186 187 /**@brief HID Service Report Map characteristic value. */ 188 typedef struct { 189 uint8_t *p_map; /**< Pointer to the report map. */ 190 uint16_t len; /**< The length of report map. */ 191 } hids_report_map_t; 192 193 194 /**@brief HID Service event handler type. 195 * 196 * @param[in] p_evt Pointer to a HID Service event variable. 197 */ 198 typedef void (*hids_evt_handler_t)(hids_evt_t *p_evt); 199 200 201 /**@brief HID Service initialization variable. */ 202 typedef struct { 203 hids_evt_handler_t evt_handler; /**< Handle events in HID Service. */ 204 bool is_kb; /**< TRUE if device is operating as a keyboard, FALSE if it is not. */ 205 bool is_mouse; /**< TRUE if device is operating as a mouse, FALSE if it is not. */ 206 hids_hid_info_t hid_info; /**< Value of HID information characteristic. */ 207 hids_report_map_t report_map; /**< HID Service Report Map characteristic value. */ 208 uint8_t input_report_count; /**< Number of Input Report characteristics. */ 209 hids_report_int_t input_report_array[3]; /**< HID input Report Reference value. */ 210 bool 211 out_report_sup; /**< TRUE if output Report characteristic suport, FALSE if it is nonsupport. */ 212 hids_report_int_t output_report; /**< HID output Report Reference value. */ 213 bool 214 feature_report_sup; /**< TRUE if feature Report characteristic suport, FALSE if it is nonsupport. */ 215 hids_report_int_t feature_report; /**< HID feature Report Reference value. */ 216 } hids_init_t; 217 /** @} */ 218 219 /** 220 * @defgroup HIDS_FUNCTION Functions 221 * @{ 222 */ 223 224 /** 225 ***************************************************************************************** 226 * @brief Initialize a HID Service instance in ATT DB. 227 * 228 * @param[in] p_hids_init: Pointer to a HID Service initialization variable. 229 * 230 * @return Result of service initialization. 231 ***************************************************************************************** 232 */ 233 sdk_err_t hids_service_init(hids_init_t *p_hids_init); 234 235 /** 236 ***************************************************************************************** 237 * @brief Send an input report. 238 * 239 * @param[in] conn_idx: Connection index. 240 * @param[in] rep_idx: Input report inedx. 241 * @param[in] p_data: Pointer to data to be sent. 242 * @param[in] length: Length of data to be sent. 243 * 244 * @return BLE_SDK_SUCCESS on success, otherwise an error code. 245 ***************************************************************************************** 246 */ 247 sdk_err_t hids_input_rep_send(uint8_t conn_idx, uint8_t rep_idx, uint8_t *p_data, uint16_t length); 248 249 /** 250 ***************************************************************************************** 251 * @brief Send boot keyboard input report. 252 * 253 * @param[in] conn_idx: Connection index. 254 * @param[in] p_data: Pointer to data to be sent. 255 * @param[in] length: Length of data to be sent. 256 * 257 * @return BLE_SDK_SUCCESS on success, otherwise an error code. 258 ***************************************************************************************** 259 */ 260 sdk_err_t hids_boot_kb_in_rep_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length); 261 262 /** 263 ***************************************************************************************** 264 * @brief Send boot mouse input report. 265 * 266 * @param[in] conn_idx: Connection index. 267 * @param[in] p_data: Pointer to data to be sent. 268 * @param[in] length: Length of data to be sent. 269 * 270 * @return BLE_SDK_SUCCESS on success, otherwise an error code. 271 ***************************************************************************************** 272 */ 273 sdk_err_t hids_boot_mouse_in_rep_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length); 274 /** @} */ 275 276 #endif 277 /** @} */ 278 /** @} */ 279 280