tests: usb: uvc: connect USB device and host via UVB

Josuah Demangeon · Josuah Demangeon · commit 771738e93e17 · 2025-08-09T19:12:01.000Z
Add a test to run the USB Video Class host support by using
the existing Zephyr USB Video Class device support.
This allows running implementing the host side from the device side.
A draft implementation of UVC is added leveraging this test.

Signed-off-by: Josuah Demangeon &lt;josuah.demangeon@nordicsemi.no&gt;
diff --git a/dts/bindings/usb/zephyr,uvc-host.yaml b/dts/bindings/usb/zephyr,uvc-host.yaml
@@ -0,0 +1,15 @@
+# Copyright (c) 2025 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: |
+  USB Video Class (UVC) host instance.
+
+  Each UVC instance added to the USB Host Controller (UHC) node will be visible
+  as a new camera from Zephyr point of view.
+
+  as soon as a camera is connected to USB this device will be usable by the application as a
+  video device, following the video API.
+
+compatible: "zephyr,uvc-host"
+
+include: base.yaml
diff --git a/subsys/usb/host/CMakeLists.txt b/subsys/usb/host/CMakeLists.txt
@@ -16,6 +16,11 @@ zephyr_library_sources_ifdef(
 	usbh_shell.c
 )
 
+zephyr_library_sources_ifdef(
+	CONFIG_USBH_VIDEO_CLASS
+	class/usbh_uvc.c
+)
+
 zephyr_library_sources_ifdef(
   CONFIG_USBIP
   usbip.c
diff --git a/subsys/usb/host/Kconfig b/subsys/usb/host/Kconfig
@@ -54,5 +54,6 @@ config USBH_MAX_UHC_MSG
 	  Maximum number of USB host controller events that can be queued.
 
 rsource "Kconfig.usbip"
+rsource "class/Kconfig"
 
 endif # USB_HOST_STACK
diff --git a/subsys/usb/host/class/Kconfig b/subsys/usb/host/class/Kconfig
@@ -0,0 +1,5 @@
+# Copyright (c) 2025 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: Apache-2.0
+
+rsource "Kconfig.uvc"
diff --git a/subsys/usb/host/class/Kconfig.uvc b/subsys/usb/host/class/Kconfig.uvc
@@ -0,0 +1,19 @@
+# Copyright (c) 2025 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: Apache-2.0
+
+config USBH_VIDEO_CLASS
+	bool "USB Video Class implementation [EXPERIMENTAL]"
+	depends on DT_HAS_ZEPHYR_UVC_HOST_ENABLED
+	select EXPERIMENTAL
+	help
+	  USB Host Video Class (UVC) implementation.
+
+if USBH_VIDEO_CLASS
+
+module = USBH_VIDEO
+module-str = usbh uvc
+default-count = 1
+source "subsys/logging/Kconfig.template.log_config"
+
+endif # USBH_VIDEO_CLASS
diff --git a/subsys/usb/host/class/usbh_uvc.c b/subsys/usb/host/class/usbh_uvc.c
@@ -37,6 +37,10 @@ struct usbh_uvc_data {
 	int todo;
 };
 
+struct usbh_uvc_config {
+	struct usbh_context *uhs_ctx;
+};
+
 static int usbh_uvc_request(struct usbh_context *const uhs_ctx, struct uhc_transfer *const xfer,
 			    int err)
 {
diff --git a/subsys/usb/host/usbh_core.c b/subsys/usb/host/usbh_core.c
@@ -29,7 +29,7 @@ K_MSGQ_DEFINE(usbh_msgq, sizeof(struct uhc_event),
 K_MSGQ_DEFINE(usbh_bus_msgq, sizeof(struct uhc_event),
 	      CONFIG_USBH_MAX_UHC_MSG, sizeof(uint32_t));
 
-extern const struct usbh_class_data *usbh_class_data;
+extern const struct usbh_class_data *usbh_class;
 
 static int usbh_event_carrier(const struct device *dev,
 			      const struct uhc_event *const event)
@@ -75,7 +75,7 @@ static void dev_connected_handler(struct usbh_context *const ctx,
 		return;
 	}
 
-	if (usbh_class_data->connected(ctx)) {
+	if (usbh_class->connected(ctx)) {
 		LOG_ERR("The class failed to handle the connection");
 		return;
 	}
diff --git a/tests/subsys/usb/uvc/CMakeLists.txt b/tests/subsys/usb/uvc/CMakeLists.txt
@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(uvc_uvb)
+
+# This sample cannot use the common USB sample infrastructure as we do not want
+# to initialize the board default `zephyr_udc0` but instead an unrelated `virtual_udc0`.
+#include(${ZEPHYR_BASE}/samples/subsys/usb/common/common.cmake)
+
+FILE(GLOB app_sources src/*.c)
+target_sources(app PRIVATE ${app_sources})
+zephyr_include_directories(${ZEPHYR_BASE}/subsys/usb/host)
diff --git a/tests/subsys/usb/uvc/app.overlay b/tests/subsys/usb/uvc/app.overlay
@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/ {
+	virtual_uhc0: uhc-virtual {
+		compatible = "zephyr,uhc-virtual";
+		maximum-speed = "full-speed";
+
+		virtual_udc0: udc-virtual {
+			compatible = "zephyr,udc-virtual";
+			num-bidir-endpoints = <4>;
+			maximum-speed = "full-speed";
+		};
+	};
+
+	uvc_device: uvc-device {
+		compatible = "zephyr,uvc-device";
+	};
+
+	uvc_host: uvc-host {
+		compatible = "zephyr,uvc-host";
+	};
+};
diff --git a/tests/subsys/usb/uvc/prj.conf b/tests/subsys/usb/uvc/prj.conf
@@ -0,0 +1,15 @@
+CONFIG_LOG=y
+CONFIG_UDC_BUF_POOL_SIZE=2048
+CONFIG_UDC_DRIVER_LOG_LEVEL_INF=y
+CONFIG_UHC_DRIVER_LOG_LEVEL_INF=y
+CONFIG_USBD_VIDEO_CLASS=y
+CONFIG_USBD_VIDEO_LOG_LEVEL_INF=y
+CONFIG_USBH_LOG_LEVEL_INF=y
+CONFIG_USBH_VIDEO_CLASS=y
+CONFIG_USBH_VIDEO_LOG_LEVEL_INF=y
+CONFIG_USB_DEVICE_STACK_NEXT=y
+CONFIG_USB_HOST_STACK=y
+CONFIG_UVB_LOG_LEVEL_INF=y
+CONFIG_VIDEO=y
+CONFIG_VIDEO_LOG_LEVEL_INF=y
+CONFIG_ZTEST=y
diff --git a/tests/subsys/usb/uvc/src/main.c b/tests/subsys/usb/uvc/src/main.c
@@ -0,0 +1,138 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/device.h>
+#include <zephyr/logging/log.h>
+#include <zephyr/usb/usbd.h>
+#include <zephyr/usb/usbh.h>
+#include <zephyr/usb/class/usbd_uvc.h>
+#include <zephyr/ztest.h>
+
+LOG_MODULE_REGISTER(app, LOG_LEVEL_INF);
+
+/*
+ * Minimal USB Host initialization.
+ */
+
+USBH_CONTROLLER_DEFINE(app_usbh,
+		       DEVICE_DT_GET(DT_NODELABEL(virtual_uhc0)));
+
+struct usbh_context *app_usbh_init_controller(void)
+{
+	int err;
+
+	err = usbh_init(&app_usbh);
+	if (err) {
+		LOG_ERR("Failed to initialize host support");
+		return NULL;
+	}
+
+	return &app_usbh;
+}
+
+USBD_DEVICE_DEFINE(app_usbd, DEVICE_DT_GET(DT_NODELABEL(virtual_udc0)), 0x2fe3, 0x9999);
+USBD_DESC_LANG_DEFINE(app_lang);
+USBD_DESC_MANUFACTURER_DEFINE(app_mfr, "Nordic");
+USBD_DESC_PRODUCT_DEFINE(app_product, "Virtual UVC device");
+USBD_DESC_CONFIG_DEFINE(fs_cfg_desc, "FS Configuration");
+USBD_CONFIGURATION_DEFINE(app_fs_config, 0, 200, &fs_cfg_desc);
+
+/*
+ * Minimal USB Device initialization.
+ */
+
+struct usbd_context *app_usbd_init_device(void)
+{
+	int ret;
+
+	ret = usbd_add_descriptor(&app_usbd, &app_lang);
+	if (ret != 0) {
+		LOG_ERR("Failed to initialize language descriptor (%d)", ret);
+		return NULL;
+	}
+
+	ret = usbd_add_descriptor(&app_usbd, &app_mfr);
+	if (ret != 0) {
+		LOG_ERR("Failed to initialize manufacturer descriptor (%d)", ret);
+		return NULL;
+	}
+
+	ret = usbd_add_descriptor(&app_usbd, &app_product);
+	if (ret != 0) {
+		LOG_ERR("Failed to initialize product descriptor (%d)", ret);
+		return NULL;
+	}
+
+	ret = usbd_add_configuration(&app_usbd, USBD_SPEED_FS, &app_fs_config);
+	if (ret != 0) {
+		LOG_ERR("Failed to add Full-Speed configuration");
+		return NULL;
+	}
+
+	ret = usbd_register_all_classes(&app_usbd, USBD_SPEED_FS, 1, NULL);
+	if (ret != 0) {
+		LOG_ERR("Failed to add register classes");
+		return NULL;
+	}
+
+	usbd_device_set_code_triple(&app_usbd, USBD_SPEED_FS, USB_BCC_MISCELLANEOUS, 0x02, 0x01);
+
+	usbd_self_powered(&app_usbd, USB_SCD_SELF_POWERED);
+
+	ret = usbd_init(&app_usbd);
+	if (ret != 0) {
+		LOG_ERR("Failed to initialize device support");
+		return NULL;
+	}
+
+	return &app_usbd;
+}
+
+/*
+ * Test using this host connected to this device via UVB
+ */
+
+const struct device *const uvc_dev = DEVICE_DT_GET(DT_NODELABEL(uvc_device));
+const struct device *const video_dev = DEVICE_DT_GET(DT_CHOSEN(zephyr_camera));
+
+ZTEST(usb_uvc, test_virtual_device_virtual_host)
+{
+	struct usbd_context *usbd_ctx;
+	struct usbh_context *usbh_ctx;
+	int ret;
+
+	uvc_set_video_dev(uvc_dev, video_dev);
+
+	usbd_ctx = app_usbd_init_device();
+	zassert_not_null(usbd_ctx, "USB device initialization must succeed");
+
+	usbh_ctx = app_usbh_init_controller();
+	zassert_not_null(usbh_ctx, "USB host initialization must succeed");
+
+	ret = usbd_enable(usbd_ctx);
+	zassert_ok(ret, "USB device error code %d must be 0", ret);
+
+	ret = usbh_enable(usbh_ctx);
+	zassert_ok(ret, "USB host enable error code %d must be 0", ret);
+
+	k_sleep(K_MSEC(500));
+
+	/* TODO: test the video devices here. */
+
+	ret = usbh_disable(usbh_ctx);
+	zassert_ok(ret, "USB host disable error code %d must be 0", ret);
+
+	ret = usbd_disable(usbd_ctx);
+	zassert_ok(ret, "USB device disable error code %d must be 0", ret);
+
+	ret = usbh_shutdown(usbh_ctx);
+	zassert_ok(ret, "USB host shutdown error code %d must be 0", ret);
+
+	ret = usbd_shutdown(usbd_ctx);
+	zassert_ok(ret, "USB device shutdown error code %d must be 0", ret);
+}
+
+ZTEST_SUITE(usb_uvc, NULL, NULL, NULL, NULL, NULL);
diff --git a/tests/subsys/usb/uvc/testcase.yaml b/tests/subsys/usb/uvc/testcase.yaml
@@ -0,0 +1,11 @@
+tests:
+  usb.uvc:
+    tags:
+      - usb
+      - video
+    platform_allow:
+      - native_sim/native
+    integration_platforms:
+      - native_sim/native
+    extra_args:
+      - platform:native_sim/native:SNIPPET="video-sw-generator"

Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,7 @@ K_MSGQ_DEFINE(usbh_msgq, sizeof(struct uhc_event),`
`29`	`29`	`K_MSGQ_DEFINE(usbh_bus_msgq, sizeof(struct uhc_event),`
`30`	`30`	`CONFIG_USBH_MAX_UHC_MSG, sizeof(uint32_t));`
`31`	`31`
`32`		`-extern const struct usbh_class_data *usbh_class_data;`
	`32`	`+extern const struct usbh_class_data *usbh_class;`
`33`	`33`
`34`	`34`	`static int usbh_event_carrier(const struct device *dev,`
`35`	`35`	`const struct uhc_event *const event)`
`@@ -75,7 +75,7 @@ static void dev_connected_handler(struct usbh_context *const ctx,`
`75`	`75`	`return;`
`76`	`76`	`}`
`77`	`77`
`78`		`- if (usbh_class_data->connected(ctx)) {`
	`78`	`+ if (usbh_class->connected(ctx)) {`
`79`	`79`	`LOG_ERR("The class failed to handle the connection");`
`80`	`80`	`return;`
`81`	`81`	`}`