HID Host API
#include "src/classic/hid_host.h"
hid_host_init
void hid_host_init(uint8_t * hid_descriptor_storage, uint16_t hid_descriptor_storage_len);
Set up HID Host and provide storage for HID Descriptors If storage for HID Descriptors is provided, the HID Host will fetch and store the HID Descriptors for each connection and inform the application via HID_SUBEVENT_DESCRIPTOR_AVAILABLE event. The app can then access the HID descriptor for a particular connection with hid_descriptor_storage_get_descriptor_data and hid_descriptor_storage_get_descriptor_len.
Note: if hid_descriptor_storage is NULL, the HID Host will not store the HID Descriptor
Parameters
- hid_descriptor_storage
- hid_descriptor_storage_len
hid_host_register_packet_handler
void hid_host_register_packet_handler(btstack_packet_handler_t callback);
Register callback for the HID Host.
Note: HID Reports might be larger than what fits into regular HCI Event, i.e. the 8-bit lenght field might be invalid Instead, you can use the provided uint16_t packet_size value
Parameters
- callback
hid_host_connect
uint8_t hid_host_connect(bd_addr_t remote_addr, hid_protocol_mode_t protocol_mode, uint16_t * hid_cid);
Create HID connection to HID Device and emit HID_SUBEVENT_CONNECTION_OPENED event with status code, followed by HID_SUBEVENT_DESCRIPTOR_AVAILABLE that informs if the HID Descriptor was found. In the case of incoming connection, i.e. HID Device initiating the connection, the HID_SUBEVENT_DESCRIPTOR_AVAILABLE is delayed, and the reports may already come via HID_SUBEVENT_REPORT event. It is up to the application code if these reports should be buffered or ignored until the descriptor is available.
Note: HID_PROTOCOL_MODE_REPORT_WITH_FALLBACK_TO_BOOT will try ti set up REPORT mode, but fallback to BOOT mode if necessary.
Note: HID_SUBEVENT_DESCRIPTOR_AVAILABLE possible status values are: - ERROR_CODE_SUCCESS if descriptor available, - ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if not, and - ERROR_CODE_MEMORY_CAPACITY_EXCEEDED if descriptor is larger then the available space
Parameters
- remote_addr
- protocol_mode: see hid_protocol_mode_t in btstack_hid.h
- hid_cid: to use for other commands
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_COMMAND_DISALLOWED, BTSTACK_MEMORY_ALLOC_FAILED
hid_host_accept_connection
uint8_t hid_host_accept_connection(uint16_t hid_cid, hid_protocol_mode_t protocol_mode);
Accept incoming HID connection, this should be called upon receiving HID_SUBEVENT_INCOMING_CONNECTION event.
Parameters
- hid_cid
- protocol_mode: see hid_protocol_mode_t in btstack_hid.h
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
hid_host_decline_connection
uint8_t hid_host_decline_connection(uint16_t hid_cid);
Decline incoming HID connection, this should be called upon receiving HID_SUBEVENT_INCOMING_CONNECTION event.
Parameters
- hid_cid
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
hid_host_disconnect
void hid_host_disconnect(uint16_t hid_cid);
Disconnect from HID Device and emit HID_SUBEVENT_CONNECTION_CLOSED event.
Parameters
- hid_cid
// Control messages:
hid_host_send_suspend
uint8_t hid_host_send_suspend(uint16_t hid_cid);
Send SUSPEND control signal to connected HID Device. A Bluetooth HID Device which receives a SUSPEND control signal may optionally disconnect from the Bluetooth HID Host.
Parameters
- hid_cid
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
hid_host_send_exit_suspend
uint8_t hid_host_send_exit_suspend(uint16_t hid_cid);
Order connected HID Device to exit suspend mode. The Bluetooth HID Device shall send a report to the Bluetooth HID Host.
Parameters
- hid_cid
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
hid_host_send_virtual_cable_unplug
uint8_t hid_host_send_virtual_cable_unplug(uint16_t hid_cid);
Unplug connected HID Device.
Note: This is the only command that can be also received from HID Device. It will be indicated by receiving HID_SUBEVENT_VIRTUAL_CABLE_UNPLUG event, as well as disconnecting HID Host from device.
Parameters
- hid_cid
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
hid_host_send_set_protocol_mode
uint8_t hid_host_send_set_protocol_mode(uint16_t hid_cid, hid_protocol_mode_t protocol_mode);
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
Parameters
- hid_cid
- protocol_mode: see hid_protocol_mode_t in btstack_hid.h
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
hid_host_send_get_protocol
uint8_t hid_host_send_get_protocol(uint16_t hid_cid);
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
Parameters
- hid_cid
- protocol_mode: see hid_protocol_mode_t in btstack_hid.h
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
hid_host_send_set_report
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);
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.
Parameters
- hid_cid
- report_type: see hid_report_type_t in btstack_hid.h
- report_id: or HID_REPORT_ID_UNDEFINED
- report
- report_len
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
hid_host_send_get_report
uint8_t hid_host_send_get_report(uint16_t hid_cid, hid_report_type_t report_type, uint16_t report_id);
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. Polling Bluetooth HID Devices using the GET_REPORT transfer is costly in terms of time and overhead, and should be avoided whenever possible. The GET_REPORT transfer is typically only used by applications to determine the initial state of a Bluetooth HID Device. If the state of a report changes frequently, then the report should be reported over the more efficient Interrupt channel, see hid_host_send_report.
Parameters
- hid_cid
- report_type: see hid_report_type_t in btstack_hid.h
- report_id: or HID_REPORT_ID_UNDEFINED
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
hid_host_send_report
uint8_t hid_host_send_report(uint16_t hid_cid, uint16_t report_id, const uint8_t * report, uint16_t report_len);
Send HID output report on interrupt channel.
Parameters
- hid_cid
- report_id: or HID_REPORT_ID_UNDEFINED
- report
- report_len
Returns
- uint8_t: status ERROR_CODE_SUCCESS on success, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER, ERROR_CODE_COMMAND_DISALLOWED
hid_descriptor_storage_get_descriptor_data
const uint8_t * hid_descriptor_storage_get_descriptor_data(uint16_t hid_cid);
Get descriptor data
Parameters
- hid_cid
Returns
- const uint8_t *: data
hid_descriptor_storage_get_descriptor_len
uint16_t hid_descriptor_storage_get_descriptor_len(uint16_t hid_cid);
Get descriptor length
Parameters
- hid_cid
Returns
- uint16_t: length
hid_host_deinit
void hid_host_deinit(void);
De-Init HID Device