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)

Initializes HIDD interface. This function should be called after esp_bluedroid_init() 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() 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() 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() 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() 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.

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() 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() 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() 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() 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

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

Provide feedback about this document