# 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

- 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

esp_err_t esp_bt_hid_host_get_profile_status(esp_hidh_profile_status_t *profile_status)

  This function is used to get the status of hid host.

  Parameters:

    profile_status -- [out] - HID host status

  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 initiate 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 attributes of HID devices: HID country code (https://www.usb.org/sites/default/files/hid1_11.pdf)

  int dl_len

    SDP attributes of HID devices: HID device descriptor length

  uint8_t dsc_list[BTHH_MAX_DSC_LEN]

    SDP attributes of HID devices: HID device descriptor definition

struct esp_hidh_profile_status_t

  HID host profile status parameters.

  Public Members

  bool hidh_inited

    HID host initialization

  uint8_t conn_num

    Number of connections

  uint8_t plug_vc_dev_num

    Number of plugged virtual cable devices

### 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 initiates 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

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.