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