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 Example

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

  • This is an example of Bluetooth HID mouse device. The device running this example can be discovered and connected by a Bluetooth HID Host device such as a PC, and the pointer will move left and right after HID connection is established - bluetooth/bluedroid/classic_bt/bt_hid_mouse_device

API Reference

Header File

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)

This function initializes HIDD. This function should be called after esp_bluedroid_enable and esp_bluedroid_init 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)

This function de-initializes HIDD interface. This function should be called after esp_bluedroid_enable() and esp_bluedroid_init() 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_enable and esp_bluedroid_init success, and must be done 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_enable and esp_bluedroid_init 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)

This function connects HIDD interface to connected bluetooth device, if not done already. When the operation is complete the callback function will be called with ESP_HIDD_OPEN_EVT.

Parameters

bd_addr[in] Remote host bluetooth device address.

Returns

  • ESP_OK: success

  • other: failed

esp_err_t esp_bt_hid_device_disconnect(void)

This function disconnects HIDD interface. When the operation is complete the callback function will be called with ESP_HIDD_CLOSE_EVT.

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)

Send HIDD report. 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 HIDD handshake with error info for invalid set_report. 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)

Unplug virtual cable of HIDD. When the operation is complete the callback function will be called with ESP_HIDD_VC_UNPLUG_EVT.

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

Macros

ESP_HID_CLASS_UNKNOWN

subclass of hid device

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

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

Event type

Param param

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

connection to remote Bluetooth device

enumerator ESP_HIDD_CONN_STATE_DISCONNECTED

connection released

enumerator ESP_HIDD_CONN_STATE_DISCONNECTING

disconnecting to 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 [anonymous]

HID Boot Protocol report size including report ID.

Values:

enumerator ESP_HIDD_BOOT_REPORT_SIZE_KEYBOARD

report size of Boot Protocol keyboard report

enumerator ESP_HIDD_BOOT_REPORT_SIZE_MOUSE

report size of Boot Protocol mouse report

enum esp_hidd_cb_event_t

HID device callback function events.

Values:

enumerator ESP_HIDD_INIT_EVT

When HID device is initialized, the event comes

enumerator ESP_HIDD_DEINIT_EVT

When HID device is deinitialized, the event comes

enumerator ESP_HIDD_REGISTER_APP_EVT

When HID device application registered, the event comes

enumerator ESP_HIDD_UNREGISTER_APP_EVT

When HID device application unregistered, the event comes

enumerator ESP_HIDD_OPEN_EVT

When HID device connection to host opened, the event comes

enumerator ESP_HIDD_CLOSE_EVT

When HID device connection to host closed, the event comes

enumerator ESP_HIDD_SEND_REPORT_EVT

When HID device send report to lower layer, the event comes

enumerator ESP_HIDD_REPORT_ERR_EVT

When HID device report handshanke error to lower layer, the event comes

enumerator ESP_HIDD_GET_REPORT_EVT

When HID device receives GET_REPORT request from host, the event comes

enumerator ESP_HIDD_SET_REPORT_EVT

When HID device receives SET_REPORT request from host, the event comes

enumerator ESP_HIDD_SET_PROTOCOL_EVT

When HID device receives SET_PROTOCOL request from host, the event comes

enumerator ESP_HIDD_INTR_DATA_EVT

When HID device receives DATA from host on intr, the event comes

enumerator ESP_HIDD_VC_UNPLUG_EVT

When HID device initiates Virtual Cable Unplug, the event comes

enumerator ESP_HIDD_API_ERR_EVT

When HID device has API error, the event comes

enum esp_hidd_status_t

Values:

enumerator ESP_HIDD_SUCCESS
enumerator ESP_HIDD_ERROR

general ESP HD 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 shall init first

enumerator ESP_HIDD_NEED_DEINIT

HIDD module shall deinit first

enumerator ESP_HIDD_NEED_REG

HIDD module shall register first

enumerator ESP_HIDD_NEED_DEREG

HIDD module shall deregister first

enumerator ESP_HIDD_NO_CONNECTION

connection may have been closed