feat(hid_host): Add support for global suspend/resume

    - usb_host lib supports global suspend and resume
    - backward compatibility with older IDF releases
    - HID Host target tests

Author: peter-marcisovsky

host/class/hid/usb_host_hid/CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Added a limitation for the HID report descriptor size to a maximum of 2048 bytes
+- Added global suspend/resume support
 
 ## [1.0.4] - 2025-09-24
 

host/class/hid/usb_host_hid/hid_host.c

@@ -96,6 +96,7 @@ typedef enum {
     HID_INTERFACE_STATE_READY,                  /**< HID Interface opened and ready to start transfer */
     HID_INTERFACE_STATE_ACTIVE,                 /**< HID Interface is in use */
     HID_INTERFACE_STATE_WAIT_USER_DELETION,     /**< HID Interface wait user to be removed */
+    HID_INTERFACE_STATE_SUSPENDED,              /**< HID Interface (and the whole device) is suspended */
     HID_INTERFACE_STATE_MAX
 } hid_iface_state_t;
 
@@ -116,6 +117,7 @@ typedef struct hid_interface {
     hid_host_interface_event_cb_t user_cb;  /**< Interface application callback */
     void *user_cb_arg;                      /**< Interface application callback arg */
     hid_iface_state_t state;                /**< Interface state */
+    hid_iface_state_t last_state;           /**< Interface last state before entering suspended mode */
 } hid_iface_t;
 
 /**
@@ -555,6 +557,179 @@ static esp_err_t hid_host_device_disconnected(usb_device_handle_t dev_hdl)
     return ESP_OK;
 }
 
+#ifdef HID_HOST_SUSPEND_RESUME_API_SUPPORTED
+
+/**
+ * @brief Suspend interface
+ *
+ * @note endpoints are already halted and flushed when a global suspend is issues by the USB Host lib
+ * @param[in] iface    HID interface handle
+ * @param[in] stop_ep  Stop (halt and flush) endpoint
+ *
+ * @return esp_err_t
+ */
+static esp_err_t hid_host_suspend_interface(hid_iface_t *iface, bool stop_ep)
+{
+    HID_RETURN_ON_INVALID_ARG(iface);
+    HID_RETURN_ON_INVALID_ARG(iface->parent);
+
+    HID_RETURN_ON_FALSE(is_interface_in_list(iface),
+                        ESP_ERR_NOT_FOUND,
+                        "Interface handle not found");
+
+    HID_RETURN_ON_FALSE((HID_INTERFACE_STATE_SUSPENDED != iface->state),
+                        ESP_ERR_INVALID_STATE,
+                        "Interface wrong state");
+
+    // EP is usually stopped by usb_host_lib, in case of global suspend, thus no need to Halt->Flush EP again
+    if (stop_ep) {
+        HID_RETURN_ON_ERROR( usb_host_endpoint_halt(iface->parent->dev_hdl, iface->ep_in),
+                             "Unable to HALT EP");
+        HID_RETURN_ON_ERROR( usb_host_endpoint_flush(iface->parent->dev_hdl, iface->ep_in),
+                             "Unable to FLUSH EP");
+        // Don't clear EP, it must remain halted, when the device is in suspended state
+    }
+
+    iface->last_state = iface->state;
+    iface->state = HID_INTERFACE_STATE_SUSPENDED;
+
+    return ESP_OK;
+}
+
+/**
+ * @brief Resume interface
+ *
+ * @note endpoints are already cleared when a global resume is issues by the USB Host lib
+ * @param[in] iface      HID interface handle
+ * @param[in] resume_ep  Resume (clear) endpoint
+ *
+ * @return esp_err_t
+ */
+static esp_err_t hid_host_resume_interface(hid_iface_t *iface, bool resume_ep)
+{
+    HID_RETURN_ON_INVALID_ARG(iface);
+    HID_RETURN_ON_INVALID_ARG(iface->parent);
+
+    HID_RETURN_ON_FALSE(is_interface_in_list(iface),
+                        ESP_ERR_NOT_FOUND,
+                        "Interface handle not found");
+
+    if (HID_INTERFACE_STATE_ACTIVE == iface->state) {
+        // Interface already auto-resumed by hid_host_device_start(), return early and continue to resume event delivery
+        return ESP_OK;
+    }
+
+    HID_RETURN_ON_FALSE ((HID_INTERFACE_STATE_SUSPENDED == iface->state),
+                         ESP_ERR_INVALID_STATE,
+                         "Interface wrong state");
+
+    // EP is usually cleared by usb_host_lib, in case of global suspend, thus no need to Clear an EP again
+    if (resume_ep) {
+        usb_host_endpoint_clear(iface->parent->dev_hdl, iface->ep_in);
+    }
+
+    // Use the last device state before the device went to suspended state as the current state
+    iface->state = iface->last_state;
+
+    if (iface->in_xfer == NULL) {
+        return ESP_OK;
+    }
+
+    // If the last state before the device went to suspended state was active state, start the data transfer
+    if (iface->last_state == HID_INTERFACE_STATE_ACTIVE) {
+        // start data transfer
+        HID_RETURN_ON_ERROR( usb_host_transfer_submit(iface->in_xfer), "Unable to start data transfer");
+    }
+
+    return ESP_OK;
+}
+
+/**
+ * @brief Suspend device
+ *
+ * Go through list, suspend all devices and deliver suspend events
+ *
+ * @param[in] dev_hdl    USB Device handle
+ *
+ * @return esp_err_t
+ */
+static esp_err_t hid_host_device_suspended(usb_device_handle_t dev_hdl)
+{
+    hid_device_t *hid_device = get_hid_device_by_handle(dev_hdl);
+    HID_RETURN_ON_INVALID_ARG(hid_device);
+
+    HID_ENTER_CRITICAL();
+    hid_iface_t *hid_iface_curr;
+    hid_iface_t *hid_iface_next;
+    // Go through list
+    hid_iface_curr = STAILQ_FIRST(&s_hid_driver->hid_ifaces_tailq);
+    while (hid_iface_curr != NULL) {
+        hid_iface_next = STAILQ_NEXT(hid_iface_curr, tailq_entry);
+        HID_EXIT_CRITICAL();
+
+        if (hid_iface_curr->parent && (hid_iface_curr->parent->dev_addr == hid_device->dev_addr)) {
+            esp_err_t ret = hid_host_suspend_interface(hid_iface_curr, false);
+
+            // Make sure the device is connected and the interface is found otherwise don't deliver suspend event
+            if (ret != ESP_ERR_NOT_FOUND) {
+
+                // We will deliver the suspend event, if the hid_host_suspend_interface fails with other errors,
+                // as the usb_host_lib has already suspended the root port anyway
+                hid_host_user_interface_callback(hid_iface_curr, HID_HOST_INTERFACE_EVENT_SUSPENDED);
+            }
+        }
+        HID_ENTER_CRITICAL();
+        hid_iface_curr = hid_iface_next;
+    }
+    HID_EXIT_CRITICAL();
+
+    return ESP_OK;
+}
+
+/**
+ * @brief Resume device
+ *
+ * Go through list, resume all devices and deliver resume events
+ *
+ * @param[in] dev_hdl    USB Device handle
+ *
+ * @return esp_err_t
+ */
+static esp_err_t hid_host_device_resumed(usb_device_handle_t dev_hdl)
+{
+    hid_device_t *hid_device = get_hid_device_by_handle(dev_hdl);
+    HID_RETURN_ON_INVALID_ARG(hid_device);
+
+    HID_ENTER_CRITICAL();
+    hid_iface_t *hid_iface_curr;
+    hid_iface_t *hid_iface_next;
+    // Go through list
+    hid_iface_curr = STAILQ_FIRST(&s_hid_driver->hid_ifaces_tailq);
+    while (hid_iface_curr != NULL) {
+        hid_iface_next = STAILQ_NEXT(hid_iface_curr, tailq_entry);
+        HID_EXIT_CRITICAL();
+
+        if (hid_iface_curr->parent && (hid_iface_curr->parent->dev_addr == hid_device->dev_addr)) {
+            esp_err_t ret = hid_host_resume_interface(hid_iface_curr, false);
+
+            // Make sure the device is connected and the interface is found otherwise don't deliver resume event
+            if (ret != ESP_ERR_NOT_FOUND) {
+
+                // We will deliver the resume event, if the hid_host_resume_interface fails with other errors,
+                // as the usb_host_lib has already resumed the root port anyway
+                hid_host_user_interface_callback(hid_iface_curr, HID_HOST_INTERFACE_EVENT_RESUMED);
+            }
+        }
+        HID_ENTER_CRITICAL();
+        hid_iface_curr = hid_iface_next;
+    }
+    HID_EXIT_CRITICAL();
+
+    return ESP_OK;
+}
+
+#endif // HID_HOST_SUSPEND_RESUME_API_SUPPORTED
+
 /**
  * @brief USB Host Client's event callback
  *
@@ -563,10 +738,28 @@ static esp_err_t hid_host_device_disconnected(usb_device_handle_t dev_hdl)
  */
 static void client_event_cb(const usb_host_client_event_msg_t *event, void *arg)
 {
-    if (event->event == USB_HOST_CLIENT_EVENT_NEW_DEV) {
+    switch (event->event) {
+    case USB_HOST_CLIENT_EVENT_NEW_DEV:
+        ESP_LOGD(TAG, "New device connected");
         hid_host_device_init_attempt(event->new_dev.address);
-    } else if (event->event == USB_HOST_CLIENT_EVENT_DEV_GONE) {
+        break;
+    case USB_HOST_CLIENT_EVENT_DEV_GONE:
+        ESP_LOGD(TAG, "Device suddenly disconnected");
         hid_host_device_disconnected(event->dev_gone.dev_hdl);
+        break;
+#ifdef HID_HOST_SUSPEND_RESUME_API_SUPPORTED
+    case USB_HOST_CLIENT_EVENT_DEV_SUSPENDED:
+        ESP_LOGD(TAG, "Device suspended");
+        hid_host_device_suspended(event->dev_suspend_resume.dev_hdl);
+        break;
+    case USB_HOST_CLIENT_EVENT_DEV_RESUMED:
+        ESP_LOGD(TAG, "Device resumed");
+        hid_host_device_resumed(event->dev_suspend_resume.dev_hdl);
+        break;
+#endif // HID_HOST_SUSPEND_RESUME_API_SUPPORTED
+    default:
+        ESP_LOGW(TAG, "Unrecognized USB Host client event");
+        break;
     }
 }
 
@@ -633,14 +826,19 @@ static esp_err_t hid_host_disable_interface(hid_iface_t *iface)
                         ESP_ERR_NOT_FOUND,
                         "Interface handle not found");
 
-    HID_RETURN_ON_FALSE((HID_INTERFACE_STATE_ACTIVE == iface->state),
+    HID_RETURN_ON_FALSE((HID_INTERFACE_STATE_ACTIVE == iface->state ||
+                         HID_INTERFACE_STATE_SUSPENDED == iface->state),
                         ESP_ERR_INVALID_STATE,
                         "Interface wrong state");
 
-    HID_RETURN_ON_ERROR( usb_host_endpoint_halt(iface->parent->dev_hdl, iface->ep_in),
-                         "Unable to HALT EP");
-    HID_RETURN_ON_ERROR( usb_host_endpoint_flush(iface->parent->dev_hdl, iface->ep_in),
-                         "Unable to FLUSH EP");
+    if (HID_INTERFACE_STATE_ACTIVE == iface->state) {
+        HID_RETURN_ON_ERROR( usb_host_endpoint_halt(iface->parent->dev_hdl, iface->ep_in),
+                             "Unable to HALT EP");
+        HID_RETURN_ON_ERROR( usb_host_endpoint_flush(iface->parent->dev_hdl, iface->ep_in),
+                             "Unable to FLUSH EP");
+    }
+    // If interface state is suspended, the EP is already flushed and halted, only clear the EP
+    // If suspended, may return ESP_ERR_INVALID_STATE
     usb_host_endpoint_clear(iface->parent->dev_hdl, iface->ep_in);
 
     iface->state = HID_INTERFACE_STATE_READY;
@@ -1220,15 +1418,15 @@ esp_err_t hid_host_device_close(hid_host_device_handle_t hid_dev_handle)
              hid_iface->dev_params.iface_num,
              hid_iface->state);
 
-    if (HID_INTERFACE_STATE_ACTIVE == hid_iface->state) {
+    if (HID_INTERFACE_STATE_ACTIVE == hid_iface->state ||
+            HID_INTERFACE_STATE_SUSPENDED == hid_iface->state) {
         HID_RETURN_ON_ERROR( hid_host_disable_interface(hid_iface),
                              "Unable to disable HID Interface");
     }
 
     if (HID_INTERFACE_STATE_READY == hid_iface->state) {
         HID_RETURN_ON_ERROR( hid_host_interface_release_and_free_transfer(hid_iface),
                              "Unable to release HID Interface");
-
         // If the device is closing by user before device detached we need to flush user callback here
         free(hid_iface->report_desc);
         hid_iface->report_desc = NULL;
@@ -1329,7 +1527,7 @@ esp_err_t hid_host_device_start(hid_host_device_handle_t hid_dev_handle)
                         ESP_ERR_NOT_FOUND,
                         "Interface handle not found");
 
-    HID_RETURN_ON_FALSE ((HID_INTERFACE_STATE_READY == iface->state),
+    HID_RETURN_ON_FALSE ((HID_INTERFACE_STATE_READY == iface->state || HID_INTERFACE_STATE_SUSPENDED == iface->state),
                          ESP_ERR_INVALID_STATE,
                          "Interface wrong state");
 
@@ -1353,6 +1551,15 @@ esp_err_t hid_host_device_stop(hid_host_device_handle_t hid_dev_handle)
 
     HID_RETURN_ON_INVALID_ARG(iface);
 
+    HID_RETURN_ON_FALSE(is_interface_in_list(iface), ESP_ERR_NOT_FOUND, "Interface handle not found");
+
+    if (iface->state == HID_INTERFACE_STATE_SUSPENDED) {
+        // If interface is suspended, mark the last state as READY,
+        // as if the interface was stopped before entering suspended state
+        iface->last_state = HID_INTERFACE_STATE_READY;
+        return ESP_OK;
+    }
+
     return hid_host_disable_interface(iface);
 }
 

host/class/hid/usb_host_hid/include/usb/hid_host.h

@@ -11,6 +11,7 @@
 #include "esp_err.h"
 #include <freertos/FreeRTOS.h>
 
+#include "usb/usb_host.h"
 #include "hid.h"
 
 #ifdef __cplusplus
@@ -29,6 +30,11 @@ extern "C" {
 */
 #define HID_STR_DESC_MAX_LENGTH           32
 
+// For backward compatibility with IDF versions which do not have suspend/resume api
+#ifdef USB_HOST_LIB_EVENT_FLAGS_AUTO_SUSPEND
+#define HID_HOST_SUSPEND_RESUME_API_SUPPORTED
+#endif
+
 typedef struct hid_interface *hid_host_device_handle_t;    /**< Device Handle. Handle to a particular HID interface */
 
 // ------------------------ USB HID Host events --------------------------------
@@ -46,6 +52,10 @@ typedef enum {
     HID_HOST_INTERFACE_EVENT_INPUT_REPORT = 0x00,     /**< HID Device input report */
     HID_HOST_INTERFACE_EVENT_TRANSFER_ERROR,          /**< HID Device transfer error */
     HID_HOST_INTERFACE_EVENT_DISCONNECTED,            /**< HID Device has been disconnected */
+#ifdef HID_HOST_SUSPEND_RESUME_API_SUPPORTED
+    HID_HOST_INTERFACE_EVENT_SUSPENDED,               /**< HID Device has been suspended */
+    HID_HOST_INTERFACE_EVENT_RESUMED,                 /**< HID Device has been resumed */
+#endif // HID_HOST_SUSPEND_RESUME_API_SUPPORTED
 } hid_host_interface_event_t;
 
 /**
@@ -194,6 +204,7 @@ esp_err_t hid_host_device_get_raw_input_report_data(hid_host_device_handle_t hid
  *
  * Calls a callback when the HID Interface event has occurred.
  *
+ * @note Can be called on device in suspended state, it will effectively resume and start the device
  * @param[in] hid_dev_handle  HID Device handle
  * @return esp_err_t
  */
@@ -202,6 +213,8 @@ esp_err_t hid_host_device_start(hid_host_device_handle_t hid_dev_handle);
 /**
  * @brief HID Host stop device
  *
+ * @note Can be called on device in suspended state, it will effectively prevent the device from starting automatically
+ *       in case the device was started before entering suspended state
  * @param[in] hid_dev_handle  HID Device handle
  *
  * @return esp_err_t