feat(hid_host): Start HID Device from suspended state

Author: peter-marcisovsky

host/class/hid/usb_host_hid/hid_host.c

@@ -609,6 +609,11 @@ static esp_err_t hid_host_resume_interface(hid_iface_t *iface, bool resume_ep)
                         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");
@@ -618,14 +623,19 @@ static esp_err_t hid_host_resume_interface(hid_iface_t *iface, bool 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;
     }
 
-    // start data transfer
-    HID_RETURN_ON_ERROR( usb_host_transfer_submit(iface->in_xfer), "Unable to start data transfer");
+    // 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;
 }
 
@@ -653,8 +663,15 @@ static esp_err_t hid_host_device_suspended(usb_device_handle_t dev_hdl)
         HID_EXIT_CRITICAL();
 
         if (hid_iface_curr->parent && (hid_iface_curr->parent->dev_addr == hid_device->dev_addr)) {
-            hid_host_suspend_interface(hid_iface_curr, false);
-            hid_host_user_interface_callback(hid_iface_curr, HID_HOST_INTERFACE_EVENT_SUSPENDED);
+            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;
@@ -688,8 +705,15 @@ static esp_err_t hid_host_device_resumed(usb_device_handle_t dev_hdl)
         HID_EXIT_CRITICAL();
 
         if (hid_iface_curr->parent && (hid_iface_curr->parent->dev_addr == hid_device->dev_addr)) {
-            hid_host_resume_interface(hid_iface_curr, false);
-            hid_host_user_interface_callback(hid_iface_curr, HID_HOST_INTERFACE_EVENT_RESUMED);
+            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;
@@ -1487,7 +1511,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");
 
@@ -1511,6 +1535,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

@@ -204,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
  */
@@ -212,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

host/class/hid/usb_host_hid/test_app/main/test_hid_basic.c

@@ -23,6 +23,8 @@
 #include "test_hid_basic.h"
 #include "hid_mock_device.h"
 
+#define TEST_EVENT_WAIT_MS          500     // Time to expect driver or device event
+
 // Global variable to verify user arg passing through callbacks
 static uint32_t user_arg_value = 0x8A53E0A4; // Just a constant random number
 
@@ -1030,7 +1032,6 @@ TEST_CASE("auto_suspend_timer", "[hid_host]")
     vQueueDelete(hid_host_test_event_queue);
     hid_host_test_event_queue = NULL;
 }
-
 /**
  * @brief Resume by transfer submit
  *
@@ -1041,6 +1042,8 @@ TEST_CASE("auto_suspend_timer", "[hid_host]")
  *     - Install USB Host lib, Install HID driver, open device and start device
  *     - Manually suspend the root port, expect suspend event
  *     - Issue a CTRL transfer to the device, expect the root port to be resumed, expect resume event
+ *     - Manually suspend the root port, expect suspend event
+ *     - Start the device, expect the root port to be resumed, expect resume event
  *     - Teardown
  */
 TEST_CASE("resume_by_transfer_submit", "[hid_host]")
@@ -1073,6 +1076,17 @@ TEST_CASE("resume_by_transfer_submit", "[hid_host]")
     expected_event.interface_evt.event = HID_HOST_INTERFACE_EVENT_RESUMED;
     hid_host_test_expect_event(&expected_event, expect_event_ticks);
 
+    // Suspend the root port manually
+    TEST_ASSERT_EQUAL(ESP_OK, usb_host_lib_root_port_suspend());
+    expected_event.event_group = HID_INTERFACE_EVENT;
+    expected_event.interface_evt.event = HID_HOST_INTERFACE_EVENT_SUSPENDED;
+    hid_host_test_expect_event(&expected_event, expect_event_ticks);
+
+    // Auto resume the device by calling device start
+    TEST_ASSERT_EQUAL(ESP_OK, hid_host_device_start(global_hdl));
+    expected_event.interface_evt.event = HID_HOST_INTERFACE_EVENT_RESUMED;
+    hid_host_test_expect_event(&expected_event, expect_event_ticks);
+
     // Tear down test
     test_hid_teardown();
     vQueueDelete(hid_host_test_event_queue);

host/class/hid/usb_host_hid/test_app/main/test_hid_err_handling.c

@@ -281,56 +281,6 @@ static void test_open_suspended_device(void)
     test_event_queue = NULL;
 }
 
-/**
- * @brief Start suspended device
- *
- * Purpose:
- *     - Test HID Host reaction to starting an opened device, which is in suspended state
- *
- * Procedure:
- *     - Install USB Host lib, Install HID driver, wait for device connection, open the device
- *     - Suspend the root port and fail to start a device
- *     - Resume the root port, teardown
- */
-static void test_start_suspended_device(void)
-{
-    ESP_LOGI(TAG, "Start suspended device");
-    test_event_queue = xQueueCreate(4, sizeof(test_event_queue_t));
-    TEST_ASSERT_NOT_NULL(test_event_queue);
-
-    test_hid_setup(test_hid_host_event_callback_open_event, HID_TEST_EVENT_HANDLE_IN_DRIVER);
-
-    // Make sure connect events are delivered from both devices
-    test_event_queue_t queue_item_1, queue_item_2;
-    TEST_ASSERT_EQUAL(pdTRUE, xQueueReceive(test_event_queue, &queue_item_1, pdMS_TO_TICKS(500)));
-    TEST_ASSERT_EQUAL(pdTRUE, xQueueReceive(test_event_queue, &queue_item_2, pdMS_TO_TICKS(500)));
-
-    const hid_host_device_config_t dev_config = {
-        .callback = test_hid_host_interface_event_close,
-        .callback_arg = NULL
-    };
-
-    // Open devices normally
-    TEST_ASSERT_EQUAL(ESP_OK, hid_host_device_open(queue_item_1.hid_device_handle, &dev_config));
-    TEST_ASSERT_EQUAL(ESP_OK, hid_host_device_open(queue_item_2.hid_device_handle, &dev_config));
-
-    printf("Issue suspend\n");
-    TEST_ASSERT_EQUAL(ESP_OK, usb_host_lib_root_port_suspend());
-    vTaskDelay(pdMS_TO_TICKS(100));
-
-    // Try to start devices with the root port suspended
-    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, hid_host_device_start(queue_item_1.hid_device_handle));
-    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, hid_host_device_start(queue_item_2.hid_device_handle));
-
-    printf("Issue resume\n");
-    TEST_ASSERT_EQUAL(ESP_OK, usb_host_lib_root_port_resume());
-    vTaskDelay(pdMS_TO_TICKS(100));
-
-    // Teardown
-    test_hid_teardown();
-    vQueueDelete(test_event_queue);
-    test_event_queue = NULL;
-}
 #endif // HID_HOST_SUSPEND_RESUME_API_SUPPORTED
 
 // ----------------------- Public --------------------------
@@ -351,6 +301,5 @@ TEST_CASE("error_handling", "[hid_host]")
     test_uninstall_hid_driver_while_device_is_present();
 #ifdef HID_HOST_SUSPEND_RESUME_API_SUPPORTED
     test_open_suspended_device();
-    test_start_suspended_device();
 #endif // HID_HOST_SUSPEND_RESUME_API_SUPPORTED
 }