1 /* 2 * Copyright (C) 2020 BlueKitchen GmbH 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. Neither the name of the copyright holders nor the names of 14 * contributors may be used to endorse or promote products derived 15 * from this software without specific prior written permission. 16 * 4. Any redistribution, use, or modification is done solely for 17 * personal benefit and not for any commercial purpose or for 18 * monetary gain. 19 * 20 * THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS 21 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BLUEKITCHEN 24 * GMBH OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 26 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 27 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 30 * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31 * SUCH DAMAGE. 32 * 33 * Please inquire about commercial licensing options at 34 * [email protected] 35 * 36 */ 37 38 /** 39 * @title HID Host 40 * 41 */ 42 43 #ifndef HID_HOST_H 44 #define HID_HOST_H 45 46 #include <stdint.h> 47 #include "btstack_defines.h" 48 #include "bluetooth.h" 49 #include "btstack_hid.h" 50 #include "btstack_hid_parser.h" 51 52 #if defined __cplusplus 53 extern "C" { 54 #endif 55 56 57 typedef enum { 58 HID_HOST_IDLE, 59 HID_HOST_W2_SEND_SDP_QUERY, 60 HID_HOST_W4_SDP_QUERY_RESULT, 61 62 HID_HOST_W4_CONTROL_CONNECTION_ESTABLISHED, 63 HID_HOST_CONTROL_CONNECTION_ESTABLISHED, 64 65 HID_HOST_W4_SET_BOOT_MODE, 66 HID_HOST_W4_INCOMING_INTERRUPT_CONNECTION, 67 HID_HOST_W4_INTERRUPT_CONNECTION_ESTABLISHED, 68 HID_HOST_CONNECTION_ESTABLISHED, 69 70 HID_HOST_W2_SEND_GET_REPORT, 71 HID_HOST_W4_GET_REPORT_RESPONSE, 72 HID_HOST_W2_SEND_SET_REPORT, 73 HID_HOST_W4_SET_REPORT_RESPONSE, 74 HID_HOST_W2_SEND_GET_PROTOCOL, 75 HID_HOST_W4_GET_PROTOCOL_RESPONSE, 76 77 HID_HOST_W2_SEND_REPORT, 78 HID_HOST_W4_SEND_REPORT_RESPONSE, 79 80 HID_HOST_W4_INTERRUPT_CONNECTION_DISCONNECTED, 81 HID_HOST_W4_CONTROL_CONNECTION_DISCONNECTED 82 } hid_host_state_t; 83 84 typedef struct { 85 btstack_linked_item_t item; 86 87 uint16_t hid_cid; 88 hci_con_handle_t con_handle; 89 90 bd_addr_t remote_addr; 91 92 uint16_t control_cid; 93 uint16_t control_psm; 94 uint16_t interrupt_cid; 95 uint16_t interrupt_psm; 96 97 hid_host_state_t state; 98 bool incoming; 99 hid_protocol_mode_t protocol_mode; 100 101 bool set_protocol; 102 bool w4_set_protocol_response; 103 hid_protocol_mode_t requested_protocol_mode; 104 105 uint16_t host_max_latency; 106 uint16_t host_min_timeout; 107 108 uint16_t hid_descriptor_offset; 109 uint16_t hid_descriptor_len; 110 uint16_t hid_descriptor_max_len; 111 uint8_t hid_descriptor_status; // ERROR_CODE_SUCCESS if descriptor available, 112 // ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if not, and 113 // ERROR_CODE_MEMORY_CAPACITY_EXCEEDED if descriptor is larger then the available space 114 115 uint8_t user_request_can_send_now; 116 117 // get report 118 hid_report_type_t report_type; 119 uint16_t report_id; 120 121 // control message, bit mask: 122 // SUSSPEND 1 123 // EXIT_SUSSPEND 2 124 // VIRTUAL_CABLE_UNPLUG 4 125 uint8_t control_tasks; 126 127 // set report 128 const uint8_t * report; 129 uint16_t report_len; 130 } hid_host_connection_t; 131 132 /* API_START */ 133 134 /** 135 * @brief Set up HID Host 136 * @param hid_descriptor_storage 137 * @param hid_descriptor_storage_len 138 */ 139 void hid_host_init(uint8_t * hid_descriptor_storage, uint16_t hid_descriptor_storage_len); 140 141 /** 142 * @brief Register callback for the HID Host. 143 * @param callback 144 */ 145 void hid_host_register_packet_handler(btstack_packet_handler_t callback); 146 147 /** 148 * @brief Create HID connection to HID Device and emit HID_SUBEVENT_CONNECTION_OPENED event with status code, 149 * followed by HID_SUBEVENT_DESCRIPTOR_AVAILABLE that informs if the HID Descriptor was found. In the case of incoming 150 * connection, i.e. HID Device initiating the connection, the HID_SUBEVENT_DESCRIPTOR_AVAILABLE is delayed, and the reports 151 * may already come via HID_SUBEVENT_REPORT event. It is up to the application code if 152 * these reports should be buffered or ignored until the descriptor is available. 153 * @note HID_PROTOCOL_MODE_REPORT_WITH_FALLBACK_TO_BOOT will try ti set up REPORT mode, but fallback to BOOT mode if necessary. 154 * @note HID_SUBEVENT_DESCRIPTOR_AVAILABLE possible status values are: 155 * - ERROR_CODE_SUCCESS if descriptor available, 156 * - ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if not, and 157 * - ERROR_CODE_MEMORY_CAPACITY_EXCEEDED if descriptor is larger then the available space 158 * @param remote_addr 159 * @param protocol_mode see hid_protocol_mode_t in btstack_hid.h 160 * @param hid_cid to use for other commands 161 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_COMMAND_DISALLOWED, BTSTACK_MEMORY_ALLOC_FAILED 162 */ 163 uint8_t hid_host_connect(bd_addr_t remote_addr, hid_protocol_mode_t protocol_mode, uint16_t * hid_cid); 164 165 166 /** 167 * @brief Accept incoming HID connection, this should be called upon receiving HID_SUBEVENT_INCOMING_CONNECTION event. 168 * @param hid_cid 169 * @param protocol_mode see hid_protocol_mode_t in btstack_hid.h 170 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED 171 */ 172 uint8_t hid_host_accept_connection(uint16_t hid_cid, hid_protocol_mode_t protocol_mode); 173 174 /** 175 * @brief Decline incoming HID connection, this should be called upon receiving HID_SUBEVENT_INCOMING_CONNECTION event. 176 * @param hid_cid 177 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED 178 */ 179 uint8_t hid_host_decline_connection(uint16_t hid_cid); 180 181 /** 182 * @brief Disconnect from HID Device and emit HID_SUBEVENT_CONNECTION_CLOSED event. 183 * @param hid_cid 184 */ 185 void hid_host_disconnect(uint16_t hid_cid); 186 187 // Control messages: 188 189 /** 190 * @brief Send SUSPEND control signal to connected HID Device. A Bluetooth HID Device which receives a SUSPEND control signal 191 * may optionally disconnect from the Bluetooth HID Host. 192 * @param hid_cid 193 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED 194 */ 195 uint8_t hid_host_send_suspend(uint16_t hid_cid); 196 197 /** 198 * @brief Order connected HID Device to exit suspend mode. 199 * The Bluetooth HID Device shall send a report to the Bluetooth HID Host. 200 * @param hid_cid 201 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED 202 */ 203 uint8_t hid_host_send_exit_suspend(uint16_t hid_cid); 204 205 /** 206 * @brief Unplug connected HID Device. 207 * @note This is the only command that can be also received from HID Device. It will be indicated by receiving 208 * HID_SUBEVENT_VIRTUAL_CABLE_UNPLUG event, as well as disconnecting HID Host from device. 209 * @param hid_cid 210 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED 211 */ 212 uint8_t hid_host_send_virtual_cable_unplug(uint16_t hid_cid); 213 214 /** 215 * @brief Set Protocol Mode on the Bluetooth HID Device and emit HID_SUBEVENT_SET_PROTOCOL_RESPONSE event with handshake_status, see hid_handshake_param_type_t 216 * @param hid_cid 217 * @param protocol_mode see hid_protocol_mode_t in btstack_hid.h 218 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED 219 */ 220 uint8_t hid_host_send_set_protocol_mode(uint16_t hid_cid, hid_protocol_mode_t protocol_mode); 221 222 /** 223 * @brief Retrieve the Protocol Mode of the Bluetooth HID Device and emit HID_SUBEVENT_GET_PROTOCOL_RESPONSE with handshake_status, see hid_handshake_param_type_t 224 * @param hid_cid 225 * @param protocol_mode see hid_protocol_mode_t in btstack_hid.h 226 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED 227 */ 228 uint8_t hid_host_send_get_protocol(uint16_t hid_cid); 229 230 /** 231 * @brief Send report to a Bluetooth HID Device and emit HID_SUBEVENT_SET_REPORT_RESPONSE with handshake_status, see hid_handshake_param_type_t. The Bluetooth HID Host shall send complete reports. 232 * @param hid_cid 233 * @param report_type see hid_report_type_t in btstack_hid.h 234 * @param report_id or HID_REPORT_ID_UNDEFINED 235 * @param report 236 * @param report_len 237 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED 238 */ 239 uint8_t hid_host_send_set_report(uint16_t hid_cid, hid_report_type_t report_type, uint16_t report_id, const uint8_t * report, uint8_t report_len); 240 241 /** 242 * @brief Request a HID report from the Bluetooth HID Device and emit HID_SUBEVENT_GET_REPORT_RESPONSE event with with handshake_status, see hid_handshake_param_type_t. 243 * Polling Bluetooth HID Devices using the GET_REPORT transfer is costly in terms of time and overhead, 244 * and should be avoided whenever possible. The GET_REPORT transfer is typically only used by applications 245 * to determine the initial state of a Bluetooth HID Device. If the state of a report changes frequently, 246 * then the report should be reported over the more efficient Interrupt channel, see hid_host_send_report. 247 * @param hid_cid 248 * @param report_type see hid_report_type_t in btstack_hid.h 249 * @param report_id or HID_REPORT_ID_UNDEFINED 250 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED 251 */ 252 uint8_t hid_host_send_get_report(uint16_t hid_cid, hid_report_type_t report_type, uint16_t report_id); 253 254 /** 255 * @brief Send HID output report on interrupt channel. 256 * @param hid_cid 257 * @param report_id or HID_REPORT_ID_UNDEFINED 258 * @param report 259 * @param report_len 260 * @result status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED 261 */ 262 uint8_t hid_host_send_report(uint16_t hid_cid, uint16_t report_id, const uint8_t * report, uint8_t report_len); 263 264 /** 265 * @brief Get descriptor data 266 * @param hid_cid 267 * @result data 268 */ 269 const uint8_t * hid_descriptor_storage_get_descriptor_data(uint16_t hid_cid); 270 271 /** 272 * @brief Get descriptor length 273 * @param hid_cid 274 * @result length 275 */ 276 uint16_t hid_descriptor_storage_get_descriptor_len(uint16_t hid_cid); 277 278 /** 279 * @brief De-Init HID Device 280 */ 281 void hid_host_deinit(void); 282 283 /* API_END */ 284 285 286 #if defined __cplusplus 287 } 288 #endif 289 290 #endif 291