From 028f7779f574ee1c3980a72a4bd2511628358342 Mon Sep 17 00:00:00 2001 From: gongyantao Date: Fri, 16 Jun 2023 15:20:25 +0800 Subject: [PATCH 1/2] resolve the conflicts --- .../bluedroid/api/include/api/esp_hidh_api.h | 85 +++++++++++++------ 1 file changed, 58 insertions(+), 27 deletions(-) diff --git a/components/bt/host/bluedroid/api/include/api/esp_hidh_api.h b/components/bt/host/bluedroid/api/include/api/esp_hidh_api.h index c0e3a6441e1..3c286b44815 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_hidh_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_hidh_api.h @@ -16,6 +16,7 @@ extern "C" { #endif +/// maximum size of HID Device report descriptor #define BTHH_MAX_DSC_LEN 884 /** @@ -29,31 +30,30 @@ typedef enum { 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 is out of range or inappropriate */ + 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; /** @@ -98,16 +98,47 @@ typedef enum { 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_SDP_DISABLE = 0x0008, /*!< whether connections to the SDP channel and control or interrupt + channel are mutually exclusive */ + ESP_HIDH_DEV_ATTR_BATTERY_POWER = 0x0010, /*!< whether HID device is battery-powered */ + ESP_HIDH_DEV_ATTR_REMOTE_AWAKE = 0x0020, /*!< whether the HID device is designed to be capable to provide wake-up + signal to host */ + ESP_HIDH_DEV_ATTR_SUPERVISION_TIMEOUT = 0x0040, /*!< recommended supvervision timeout value in slots */ + ESP_HIDH_DEV_ATTR_SSR_MAX_LATENCY = 0x0080, /*!< maximum latency for Sniff Subrate request */ + ESP_HIDH_DEV_ATTR_SSR_MIN_TIMEOUT = 0x0100, /*!< minimum timeout for Sniff Subrate request */ +} 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 */ + int dl_len; /*!< SDP attrbutes of HID devices: size of device report descriptor size */ + uint8_t dsc_list[BTHH_MAX_DSC_LEN]; /*!< SDP attrbutes of HID devices: device report descriptor */ } esp_hidh_hid_info_t; /** From d4ac2380e72025855fb9d320fe72243d0205197a Mon Sep 17 00:00:00 2001 From: wangmengyang Date: Fri, 25 Mar 2022 18:20:37 +0800 Subject: [PATCH 2/2] component/docs: enable generation of API-reference documents for Bluetooth HID host --- .../bluedroid/api/include/api/esp_hidh_api.h | 62 ++++++++----------- docs/conf_common.py | 1 + docs/doxygen/Doxyfile | 1 + .../en/api-reference/bluetooth/classic_bt.rst | 1 + docs/en/api-reference/bluetooth/esp_hidh.rst | 20 ++++++ .../api-reference/bluetooth/esp_hidh.rst | 1 + 6 files changed, 51 insertions(+), 35 deletions(-) create mode 100644 docs/en/api-reference/bluetooth/esp_hidh.rst create mode 100644 docs/zh_CN/api-reference/bluetooth/esp_hidh.rst diff --git a/components/bt/host/bluedroid/api/include/api/esp_hidh_api.h b/components/bt/host/bluedroid/api/include/api/esp_hidh_api.h index 3c286b44815..5d3924d8bae 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_hidh_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_hidh_api.h @@ -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 * @@ -27,7 +27,7 @@ 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; /** @@ -38,7 +38,7 @@ typedef enum { 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 is out of range or inappropriate */ + 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 */ @@ -79,23 +79,23 @@ 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; /** @@ -105,14 +105,6 @@ 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_SDP_DISABLE = 0x0008, /*!< whether connections to the SDP channel and control or interrupt - channel are mutually exclusive */ - ESP_HIDH_DEV_ATTR_BATTERY_POWER = 0x0010, /*!< whether HID device is battery-powered */ - ESP_HIDH_DEV_ATTR_REMOTE_AWAKE = 0x0020, /*!< whether the HID device is designed to be capable to provide wake-up - signal to host */ - ESP_HIDH_DEV_ATTR_SUPERVISION_TIMEOUT = 0x0040, /*!< recommended supvervision timeout value in slots */ - ESP_HIDH_DEV_ATTR_SSR_MAX_LATENCY = 0x0080, /*!< maximum latency for Sniff Subrate request */ - ESP_HIDH_DEV_ATTR_SSR_MIN_TIMEOUT = 0x0100, /*!< minimum timeout for Sniff Subrate request */ } esp_hidh_dev_attr_t; /** @@ -136,9 +128,9 @@ typedef struct { 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 */ - int dl_len; /*!< SDP attrbutes of HID devices: size of device report descriptor size */ - uint8_t dsc_list[BTHH_MAX_DSC_LEN]; /*!< SDP attrbutes of HID devices: device report descriptor */ + 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; /** @@ -289,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 */ @@ -346,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. @@ -357,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. diff --git a/docs/conf_common.py b/docs/conf_common.py index d053ea7341b..90457186848 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -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', diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index e76ff563b01..ea185191374 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -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 \ diff --git a/docs/en/api-reference/bluetooth/classic_bt.rst b/docs/en/api-reference/bluetooth/classic_bt.rst index 0fbc223ab54..4c84752c55c 100644 --- a/docs/en/api-reference/bluetooth/classic_bt.rst +++ b/docs/en/api-reference/bluetooth/classic_bt.rst @@ -12,5 +12,6 @@ CLASSIC BT BT HFP Client BT HFP AG BT HID DEVICE + BT HID HOST BT L2CAP BT SDP diff --git a/docs/en/api-reference/bluetooth/esp_hidh.rst b/docs/en/api-reference/bluetooth/esp_hidh.rst new file mode 100644 index 00000000000..940f8e30809 --- /dev/null +++ b/docs/en/api-reference/bluetooth/esp_hidh.rst @@ -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 diff --git a/docs/zh_CN/api-reference/bluetooth/esp_hidh.rst b/docs/zh_CN/api-reference/bluetooth/esp_hidh.rst new file mode 100644 index 00000000000..5bb6870068b --- /dev/null +++ b/docs/zh_CN/api-reference/bluetooth/esp_hidh.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/bluetooth/esp_hidh.rst