1.. zephyr:code-sample:: webusb
2   :name: WebUSB
3   :relevant-api: usbd_api
4
5   Receive and echo data from a web page using WebUSB API.
6
7Overview
8********
9
10This sample demonstrates how to use the Binary Device Object Store (BOS),
11Microsoft OS 2.0 descriptors, and WebUSB descriptors to implement a WebUSB
12sample application. The sample USB function receives the data and echoes back
13to the WebUSB API based application running in the browser on your local host.
14This sample can be found at :zephyr_file:`samples/subsys/usb/webusb` in the
15Zephyr project tree.
16
17Requirements
18************
19
20This project requires a USB device controller driver using the UDC API.
21On your host computer, this project requires a web browser that supports the
22WebUSB API, such as Chromium or a Chromium-based browser.
23
24Building and Running
25********************
26
27Build and flash webusb sample with:
28
29.. zephyr-app-commands::
30   :zephyr-app: samples/subsys/usb/webusb
31   :board: <board to use>
32   :goals: flash
33   :compact:
34
35Demonstration
36*************
37
38The sample includes a simple WebUSB API application and can be found in the
39sample directory: :zephyr_file:`samples/subsys/usb/webusb/index.html`.
40
41There are two ways to access this sample page:
42
43* Using browser go to :doc:`demo`
44
45* Start a web server in the sample directory:
46
47  .. code-block:: console
48
49     $ python -m http.server
50
51Then follow these steps:
52
53#. Connect the board to your host.
54
55#. Once the device has booted, you may see a notification from the browser: "Go
56   to localhost to connect". Click on the notification to open the demo page.  If
57   there is no notification from the browser, open the URL http://localhost:8001/
58   in your browser.
59
60#. Click on the :guilabel:`Connect` button to connect to the device.
61
62#. Send some text to the device by clicking on the :guilabel:`Send` button.
63   The demo application will receive the same text from the device and display
64   it in the text area.
65
66References
67***********
68
69WebUSB API Specification:
70https://wicg.github.io/webusb/
71
72Chrome for Developers, "Access USB Devices on the Web":
73https://developer.chrome.com/docs/capabilities/usb
74