Bluetooth® HID Host API
Overview
A Bluetooth HID host is a device or software that is capable of connecting and communicating with Bluetooth HID devices, such as keyboards, mice. Users can use the Bluetooth HID Host APIs to send output data or control commands to the HID devices, enabling them to control the behavior or settings of the devices.
Application Examples
bluetooth/esp_hid_host demonstrates how to use the ESP-IDF Bluetooth HID Host APIs to create a Bluetooth Classic, Bluetooth LE, or Bluetooth dual-mode HID host that scans and connects to the most recently discovered Bluetooth HID device, dumps the HID device information, and receives data sent by the HID device.
API Reference
Header File
This header file can be included with:
#include "esp_hidh_api.h"
This header file is a part of the API provided by the
bt
component. To declare that your component depends onbt
, add the following to your CMakeLists.txt:REQUIRES bt
or
PRIV_REQUIRES bt
Functions
-
esp_err_t esp_bt_hid_host_register_callback(esp_hh_cb_t callback)
This function is called to init callbacks with HID host module.
- Parameters
callback -- [in] pointer to the init callback function.
- Returns
ESP_OK: success
other: failed
-
esp_err_t esp_bt_hid_host_init(void)
This function initializes HID host. This function should be called after esp_bluedroid_enable() and esp_bluedroid_init()/esp_bluedroid_init_with_cfg() success, and should be called after esp_bt_hid_host_register_callback(). When the operation is complete the callback function will be called with ESP_HIDH_INIT_EVT.
- Returns
ESP_OK: success
other: failed
-
esp_err_t esp_bt_hid_host_deinit(void)
Closes the interface. This function should be called after esp_bluedroid_enable() and esp_bluedroid_init()/esp_bluedroid_init_with_cfg() success, and should be called after esp_bt_hid_host_init(). When the operation is complete the callback function will be called with ESP_HIDH_DEINIT_EVT.
- Returns
- ESP_OK: success
other: failed
-
esp_err_t esp_bt_hid_host_connect(esp_bd_addr_t bd_addr)
Connect to HID device. When the operation is complete the callback function will be called with ESP_HIDH_OPEN_EVT.
- Parameters
bd_addr -- [in] Remote device bluetooth device address.
- Returns
- ESP_OK: success
other: failed
-
esp_err_t esp_bt_hid_host_disconnect(esp_bd_addr_t bd_addr)
Disconnect from HID device. When the operation is complete the callback function will be called with ESP_HIDH_CLOSE_EVT.
- Parameters
bd_addr -- [in] Remote device bluetooth device address.
- Returns
- ESP_OK: success
other: failed
-
esp_err_t esp_bt_hid_host_virtual_cable_unplug(esp_bd_addr_t bd_addr)
Virtual UnPlug (VUP) the specified HID device. When the operation is complete the callback function will be called with ESP_HIDH_VC_UNPLUG_EVT.
- Parameters
bd_addr -- [in] Remote device bluetooth device address.
- Returns
- ESP_OK: success
other: failed
-
esp_err_t esp_bt_hid_host_set_info(esp_bd_addr_t bd_addr, esp_hidh_hid_info_t *hid_info)
Set the HID device descriptor for the specified HID device. When the operation is complete the callback function will be called with ESP_HIDH_SET_INFO_EVT.
- Parameters
bd_addr -- [in] Remote device bluetooth device address.
hid_info -- [in] HID device descriptor structure.
- Returns
- ESP_OK: success
other: failed
-
esp_err_t esp_bt_hid_host_get_protocol(esp_bd_addr_t bd_addr)
Get the HID proto mode. When the operation is complete the callback function will be called with ESP_HIDH_GET_PROTO_EVT.
- Parameters
bd_addr -- [in] Remote device bluetooth device address.
- Returns
ESP_OK: success
other: failed
-
esp_err_t esp_bt_hid_host_set_protocol(esp_bd_addr_t bd_addr, esp_hidh_protocol_mode_t protocol_mode)
Set the HID proto mode. When the operation is complete the callback function will be called with ESP_HIDH_SET_PROTO_EVT.
- Parameters
bd_addr -- [in] Remote device bluetooth device address.
protocol_mode -- [in] Protocol mode type.
- Returns
ESP_OK: success
other: failed
-
esp_err_t esp_bt_hid_host_get_idle(esp_bd_addr_t bd_addr)
Get the HID Idle Time. When the operation is complete the callback function will be called with ESP_HIDH_GET_IDLE_EVT.
- Parameters
bd_addr -- [in] Remote device bluetooth device address.
- Returns
ESP_OK: success
other: failed
-
esp_err_t esp_bt_hid_host_set_idle(esp_bd_addr_t bd_addr, uint16_t idle_time)
Set the HID Idle Time. When the operation is complete the callback function will be called with ESP_HIDH_SET_IDLE_EVT.
- Parameters
bd_addr -- [in] Remote device bluetooth device address.
idle_time -- [in] Idle time rate
- Returns
- ESP_OK: success
other: failed
-
esp_err_t esp_bt_hid_host_get_report(esp_bd_addr_t bd_addr, esp_hidh_report_type_t report_type, uint8_t report_id, int buffer_size)
Send a GET_REPORT to HID device. When the operation is complete the callback function will be called with ESP_HIDH_GET_RPT_EVT.
- Parameters
bd_addr -- [in] Remote device bluetooth device address.
report_type -- [in] Report type
report_id -- [in] Report id
buffer_size -- [in] Buffer size
- Returns
- ESP_OK: success
other: failed
-
esp_err_t esp_bt_hid_host_set_report(esp_bd_addr_t bd_addr, esp_hidh_report_type_t report_type, uint8_t *report, size_t len)
Send a SET_REPORT to HID device. When the operation is complete the callback function will be called with ESP_HIDH_SET_RPT_EVT.
- Parameters
bd_addr -- [in] Remote device bluetooth device address.
report_type -- [in] Report type
report -- [in] Report data pointer
len -- [in] Report data length
- Returns
- ESP_OK: success
other: failed
-
esp_err_t esp_bt_hid_host_send_data(esp_bd_addr_t bd_addr, uint8_t *data, size_t len)
Send data to HID device. When the operation is complete the callback function will be called with ESP_HIDH_DATA_EVT.
- Parameters
bd_addr -- [in] Remote device bluetooth device address.
data -- [in] Data pointer
len -- [in] Data length
- Returns
- ESP_OK: success
other: failed
Unions
-
union esp_hidh_cb_param_t
- #include <esp_hidh_api.h>
HID host callback parameters union.
Public Members
-
struct esp_hidh_cb_param_t::hidh_init_evt_param init
HIDH callback param of ESP_HIDH_INIT_EVT
-
struct esp_hidh_cb_param_t::hidh_uninit_evt_param deinit
HIDH callback param of ESP_HIDH_DEINIT_EVT
-
struct esp_hidh_cb_param_t::hidh_open_evt_param open
HIDH callback param of ESP_HIDH_OPEN_EVT
-
struct esp_hidh_cb_param_t::hidh_close_evt_param close
HIDH callback param of ESP_HIDH_CLOSE_EVT
-
struct esp_hidh_cb_param_t::hidh_unplug_evt_param unplug
HIDH callback param of ESP_HIDH_VC_UNPLUG_EVT
-
struct esp_hidh_cb_param_t::hidh_get_proto_evt_param get_proto
HIDH callback param of ESP_HIDH_GET_PROTO_EVT
-
struct esp_hidh_cb_param_t::hidh_set_proto_evt_param set_proto
HIDH callback param of ESP_HIDH_SET_PROTO_EVT
-
struct esp_hidh_cb_param_t::hidh_get_rpt_evt_param get_rpt
HIDH callback param of ESP_HIDH_GET_RPT_EVT
-
struct esp_hidh_cb_param_t::hidh_set_rpt_evt_param set_rpt
HIDH callback param of ESP_HIDH_SET_RPT_EVT
-
struct esp_hidh_cb_param_t::hidh_send_data_evt_param send_data
HIDH callback param of ESP_HIDH_DATA_EVT
-
struct esp_hidh_cb_param_t::hidh_get_idle_evt_param get_idle
HIDH callback param of ESP_HIDH_GET_IDLE_EVT
-
struct esp_hidh_cb_param_t::hidh_set_idle_evt_param set_idle
HIDH callback param of ESP_HIDH_SET_IDLE_EVT
-
struct esp_hidh_cb_param_t::hidh_data_ind_evt_param data_ind
HIDH callback param of ESP_HIDH_DATA_IND_EVT
-
struct esp_hidh_cb_param_t::hidh_add_dev_evt_param add_dev
HIDH callback param of ESP_HIDH_ADD_DEV_EVT
-
struct esp_hidh_cb_param_t::hidh_rmv_dev_evt_param rmv_dev
HIDH callback param of ESP_HIDH_RMV_DEV_EVT
-
struct esp_hidh_cb_param_t::hidh_get_dscp_evt_param dscp
HIDH callback param of ESP_HIDH_GET_DSCP_EVT
-
struct esp_hidh_cb_param_t::hidh_set_info_evt_param set_info
HIDH callback param of ESP_HIDH_SET_INFO_EVT
-
struct hidh_add_dev_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_ADD_DEV_EVT.
Public Members
-
esp_hidh_status_t status
operation status
-
uint8_t handle
device handle
-
esp_bd_addr_t bd_addr
device address
-
esp_hidh_status_t status
-
struct hidh_close_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_CLOSE_EVT.
Public Members
-
esp_hidh_status_t status
operation status
-
uint8_t reason
lower layer failed reason(ref hiddefs.h)
-
esp_hidh_connection_state_t conn_status
connection status
-
uint8_t handle
device handle
-
esp_hidh_status_t status
-
struct hidh_data_ind_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_DATA_IND_EVT.
Public Members
-
esp_hidh_status_t status
operation status
-
uint8_t handle
device handle
-
esp_hidh_protocol_mode_t proto_mode
protocol mode
-
uint16_t len
data length
-
uint8_t *data
data pointer
-
esp_hidh_status_t status
-
struct hidh_get_dscp_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_GET_DSCP_EVT.
Public Members
-
esp_hidh_status_t status
operation status
-
uint8_t handle
device handle
-
bool added
Indicate if added
-
uint16_t vendor_id
Vendor ID
-
uint16_t product_id
Product ID
-
uint16_t version
Version
-
uint16_t ssr_max_latency
SSR max latency in slots
-
uint16_t ssr_min_tout
SSR min timeout in slots
-
uint8_t ctry_code
Country Code
-
uint16_t dl_len
Device descriptor length
-
uint8_t *dsc_list
Device descriptor pointer
-
esp_hidh_status_t status
-
struct hidh_get_idle_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_GET_IDLE_EVT.
Public Members
-
esp_hidh_status_t status
operation status
-
uint8_t handle
device handle
-
uint8_t idle_rate
idle rate
-
esp_hidh_status_t status
-
struct hidh_get_proto_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_GET_PROTO_EVT.
Public Members
-
esp_hidh_status_t status
operation status
-
uint8_t handle
device handle
-
esp_hidh_protocol_mode_t proto_mode
protocol mode
-
esp_hidh_status_t status
-
struct hidh_get_rpt_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_GET_RPT_EVT.
Public Members
-
esp_hidh_status_t status
operation status
-
uint8_t handle
device handle
-
uint16_t len
data length
-
uint8_t *data
data pointer
-
esp_hidh_status_t status
-
struct hidh_init_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_INIT_EVT.
Public Members
-
esp_hidh_status_t status
status
-
esp_hidh_status_t status
-
struct hidh_open_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_OPEN_EVT.
Public Members
-
esp_hidh_status_t status
operation status
-
esp_hidh_connection_state_t conn_status
connection status
-
bool is_orig
indicate if host intiate the connection
-
uint8_t handle
device handle
-
esp_bd_addr_t bd_addr
device address
-
esp_hidh_status_t status
-
struct hidh_rmv_dev_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_RMV_DEV_EVT.
Public Members
-
esp_hidh_status_t status
operation status
-
uint8_t handle
device handle
-
esp_bd_addr_t bd_addr
device address
-
esp_hidh_status_t status
-
struct hidh_send_data_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_DATA_EVT.
Public Members
-
esp_hidh_status_t status
operation status
-
uint8_t handle
device handle
-
uint8_t reason
lower layer failed reason(ref hiddefs.h)
-
esp_hidh_status_t status
-
struct hidh_set_idle_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_SET_IDLE_EVT.
-
struct hidh_set_info_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_SET_INFO_EVT.
Public Members
-
esp_hidh_status_t status
operation status
-
uint8_t handle
device handle
-
esp_bd_addr_t bd_addr
device address
-
esp_hidh_status_t status
-
struct hidh_set_proto_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_SET_PROTO_EVT.
-
struct hidh_set_rpt_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_SET_RPT_EVT.
-
struct hidh_uninit_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_DEINIT_EVT.
Public Members
-
esp_hidh_status_t status
status
-
esp_hidh_status_t status
-
struct hidh_unplug_evt_param
- #include <esp_hidh_api.h>
ESP_HIDH_VC_UNPLUG_EVT.
Public Members
-
esp_hidh_status_t status
operation status
-
esp_hidh_connection_state_t conn_status
connection status
-
uint8_t handle
device handle
-
esp_hidh_status_t status
-
struct esp_hidh_cb_param_t::hidh_init_evt_param init
Structures
-
struct esp_hidh_hid_info_t
HID device information from HID Device Service Record and Device ID Service Record.
Public Members
-
int attr_mask
device attribute bit mask, refer to esp_hidh_dev_attr_t
-
uint8_t sub_class
HID device subclass
-
uint8_t app_id
application ID, refer to esp_hidh_dev_app_id_t
-
int vendor_id
Device ID information: vendor ID
-
int product_id
Device ID information: product ID
-
int version
Device ID information: version
-
uint8_t ctry_code
SDP attrbutes of HID devices: HID country code (https://www.usb.org/sites/default/files/hid1_11.pdf)
-
int dl_len
SDP attrbutes of HID devices: HID device descriptor length
-
uint8_t dsc_list[BTHH_MAX_DSC_LEN]
SDP attrbutes of HID devices: HID device descriptor definition
-
int attr_mask
Macros
-
BTHH_MAX_DSC_LEN
maximum size of HID Device report descriptor
Type Definitions
-
typedef void (*esp_hh_cb_t)(esp_hidh_cb_event_t event, esp_hidh_cb_param_t *param)
HID host callback function type.
- Param event
Event type
- Param param
Point to callback parameter, currently is union type
Enumerations
-
enum esp_hidh_connection_state_t
HID host connection state.
Values:
-
enumerator ESP_HIDH_CONN_STATE_CONNECTED
connected state
-
enumerator ESP_HIDH_CONN_STATE_CONNECTING
connecting state
-
enumerator ESP_HIDH_CONN_STATE_DISCONNECTED
disconnected state
-
enumerator ESP_HIDH_CONN_STATE_DISCONNECTING
disconnecting state
-
enumerator ESP_HIDH_CONN_STATE_UNKNOWN
unknown state (initial state)
-
enumerator ESP_HIDH_CONN_STATE_CONNECTED
-
enum esp_hidh_status_t
HID handshake error code and vendor-defined result code.
Values:
-
enumerator ESP_HIDH_OK
successful
-
enumerator ESP_HIDH_HS_HID_NOT_READY
handshake error: device not ready
-
enumerator ESP_HIDH_HS_INVALID_RPT_ID
handshake error: invalid report ID
-
enumerator ESP_HIDH_HS_TRANS_NOT_SPT
handshake error: HID device does not support the request
-
enumerator ESP_HIDH_HS_INVALID_PARAM
handshake error: parameter value does not meet the expected criteria of called function or API
-
enumerator ESP_HIDH_HS_ERROR
handshake error: HID device could not identify the error condition
-
enumerator ESP_HIDH_ERR
general ESP HID Host error
-
enumerator ESP_HIDH_ERR_SDP
SDP error
-
enumerator ESP_HIDH_ERR_PROTO
SET_PROTOCOL error, only used in ESP_HIDH_OPEN_EVT callback
-
enumerator ESP_HIDH_ERR_DB_FULL
device database full, used in ESP_HIDH_OPEN_EVT/ESP_HIDH_ADD_DEV_EVT
-
enumerator ESP_HIDH_ERR_TOD_UNSPT
type of device not supported
-
enumerator ESP_HIDH_ERR_NO_RES
out of system resources
-
enumerator ESP_HIDH_ERR_AUTH_FAILED
authentication fail
-
enumerator ESP_HIDH_ERR_HDL
connection handle error
-
enumerator ESP_HIDH_ERR_SEC
encryption error
-
enumerator ESP_HIDH_BUSY
vendor-defined: temporarily can not handle this request
-
enumerator ESP_HIDH_NO_DATA
vendor-defined: no data.
-
enumerator ESP_HIDH_NEED_INIT
vendor-defined: HIDH module shall initialize first
-
enumerator ESP_HIDH_NEED_DEINIT
vendor-defined: HIDH module shall de-deinitialize first
-
enumerator ESP_HIDH_NO_CONNECTION
vendor-defined: connection may have been closed
-
enumerator ESP_HIDH_OK
-
enum esp_hidh_protocol_mode_t
HID host protocol modes.
Values:
-
enumerator ESP_HIDH_BOOT_MODE
boot protocol mode
-
enumerator ESP_HIDH_REPORT_MODE
report protocol mode
-
enumerator ESP_HIDH_UNSUPPORTED_MODE
unsupported protocol mode
-
enumerator ESP_HIDH_BOOT_MODE
-
enum esp_hidh_report_type_t
HID host report types.
Values:
-
enumerator ESP_HIDH_REPORT_TYPE_OTHER
unsupported report type
-
enumerator ESP_HIDH_REPORT_TYPE_INPUT
input report type
-
enumerator ESP_HIDH_REPORT_TYPE_OUTPUT
output report type
-
enumerator ESP_HIDH_REPORT_TYPE_FEATURE
feature report type
-
enumerator ESP_HIDH_REPORT_TYPE_OTHER
-
enum esp_hidh_cb_event_t
HID host callback function events.
Values:
-
enumerator ESP_HIDH_INIT_EVT
when HID host is initialized, the event comes
-
enumerator ESP_HIDH_DEINIT_EVT
when HID host is deinitialized, the event comes
-
enumerator ESP_HIDH_OPEN_EVT
when HID host connection opened, the event comes
-
enumerator ESP_HIDH_CLOSE_EVT
when HID host connection closed, the event comes
-
enumerator ESP_HIDH_GET_RPT_EVT
when Get_Report command is called, the event comes
-
enumerator ESP_HIDH_SET_RPT_EVT
when Set_Report command is called, the event comes
-
enumerator ESP_HIDH_GET_PROTO_EVT
when Get_Protocol command is called, the event comes
-
enumerator ESP_HIDH_SET_PROTO_EVT
when Set_Protocol command is called, the event comes
-
enumerator ESP_HIDH_GET_IDLE_EVT
when Get_Idle command is called, the event comes
-
enumerator ESP_HIDH_SET_IDLE_EVT
when Set_Idle command is called, the event comes
-
enumerator ESP_HIDH_GET_DSCP_EVT
when HIDH is initialized, the event comes
-
enumerator ESP_HIDH_ADD_DEV_EVT
when a device is added, the event comes
-
enumerator ESP_HIDH_RMV_DEV_EVT
when a device is removed, the event comes
-
enumerator ESP_HIDH_VC_UNPLUG_EVT
when virtually unplugged, the event comes
-
enumerator ESP_HIDH_DATA_EVT
when send data on interrupt channel, the event comes
-
enumerator ESP_HIDH_DATA_IND_EVT
when receive data on interrupt channel, the event comes
-
enumerator ESP_HIDH_SET_INFO_EVT
when set the HID device descriptor, the event comes
-
enumerator ESP_HIDH_INIT_EVT
-
enum esp_hidh_dev_attr_t
HID device information from HID Device Service Record and Device ID Service Record.
Values:
-
enumerator ESP_HIDH_DEV_ATTR_VIRTUAL_CABLE
whether Virtual Cables is supported
-
enumerator ESP_HIDH_DEV_ATTR_NORMALLY_CONNECTABLE
whether device is in Page Scan mode when there is no active connection
-
enumerator ESP_HIDH_DEV_ATTR_RECONNECT_INITIATE
whether the HID device inititates the reconnection process
-
enumerator ESP_HIDH_DEV_ATTR_VIRTUAL_CABLE
-
enum esp_hidh_dev_app_id_t
application ID(non-zero) for each type of device
Values:
-
enumerator ESP_HIDH_APP_ID_MOUSE
pointing device
-
enumerator ESP_HIDH_APP_ID_KEYBOARD
keyboard
-
enumerator ESP_HIDH_APP_ID_REMOTE_CONTROL
remote control
-
enumerator ESP_HIDH_APP_ID_JOYSTICK
joystick
-
enumerator ESP_HIDH_APP_ID_GAMEPAD
gamepad
-
enumerator ESP_HIDH_APP_ID_MOUSE