zephyr

History

Tomasz Moń 2f24adbe0f usb: device: Do not claim to be USB 3.2 device The bcdUSB value 0x0210 defined in USB 3.2 Specification indicates USB 3.2 device operating in one of the USB 2.0 modes. USB 2.0 Link Power Management Addendum defines bcdUSB value 0x0201 to indicate that USB 2.0 device supports the request to read the BOS Descriptor. The main difference between bcdUSB 0x0210 and 0x0201 is that the USB 3.2 device must support LPM, while USB 2.0 devices can (but are not required to) support LPM. The difference is respected by USB 3 Gen X Command Verifier (2.3.0.0) Chapter 9 Tests [USB 2 devices], where the test behaves as follows: * For bcdUSB 0x0200: Checking Device Under Test for LPM L1 Compatibility... USB version of device is 2.00. DUT is NOT compatible with LPM. LPM is NOT required for DUT LPM is only supported in USB version 2.01 and above. * For bcdUSB 0x0201: Checking Device Under Test for LPM L1 Compatibility... USB version of device is 2.01. DUT IS compatible with LPM. LPM is NOT required for DUT USB 2.0 Extension Descriptor bmAttributes: LPM Capable = 0 BESL and Alternate HIRD Supported = 0 Baseline BESL Valid = 0 Deep BESL Valid = 0 Baseline BESL: 0d Deep BESL: 0d LPM is not supported * For bcdUSB 0x0210: Checking Device Under Test for LPM L1 Compatibility... USB version of device is 2.10. DUT IS compatible with LPM. LPM IS required for DUT USB 2.0 Extension Descriptor bmAttributes: LPM Capable = 0 BESL and Alternate HIRD Supported = 0 Baseline BESL Valid = 0 Deep BESL Valid = 0 Baseline BESL: 0d Deep BESL: 0d (USB: 9.6.2.1.6) Bit 1 in Attributes field of a USB 2.0 Extension descriptor returned in response to a GetDescriptor(BOS) request must be 1 for LS/FS/HS devices that support LPM L1. The test fails when LPM bit is not set in USB 2.0 Extension Descriptor only when bcdUSB is 0x0210. The test failure was incorrectly fixed in commit `312429be3c` ("usb: samples: Add Extension descriptor to webUSB sample."). Properly fix the issue by changing bcdUSB to 0x0201 and removing the false LPM support claim. The false LPM claim was leading to device ceasing to work after some time if there was no traffic from host to device (when the host is likely to have executed the LPM L1 transition that was not properly handled by the device). Signed-off-by: Tomasz Moń <tomasz.mon@nordicsemi.no>		2024-05-06 14:54:23 +01:00
..
src	usb: device: Do not claim to be USB 3.2 device	2024-05-06 14:54:23 +01:00
CMakeLists.txt	cmake: increase minimal required version to 3.20.0	2021-08-20 09:47:34 +02:00
demo.rst	samples: webusb: Include demo.rst to documentation	2023-09-25 09:48:01 +02:00
index.html	samples: webusb: Fix HTML validator issues	2023-09-25 09:48:01 +02:00
prj.conf	samples: Explicitly disable boot USB device support init at boot	2023-01-10 12:21:10 +01:00
README.rst	samples: webusb: Update README	2023-09-25 09:48:01 +02:00
sample.yaml	samples/subsys: Use hwmv2 native targets identifiers	2024-03-15 16:13:12 +01:00

README.rst

.. zephyr:code-sample:: webusb
   :name: WebUSB
   :relevant-api: usbd_api

   Receive and echo data from a web page using WebUSB API.

For a deeper dive into the WebUSB, refer to
https://developers.google.com/web/updates/2016/03/access-usb-devices-on-the-web

WebUSB API Specification:
https://wicg.github.io/webusb/

Overview
********

This simple echo application demonstrates the WebUSB sample application.
This application receives the data and echoes back to the WebUSB
based web application (web page) running in the browser at host.
This application is intended for testing purposes only. For running
real usecase, implement applications based on the WebUSB API.
This sample can be found under :zephyr_file:`samples/subsys/usb/webusb` in the
Zephyr project tree.

Requirements
************

This project requires an USB device driver, which is available for multiple
boards supported in Zephyr.

Building and Running
********************

Build and flash webusb sample with:

.. zephyr-app-commands::
   :zephyr-app: samples/subsys/usb/webusb
   :board: <board to use>
   :goals: flash
   :compact:

Testing with the latest Google Chrome on host
*********************************************

This sample application requires the latest Google Chrome, a web page
based on WebUSB API to connect to the USB device and optionally
http server running on localhost to serve the web page.

WebUSB is a powerful new feature added to the Web and it is available
only to secure origins. This means the web page/site that is used to
connect to the device must be served over a secure connection (HTTPS).

Follow these steps to run the demo on your host system:

#. Run the latest Google Chrome on host.

#. Implement a web app (web page) using WebUSB API and run
   it on localhost.

   The sample can be found in the webusb sample directory:
   :zephyr_file:`samples/subsys/usb/webusb/index.html`.

   This sample web page demonstrates how to create and use a WebUSB
   interface, as well as demonstrate the communication between browser
   and WebUSB enabled device.

   There are two ways to access this sample page:

   * Using Chrome browser go to :doc:`demo`

   * Host the demo page locally: Start a web server
     in the webusb sample directory.

     .. code-block:: console

        $ python -m http.server

     Using Chrome browser open url http://localhost:8001/

#. Connect the board to your host.

#. Once the device is booted, you should see a notification from
   Chrome: "Go to localhost to connect.". Click on the notification
   to open demo page.
   Note that at the moment WebUSB landing page notification is disabled
   in Chrome on Windows. See https://github.com/WICG/webusb#implementation-status

#. Click on the :guilabel:`Connect` button to connect to the device.

#. Send some text to the device by clicking on the :guilabel:`Send` button.
   The demo app will receive the same text from the device and display it in
   the text area.