samples: subsys: usb: shell: allow host-only operation by josuah · Pull Request #105005 · zephyrproject-rtos/zephyr

josuah · 2026-03-06T01:32:05Z

Update build instructions to allow host-only operation.

Doc build https://builds.zephyrproject.io/zephyr/pr/105005/docs/samples/subsys/usb/shell/README.html#usb-shell

Testing `device` (hardware):

west build -b nrf52840dk/nrf52840 samples/subsys/usb/shell

[23165.768788] usb 3-1.1.4.4: new full-speed USB device number 14 using xhci_hcd
[23165.859755] usb 3-1.1.4.4: New USB device found, idVendor=2fe3, idProduct=ffff, bcdDevice= 4.03
[23165.859772] usb 3-1.1.4.4: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[23165.859779] usb 3-1.1.4.4: Product: Zephyr USBD foobaz
[23165.859783] usb 3-1.1.4.4: Manufacturer: ZEPHYR
[23165.859787] usb 3-1.1.4.4: SerialNumber: C1996FC49FA36360

Testing `host` + `virtual` (native_sim):

west build -b native_sim/native/64 samples/subsys/usb/shell \
  -DCONF_FILE=prj_host.conf \
  -DEXTRA_DTC_OVERLAY_FILE=virtual.overlay \
  -DCONFIG_SERIAL=y

uart:~$ usbh init  
uart:~$ usbh enable
uart:~$ usbh device list
<no device listed, as expected>

Testing `device` + `host` + `virtual` (native_sim):

west build -b native_sim/native/64 samples/subsys/usb/shell \
  -DEXTRA_CONF_FILE=prj_host.conf \
  -DEXTRA_DTC_OVERLAY_FILE=virtual.overlay \
  -DCONFIG_SERIAL=y
 
uart:~$ usbh init
uart:~$ usbh enable
uart:~$ usbd config add FS1
uart:~$ usbd config add HS1
uart:~$ usbd class register loopback_0 fs 1
uart:~$ usbd class register loopback_0 hs 1
uart:~$ usbd init
uart:~$ usbd enable
uart:~$ usbh device list
uart:~$ usbh device descriptor configuration 1 0

josuah · 2026-03-06T22:17:52Z

Force-push:

also adjust dependencies and tags

sonarqubecloud · 2026-03-06T22:49:11Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

github-actions · 2026-04-16T01:04:56Z

This pull request has been marked as stale because it has been open (more than) 30 days with no activity. Remove the stale label or add a comment saying that you would like to have the label removed otherwise this pull request will automatically be closed in 7 days. Note, that you can always re-open a closed pull request at any time.

josuah · 2026-04-25T14:00:34Z

Force-push:

Rebase on latest main

maass-hamburg · 2026-04-27T07:55:25Z


-For the USB host functionality a supported host controller is required,
-currently it is only MAX3421E. The example can be built as follows:
+Assuming the board has a supported USB device controller, the example can be


Suggested change

Assuming the board has a supported USB device controller, the example can be

Assuming the board has a supported USB host controller, the example can be

host not device

Good catch.

maass-hamburg · 2026-04-27T07:55:57Z

+.. zephyr-app-commands::
+   :zephyr-app: samples/subsys/usb/shell
+   :board: nrf52840dk/nrf52840
+   :shield: sparkfun_max3421e


if we assume that the board ahs a host controller, then the shield should not be needed

Very true, the description does say "assuming the board has a supported USB host controller", picking FRDM-RW612 in the meantime that nRF54LM20's DWC2 is ready.

still in it

maass-hamburg · 2026-04-27T08:12:25Z

    platform_allow:
      - nrf52840dk/nrf52840
      - frdm_k64f
    build_only: true


if we take the changes of #105083 for adding the usbh tag

nrf52840dk/nrf52840 and frdm_k64f both don't not have that tag, so it wouldn't be tested

Might be an idea to have two cases of this, one that depends of the usbh tag but without the shield and one for the shield variant but then without the usbh tag, as the original boards don't have a host controller

Good point, there is no tag for shields.

maass-hamburg · 2026-04-27T10:10:48Z

      - shield
    extra_args:
-      - CONF_FILE="device_and_host_prj.conf"
+      - CONF_FILE="prj_host.conf"


if we use the CONF_FILE argument the board specific files in boards are ignored. see https://docs.zephyrproject.org/latest/build/kconfig/setting.html#the-initial-configuration But for qemu boards i need to set

CONFIG_QEMU_EXTRA_FLAGS="-device usb-ccid"

for example (see https://qemu-project.gitlab.io/qemu/system/devices/usb.html) to add usb devices to the bus

To avoid skipping board-specific conf, there need to be no -DCONF_FILE, we can only rely on -DEXTRA_CONF_FILE= and -DFILE_SUFFIX=.

I suspect enabling the USB Host/Device controllers might happen in a board-specific way, so this narrows it down to FILE_SUFFIX= to have have per-board host/device variants too.

I will try with this thank you.

josuah · 2026-04-27T14:17:43Z

@maass-hamburg does it solve your use-case now?

It should be possible to have a boards/qemu_cortex_m3_host.conf with CONFIG_QEMU_EXTRA_FLAGS="-device usb-ccid" inside.

jfischer-no · 2026-04-27T15:05:02Z

+
+.. zephyr-app-commands::
+   :zephyr-app: samples/subsys/usb/shell
+   :board: frdm_k11f


What board is frdm_k11f?

This is a plain typo! In reaction to #105005 (comment) I tried to pick a board with zephyr_uhc0 enabled, and found frdm_k22f.

What board should I target for the host-only operation?

jfischer-no · 2026-04-27T15:21:32Z

+Assuming the board has **both** a supported USB device and host controller
+(i.e. using an USB host shield), the example can be built like:


Suggested change

Assuming the board has **both** a supported USB device and host controller

(i.e. using an USB host shield), the example can be built like:

Assuming the board has a supported USB device and host controller,

the example can be built like:

Also, I want to keep device_and_host, perhaps renamed to prj_device_and_host.conf. The meaning of both is unclear. I also prefer to explicitly describe how prj_*.conf is supposed to be used because things like -DFILE_SUFFIX=both are less accessible.

done

I confirm native_sim works:

$ west twister -s sample.usbh.shell.virtual ... $ twister-out/native_sim_native_64/host_gnu/samples/subsys/usb/shell/sample.usbh.shell.virtual/zephyr/zephyr.exe uart connected to pseudotty: /dev/pts/3 *** Booting Zephyr OS build v4.4.0-1127-ga63b0b2b2587 ***

Then connecting to /dev/pts/3 permits communication with the USB host and device shell to

jfischer-no · 2026-04-27T15:23:12Z

@@ -1,12 +1,13 @@
-CONFIG_SHELL=y


What is the point to reorder all the lines? I do not see a good reason and it just makes it harder to review.

I wanted to merge the host and device side back together after splitting them, but now I realize this is already there upstream, so I should use this instead.

jfischer-no · 2026-04-27T15:25:04Z

+    depends_on:
+      - usbd
+    tags:
+      - usbd


The tag is usb and should not be changed. Should not be mixed with the supported feature usbd this sample depends on. Same applies to usbh.

Thank you for the distinction between features and tags.

jfischer-no · 2026-04-27T15:27:16Z

+    extra_args:
+      - FILE_SUFFIX=host
+    platform_allow:
+      - rd_rw612_bga


Could you verify that this board is working?

No as unfortunately not available to the public.

This was used for UVC Host by @AidenHu.

Glad to know which board to use in the meantime this gets ready. Maybe still using the nRF52840 with the shield for now?

(In the meantime, I am hurrying on DWC2 Host...)

Let's keep rd_rw612_bga, we can replace it with integration_platforms later.

jfischer-no · 2026-04-27T16:22:36Z

-    tags: usb
-    extra_args: CONF_FILE="device_and_host_prj.conf"
+    depends_on:
+      - usbh
+      - usbd
+    tags:
+      - usbh
+      - usbd
+    extra_args:
+      - FILE_SUFFIX=both
+      - EXTRA_DTC_OVERLAY_FILE="virtual.conf"


I wanted to replace qemu_contex_m3 with native_sim for a long time. As you are changing it, please replace platform_allow: qemu_cortex_m3 with platform_allow: native_sim. Note, EXTRA_DTC_OVERLAY_FILE should be EXTRA_DTC_OVERLAY_FILE="virtual.overlay". Remove boards/qemu_cortex_m3.* overlays.

I will double-check what the CI is doing, maybe it ignored this so did not raise an error. Sorry for this typo.

In order to allow host-only operation, replace the configuration files by prj_{host,device,device_and_host}.conf selected by the extra command line flag -DFILE_SUFFIX={host,device,device_and_host}. The virtual USB bus is still usable by adding this to any configuration -DEXTRA_DTC_OVERLAY_FILE=virtual.overlay Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

sonarqubecloud · 2026-04-28T01:31:03Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

zephyrbot added area: Samples Samples area: USB Universal Serial Bus labels Mar 6, 2026

zephyrbot requested review from JarmouniA, jfischer-no, kartben, nashif and tmon-nordic March 6, 2026 01:35

zephyrbot assigned jfischer-no Mar 6, 2026

josuah force-pushed the usb_shell_suffix branch 4 times, most recently from c341247 to e708d95 Compare March 6, 2026 22:16

josuah mentioned this pull request Mar 6, 2026

subsys: usb: shell: Added pytest roma-jam-lab/zephyr#6

Open

tmon-nordic previously approved these changes Mar 16, 2026

View reviewed changes

github-actions Bot added the Stale label Apr 16, 2026

github-actions Bot closed this Apr 23, 2026

josuah reopened this Apr 25, 2026

josuah removed the Stale label Apr 25, 2026

josuah force-pushed the usb_shell_suffix branch from e708d95 to 6411aa8 Compare April 25, 2026 14:00

This was referenced Apr 25, 2026

drivers: usb: add generic ohci host driver #107065

Open

DWC2 USB Host controller (UHC) #102931

Open

maass-hamburg reviewed Apr 27, 2026

View reviewed changes

josuah dismissed tmon-nordic’s stale review via 310c63c April 27, 2026 13:56

josuah force-pushed the usb_shell_suffix branch from 6411aa8 to 310c63c Compare April 27, 2026 13:56

jfischer-no requested changes Apr 27, 2026

View reviewed changes

josuah force-pushed the usb_shell_suffix branch from 310c63c to 59fce8d Compare April 28, 2026 00:30

jfischer-no approved these changes Apr 28, 2026

View reviewed changes

josuah requested review from maass-hamburg and tmon-nordic April 28, 2026 12:27

tmon-nordic approved these changes Apr 28, 2026

View reviewed changes

kartben merged commit ae4cf3b into zephyrproject-rtos:main Apr 28, 2026
20 checks passed

	Assuming the board has a supported USB device controller, the example can be
	Assuming the board has a supported USB host controller, the example can be

		Assuming the board has both a supported USB device and host controller
		(i.e. using an USB host shield), the example can be built like:

Conversation

josuah commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Testing device (hardware):

Testing host + virtual (native_sim):

Testing device + host + virtual (native_sim):

Uh oh!

josuah commented Mar 6, 2026

Uh oh!

sonarqubecloud Bot commented Mar 6, 2026

Quality Gate passed

Uh oh!

github-actions Bot commented Apr 16, 2026

Uh oh!

josuah commented Apr 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

josuah Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

josuah commented Apr 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented Apr 28, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

josuah commented Mar 6, 2026 •

edited

Loading

Testing `device` (hardware):

Testing `host` + `virtual` (native_sim):

Testing `device` + `host` + `virtual` (native_sim):

josuah Apr 27, 2026 •

edited

Loading