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 Example

Check bluetooth folder in ESP-IDF examples, which contains the following application:

Example bluetooth/esp_hid_host is implemented using the generic esp_hid APIs. esp_hid APIs are build upon the Bluetooth HID APIs and can be a reference.

API Reference

Header File

components/bt/host/bluedroid/api/include/api/esp_hidh_api.h
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 on bt, 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

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

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

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

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

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

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

struct hidh_init_evt_param

#include <esp_hidh_api.h>

ESP_HIDH_INIT_EVT.

Public Members

esp_hidh_status_t status: 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

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

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)

struct hidh_set_idle_evt_param

#include <esp_hidh_api.h>

ESP_HIDH_SET_IDLE_EVT.

Public Members

esp_hidh_status_t status: operation status

uint8_t handle: device handle

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

struct hidh_set_proto_evt_param

#include <esp_hidh_api.h>

ESP_HIDH_SET_PROTO_EVT.

Public Members

esp_hidh_status_t status: operation status

uint8_t handle: device handle

struct hidh_set_rpt_evt_param

#include <esp_hidh_api.h>

ESP_HIDH_SET_RPT_EVT.

Public Members

esp_hidh_status_t status: operation status

uint8_t handle: device handle

struct hidh_uninit_evt_param

#include <esp_hidh_api.h>

ESP_HIDH_DEINIT_EVT.

Public Members

esp_hidh_status_t status: 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

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

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)

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

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

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

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

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

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

Provide feedback about this document