# Using WebUSB with Arduino and TinyUSB ## Overview ![](https://cdn-learn.adafruit.com/assets/assets/000/080/077/medium800thumb/arduino_compatibles_webusb.jpg?1566937518) This guide will show how the combination of the Open Source TinyUSB USB port software and the Chrome WebUSB browser capability provides programmers and users the ability to plug in microcontroller-based projects and have them interact with the user in a web browser. No additional code is required on the display computer other than a standard Chrome browser window (ie. no plug-ins, etc.) This capability is ideal for schools, learning, ease of use, and assistive technology applications. ![](https://cdn-learn.adafruit.com/assets/assets/000/079/418/medium800/arduino_compatibles_webusb_and_tinyusb.jpg?1565794396) ## What is WebUSB? [WebUSB](https://developers.google.com/web/updates/2016/03/access-usb-devices-on-the-web) is a recent standard for securely providing access to USB devices from web pages. It is available in Chrome 61 since September, 2017 and all current versions. One of the reasons the WebUSB API has been created: to provide a way to expose USB device services to the Web. With this API, hardware manufacturers are able to build cross-platform JavaScript SDKs for their devices. But most importantly, this  **makes USB safer and easier to use by bringing it to the Web**. Let's see what you can expect with the WebUSB API: 1. Buy a USB device. 2. Plug it into your computer. 3. A notification appears right away, with the right website to go to for this device. 4. Simply click on it. Website is there and ready to use! 5. Click to connect and a USB device chooser shows up in Chrome, where you can pick your device. 6. Tada! What would this procedure be like without the WebUSB API? - Read a box, label, or search on line and possibly end up on the wrong website. - Have to install a native application. - Is it supported on my operating system? Make sure you download the "right" thing. - Scary OS prompts popup and warn you about installing drivers/applications from the Internet. - Malfunctioning code harms the whole computer. The Web is built to [contain malfunctioning websites](https://www.youtube.com/watch?v=29e0CtgXZSI). - Only use the USB device once? On the Web, the website is gone once you closed tab. On a computer the code sticks around. ![](https://cdn-learn.adafruit.com/assets/assets/000/079/417/medium800/arduino_compatibles_tinyusb-single.png?1565793872) ## How does TinyUSB Help? [TinyUSB](https://github.com/hathach/tinyusb) is an open-source cross-platform USB Host/Device stack for embedded system. It is designed to be memory-safe with no dynamic allocation and thread-safe with all interrupt events are deferred then handled in the stack's task function. While there are some other USB stacks for microcontrollers, notably the Arduino stack, TinyUSB is compatible with a wide range of microcontrollers, has better device support, and is MIT licensed. The TinyUSB library is on Adafruit's GitHub repo [here](https://github.com/adafruit/Adafruit_TinyUSB_Arduino). ## WebUSB and TinyUSB Together Adafruit has worked to ensure TinyUSB works with WebUSB. Together, they allow Adafruit and compatible microcontrollers to work with WebUSB browsers like Chrome with no drivers on the host computer/tablet/phone/chromebook. Super simple and this works well in environments like schools. # Using WebUSB with Arduino and TinyUSB ## Computer and Mobile Hardware ![](https://cdn-learn.adafruit.com/assets/assets/000/079/419/medium800/arduino_compatibles_jessica-lewis-jemhCs-d_vU-unsplash-trim.jpg?1565796789 Photo by Jessica Lewis on Unsplash) ## Computers and Chrome This project has been tested with computers running Windows 10, OSX, and Linux. The only requirement is the Chrome browser must be loaded and the version of the browser must be 61 or higher (best to be near the latest version). A Chromebook with the latest software was tested and this project works great. The Chromebook is a Samsung model that dates from perhaps 2017. The ChromeOS software was updated to ensure the best compatibility. Most desktops work fine with Chrome including PC, mac, and Linux. The browser is a bit of a memory hog but WebUSB compatibility doesn't add any significant memory use. ## Mobile Devices Support has been tested with iPhone and Android as they both support Chrome. There may be security prompts asking if it is ok for Chrome to use the USB port, to which you should answer yes.  ## Computer / Mobile Device USB Port To use WebUSB, your computing device needs to have a free USB port (USB 2 is fine). Some devices do not have a USB port but some other connector (like Apple Lightning connectors). You will need an adaptor device or cable to convert that port to a USB port (and beware, not all adaptors are equally effective). Some modern Android devices have a USB C port while older devices have a micro-B USB port. The goal is getting a cable that will connect the version of USB present to a micro-B USB plug. Here are some cables that may help bridge the gap between the microcontroller and the computer/mobile USB port: - [Micro-B USB to micro-B USB OTG, 10 inches/25 cm cable](https://www.adafruit.com/product/3610) - USB A to micro-B USB cable - [3 foot](https://www.adafruit.com/product/592) and [2 meter](https://www.adafruit.com/product/2185) - [USB C to micro-B USB cable](https://www.adafruit.com/product/3878) - [iOS Lightning to USB OTG Cable](https://www.adafruit.com/product/3940) - [USB 3-in-1 Sync and Charge micro-B / Type C / Lightning Cable](https://www.adafruit.com/product/3679) OTG stands for On the Go, and is required for some mobile devices to recognize external connections. # Using WebUSB with Arduino and TinyUSB ## Compatible Microcontrollers Adafruit has tested WebUSB and TinyUSB with Microchip (formerly Atmel) ATSAMD21 and ATSAMD51 based processor boards sold by Adafruit. The Nordic nRF52840 is also supported by TinyUSB. ![](https://cdn-learn.adafruit.com/assets/assets/000/079/439/medium800/arduino_compatibles_C01F004.png?1565809868) ## Circuit Playground Express This project will use the ATSAMD21-based Adafruit Circuit Playground Express (CPX). This board has sensors, buttons, and NeoPixel LEDs to provide an excellent test platform. USB connectivity is via a micro-B USB connection. The Circuit Playground Express supports a number of programming methods including CircuitPython, Microsoft MakeCode, and Arduino. Adafruit has developed demonstrations of WebUSB and TinyUSB in Arduino as of the publication of this guide. # Using WebUSB with Arduino and TinyUSB ## Install the Arduino IDE ![](https://cdn-learn.adafruit.com/assets/assets/000/079/455/medium800/arduino_compatibles_C08F001.png?1565818023) The Arduino IDE (Integrated Development Environment) is a graphics interface to a language based on C/C++. It is used extensively for programming a very wide variety of microcontrollers. If you do not have the latest version of the Arduino IDE software, it is suggested you download and install the latest version. The latest versions of the Arduino IDE have a library manager and board manager which are needed. It also has a new feature to switch between the ARduino USB Stack and the TinyUSB stack. for those reasons, using the WebUSB code should be used only on very recent IDE versions. See the following pages on the steps to download the IDE and install it on your operating system. - [Download Software](https://learn.adafruit.com/using-webusb-with-arduino-and-tinyusb/download-software) - [Install Software Windows](https://learn.adafruit.com/using-webusb-with-arduino-and-tinyusb/install-software-windows) - [Install Software Mac](https://learn.adafruit.com/using-webusb-with-arduino-and-tinyusb/install-software-mac-os-x) - [Install Software Linux](https://learn.adafruit.com/using-webusb-with-arduino-and-tinyusb/install-software-linux) # Using WebUSB with Arduino and TinyUSB ## Library, Board, and TinyUSB Selection Once you have the Arduino IDE installed or updated, you will need to set some parameters to get the right libraries, board definition file, and the TinyUSB stack. ## Install Libraries In the Arduino IDE menus, go to **Sketch** -\> **Include Library** -\> **Manage Libraries**. You will need to ensure you have the latest versions of the following libraries: - **Adafruit\_TinyUSB** - **Adafruit\_NeoPixel** ![arduino_compatibles_library-manager.png](https://cdn-learn.adafruit.com/assets/assets/000/079/656/medium640/arduino_compatibles_library-manager.png?1566334576) ![arduino_compatibles_Capture.jpg](https://cdn-learn.adafruit.com/assets/assets/000/079/657/medium640/arduino_compatibles_Capture.jpg?1566334840) ![arduino_compatibles_Capture2.jpg](https://cdn-learn.adafruit.com/assets/assets/000/079/658/medium640/arduino_compatibles_Capture2.jpg?1566334956) ## Board Definition File You will need to test this on an Adafruit SAMD board such as the Circuit Playground Express, Metro Express M0/M4, Feather Express M0/M4, and others. In the menu go to **Tools** -\> **Board** -\> **Boards Manager**. Type in **Adafruit SAMD** to search. It will likely pull up both the Arduino SAMD board package and the Adafruit SAMD board package. Select the **Adafruit SAMD** package and ensure it is at least version 1.5.3 or higher for TinyUSB and WebUSB work. ![arduino_compatibles_board-manager.png](https://cdn-learn.adafruit.com/assets/assets/000/079/660/medium640/arduino_compatibles_board-manager.png?1566335212) ![arduino_compatibles_Capture3.jpg](https://cdn-learn.adafruit.com/assets/assets/000/079/662/medium640/arduino_compatibles_Capture3.jpg?1566335541) Info: ## Using the TinyUSB Stack Finally, go to **Tools** -\> **USB Stack** and select **TinyUSB**. If this is not selectable, update your version of the Arduino IDE. Switching the USB stack puts in TinyUSB instead of the default Arduino USB stack. TinyUSB has more features including WebUSB support. ![arduino_compatibles_tinyusb_stack.png](https://cdn-learn.adafruit.com/assets/assets/000/079/666/medium640/arduino_compatibles_tinyusb_stack.png?1566335756) ## All set for the Circuit Playground Express The screen below shows the Arduino IDE with a Circuit Playground Express board. The CPX is plugged in and in bootloader mode by tapping Reset once or twice and seeing a circle of green lights. See the settings circled in red. ![](https://cdn-learn.adafruit.com/assets/assets/000/080/025/medium800/arduino_compatibles_setup_done.png?1566916320) Ok, that is all the configuration needed to work with the code in the two examples next. # Using WebUSB with Arduino and TinyUSB ## RGB Color Picker Example This sketch demonstrates a microcontroller receiving color information from a browser with WebUSB support (re. Chrome). # Quickstart for Circuit Playground Express If you're using a Circuit Playground Express, you can download this UF2, and install it by double-clicking into **CPLAYBOOT** mode and dragging over the UF2 file [CPX_WebUSB_Color_Picker.UF2](https://cdn-learn.adafruit.com/assets/assets/000/080/069/original/CPX_WebUSB_Color_Picker.UF2?1566935109) ## Load the Example Code to Your Microcontroller Click Download in the code window below and save the Arduino sketch in your Arduino file folder. Open the code with the Arduino IDE **File** -\> **Open** command. https://github.com/adafruit/Adafruit_TinyUSB_Arduino/blob/master/examples/WebUSB/webusb_rgb/webusb_rgb.ino Ensure you have set up the IDE per the previous instructions for the board type, correct library, and use of TinyUSB. Connect the microcontroller to your computer/device via the USB cabling discussed previously. Place your Circuit Playground Express in bootloader mode by pressing the tiny onboard reset button once or twice (depending on how it was programmed earlier). The board should flash red briefly and then display a green circle of lights. Select the correct port for the board in the IDE by going to **Tools** -\> **Port** in the menus and you should see the Circuit Playground Express listed as a possible selection. Use **Sketch** -\> **Upload** (or the circle with the right arrow button) to load the Arduino code onto the Circuit Playground Express. If you get any compile errors, look on the previous page for library requirements, the correct board definition file, and selecting TinyUSB. After upload, the ring of NeoPixel LEDs will turn red. The board is now ready to test. ## Use After enumerating successfully Chrome will pop-up a notification with a URL to a landing page, click on it to test. On Windows there is a [known bug](https*/,%20%22adafruit.github.io/Adafruit_TinyUSB_Arduino/examples/webusb-rgb), you'll have to click on the button below to go to the test web page. [Test Web Page for the RGB Color Picker Example](https://adafruit.github.io/Adafruit_TinyUSB_Arduino/examples/webusb-rgb/index.html) Click  **Connect**  and select your microcontroller. For example: Circuit Playground Express. If you see text "Unknown Device", that can happen and it should connect if selected. Changing USB ports often clears this text up. ![arduino_compatibles_rgb_connect.png](https://cdn-learn.adafruit.com/assets/assets/000/080/064/medium640/arduino_compatibles_rgb_connect.png?1566934300) When connected the NeoPixel LEDs will change color to Green, the same color as on screen. ![arduino_compatibles_windows_RGB.jpg](https://cdn-learn.adafruit.com/assets/assets/000/080/026/medium640/arduino_compatibles_windows_RGB.jpg?1566917586) Now click the green circle. You will see an operating system dependent pop-up asking you to pick a new color for the NeoPixels. Select a color and click "Ok". I'll pick blue for my choice. ![arduino_compatibles_windows_RGB_select.jpg](https://cdn-learn.adafruit.com/assets/assets/000/080/027/medium640/arduino_compatibles_windows_RGB_select.jpg?1566917718) You will then see the web page again and all the LEDs will now be blue (or whatever color you chose). ![arduino_compatibles_hero.jpg](https://cdn-learn.adafruit.com/assets/assets/000/080/065/medium640/arduino_compatibles_hero.jpg?1566934428) ## Behind the Scenes The computer/mobile device will, behind the scenes, send a color value from the browser in the format '#RRGGBB'. The Arduino sketch will change the color of the microcontroller's onboard NeoPixels accordingly. When connected, this process may continue indefinitely, the board will change color to whatever color you chose in the browser. This demonstrates one way communication from the browser to the microcontroller. When done, you can click the **Disconnect** button to stop communications. ![](https://cdn-learn.adafruit.com/assets/assets/000/080/078/medium800thumb/arduino_compatibles_webusb.jpg?1566937549) # Using WebUSB with Arduino and TinyUSB ## Serial Communications Example This sketch demonstrates WebUSB sending text from the browser to a microcontroller which in turn sends the text back to the browser. ## Load the Example Code to Your Microcontroller Click Download in the code window below and save the Arduino sketch in your Arduino sketches folder. Open the code with the Arduino IDE **File** -\> **Open** command. https://github.com/adafruit/Adafruit_TinyUSB_Arduino/blob/master/examples/WebUSB/webusb_serial/webusb_serial.ino Ensure you have set up the IDE per the previous instructions for the board type, correct library, and use of TinyUSB. Connect the microcontroller to your computer/device via the USB cabling discussed previously. Place your Circuit Playground Express in bootloader mode by pressing the tiny onboard reset button once or twice (depending on how it was programmed earlier). The board should flash red briefly and then display a green circle of lights. Select the correct port for the board in the IDE by going to **Tools** -\> **Port** in the menus and you should see the Circuit Playground Express listed as a possible selection. Use **Sketch** -\> **Upload** (or the circle with the right arrow button) to load the Arduino code onto the Circuit Playground Express. If you get any compile errors, look on the previous page for library requirements, the correct board definition file, and selecting TinyUSB. After upload, the ring of NeoPixel LEDs on the CPX will turn off. The board is now ready to test. ## Use Warning: After enumerating successfully, Chrome will pop-up a notification with a URL to a landing page, click on it to test. On Windows there is a [known bug](https*/,%20%22adafruit.github.io/Adafruit_TinyUSB_Arduino/examples/webusb-rgb), you'll have to click on the button below to go to the test web page. [Test Web Page for the Serial Communications Example](https://adafruit.github.io/Adafruit_TinyUSB_Arduino/examples/webusb-serial/index.html) Click "Connect" and select your microcontroller. For example: Circuit Playground Express. When connected, the right Receiver window will display the text "TinyUSB WebUSB Serial example" - this is the board sending its first text message to the browser via WebUSB. ![](https://cdn-learn.adafruit.com/assets/assets/000/080/062/medium800/arduino_compatibles_serial_connect_-_trim.png?1566933991) Click inside the left Sender window with your mouse or cursor.  Type something such as "Adabot is my friend" As you type, the characters are echoed in the receiver window.  The last line shows that I used a backspace to correct a typo. The echo routine in the Arduino example code doesn't recognize backspace as going back one character so the mistyped character is echoed in the Receiver window. ![](https://cdn-learn.adafruit.com/assets/assets/000/080/063/medium800/arduino_compatibles_serial_use_-_trim.png?1566934029) ## Behind the Scenes The computer/mobile device sends character data from the browser Sender window to the microcontroller via the USB serial connection. The microcontroller looks for text and immediately sends the text back via WebUSB to the browser where it appears in the Receiver window. When connected, this process may continue indefinitely, the board will continuing echoing typed text. The microcontroller does not recognize extended keyboard input at present (as shown with backspace). This demonstrates two way communications from the browser to the microcontroller. The Arduino program can be changed to do any manner of serial communication, unidirectional or bidirectional. When done, you can click the Disconnect button to stop communications. ## Featured Products ### Circuit Playground Express [Circuit Playground Express](https://www.adafruit.com/product/3333) **Circuit Playground Express** is the next step towards a perfect introduction to electronics and programming. We've taken the original Circuit Playground Classic and made it even better! Not only did we pack even more sensors in, we also made it even easier to... In Stock [Buy Now](https://www.adafruit.com/product/3333) [Related Guides to the Product](https://learn.adafruit.com/products/3333/guides) ### USB A/Micro Cable - 2m [USB A/Micro Cable - 2m](https://www.adafruit.com/product/2185) This is your standard USB A-Plug to Micro-USB cable. It's 2 meters long so you'll have plenty of cord to work with for those longer extensions. In Stock [Buy Now](https://www.adafruit.com/product/2185) [Related Guides to the Product](https://learn.adafruit.com/products/2185/guides) ### USB cable - USB A to Micro-B [USB cable - USB A to Micro-B](https://www.adafruit.com/product/592) This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or microcontroller Approximately 3 feet / 1 meter long In Stock [Buy Now](https://www.adafruit.com/product/592) [Related Guides to the Product](https://learn.adafruit.com/products/592/guides) ### USB C to Micro B Cable - 3 ft 1 meter [USB C to Micro B Cable - 3 ft 1 meter](https://www.adafruit.com/product/3878) As technology changes and adapts, so does Adafruit! Rather than the regular USB A, this cable has  **USB C to Micro B**  plugs! USB C is the latest industry-standard connector for transmitting data _and_ power. Like Lightning and MagSafe cables, USB C has no... Out of Stock [Buy Now](https://www.adafruit.com/product/3878) [Related Guides to the Product](https://learn.adafruit.com/products/3878/guides) ### Micro USB to Micro USB OTG Cable - 10-12" / 25-30cm long [Micro USB to Micro USB OTG Cable - 10-12" / 25-30cm long](https://www.adafruit.com/product/3610) This cable is a little unusual, rather than having a USB A plug on one end, it has _two_ Micro B USB connections! What is this for? It's for when you have a "USB On-The-Go (OTG)" device, and you want to plug in another USB device. For example, a Pi Zero or Pi Zero W has a... In Stock [Buy Now](https://www.adafruit.com/product/3610) [Related Guides to the Product](https://learn.adafruit.com/products/3610/guides) ### USB 3-in-1 Sync and Charge Cable - Micro B / Type-C / Lightning [USB 3-in-1 Sync and Charge Cable - Micro B / Type-C / Lightning](https://www.adafruit.com/product/3679) As USB technology evolves you'll want the **One Cable To Sync/Charge All Things** (or, at least, portable devices with Micro-B, Type C, or Lightning ports) and this cable will do the job nicely This very nice **USB 3-in-1 Charging Cable** looks like... No Longer Stocked [Buy Now](https://www.adafruit.com/product/3679) [Related Guides to the Product](https://learn.adafruit.com/products/3679/guides) ### iOS Lightning to USB OTG Cable [iOS Lightning to USB OTG Cable](https://www.adafruit.com/product/3940) Your iOS phone or tablet may not have a USB port on the bottom but that doesn't mean you can't use it to connect USB devices. Secretly known as a 'Camera Connector' or 'MIDI Connector' cable, this doohicky plugs into the bottom of your iOs device and gives you a USB A... In Stock [Buy Now](https://www.adafruit.com/product/3940) [Related Guides to the Product](https://learn.adafruit.com/products/3940/guides) ## Related Guides - [Adafruit Circuit Playground Express](https://learn.adafruit.com/adafruit-circuit-playground-express.md) - [Mount for CRICKIT](https://learn.adafruit.com/mount-for-crickit.md) - [LEGO Compatible Crickit Rover](https://learn.adafruit.com/lego-compatible-crickit-rover.md) - [Hello World of Robotics with Crickit](https://learn.adafruit.com/hello-world-of-robotics-with-crickit.md) - [Sewable NeoPixels](https://learn.adafruit.com/flora-rgb-smart-pixels.md) - [Using Servos With CircuitPython and Arduino](https://learn.adafruit.com/using-servos-with-circuitpython.md) - [Stumble-Bot](https://learn.adafruit.com/stumble-bot-with-circuit-playground-and-crickit.md) - [Make It Sound](https://learn.adafruit.com/make-it-sound.md) - [Easter Egg Light Stand](https://learn.adafruit.com/easter-egg-light-stand.md) - [Pushrod Garage](https://learn.adafruit.com/pushrod-garage.md) - [Datalogging and File Storage in MakeCode](https://learn.adafruit.com/data-logging-and-file-storage-in-makecode.md) - [CPX Mystery Dreidel](https://learn.adafruit.com/cpx-mystery-dreidel.md) - [Trash Panda](https://learn.adafruit.com/trash-panda-circuit-python-crickit.md) - [Jellyfish Umbrella with easy WLED WiFi Control](https://learn.adafruit.com/jellyfish-umbrella-with-easy-wled-wifi-control.md) - [Make It Glow With Crickit](https://learn.adafruit.com/make-it-glow-with-crickit.md) - [Snap Fit Mount for Circuit Playground Express](https://learn.adafruit.com/snap-fit-mount-for-circuit-playground-express.md)