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

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

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.

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

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

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