esp_hidd_api.h

/*
 * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 *
 * SPDX-FileContributor: Blake Felt
 */

#ifndef __ESP_HIDD_API_H__
#define __ESP_HIDD_API_H__

#include "esp_bt_defs.h"
#include "esp_err.h"

#ifdef __cplusplus
extern "C" {
#endif

/// 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 result code
 */
typedef enum {
    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,                  /*!< 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,                   /*!< 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,                     /*!< 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 HID device characteristics for SDP server
 */
typedef struct {
    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 negotiated over L2CAP
 */
typedef struct {
    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;

/**
 * @brief HID device callback function events
 */
typedef enum {
    ESP_HIDD_INIT_EVT = 0,       /*!< When HID device is initialized, the event comes */
    ESP_HIDD_DEINIT_EVT,         /*!< When HID device is deinitialized, the event comes */
    ESP_HIDD_REGISTER_APP_EVT,   /*!< When HID device application registered, the event comes */
    ESP_HIDD_UNREGISTER_APP_EVT, /*!< When HID device application unregistered, the event comes */
    ESP_HIDD_OPEN_EVT,           /*!< When HID device connection to host opened, the event comes */
    ESP_HIDD_CLOSE_EVT,          /*!< When HID device connection to host closed, the event comes */
    ESP_HIDD_SEND_REPORT_EVT,    /*!< When HID device send report to lower layer, the event comes */
    ESP_HIDD_REPORT_ERR_EVT,     /*!< When HID device report handshanke error to lower layer, the event comes */
    ESP_HIDD_GET_REPORT_EVT,     /*!< When HID device receives GET_REPORT request from host, the event comes */
    ESP_HIDD_SET_REPORT_EVT,     /*!< When HID device receives SET_REPORT request from host, the event comes */
    ESP_HIDD_SET_PROTOCOL_EVT,   /*!< When HID device receives SET_PROTOCOL request from host, the event comes */
    ESP_HIDD_INTR_DATA_EVT,      /*!< When HID device receives DATA from host on intr, the event comes */
    ESP_HIDD_VC_UNPLUG_EVT,      /*!< When HID device initiates Virtual Cable Unplug, the event comes */
    ESP_HIDD_API_ERR_EVT         /*!< When HID device has API error, the event comes */
} esp_hidd_cb_event_t;

typedef enum {
    ESP_HIDD_SUCCESS,
    ESP_HIDD_ERROR,         /*!< general ESP HD error */
    ESP_HIDD_NO_RES,        /*!< out of system resources */
    ESP_HIDD_BUSY,          /*!< Temporarily can not handle this request. */
    ESP_HIDD_NO_DATA,       /*!< No data. */
    ESP_HIDD_NEED_INIT,     /*!< HIDD module shall init first */
    ESP_HIDD_NEED_DEINIT,   /*!< HIDD module shall deinit first */
    ESP_HIDD_NEED_REG,      /*!< HIDD module shall register first */
    ESP_HIDD_NEED_DEREG,    /*!< HIDD module shall deregister first */
    ESP_HIDD_NO_CONNECTION, /*!< connection may have been closed */
} esp_hidd_status_t;

/**
 * @brief HID device callback parameters union
 */
typedef union {
    /**
     * @brief ESP_HIDD_INIT_EVT
     */
    struct hidd_init_evt_param {
        esp_hidd_status_t status; /*!< operation status */
    } init;                       /*!< HIDD callback param of ESP_HIDD_INIT_EVT */

    /**
     * @brief ESP_HIDD_DEINIT_EVT
     */
    struct hidd_deinit_evt_param {
        esp_hidd_status_t status; /*!< operation status */
    } deinit;                     /*!< HIDD callback param of ESP_HIDD_DEINIT_EVT */

    /**
     * @brief ESP_HIDD_REGISTER_APP_EVT
     */
    struct hidd_register_app_evt_param {
        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 */
    } register_app;               /*!< HIDD callback param of ESP_HIDD_REGISTER_APP_EVT */

    /**
     * @brief ESP_HIDD_UNREGISTER_APP_EVT
     */
    struct hidd_unregister_app_evt_param {
        esp_hidd_status_t status; /*!< operation status         */
    } unregister_app;             /*!< HIDD callback param of ESP_HIDD_UNREGISTER_APP_EVT */

    /**
     * @brief ESP_HIDD_OPEN_EVT
     */
    struct hidd_open_evt_param {
        esp_hidd_status_t status;                /*!< operation status         */
        esp_hidd_connection_state_t conn_status; /*!< connection status */
        esp_bd_addr_t bd_addr;                   /*!< host address */
    } open;                                      /*!< HIDD callback param of ESP_HIDD_OPEN_EVT */

    /**
     * @brief ESP_HIDD_CLOSE_EVT
     */
    struct hidd_close_evt_param {
        esp_hidd_status_t status;                /*!< operation status         */
        esp_hidd_connection_state_t conn_status; /*!< connection status        */
    } close;                                     /*!< HIDD callback param of ESP_HIDD_CLOSE_EVT */

    /**
     * @brief ESP_HIDD_SEND_REPORT_EVT
     */
    struct hidd_send_report_evt_param {
        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         */
    } send_report;                          /*!< HIDD callback param of ESP_HIDD_SEND_REPORT_EVT */

    /**
     * @brief ESP_HIDD_REPORT_ERR_EVT
     */
    struct hidd_report_err_evt_param {
        esp_hidd_status_t status; /*!< operation status         */
        uint8_t reason;           /*!< lower layer failed reason(ref hiddefs.h)           */
    } report_err;                 /*!< HIDD callback param of ESP_HIDD_REPORT_ERR_EVT */

    /**
     * @brief ESP_HIDD_GET_REPORT_EVT
     */
    struct hidd_get_report_evt_param {
        esp_hidd_report_type_t report_type; /*!< report type        */
        uint8_t report_id;                  /*!< report id         */
        uint16_t buffer_size;               /*!< buffer size         */
    } get_report;                           /*!< HIDD callback param of ESP_HIDD_GET_REPORT_EVT */

    /**
     * @brief ESP_HIDD_SET_REPORT_EVT
     */
    struct hidd_set_report_evt_param {
        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         */
    } set_report;                           /*!< HIDD callback param of ESP_HIDD_SET_REPORT_EVT */

    /**
     * @brief ESP_HIDD_SET_PROTOCOL_EVT
     */
    struct hidd_set_protocol_evt_param {
        esp_hidd_protocol_mode_t protocol_mode; /*!< protocol mode        */
    } set_protocol;                             /*!< HIDD callback param of ESP_HIDD_SET_PROTOCOL_EVT */

    /**
     * @brief ESP_HIDD_INTR_DATA_EVT
     */
    struct hidd_intr_data_evt_param {
        uint8_t report_id; /*!< interrupt channel report id         */
        uint16_t len;      /*!< interrupt channel report data length         */
        uint8_t *data;     /*!< interrupt channel report data pointer         */
    } intr_data;           /*!< HIDD callback param of ESP_HIDD_INTR_DATA_EVT */

    /**
     * @brief ESP_HIDD_VC_UNPLUG_EVT
     */
    struct hidd_vc_unplug_param {
        esp_hidd_status_t status;                /*!< operation status         */
        esp_hidd_connection_state_t conn_status; /*!< connection status        */
    } vc_unplug;                                 /*!< HIDD callback param of ESP_HIDD_VC_UNPLUG_EVT */
} esp_hidd_cb_param_t;

/**
 * @brief           HID device callback function type.
 * @param           event: Event type
 * @param           param: Point to callback parameter, currently is union type
 */
typedef void (*esp_hd_cb_t)(esp_hidd_cb_event_t event, esp_hidd_cb_param_t *param);

/**
 * @brief           This function is called to init callbacks with HID device module.
 *
 * @param[in]       callback: pointer to the init callback function.
 *
 * @return
 *                  - ESP_OK: success
 *                  - other: failed
 */
esp_err_t esp_bt_hid_device_register_callback(esp_hd_cb_t callback);

/**
 * @brief           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.
 *
 * @return
 *                  - ESP_OK: success
 *                  - other: failed
 */
esp_err_t esp_bt_hid_device_init(void);

/**
 * @brief           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.
 *
 * @return
 *                  - ESP_OK: success
 *                  - other: failed
 */
esp_err_t esp_bt_hid_device_deinit(void);

/**
 * @brief           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.
 *
 * @param[in]       app_param: HIDD parameters
 * @param[in]       in_qos: incoming QoS parameters
 * @param[in]       out_qos: outgoing QoS parameters
 *
 * @return
 *                  - 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);

/**
 * @brief           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.
 *
 * @return
 *                  - ESP_OK: success
 *                  - other: failed
 */
esp_err_t esp_bt_hid_device_unregister_app(void);

/**
 * @brief           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.
 *
 * @param[in]       bd_addr: Remote host bluetooth device address.
 *
 * @return
 *                  - ESP_OK: success
 *                  - other: failed
 */
esp_err_t esp_bt_hid_device_connect(esp_bd_addr_t bd_addr);

/**
 * @brief           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.
 *
 * @return
 *                  - ESP_OK: success
 *                  - other: failed
 */
esp_err_t esp_bt_hid_device_disconnect(void);

/**
 * @brief           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.
 *
 * @param[in]       type: type of report
 * @param[in]       id: report id as defined by descriptor
 * @param[in]       len: length of report
 * @param[in]       data: report data
 *
 * @return
 *                  - 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);

/**
 * @brief           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.
 *
 * @param[in]       error: type of error
 *
 * @return
 *                  - ESP_OK: success
 *                  - other: failed
 */
esp_err_t esp_bt_hid_device_report_error(esp_hidd_handshake_error_t error);

/**
 * @brief           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,
 *
 * @return          - ESP_OK: success
 *                  - other: failed
 */
esp_err_t esp_bt_hid_device_virtual_cable_unplug(void);

#ifdef __cplusplus
}
#endif

#endif