README.rst
1.. zephyr:code-sample:: legacy-webusb
2 :name: Legacy WebUSB
3 :relevant-api: _usb_device_core_api
4
5 Receive and echo data from a web page using WebUSB API.
6
7For a deeper dive into the WebUSB, refer to
8https://developers.google.com/web/updates/2016/03/access-usb-devices-on-the-web
9
10WebUSB API Specification:
11https://wicg.github.io/webusb/
12
13Overview
14********
15
16This simple echo application demonstrates the WebUSB sample application.
17This application receives the data and echoes back to the WebUSB
18based web application (web page) running in the browser at host.
19This application is intended for testing purposes only. For running
20real usecase, implement applications based on the WebUSB API.
21This sample can be found under :zephyr_file:`samples/subsys/usb/legacy/webusb` in the
22Zephyr project tree.
23
24.. note::
25 This samples demonstrate deprecated :ref:`usb_device_stack`.
26
27Requirements
28************
29
30This project requires an USB device driver, which is available for multiple
31boards supported in Zephyr.
32
33Building and Running
34********************
35
36Build and flash webusb sample with:
37
38.. zephyr-app-commands::
39 :zephyr-app: samples/subsys/usb/legacy/webusb
40 :board: <board to use>
41 :goals: flash
42 :compact:
43
44Testing with the latest Google Chrome on host
45*********************************************
46
47This sample application requires the latest Google Chrome, a web page
48based on WebUSB API to connect to the USB device and optionally
49http server running on localhost to serve the web page.
50
51WebUSB is a powerful new feature added to the Web and it is available
52only to secure origins. This means the web page/site that is used to
53connect to the device must be served over a secure connection (HTTPS).
54
55Follow these steps to run the demo on your host system:
56
57#. Run the latest Google Chrome on host.
58
59#. Implement a web app (web page) using WebUSB API and run
60 it on localhost.
61
62 The sample can be found in the webusb sample directory:
63 :zephyr_file:`samples/subsys/usb/legacy/webusb/index.html`.
64
65 This sample web page demonstrates how to create and use a WebUSB
66 interface, as well as demonstrate the communication between browser
67 and WebUSB enabled device.
68
69 There are two ways to access this sample page:
70
71 * Using Chrome browser go to :doc:`demo`
72
73 * Host the demo page locally: Start a web server
74 in the webusb sample directory.
75
76 .. code-block:: console
77
78 $ python -m http.server
79
80 Using Chrome browser open url http://localhost:8001/
81
82#. Connect the board to your host.
83
84#. Once the device is booted, you should see a notification from
85 Chrome: "Go to localhost to connect.". Click on the notification
86 to open demo page.
87 Note that at the moment WebUSB landing page notification is disabled
88 in Chrome on Windows. See https://github.com/WICG/webusb#implementation-status
89
90#. Click on the :guilabel:`Connect` button to connect to the device.
91
92#. Send some text to the device by clicking on the :guilabel:`Send` button.
93 The demo app will receive the same text from the device and display it in
94 the text area.
95