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