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

Source


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

Source


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

Returns

Source


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

Returns

Source


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

Returns

Source


hid_host_disconnect

void hid_host_disconnect(uint16_t hid_cid);

Disconnect from HID Device and emit HID_SUBEVENT_CONNECTION_CLOSED event.

Parameters

Source


// 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

Returns

Source


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

Returns

Source


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

Returns

Source


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

Returns

Source


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

Returns

Source


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

Returns

Source


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

Returns

Source


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

Returns

Source


hid_descriptor_storage_get_descriptor_data

const uint8_t * hid_descriptor_storage_get_descriptor_data(uint16_t hid_cid);

Get descriptor data

Parameters

Returns

Source


hid_descriptor_storage_get_descriptor_len

uint16_t hid_descriptor_storage_get_descriptor_len(uint16_t hid_cid);

Get descriptor length

Parameters

Returns

Source


hid_host_deinit

void hid_host_deinit(void);

De-Init HID Device

Source