Merge branch 'docs/update_esp_hid_device_v4.4' into 'release/v4.4'

docs: fixed missing API-reference documents for Bluetooth HID device(backport v4.4)

See merge request espressif/esp-idf!19582

components/bt/host/bluedroid/api/include/api/esp_hidd_api.h

@@ -23,86 +23,100 @@
 extern "C" {
 #endif
 
-/* sub_class of hid device */
-#define ESP_HID_CLASS_UNKNOWN      (0x00<<2)
-#define ESP_HID_CLASS_JOS          (0x01<<2)           /* joy stick */
-#define ESP_HID_CLASS_GPD          (0x02<<2)           /* game pad */
-#define ESP_HID_CLASS_RMC          (0x03<<2)           /* remote control */
-#define ESP_HID_CLASS_SED          (0x04<<2)           /* sensing device */
-#define ESP_HID_CLASS_DGT          (0x05<<2)           /* Digitizer tablet */
-#define ESP_HID_CLASS_CDR          (0x06<<2)           /* card reader */
-#define ESP_HID_CLASS_KBD          (0x10<<2)           /* keyboard */
-#define ESP_HID_CLASS_MIC          (0x20<<2)           /* pointing device */
-#define ESP_HID_CLASS_COM          (0x30<<2)           /* Combo keyboard/pointing */
+/// subclass of hid device
+#define ESP_HID_CLASS_UNKNOWN      (0x00<<2)           /*!< unknown HID device subclass */
+#define ESP_HID_CLASS_JOS          (0x01<<2)           /*!< joystick */
+#define ESP_HID_CLASS_GPD          (0x02<<2)           /*!< game pad */
+#define ESP_HID_CLASS_RMC          (0x03<<2)           /*!< remote control */
+#define ESP_HID_CLASS_SED          (0x04<<2)           /*!< sensing device */
+#define ESP_HID_CLASS_DGT          (0x05<<2)           /*!< digitizer tablet */
+#define ESP_HID_CLASS_CDR          (0x06<<2)           /*!< card reader */
+#define ESP_HID_CLASS_KBD          (0x10<<2)           /*!< keyboard */
+#define ESP_HID_CLASS_MIC          (0x20<<2)           /*!< pointing device */
+#define ESP_HID_CLASS_COM          (0x30<<2)           /*!< combo keyboard/pointing */
 
 /**
- * @brief HIDD handshake error
+ * @brief HIDD handshake result code
  */
 typedef enum {
-    ESP_HID_PAR_HANDSHAKE_RSP_SUCCESS = 0,
-    ESP_HID_PAR_HANDSHAKE_RSP_NOT_READY = 1,
-    ESP_HID_PAR_HANDSHAKE_RSP_ERR_INVALID_REP_ID = 2,
-    ESP_HID_PAR_HANDSHAKE_RSP_ERR_UNSUPPORTED_REQ = 3,
-    ESP_HID_PAR_HANDSHAKE_RSP_ERR_INVALID_PARAM = 4,
-    ESP_HID_PAR_HANDSHAKE_RSP_ERR_UNKNOWN = 14,
-    ESP_HID_PAR_HANDSHAKE_RSP_ERR_FATAL = 15
+    ESP_HID_PAR_HANDSHAKE_RSP_SUCCESS = 0,                 /*!< successful */
+    ESP_HID_PAR_HANDSHAKE_RSP_NOT_READY = 1,               /*!< not ready, device is too busy to accept data */
+    ESP_HID_PAR_HANDSHAKE_RSP_ERR_INVALID_REP_ID = 2,      /*!< invalid report ID */
+    ESP_HID_PAR_HANDSHAKE_RSP_ERR_UNSUPPORTED_REQ = 3,     /*!< device does not support the request */
+    ESP_HID_PAR_HANDSHAKE_RSP_ERR_INVALID_PARAM = 4,       /*!< parameter value is out of range or inappropriate */
+    ESP_HID_PAR_HANDSHAKE_RSP_ERR_UNKNOWN = 14,            /*!< device could not identify the error condition */
+    ESP_HID_PAR_HANDSHAKE_RSP_ERR_FATAL = 15,              /*!< restart is essential to resume functionality */
 } esp_hidd_handshake_error_t;
 
 /**
  * @brief HIDD report types
  */
 typedef enum {
-    ESP_HIDD_REPORT_TYPE_OTHER = 0,
-    ESP_HIDD_REPORT_TYPE_INPUT,
-    ESP_HIDD_REPORT_TYPE_OUTPUT,
-    ESP_HIDD_REPORT_TYPE_FEATURE,
-    // special value for reports to be sent on INTR(INPUT is assumed)
-    ESP_HIDD_REPORT_TYPE_INTRDATA
+    ESP_HIDD_REPORT_TYPE_OTHER = 0,                  /*!< unknown report type */
+    ESP_HIDD_REPORT_TYPE_INPUT,                      /*!< input report */
+    ESP_HIDD_REPORT_TYPE_OUTPUT,                     /*!< output report */
+    ESP_HIDD_REPORT_TYPE_FEATURE,                    /*!< feature report */
+    ESP_HIDD_REPORT_TYPE_INTRDATA,                   /*!< special value for reports to be sent on interrupt channel, INPUT is assumed */
 } esp_hidd_report_type_t;
 
 /**
  * @brief HIDD connection state
  */
 typedef enum {
-    ESP_HIDD_CONN_STATE_CONNECTED,
-    ESP_HIDD_CONN_STATE_CONNECTING,
-    ESP_HIDD_CONN_STATE_DISCONNECTED,
-    ESP_HIDD_CONN_STATE_DISCONNECTING,
-    ESP_HIDD_CONN_STATE_UNKNOWN
+    ESP_HIDD_CONN_STATE_CONNECTED,                   /*!< HID connection established */
+    ESP_HIDD_CONN_STATE_CONNECTING,                  /*!< connection to remote Bluetooth device */
+    ESP_HIDD_CONN_STATE_DISCONNECTED,                /*!< connection released */
+    ESP_HIDD_CONN_STATE_DISCONNECTING,               /*!< disconnecting to remote Bluetooth device*/
+    ESP_HIDD_CONN_STATE_UNKNOWN,                     /*!< unknown connection state */
 } esp_hidd_connection_state_t;
 
 /**
  * @brief HID device protocol modes
  */
 typedef enum {
-    ESP_HIDD_REPORT_MODE = 0x00,
-    ESP_HIDD_BOOT_MODE = 0x01,
-    ESP_HIDD_UNSUPPORTED_MODE = 0xff
+    ESP_HIDD_REPORT_MODE = 0x00,                     /*!< Report Protocol Mode */
+    ESP_HIDD_BOOT_MODE = 0x01,                       /*!< Boot Protocol Mode */
+    ESP_HIDD_UNSUPPORTED_MODE = 0xff,                /*!< unsupported */
 } esp_hidd_protocol_mode_t;
 
+/**
+ * @brief HID Boot Protocol report IDs
+ */
+typedef enum {
+    ESP_HIDD_BOOT_REPORT_ID_KEYBOARD = 1,            /*!< report ID of Boot Protocol keyboard report */
+    ESP_HIDD_BOOT_REPORT_ID_MOUSE = 2,               /*!< report ID of Boot Protocol mouse report */
+} esp_hidd_boot_report_id_t;
+
+/**
+ * @brief HID Boot Protocol report size including report ID
+ */
+enum {
+    ESP_HIDD_BOOT_REPORT_SIZE_KEYBOARD = 9,          /*!< report size of Boot Protocol keyboard report */
+    ESP_HIDD_BOOT_REPORT_SIZE_MOUSE = 4,             /*!< report size of Boot Protocol mouse report */
+};
 
 /**
- * @brief HIDD characteristics for SDP report
+ * @brief HID device characteristics for SDP server
  */
 typedef struct {
-    const char *name;
-    const char *description;
-    const char *provider;
-    uint8_t subclass;
-    uint8_t *desc_list;
-    int desc_list_len;
+    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 */
 } esp_hidd_app_param_t;
 
 /**
- * @brief HIDD Quality of Service parameters
+ * @brief HIDD Quality of Service parameters negotiated over L2CAP
  */
 typedef struct {
-    uint8_t service_type;
-    uint32_t token_rate;
-    uint32_t token_bucket_size;
-    uint32_t peak_bandwidth;
-    uint32_t access_latency;
-    uint32_t delay_variation;
+    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 */
 } esp_hidd_qos_param_t;
 
 /**

docs/conf_common.py

@@ -39,6 +39,7 @@
 CLASSIC_BT_DOCS = ['api-reference/bluetooth/classic_bt.rst',
                    'api-reference/bluetooth/esp_a2dp.rst',
                    'api-reference/bluetooth/esp_avrc.rst',
+                   'api-reference/bluetooth/esp_hidd.rst',
                    'api-reference/bluetooth/esp_hf_defs.rst',
                    'api-reference/bluetooth/esp_hf_client.rst',
                    'api-reference/bluetooth/esp_hf_ag.rst',

docs/doxygen/Doxyfile

@@ -51,6 +51,7 @@ INPUT = \
     $(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h \
     $(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_avrc_api.h \
     $(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_spp_api.h \
+    $(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_hidd_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_hf_client_api.h \
     $(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h \

docs/en/api-reference/bluetooth/classic_bt.rst

@@ -11,3 +11,4 @@ CLASSIC BT
    BT HFP Define <esp_hf_defs>
    BT HFP Client <esp_hf_client>
    BT HFP AG <esp_hf_ag>
+   BT HID DEVICE <esp_hidd>

docs/en/api-reference/bluetooth/esp_hidd.rst

@@ -0,0 +1,19 @@
+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 :example:`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 - :example:`bluetooth/bluedroid/classic_bt/bt_hid_mouse_device`
+
+API Reference
+-------------
+
+.. include-build-file:: inc/esp_hidd_api.inc

docs/zh_CN/api-reference/bluetooth/esp_hidd.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/api-reference/bluetooth/esp_hidd.rst