# Bluetooth® HID Device API

## Overview

A Bluetooth HID device is a device providing the service of human or other data input and output to and from a Bluetooth HID Host. Users can use the Bluetooth HID Device APIs to make devices like keyboards, mice, joysticks and so on.

## Application Examples

- bluetooth/bluedroid/classic_bt/bt_hid_mouse_device demonstrates how to implement a Bluetooth HID device by simulating a Bluetooth HID mouse device that periodically sends reports to a remote Bluetooth HID host.

- bluetooth/esp_hid_device demonstrates how to create a Bluetooth Classic or Bluetooth LE HID device, which can function as a mouse or a remote control, depending on the mode set by the user.

## API Reference

### Header File

- components/bt/host/bluedroid/api/include/api/esp_hidd_api.h

- This header file can be included with:

  >     #include "esp_hidd_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_device_register_callback(esp_hd_cb_t callback)

  This function is called to init callbacks with HID device module.

  Parameters:

    callback -- [in] pointer to the init callback function.

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_bt_hid_device_init(void)

  Initializes HIDD interface. This function should be called after esp_bluedroid_init_with_cfg() and esp_bluedroid_enable() success, and should be called after esp_bt_hid_device_register_callback. When the operation is complete, the callback function will be called with ESP_HIDD_INIT_EVT.

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_bt_hid_device_deinit(void)

  De-initializes HIDD interface. This function should be called after esp_bluedroid_init_with_cfg() and esp_bluedroid_enable() success, and should be called after esp_bt_hid_device_init(). When the operation is complete, the callback function will be called with ESP_HIDD_DEINIT_EVT.

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_bt_hid_device_register_app(esp_hidd_app_param_t *app_param, esp_hidd_qos_param_t *in_qos, esp_hidd_qos_param_t *out_qos)

  Registers HIDD parameters with SDP and sets l2cap Quality of Service. This function should be called after esp_bluedroid_init_with_cfg() and esp_bluedroid_enable() success, and should be called after esp_bt_hid_device_init(). When the operation is complete, the callback function will be called with ESP_HIDD_REGISTER_APP_EVT.

  Parameters:

    - app_param -- [in] HIDD parameters

    - in_qos -- [in] incoming QoS parameters

    - out_qos -- [in] outgoing QoS parameters

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_bt_hid_device_unregister_app(void)

  Removes HIDD parameters from SDP and resets l2cap Quality of Service. This function should be called after esp_bluedroid_init_with_cfg() and esp_bluedroid_enable() success, and should be called after esp_bt_hid_device_init(). When the operation is complete, the callback function will be called with ESP_HIDD_UNREGISTER_APP_EVT.

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_bt_hid_device_connect(esp_bd_addr_t bd_addr)

  Connects to the peer HID Host with virtual cable. This function should be called after esp_bluedroid_init_with_cfg() and esp_bluedroid_enable() success, and should be called after esp_bt_hid_device_init(). When the operation is complete, the callback function will be called with ESP_HIDD_OPEN_EVT.

  Note

  The connection between the HID Host and the HID Device is established as a virtual cable by default. A new HID Host connection request will only be accepted after the previous HID Host has been explicitly unplugged. For details on disconnection and virtual cable unplugging, please refer to API `esp_bt_hid_device_disconnect` and `esp_bt_hid_device_virtual_cable_unplug`.

  Parameters:

    bd_addr -- [in] Remote host bluetooth device address.

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_bt_hid_device_disconnect(void)

  Disconnects from the currently connected HID Host. This function should be called after esp_bluedroid_init_with_cfg() and esp_bluedroid_enable() success, and should be called after esp_bt_hid_device_init(). When the operation is complete, the callback function will be called with ESP_HIDD_CLOSE_EVT.

  Note

  The disconnect operation will not remove the virtually cabled device. If the connect request from the different HID Host, it will reject the request.

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_bt_hid_device_send_report(esp_hidd_report_type_t type, uint8_t id, uint16_t len, uint8_t *data)

  Sends HID report to the currently connected HID Host. This function should be called after esp_bluedroid_init_with_cfg() and esp_bluedroid_enable() success, and should be called after esp_bt_hid_device_init(). When the operation is complete, the callback function will be called with ESP_HIDD_SEND_REPORT_EVT.

  Parameters:

    - type -- [in] type of report

    - id -- [in] report id as defined by descriptor

    - len -- [in] length of report

    - data -- [in] report data

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_bt_hid_device_report_error(esp_hidd_handshake_error_t error)

  Sends HID Handshake with error info for invalid set_report to the currently connected HID Host. This function should be called after esp_bluedroid_init_with_cfg() and esp_bluedroid_enable() success, and should be called after esp_bt_hid_device_init(). When the operation is complete, the callback function will be called with ESP_HIDD_REPORT_ERR_EVT.

  Parameters:

    error -- [in] type of error

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_bt_hid_device_virtual_cable_unplug(void)

  Remove the virtually cabled device. This function should be called after esp_bluedroid_init_with_cfg() and esp_bluedroid_enable() success, and should be called after esp_bt_hid_device_init(). When the operation is complete, the callback function will be called with ESP_HIDD_VC_UNPLUG_EVT.

  Note

  If the connection exists, then HID Device will send a `VIRTUAL_CABLE_UNPLUG` control command to the peer HID Host, and the connection will be destroyed. If the connection does not exist, then HID Device will only unplug on it's single side. Once the unplug operation is success, the related pairing and bonding information will be removed, then the HID Device can accept connection request from the different HID Host,

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_bt_hid_device_get_profile_status(esp_hidd_profile_status_t *profile_status)

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

  Parameters:

    profile_status -- [out] - HID device status

  Returns:

    - ESP_OK: success

    - other: failed

### Unions

union esp_hidd_cb_param_t
  #include <esp_hidd_api.h>

  HID device callback parameters union.

  Public Members

  struct esp_hidd_cb_param_t::hidd_init_evt_param init

    HIDD callback param of ESP_HIDD_INIT_EVT

  struct esp_hidd_cb_param_t::hidd_deinit_evt_param deinit

    HIDD callback param of ESP_HIDD_DEINIT_EVT

  struct esp_hidd_cb_param_t::hidd_register_app_evt_param register_app

    HIDD callback param of ESP_HIDD_REGISTER_APP_EVT

  struct esp_hidd_cb_param_t::hidd_unregister_app_evt_param unregister_app

    HIDD callback param of ESP_HIDD_UNREGISTER_APP_EVT

  struct esp_hidd_cb_param_t::hidd_open_evt_param open

    HIDD callback param of ESP_HIDD_OPEN_EVT

  struct esp_hidd_cb_param_t::hidd_close_evt_param close

    HIDD callback param of ESP_HIDD_CLOSE_EVT

  struct esp_hidd_cb_param_t::hidd_send_report_evt_param send_report

    HIDD callback param of ESP_HIDD_SEND_REPORT_EVT

  struct esp_hidd_cb_param_t::hidd_report_err_evt_param report_err

    HIDD callback param of ESP_HIDD_REPORT_ERR_EVT

  struct esp_hidd_cb_param_t::hidd_get_report_evt_param get_report

    HIDD callback param of ESP_HIDD_GET_REPORT_EVT

  struct esp_hidd_cb_param_t::hidd_set_report_evt_param set_report

    HIDD callback param of ESP_HIDD_SET_REPORT_EVT

  struct esp_hidd_cb_param_t::hidd_set_protocol_evt_param set_protocol

    HIDD callback param of ESP_HIDD_SET_PROTOCOL_EVT

  struct esp_hidd_cb_param_t::hidd_intr_data_evt_param intr_data

    HIDD callback param of ESP_HIDD_INTR_DATA_EVT

  struct esp_hidd_cb_param_t::hidd_vc_unplug_param vc_unplug

    HIDD callback param of ESP_HIDD_VC_UNPLUG_EVT

  struct hidd_close_evt_param
    #include <esp_hidd_api.h>

    ESP_HIDD_CLOSE_EVT.

    Public Members

    esp_hidd_status_t status

      operation status

    esp_hidd_connection_state_t conn_status

      connection status

  struct hidd_deinit_evt_param
    #include <esp_hidd_api.h>

    ESP_HIDD_DEINIT_EVT.

    Public Members

    esp_hidd_status_t status

      operation status

  struct hidd_get_report_evt_param
    #include <esp_hidd_api.h>

    ESP_HIDD_GET_REPORT_EVT.

    Public Members

    esp_hidd_report_type_t report_type

      report type

    uint8_t report_id

      report id

    uint16_t buffer_size

      buffer size

  struct hidd_init_evt_param
    #include <esp_hidd_api.h>

    ESP_HIDD_INIT_EVT.

    Public Members

    esp_hidd_status_t status

      operation status

  struct hidd_intr_data_evt_param
    #include <esp_hidd_api.h>

    ESP_HIDD_INTR_DATA_EVT.

    Public Members

    uint8_t report_id

      interrupt channel report id

    uint16_t len

      interrupt channel report data length

    uint8_t *data

      interrupt channel report data pointer

  struct hidd_open_evt_param
    #include <esp_hidd_api.h>

    ESP_HIDD_OPEN_EVT.

    Public Members

    esp_hidd_status_t status

      operation status

    esp_hidd_connection_state_t conn_status

      connection status

    esp_bd_addr_t bd_addr

      host address

  struct hidd_register_app_evt_param
    #include <esp_hidd_api.h>

    ESP_HIDD_REGISTER_APP_EVT.

    Public Members

    esp_hidd_status_t status

      operation status

    bool in_use

      indicate whether use virtual cable plug host address

    esp_bd_addr_t bd_addr

      host address

  struct hidd_report_err_evt_param
    #include <esp_hidd_api.h>

    ESP_HIDD_REPORT_ERR_EVT.

    Public Members

    esp_hidd_status_t status

      operation status

    uint8_t reason

      lower layer failed reason(ref hiddefs.h)

  struct hidd_send_report_evt_param
    #include <esp_hidd_api.h>

    ESP_HIDD_SEND_REPORT_EVT.

    Public Members

    esp_hidd_status_t status

      operation status

    uint8_t reason

      lower layer failed reason(ref hiddefs.h)

    esp_hidd_report_type_t report_type

      report type

    uint8_t report_id

      report id

  struct hidd_set_protocol_evt_param
    #include <esp_hidd_api.h>

    ESP_HIDD_SET_PROTOCOL_EVT.

    Public Members

    esp_hidd_protocol_mode_t protocol_mode

      protocol mode

  struct hidd_set_report_evt_param
    #include <esp_hidd_api.h>

    ESP_HIDD_SET_REPORT_EVT.

    Public Members

    esp_hidd_report_type_t report_type

      report type

    uint8_t report_id

      report id

    uint16_t len

      set_report data length

    uint8_t *data

      set_report data pointer

  struct hidd_unregister_app_evt_param
    #include <esp_hidd_api.h>

    ESP_HIDD_UNREGISTER_APP_EVT.

    Public Members

    esp_hidd_status_t status

      operation status

  struct hidd_vc_unplug_param
    #include <esp_hidd_api.h>

    ESP_HIDD_VC_UNPLUG_EVT.

    Public Members

    esp_hidd_status_t status

      operation status

    esp_hidd_connection_state_t conn_status

      connection status

### Structures

struct esp_hidd_app_param_t

  HID device characteristics for SDP server.

  Public Members

  const char *name

    service name

  const char *description

    service description

  const char *provider

    provider name

  uint8_t subclass

    HID device subclass

  uint8_t *desc_list

    HID descriptor list

  int desc_list_len

    size in bytes of HID descriptor list

struct esp_hidd_qos_param_t

  HIDD Quality of Service parameters negotiated over L2CAP.

  Public Members

  uint8_t service_type

    the level of service, 0 indicates no traffic

  uint32_t token_rate

    token rate in bytes per second, 0 indicates "don't care"

  uint32_t token_bucket_size

    limit on the burstness of the application data

  uint32_t peak_bandwidth

    bytes per second, value 0 indicates "don't care"

  uint32_t access_latency

    maximum acceptable delay in microseconds

  uint32_t delay_variation

    the difference in microseconds between the max and min delay

struct esp_hidd_profile_status_t

  HID device profile status parameters.

  Public Members

  bool hidd_inited

    HID device initialization

  uint8_t conn_num

    Number of connections

  uint8_t plug_vc_dev_num

    Number of plugged virtual cable devices

  uint8_t reg_app_num

    Number of HID device application registrations

### Macros

ESP_HID_CLASS_UNKNOWN

  unknown HID device subclass

ESP_HID_CLASS_JOS

  joystick

ESP_HID_CLASS_GPD

  game pad

ESP_HID_CLASS_RMC

  remote control

ESP_HID_CLASS_SED

  sensing device

ESP_HID_CLASS_DGT

  digitizer tablet

ESP_HID_CLASS_CDR

  card reader

ESP_HID_CLASS_KBD

  keyboard

ESP_HID_CLASS_MIC

  pointing device

ESP_HID_CLASS_COM

  combo keyboard/pointing

ESP_HIDD_APP_DESC_LIST_LEN_MAX

  Maximum length of HID Device descriptor list

### Type Definitions

typedef void (*esp_hd_cb_t)(esp_hidd_cb_event_t event, esp_hidd_cb_param_t *param)

  HID device callback function type.

  Param event:

    [in] Event type

  Param param:

    [in] Point to callback parameter, currently is union type

### Enumerations

enum esp_hidd_handshake_error_t

  HIDD handshake result code.

  Values:

  enumerator ESP_HID_PAR_HANDSHAKE_RSP_SUCCESS

    successful

  enumerator ESP_HID_PAR_HANDSHAKE_RSP_NOT_READY

    not ready, device is too busy to accept data

  enumerator ESP_HID_PAR_HANDSHAKE_RSP_ERR_INVALID_REP_ID

    invalid report ID

  enumerator ESP_HID_PAR_HANDSHAKE_RSP_ERR_UNSUPPORTED_REQ

    device does not support the request

  enumerator ESP_HID_PAR_HANDSHAKE_RSP_ERR_INVALID_PARAM

    parameter value is out of range or inappropriate

  enumerator ESP_HID_PAR_HANDSHAKE_RSP_ERR_UNKNOWN

    device could not identify the error condition

  enumerator ESP_HID_PAR_HANDSHAKE_RSP_ERR_FATAL

    restart is essential to resume functionality

enum esp_hidd_report_type_t

  HIDD report types.

  Values:

  enumerator ESP_HIDD_REPORT_TYPE_OTHER

    unknown report type

  enumerator ESP_HIDD_REPORT_TYPE_INPUT

    input report

  enumerator ESP_HIDD_REPORT_TYPE_OUTPUT

    output report

  enumerator ESP_HIDD_REPORT_TYPE_FEATURE

    feature report

  enumerator ESP_HIDD_REPORT_TYPE_INTRDATA

    special value for reports to be sent on interrupt channel, INPUT is assumed

enum esp_hidd_connection_state_t

  HIDD connection state.

  Values:

  enumerator ESP_HIDD_CONN_STATE_CONNECTED

    HID connection established

  enumerator ESP_HIDD_CONN_STATE_CONNECTING

    connecting to remote Bluetooth device

  enumerator ESP_HIDD_CONN_STATE_DISCONNECTED

    connection released

  enumerator ESP_HIDD_CONN_STATE_DISCONNECTING

    disconnecting from remote Bluetooth device

  enumerator ESP_HIDD_CONN_STATE_UNKNOWN

    unknown connection state

enum esp_hidd_protocol_mode_t

  HID device protocol modes.

  Values:

  enumerator ESP_HIDD_REPORT_MODE

    Report Protocol Mode

  enumerator ESP_HIDD_BOOT_MODE

    Boot Protocol Mode

  enumerator ESP_HIDD_UNSUPPORTED_MODE

    unsupported

enum esp_hidd_boot_report_id_t

  HID Boot Protocol report IDs.

  Values:

  enumerator ESP_HIDD_BOOT_REPORT_ID_KEYBOARD

    report ID of Boot Protocol keyboard report

  enumerator ESP_HIDD_BOOT_REPORT_ID_MOUSE

    report ID of Boot Protocol mouse report

enum esp_hidd_cb_event_t

  HID device callback function events.

  Values:

  enumerator ESP_HIDD_INIT_EVT

    HID device initialized.

  enumerator ESP_HIDD_DEINIT_EVT

    HID device deinitialized.

  enumerator ESP_HIDD_REGISTER_APP_EVT

    HID device application registered.

  enumerator ESP_HIDD_UNREGISTER_APP_EVT

    HID device application unregistered.

  enumerator ESP_HIDD_OPEN_EVT

    HID device connection to host opened.

  enumerator ESP_HIDD_CLOSE_EVT

    HID device connection to host closed.

  enumerator ESP_HIDD_SEND_REPORT_EVT

    HID device sent report to lower layer.

  enumerator ESP_HIDD_REPORT_ERR_EVT

    HID device reported handshake error to lower layer.

  enumerator ESP_HIDD_GET_REPORT_EVT

    HID device received GET_REPORT request from host.

  enumerator ESP_HIDD_SET_REPORT_EVT

    HID device received SET_REPORT request from host.

  enumerator ESP_HIDD_SET_PROTOCOL_EVT

    HID device received SET_PROTOCOL request from host.

  enumerator ESP_HIDD_INTR_DATA_EVT

    HID device received DATA from host on interrupt channel.

  enumerator ESP_HIDD_VC_UNPLUG_EVT

    HID device initiated Virtual Cable Unplug.

  enumerator ESP_HIDD_API_ERR_EVT

    HID device had API error.

enum esp_hidd_status_t

  HID device status.

  Values:

  enumerator ESP_HIDD_SUCCESS

    successful

  enumerator ESP_HIDD_ERROR

    general ESP HID error

  enumerator ESP_HIDD_NO_RES

    out of system resources

  enumerator ESP_HIDD_BUSY

    Temporarily can not handle this request.

  enumerator ESP_HIDD_NO_DATA

    No data.

  enumerator ESP_HIDD_NEED_INIT

    HIDD module must be initialized first.

  enumerator ESP_HIDD_NEED_DEINIT

    HIDD module must be deinitialized first.

  enumerator ESP_HIDD_NEED_REG

    HIDD module must be registered first.

  enumerator ESP_HIDD_NEED_DEREG

    HIDD module must be deregistered first.

  enumerator ESP_HIDD_NO_CONNECTION

    connection may have been closed

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.