hids.h
Go to the documentation of this file.
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 "ble_prf_utils.h"
70 #include "gr_includes.h"
71 #include "custom_config.h"
72 #include <stdint.h>
73
74 /**
75 * @defgroup HIDS_MACRO Defines
76 * @{
77 */
78
79 #define HIDS_CONNECTION_MAX 10 /**< Maximum number of Heart Rate Service connections. */
80
81 #define HIDS_REPORT_MAX_SIZE 20 /**< Maximum length of report. */
82 #define HIDS_REPORT_MAP_MAX_SIZE 512 /**< Limitation of length, as per Section 2.6.1 in HIDS Spec, version 1.0 */
83
84 /**
85 * @defgroup HIDS_REPORT_TYPE Report Type values
86 * @{
87 * @brief HIDS Report Type values define.
88 */
89 #define HIDS_REP_TYPE_INPUT 1 /**< The input report type. */
90 #define HIDS_REP_TYPE_OUTPUT 2 /**< The output report type. */
91 #define HIDS_REP_TYPE_FEATURE 3 /**< The feature report type. */
92 /** @} */
93
94 /**
95 * @defgroup HIDS_INFOR_FLAGS Information Flags
96 * @{
97 * @brief HIDS Information Flags define.
98 */
99 #define HID_INFO_FLAG_REMOTE_WAKE_MSK 0x01 /**< Bit mask of Remote Wake flag in HIDS information. */
100 #define HID_INFO_FLAG_NORMALLY_CONNECTABLE_MSK 0x02 /**< Bit mask of Normally Connectable flag in HIDS information. */
101 /** @} */
102 /** @} */
103
104
105 /**
106 * @defgroup HIDS_ENUM Enumerations
107 * @{
108 */
109
110 /**@brief HID Service event type. */
111 typedef enum
112 {
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 {
127 HIDS_REPORT_TYPE_RESERVED, /**< The reserved report type. */
128 HIDS_REPORT_TYPE_IN1, /**< The input report1 type. */
129 HIDS_REPORT_TYPE_IN2, /**< The input report2 type. */
130 HIDS_REPORT_TYPE_IN3, /**< The input report3 type. */
131 HIDS_REPORT_TYPE_OUT, /**< The output report type. */
132 HIDS_REPORT_TYPE_FEATURE, /**< The feature report type. */
133 HIDS_REPORT_TYPE_KB_IN, /**< The boot keyboard input report type. */
134 HIDS_REPORT_TYPE_KB_OUT, /**< The boot keyboard output report type. */
135 HIDS_REPORT_TYPE_MOUSE_IN, /**< The boot mouse inputreport type. */
136 } hids_report_type_t;
137 /** @} */
138
139
140 /**
141 * @defgroup HIDS_TYPEDEF Typedefs
142 * @{
143 */
144
145 /**@brief HID Service event. */
146 typedef struct
147 {
148 hids_evt_type_t evt_type; /**< Type of event. */
149 uint8_t conn_idx; /**< Connect index. */
150 hids_report_type_t report_type; /**< Type of report, see @ref hids_report_type_t. */
151 uint16_t offset; /**< Offset for the write operation. */
152 uint16_t len; /**< Length of the incoming data. */
153 uint8_t const * data; /**< Incoming data, variable length */
154 }hids_evt_t;
155
156 /**@brief HID Information characteristic value. */
157 typedef struct
158 {
159 uint16_t bcd_hid; /**< 16-bit unsigned integer representing version number of base USB HID Specification implemented by HID Device */
160 uint8_t b_country_code; /**< Identifies which country the hardware is localized for. Most hardware is not localized and thus this value would be zero (0). */
161 uint8_t flags; /**< See http://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.hid_information.xml */
162 }hids_hid_info_t;
163
164
165 /**@brief Value of a Report Reference descriptor.
166 *
167 * @details This is mapping information that maps the parent characteristic to the Report ID(s) and
168 * Report Type(s) defined within a Report Map characteristic.
169 */
170 typedef struct
171 {
172 uint8_t report_id; /**< Non-zero value if there is more than one instance of the same Report Type */
173 uint8_t report_type; /**< Type of Report characteristic (see @ref HIDS_REPORT_TYPE) */
174 } hids_report_ref_t;
175
176
177 /**@brief HID Service Report characteristic define. */
178 typedef struct
179 {
180 uint16_t value_len; /**< Length of characteristic value. */
181 hids_report_ref_t ref; /**< Value of a Report Reference descriptor, see @ref hids_report_ref_t. */
182 } hids_report_int_t;
183
184
185 /**@brief HID Service Report Map characteristic value. */
186 typedef struct
187 {
188 uint8_t *p_map; /**< Pointer to the report map. */
189 uint16_t len; /**< The length of report map. */
190 } hids_report_map_t;
191
192
193 /**@brief HID Service event handler type.
194 *
195 * @param[in] p_evt Pointer to a HID Service event variable.
196 */
197 typedef void (*hids_evt_handler_t)(hids_evt_t *p_evt);
198
199
200 /**@brief HID Service initialization variable. */
201 typedef struct
202 {
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 out_report_sup; /**< TRUE if output Report characteristic suport, FALSE if it is nonsupport. */
211 hids_report_int_t output_report; /**< HID output Report Reference value. */
212 bool feature_report_sup; /**< TRUE if feature Report characteristic suport, FALSE if it is nonsupport. */
213 hids_report_int_t feature_report; /**< HID feature Report Reference value. */
214 } hids_init_t;
215 /** @} */
216
217 /**
218 * @defgroup HIDS_FUNCTION Functions
219 * @{
220 */
221
222 /**
223 *****************************************************************************************
224 * @brief Initialize a HID Service instance in ATT DB.
225 *
226 * @param[in] p_hids_init: Pointer to a HID Service initialization variable.
227 *
228 * @return Result of service initialization.
229 *****************************************************************************************
230 */
231 sdk_err_t hids_service_init(hids_init_t *p_hids_init);
232
233 /**
234 *****************************************************************************************
235 * @brief Send an input report.
236 *
237 * @param[in] conn_idx: Connection index.
238 * @param[in] rep_idx: Input report inedx.
239 * @param[in] p_data: Pointer to data to be sent.
240 * @param[in] length: Length of data to be sent.
241 *
242 * @return BLE_SDK_SUCCESS on success, otherwise an error code.
243 *****************************************************************************************
244 */
245 sdk_err_t hids_input_rep_send(uint8_t conn_idx, uint8_t rep_idx, uint8_t *p_data, uint16_t length);
246
247 /**
248 *****************************************************************************************
249 * @brief Send boot keyboard input report.
250 *
251 * @param[in] conn_idx: Connection index.
252 * @param[in] p_data: Pointer to data to be sent.
253 * @param[in] length: Length of data to be sent.
254 *
255 * @return BLE_SDK_SUCCESS on success, otherwise an error code.
256 *****************************************************************************************
257 */
258 sdk_err_t hids_boot_kb_in_rep_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
259
260 /**
261 *****************************************************************************************
262 * @brief Send boot mouse input report.
263 *
264 * @param[in] conn_idx: Connection index.
265 * @param[in] p_data: Pointer to data to be sent.
266 * @param[in] length: Length of data to be sent.
267 *
268 * @return BLE_SDK_SUCCESS on success, otherwise an error code.
269 *****************************************************************************************
270 */
271 sdk_err_t hids_boot_mouse_in_rep_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
272
273 /**
274 *****************************************************************************************
275 * @brief Provide the interface for other modules to obtain the hids service start handle .
276 *
277 * @return The hids service start handle.
278 *****************************************************************************************
279 */
280 uint16_t hids_service_start_handle_get(void);
281
282 /** @} */
283
284 #endif
285 /** @} */
286 /** @} */
287
HIDS_EVT_REP_CHAR_WRITE
@ HIDS_EVT_REP_CHAR_WRITE
New value has been written to a report characteristic.
Definition: hids.h:120
hids_report_type_t
hids_report_type_t
HID Service write report type.
Definition: hids.h:126
hids_init_t::is_kb
bool is_kb
TRUE if device is operating as a keyboard, FALSE if it is not.
Definition: hids.h:204
hids_init_t::feature_report
hids_report_int_t feature_report
HID feature Report Reference value.
Definition: hids.h:213
hids_hid_info_t::bcd_hid
uint16_t bcd_hid
16-bit unsigned integer representing version number of base USB HID Specification implemented by HID ...
Definition: hids.h:159
HIDS_REPORT_TYPE_KB_IN
@ HIDS_REPORT_TYPE_KB_IN
The boot keyboard input report type.
Definition: hids.h:133
HIDS_REPORT_TYPE_IN2
@ HIDS_REPORT_TYPE_IN2
The input report2 type.
Definition: hids.h:129
hids_evt_t::conn_idx
uint8_t conn_idx
Connect index.
Definition: hids.h:149
hids_service_start_handle_get
uint16_t hids_service_start_handle_get(void)
Provide the interface for other modules to obtain the hids service start handle .
HIDS_EVT_REPORT_MODE_ENTERED
@ HIDS_EVT_REPORT_MODE_ENTERED
Report mode entered.
Definition: hids.h:119
HIDS_EVT_IN_REP_NOTIFY_ENABLED
@ HIDS_EVT_IN_REP_NOTIFY_ENABLED
Input report notification enabled event.
Definition: hids.h:114
HIDS_REPORT_TYPE_IN1
@ HIDS_REPORT_TYPE_IN1
The input report1 type.
Definition: hids.h:128
HIDS_EVT_HOST_EXIT_SUSP
@ HIDS_EVT_HOST_EXIT_SUSP
Exit suspend command received.
Definition: hids.h:117
hids_report_int_t
HID Service Report characteristic define.
Definition: hids.h:179
hids_report_ref_t::report_type
uint8_t report_type
Type of Report characteristic (see Report Type values)
Definition: hids.h:173
HIDS_EVT_HOST_SUSP
@ HIDS_EVT_HOST_SUSP
Suspend command received.
Definition: hids.h:116
hids_service_init
sdk_err_t hids_service_init(hids_init_t *p_hids_init)
Initialize a HID Service instance in ATT DB.
hids_init_t::out_report_sup
bool out_report_sup
TRUE if output Report characteristic suport, FALSE if it is nonsupport.
Definition: hids.h:210
gr_includes.h
Include Files API.
hids_init_t::evt_handler
hids_evt_handler_t evt_handler
Handle events in HID Service.
Definition: hids.h:203
HIDS_REPORT_TYPE_RESERVED
@ HIDS_REPORT_TYPE_RESERVED
The reserved report type.
Definition: hids.h:127
hids_hid_info_t
HID Information characteristic value.
Definition: hids.h:158
hids_report_int_t::value_len
uint16_t value_len
Length of characteristic value.
Definition: hids.h:180
HIDS_EVT_IN_REP_NOTIFY_DISABLED
@ HIDS_EVT_IN_REP_NOTIFY_DISABLED
Input report notification disabled event.
Definition: hids.h:115
hids_report_map_t::len
uint16_t len
The length of report map.
Definition: hids.h:189
hids_evt_t::len
uint16_t len
Length of the incoming data.
Definition: hids.h:152
HIDS_EVT_INVALID
@ HIDS_EVT_INVALID
Invalid event.
Definition: hids.h:113
hids_evt_t::evt_type
hids_evt_type_t evt_type
Type of event.
Definition: hids.h:148
hids_init_t::feature_report_sup
bool feature_report_sup
TRUE if feature Report characteristic suport, FALSE if it is nonsupport.
Definition: hids.h:212
hids_evt_handler_t
void(* hids_evt_handler_t)(hids_evt_t *p_evt)
HID Service event handler type.
Definition: hids.h:197
hids_input_rep_send
sdk_err_t hids_input_rep_send(uint8_t conn_idx, uint8_t rep_idx, uint8_t *p_data, uint16_t length)
Send an input report.
hids_evt_t::offset
uint16_t offset
Offset for the write operation.
Definition: hids.h:151
hids_evt_type_t
hids_evt_type_t
HID Service event type.
Definition: hids.h:112
hids_report_map_t
HID Service Report Map characteristic value.
Definition: hids.h:187
hids_report_ref_t
Value of a Report Reference descriptor.
Definition: hids.h:171
hids_init_t::output_report
hids_report_int_t output_report
HID output Report Reference value.
Definition: hids.h:211
hids_init_t::is_mouse
bool is_mouse
TRUE if device is operating as a mouse, FALSE if it is not.
Definition: hids.h:205
hids_init_t::report_map
hids_report_map_t report_map
HID Service Report Map characteristic value.
Definition: hids.h:207
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
hids_hid_info_t::flags
uint8_t flags
See http://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer....
Definition: hids.h:161
hids_report_ref_t::report_id
uint8_t report_id
Non-zero value if there is more than one instance of the same Report Type.
Definition: hids.h:172
HIDS_EVT_BOOT_MODE_ENTERED
@ HIDS_EVT_BOOT_MODE_ENTERED
Boot mode entered.
Definition: hids.h:118
HIDS_REPORT_TYPE_MOUSE_IN
@ HIDS_REPORT_TYPE_MOUSE_IN
The boot mouse inputreport type.
Definition: hids.h:135
hids_report_int_t::ref
hids_report_ref_t ref
Value of a Report Reference descriptor, see hids_report_ref_t.
Definition: hids.h:181
HIDS_REPORT_TYPE_KB_OUT
@ HIDS_REPORT_TYPE_KB_OUT
The boot keyboard output report type.
Definition: hids.h:134
hids_evt_t::data
uint8_t const * data
Incoming data, variable length.
Definition: hids.h:153
hids_evt_t
HID Service event.
Definition: hids.h:147
HIDS_REPORT_TYPE_OUT
@ HIDS_REPORT_TYPE_OUT
The output report type.
Definition: hids.h:131
hids_report_map_t::p_map
uint8_t * p_map
Pointer to the report map.
Definition: hids.h:188
ble_prf_utils.h
Profile/Service Utilities API.
HIDS_REPORT_TYPE_IN3
@ HIDS_REPORT_TYPE_IN3
The input report3 type.
Definition: hids.h:130
hids_evt_t::report_type
hids_report_type_t report_type
Type of report, see hids_report_type_t.
Definition: hids.h:150
hids_boot_mouse_in_rep_send
sdk_err_t hids_boot_mouse_in_rep_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Send boot mouse input report.
HIDS_REPORT_TYPE_FEATURE
@ HIDS_REPORT_TYPE_FEATURE
The feature report type.
Definition: hids.h:132
hids_hid_info_t::b_country_code
uint8_t b_country_code
Identifies which country the hardware is localized for.
Definition: hids.h:160
hids_init_t
HID Service initialization variable.
Definition: hids.h:202
hids_init_t::hid_info
hids_hid_info_t hid_info
Value of HID information characteristic.
Definition: hids.h:206
hids_init_t::input_report_count
uint8_t input_report_count
Number of Input Report characteristics.
Definition: hids.h:208
hids_boot_kb_in_rep_send
sdk_err_t hids_boot_kb_in_rep_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Send boot keyboard input report.