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
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 onbt
, 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()/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()/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()/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()/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()/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.
- 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()/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()/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()/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()/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
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
-
esp_hidd_status_t status
-
struct hidd_deinit_evt_param
- #include <esp_hidd_api.h>
ESP_HIDD_DEINIT_EVT.
Public Members
-
esp_hidd_status_t status
operation status
-
esp_hidd_status_t 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
-
esp_hidd_report_type_t report_type
-
struct hidd_init_evt_param
- #include <esp_hidd_api.h>
ESP_HIDD_INIT_EVT.
Public Members
-
esp_hidd_status_t status
operation status
-
esp_hidd_status_t status
-
struct hidd_intr_data_evt_param
- #include <esp_hidd_api.h>
ESP_HIDD_INTR_DATA_EVT.
-
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
-
esp_hidd_status_t status
-
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
-
esp_hidd_status_t status
-
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)
-
esp_hidd_status_t status
-
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
-
esp_hidd_status_t status
-
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
-
esp_hidd_protocol_mode_t 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
-
esp_hidd_report_type_t report_type
-
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
-
esp_hidd_status_t 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
-
esp_hidd_status_t status
-
struct esp_hidd_cb_param_t::hidd_init_evt_param init
Structures
-
struct esp_hidd_app_param_t
HID device characteristics for SDP server.
-
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
-
uint8_t service_type
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
-
enumerator ESP_HID_PAR_HANDSHAKE_RSP_SUCCESS
-
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
-
enumerator ESP_HIDD_REPORT_TYPE_OTHER
-
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
-
enumerator ESP_HIDD_CONN_STATE_CONNECTED
-
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
-
enumerator ESP_HIDD_REPORT_MODE
-
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
-
enumerator ESP_HIDD_BOOT_REPORT_ID_KEYBOARD
-
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
-
enumerator ESP_HIDD_BOOT_REPORT_SIZE_KEYBOARD
-
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
-
enumerator ESP_HIDD_INIT_EVT
-
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
-
enumerator ESP_HIDD_SUCCESS