Skip to content

Commit

Permalink
Merge branch 'docs/update_esp_hid_host_v5.1' into 'release/v5.1'
Browse files Browse the repository at this point in the history 
[docs] fix documents for Bluetooth HID Host API reference (backport v5.1)

See merge request espressif/esp-idf!24389
  • Loading branch information
@jack0c
jack0c committed Jul 4, 2023
2 parents 56bb50b + 5fa5f7b commit 09f2ab8
Show file tree
Hide file tree
Showing 6 changed files with 97 additions and 50 deletions.
123 changes: 73 additions & 50 deletions components/bt/host/bluedroid/api/include/api/esp_hidh_api.h
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*
Expand All @@ -16,6 +16,7 @@
extern "C" {
#endif

/// maximum size of HID Device report descriptor
#define BTHH_MAX_DSC_LEN 884

/**
Expand All @@ -26,34 +27,33 @@ typedef enum {
ESP_HIDH_CONN_STATE_CONNECTING, /*!< connecting state */
ESP_HIDH_CONN_STATE_DISCONNECTED, /*!< disconnected state */
ESP_HIDH_CONN_STATE_DISCONNECTING, /*!< disconnecting state */
ESP_HIDH_CONN_STATE_UNKNOWN /*!< unknown state(initial state) */
ESP_HIDH_CONN_STATE_UNKNOWN /*!< unknown state (initial state) */
} esp_hidh_connection_state_t;

/**
* @brief HID handshake error code and vendor-defined result code
*/
typedef enum {
ESP_HIDH_OK,
ESP_HIDH_HS_HID_NOT_READY, /*!< handshake error : device not ready */
ESP_HIDH_HS_INVALID_RPT_ID, /*!< handshake error : invalid report ID */
ESP_HIDH_HS_TRANS_NOT_SPT, /*!< handshake error : transaction not spt */
ESP_HIDH_HS_INVALID_PARAM, /*!< handshake error : invalid paremeter */
ESP_HIDH_HS_ERROR, /*!< handshake error : unspecified HS error */
ESP_HIDH_ERR, /*!< general ESP HH error */
ESP_HIDH_OK, /*!< successful */
ESP_HIDH_HS_HID_NOT_READY, /*!< handshake error: device not ready */
ESP_HIDH_HS_INVALID_RPT_ID, /*!< handshake error: invalid report ID */
ESP_HIDH_HS_TRANS_NOT_SPT, /*!< handshake error: HID device does not support the request */
ESP_HIDH_HS_INVALID_PARAM, /*!< handshake error: parameter value does not meet the expected criteria of called function or API */
ESP_HIDH_HS_ERROR, /*!< handshake error: HID device could not identify the error condition */
ESP_HIDH_ERR, /*!< general ESP HID Host error */
ESP_HIDH_ERR_SDP, /*!< SDP error */
ESP_HIDH_ERR_PROTO, /*!< SET_Protocol error,
only used in ESP_HIDH_OPEN_EVT callback */

ESP_HIDH_ERR_DB_FULL, /*!< device database full error, used in
ESP_HIDH_OPEN_EVT/ESP_HIDH_ADD_DEV_EVT */
ESP_HIDH_ERR_PROTO, /*!< SET_PROTOCOL error, only used in ESP_HIDH_OPEN_EVT callback */
ESP_HIDH_ERR_DB_FULL, /*!< device database full, used in ESP_HIDH_OPEN_EVT/ESP_HIDH_ADD_DEV_EVT */
ESP_HIDH_ERR_TOD_UNSPT, /*!< type of device not supported */
ESP_HIDH_ERR_NO_RES, /*!< out of system resources */
ESP_HIDH_ERR_AUTH_FAILED, /*!< authentication fail */
ESP_HIDH_ERR_HDL, /*!< connection handle error */
ESP_HIDH_ERR_SEC, /*!< encryption error */
// self_defined
ESP_HIDH_BUSY, /*!< Temporarily can not handle this request. */
ESP_HIDH_NO_DATA, /*!< No data. */
ESP_HIDH_NEED_INIT, /*!< HIDH module shall init first */
ESP_HIDH_NEED_DEINIT, /*!< HIDH module shall deinit first */
ESP_HIDH_NO_CONNECTION, /*!< connection may have been closed */
ESP_HIDH_BUSY, /*!< vendor-defined: temporarily can not handle this request */
ESP_HIDH_NO_DATA, /*!< vendor-defined: no data. */
ESP_HIDH_NEED_INIT, /*!< vendor-defined: HIDH module shall initialize first */
ESP_HIDH_NEED_DEINIT, /*!< vendor-defined: HIDH module shall de-deinitialize first */
ESP_HIDH_NO_CONNECTION, /*!< vendor-defined: connection may have been closed */
} esp_hidh_status_t;

/**
Expand All @@ -79,35 +79,58 @@ typedef enum {
* @brief HID host callback function events
*/
typedef enum {
ESP_HIDH_INIT_EVT = 0, /*!< When HID host is initialized, the event comes */
ESP_HIDH_DEINIT_EVT, /*!< When HID host is deinitialized, the event comes */
ESP_HIDH_OPEN_EVT, /*!< When HID host connection opened, the event comes */
ESP_HIDH_CLOSE_EVT, /*!< When HID host connection closed, the event comes */
ESP_HIDH_GET_RPT_EVT, /*!< When Get_Report command is called, the event comes */
ESP_HIDH_SET_RPT_EVT, /*!< When Set_Report command is called, the event comes */
ESP_HIDH_GET_PROTO_EVT, /*!< When Get_Protocol command is called, the event comes */
ESP_HIDH_SET_PROTO_EVT, /*!< When Set_Protocol command is called, the event comes */
ESP_HIDH_GET_IDLE_EVT, /*!< When Get_Idle command is called, the event comes */
ESP_HIDH_SET_IDLE_EVT, /*!< When Set_Idle command is called, the event comes */
ESP_HIDH_GET_DSCP_EVT, /*!< When HIDH is initialized, the event comes */
ESP_HIDH_ADD_DEV_EVT, /*!< When a device is added, the event comes */
ESP_HIDH_RMV_DEV_EVT, /*!< When a device is removed, the event comes */
ESP_HIDH_VC_UNPLUG_EVT, /*!< When virtually unplugged, the event comes */
ESP_HIDH_DATA_EVT, /*!< When send data on interrupt channel, the event comes */
ESP_HIDH_DATA_IND_EVT, /*!< When receive data on interrupt channel, the event comes */
ESP_HIDH_SET_INFO_EVT /*!< When set the HID device descriptor, the event comes */
ESP_HIDH_INIT_EVT = 0, /*!< when HID host is initialized, the event comes */
ESP_HIDH_DEINIT_EVT, /*!< when HID host is deinitialized, the event comes */
ESP_HIDH_OPEN_EVT, /*!< when HID host connection opened, the event comes */
ESP_HIDH_CLOSE_EVT, /*!< when HID host connection closed, the event comes */
ESP_HIDH_GET_RPT_EVT, /*!< when Get_Report command is called, the event comes */
ESP_HIDH_SET_RPT_EVT, /*!< when Set_Report command is called, the event comes */
ESP_HIDH_GET_PROTO_EVT, /*!< when Get_Protocol command is called, the event comes */
ESP_HIDH_SET_PROTO_EVT, /*!< when Set_Protocol command is called, the event comes */
ESP_HIDH_GET_IDLE_EVT, /*!< when Get_Idle command is called, the event comes */
ESP_HIDH_SET_IDLE_EVT, /*!< when Set_Idle command is called, the event comes */
ESP_HIDH_GET_DSCP_EVT, /*!< when HIDH is initialized, the event comes */
ESP_HIDH_ADD_DEV_EVT, /*!< when a device is added, the event comes */
ESP_HIDH_RMV_DEV_EVT, /*!< when a device is removed, the event comes */
ESP_HIDH_VC_UNPLUG_EVT, /*!< when virtually unplugged, the event comes */
ESP_HIDH_DATA_EVT, /*!< when send data on interrupt channel, the event comes */
ESP_HIDH_DATA_IND_EVT, /*!< when receive data on interrupt channel, the event comes */
ESP_HIDH_SET_INFO_EVT /*!< when set the HID device descriptor, the event comes */
} esp_hidh_cb_event_t;

/**
* @brief HID device information from HID Device Service Record and Device ID Service Record
*/
typedef enum {
ESP_HIDH_DEV_ATTR_VIRTUAL_CABLE = 0x0001, /*!< whether Virtual Cables is supported */
ESP_HIDH_DEV_ATTR_NORMALLY_CONNECTABLE = 0x0002, /*!< whether device is in Page Scan mode when there is no active connection */
ESP_HIDH_DEV_ATTR_RECONNECT_INITIATE = 0x0004, /*!< whether the HID device inititates the reconnection process */
} esp_hidh_dev_attr_t;

/**
* @brief application ID(non-zero) for each type of device
*/
typedef enum {
ESP_HIDH_APP_ID_MOUSE = 1, /*!< pointing device */
ESP_HIDH_APP_ID_KEYBOARD = 2, /*!< keyboard */
ESP_HIDH_APP_ID_REMOTE_CONTROL = 3, /*!< remote control */
ESP_HIDH_APP_ID_JOYSTICK = 5, /*!< joystick */
ESP_HIDH_APP_ID_GAMEPAD = 6, /*!< gamepad*/
} esp_hidh_dev_app_id_t;

/**
* @brief HID device information from HID Device Service Record and Device ID Service Record
*/
typedef struct {
int attr_mask;
uint8_t sub_class;
uint8_t app_id;
int vendor_id;
int product_id;
int version;
uint8_t ctry_code;
int dl_len;
uint8_t dsc_list[BTHH_MAX_DSC_LEN];
int attr_mask; /*!< device attribute bit mask, refer to esp_hidh_dev_attr_t */
uint8_t sub_class; /*!< HID device subclass */
uint8_t app_id; /*!< application ID, refer to esp_hidh_dev_app_id_t */
int vendor_id; /*!< Device ID information: vendor ID */
int product_id; /*!< Device ID information: product ID */
int version; /*!< Device ID information: version */
uint8_t ctry_code; /*!< SDP attrbutes of HID devices: HID country code (https://www.usb.org/sites/default/files/hid1_11.pdf) */
int dl_len; /*!< SDP attrbutes of HID devices: HID device descriptor length */
uint8_t dsc_list[BTHH_MAX_DSC_LEN]; /*!< SDP attrbutes of HID devices: HID device descriptor definition */
} esp_hidh_hid_info_t;

/**
Expand Down Expand Up @@ -258,8 +281,8 @@ typedef union {
uint16_t vendor_id; /*!< Vendor ID */
uint16_t product_id; /*!< Product ID */
uint16_t version; /*!< Version */
uint16_t ssr_max_latency; /*!< SSR max latency */
uint16_t ssr_min_tout; /*!< SSR min timeout */
uint16_t ssr_max_latency; /*!< SSR max latency in slots */
uint16_t ssr_min_tout; /*!< SSR min timeout in slots */
uint8_t ctry_code; /*!< Country Code */
uint16_t dl_len; /*!< Device descriptor length */
uint8_t *dsc_list; /*!< Device descriptor pointer */
Expand Down Expand Up @@ -315,7 +338,7 @@ esp_err_t esp_bt_hid_host_init(void);
esp_err_t esp_bt_hid_host_deinit(void);

/**
* @brief Connect to hid device. When the operation is complete the callback
* @brief Connect to HID device. When the operation is complete the callback
* function will be called with ESP_HIDH_OPEN_EVT.
*
* @param[in] bd_addr: Remote device bluetooth device address.
Expand All @@ -326,7 +349,7 @@ esp_err_t esp_bt_hid_host_deinit(void);
esp_err_t esp_bt_hid_host_connect(esp_bd_addr_t bd_addr);

/**
* @brief Disconnect from hid device. When the operation is complete the callback
* @brief Disconnect from HID device. When the operation is complete the callback
* function will be called with ESP_HIDH_CLOSE_EVT.
*
* @param[in] bd_addr: Remote device bluetooth device address.
Expand Down
1 change: 1 addition & 0 deletions docs/conf_common.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@
'api-reference/bluetooth/esp_a2dp.rst',
'api-reference/bluetooth/esp_avrc.rst',
'api-reference/bluetooth/esp_hidd.rst',
'api-reference/bluetooth/esp_hidh.rst',
'api-reference/bluetooth/esp_l2cap_bt.rst',
'api-reference/bluetooth/esp_sdp.rst',
'api-reference/bluetooth/esp_hf_defs.rst',
Expand Down
1 change: 1 addition & 0 deletions docs/doxygen/Doxyfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ INPUT = \
$(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h \
$(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_defs.h \
$(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_hidd_api.h \
$(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_hidh_api.h \
$(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_l2cap_bt_api.h \
$(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_sdp_api.h \
$(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_spp_api.h \
Expand Down
1 change: 1 addition & 0 deletions docs/en/api-reference/bluetooth/classic_bt.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,5 +12,6 @@ CLASSIC BT
BT HFP Client <esp_hf_client>
BT HFP AG <esp_hf_ag>
BT HID DEVICE <esp_hidd>
BT HID HOST <esp_hidh>
BT L2CAP <esp_l2cap_bt>
BT SDP <esp_sdp>
20 changes: 20 additions & 0 deletions docs/en/api-reference/bluetooth/esp_hidh.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
Bluetooth HID Host API
========================

Overview
--------

A Bluetooth HID host is a device or software that is capable of connecting and communicating with Bluetooth HID devices, such as keyboards, mice. Users can use the Bluetooth HID Host APIs to send output data or control commands to the HID devices, enabling them to control the behavior or settings of the devices.

Application Example
-------------------

Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following application:

* Example :example:`bluetooth/esp_hid_host` is implemented using the generic esp_hid APIs. esp_hid APIs are build upon the Bluetooth HID APIs and can be a reference.


API Reference
-------------

.. include-build-file:: inc/esp_hidh_api.inc
1 change: 1 addition & 0 deletions docs/zh_CN/api-reference/bluetooth/esp_hidh.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.. include:: ../../../en/api-reference/bluetooth/esp_hidh.rst

0 comments on commit 09f2ab8

Please sign in to comment.