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

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

Provide feedback about this document