# Using a Keyboard with USB Host ## Overview ![Wired USB keyboard with hands resting in the typing position.](https://cdn-learn.adafruit.com/assets/assets/000/136/458/medium800/learn_arduino_usb_wired_keyboard_product_photo.jpg?1745423511 ) A keyboard is a lovely way to enter character data into a computing system. It's much better than the toggle switches or hexadecimal keypads on the earliest computers. These days nearly all keyboards use USB connections. While easy to use with a computer, using USB with a microcontroller system is a bit more challenging with the limited resources available and the complexity of the USB protocol. This guide provides the software, in CircuitPython and Arduino, to interface a USB keyboard with select microcontrollers with USB host capability. Warning: The code presented uses a USB code to character map for a United States 104 key keyboard standard. This can be changed to decode non-US layout keyboards to the correct character input, although that mapping must be done by the user. ## Parts ### Mini Chiclet Keyboard - USB Wired - Black [Mini Chiclet Keyboard - USB Wired - Black](https://www.adafruit.com/product/1736) Add a good quality, slim keyboard to your Raspberry Pi, Beagle Bone Black, or other single-board-computer with this sleek black chiclet keyboard. It's a full QWERTY keyboard with a USB cable and is compatible with all operating systems. We tried many keyboards to find one that felt... In Stock [Buy Now](https://www.adafruit.com/product/1736) [Related Guides to the Product](https://learn.adafruit.com/products/1736/guides) ![Angled shot of a Black woman's silver-blue manicured hands on a slim, black keyboard.](https://cdn-shop.adafruit.com/640x480/1736-04.jpg) ### Adafruit Fruit Jam - Mini RP2350 Computer [Adafruit Fruit Jam - Mini RP2350 Computer](https://www.adafruit.com/product/6200) We were catching up on a recent [hackaday hackchat with eben upton](https://hackaday.io/event/202122-raspberry-pi-hack-chat-with-eben-upton) and learned some fun facts: such as the DVI hack for the RP2040 was inspired by Out of Stock [Buy Now](https://www.adafruit.com/product/6200) [Related Guides to the Product](https://learn.adafruit.com/products/6200/guides) ![Angled shot of assembled mini computer PCB with plate.](https://cdn-shop.adafruit.com/640x480/6200-10.jpg) ### Adafruit Feather RP2040 with USB Type A Host [Adafruit Feather RP2040 with USB Type A Host](https://www.adafruit.com/product/5723) You're probably really used to microcontroller boards with USB, but what about a dev board with two? Two is more than one, so that makes it twice as good! And the  **Adafruit Feather RP2040 with USB Host** is ** ** definitely double-the-fun of our other Feather... In Stock [Buy Now](https://www.adafruit.com/product/5723) [Related Guides to the Product](https://learn.adafruit.com/products/5723/guides) ![Angled shot of black rectangular microcontroller with USB C and USB A connectors at both ends.](https://cdn-shop.adafruit.com/640x480/5723-00.jpg) ### Adafruit Metro RP2350 [Adafruit Metro RP2350](https://www.adafruit.com/product/6003) Choo! Choo! This is the RP2350 Metro Line, making all station stops at "Dual Cortex M33 mountain", "528K RAM round-about" and "16 Megabytes of Flash town". This train is piled high with hardware that complements the Raspberry Pi RP2350 chip to make it an excellent... In Stock [Buy Now](https://www.adafruit.com/product/6003) [Related Guides to the Product](https://learn.adafruit.com/products/6003/guides) ![Angled shot of black, credit card-sized microcontroller with stacking headers.](https://cdn-shop.adafruit.com/640x480/6003-06.jpg) ### Adafruit CH334F Mini 2-Port USB Hub Breakout [Adafruit CH334F Mini 2-Port USB Hub Breakout](https://www.adafruit.com/product/5999) Sometimes, you've got something with a USB host, like an embedded Linux board, and you want to connect more than one thing. Or maybe you want to turn something like a keyboard into a multi-device USB peripheral. The  **Adafruit CH334F Mini 2-Port USB Hub...** In Stock [Buy Now](https://www.adafruit.com/product/5999) [Related Guides to the Product](https://learn.adafruit.com/products/5999/guides) ![Angled shot of black, square-shaped USB breakout board.](https://cdn-shop.adafruit.com/640x480/5999-04.jpg) ### USB Type A Jack Breakout Cable with Premium Female Jumpers [USB Type A Jack Breakout Cable with Premium Female Jumpers](https://www.adafruit.com/product/4449) If you'd like to connect a USB-host-capable chip to your USB peripheral, this cable will make the task very simple.  **There is no converter chip in this cable!**  It's basically a plain USB cable that's cut in half and with jumper sockets on the power and data... In Stock [Buy Now](https://www.adafruit.com/product/4449) [Related Guides to the Product](https://learn.adafruit.com/products/4449/guides) ![USB Type A Socket Breakout Cable with Premium Female Jumpers](https://cdn-shop.adafruit.com/640x480/4449-02.jpg) ### USB Type A to Type C Cable - approx 1 meter / 3 ft long [USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474) As technology changes and adapts, so does Adafruit. This   **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop. USB C is the latest industry-standard connector for... In Stock [Buy Now](https://www.adafruit.com/product/4474) [Related Guides to the Product](https://learn.adafruit.com/products/4474/guides) ![Angled shot of a coiled black, USB-C to USB-A cable.](https://cdn-shop.adafruit.com/640x480/4474-02.jpg) # Using a Keyboard with USB Host ## CircuitPython To read data from a keyboard in CircuitPython, you must use a device which supports USB Host, such as the Adafruit Fruit Jam, Metro RP2350, or Feather RP2040 USB Host.  ### Feather RP2040 USB Host Wiring Connecting to the Feather RP2040 USB Host requires plugging in a USB keyboard to the Feather's Host port. ![USB Keyboard connected to Adafruit USB Host Feather](https://cdn-learn.adafruit.com/assets/assets/000/139/664/medium640/arduino_compatibles_feather_rp2040_kbd_direct.png?1757689879) ### Metro RP2350 USB Host Wiring Connecting to the Metro RP2350 USB Host port requires soldering pins to the broken out USB Host connections as shown in [this guide page](https://learn.adafruit.com/create-a-memory-game-on-metro-rp2350/preparing-the-metro-rp2350). Make the following connections between the Metro USB Host pins and USB Host breakout cable. - **GND** to **Black** wire - **D+** to **Green** wire - **D-** to  **White** wire - **5V** to **Red** red ![Adafruit Metro RP2350 with a USB Host breakout cable connected to the USB Host pins and a USB keyboard plugged in to the Host port.](https://cdn-learn.adafruit.com/assets/assets/000/139/665/medium640/arduino_compatibles_metro_rp2350_kbd_host_breakout.png?1757691682) ### Fruit Jam Mini Computer Connecting to the Fruit Jam requires plugging in a USB keyboard to one of the Fruit Jam's USB Host ports. ![Adafruit Fruit Jam with a USB keyboard plugged in to one of the USB Host ports](https://cdn-learn.adafruit.com/assets/assets/000/139/666/medium640/arduino_compatibles_fruit_jam_kbd_direct.png?1757692924) Warning: As of CircuitPython version 10.0.0-beta.3, the wired USB keyboard works on CircuitPython when connected directly to the USB Host pins or port. Prior releases of CircuitPython required connecting through a USB hub such as the CH334F. ## Demo Code: sys.stdin There are two possible ways to read data from a keyboard in CircuitPython. The less complex way is utilizing `sys.stdin`. Python has the concept of standard input and output streams, similar to those in Linux/Unix and other operating systems. CircuitPython has this capability and through a lot of behind the scenes code, presents a USB keyboard as a `sys.stdin` input device. Due to the way this works it is only possible to know when a key is pressed, not how long it remains pressed, nor when it is released. The `sys.stdin` method defaults to using the standard US layout for the keyboard. You can set a custom layout using the `set_user_keymap()`function [documented here.](https://docs.circuitpython.org/en/latest/shared-bindings/usb_host/index.html#usb_host.set_user_keymap) The code to get USB Host Keyboard characters and echo them to serial out is as follows: https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/USB_Host_Examples/CircuitPython_Keyboard_Stdin/code.py ![CircuitPython serial output showing the word "keyboard" typed in via the connected keyboard.](https://cdn-learn.adafruit.com/assets/assets/000/136/462/medium800thumb/learn_arduino_basic_keyboard_output.jpg?1745429479 ) ## Demo Code: USB Host The other way to read from the keyboard is more involved, the CircuitPython API for it it mimics PyUSB in CPython. The code must: - Establish the USB connection - Read USB Reports, sections of bytes sent when an action occurs on the peripheral like a key is pressed. - Parse the reports and provide meaningful input to the program. When you use this method it will disable the `sys.stdin` method shown above. You can only use a single method at a time. Using the USB Host method makes it possible to determine which keys are currently being pressed, which makes it possible for the code to know when keys are pressed, how long they're held down, and when they get released.  https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/USB_Host_Examples/CircuitPython_Keyboard_USB_Host/code.py Warning: The character mapping in the code above is for a US 104 key QWERTY keyboard. Other keyboard layouts have different mappings. You can often get the USB value map for other keyboards online or just hook up your keyboard and enter keys to determine which key maps to which character. A guide to other keymaps may be found on the internet. One resource is https://github.com/hid-io/layouts ![CircuitPython serial output showing the HID events for the word "CircuitPython" being typed in via the connected keyboard.](https://cdn-learn.adafruit.com/assets/assets/000/136/471/medium800thumb/learn_arduino_circuitpython_usbhost_output.jpg?1745436806 ) # Using a Keyboard with USB Host ## Arduino To read data from a keyboard in CircuitPython you must use a device which supports USB Host such as the Metro RP2350 or Feather RP2040 USB Host.  ### Feather RP2040 USB Host Wiring Simply plug the keyboard into the USB Host port on the Feather RP2040 USB Host ![Feather RP2040 USB Host connected to a basic USB keyboard.](https://cdn-learn.adafruit.com/assets/assets/000/136/463/medium640/learn_arduino_feather_rp2040_usbhost_keyboard_nohub.png?1745434784) ### Metro RP2350 Wiring Connecting to the Metro RP2350 USB Host port requires soldering pins to the broken out USB Host connections as shown in [this guide page](https://learn.adafruit.com/create-a-memory-game-on-metro-rp2350/preparing-the-metro-rp2350). Make the following connections between the Metro USB Host pins and CH334F host connection opposite the USB C connector. - **GND** to **GND** with  **Black** or **Blue** - **D+** to **D+** with **Green** - **D-** to **D-** with **White** - **5V** to **5V** with **Red** Note that the data pins are swapped on the Metro compared to the CH334F breakout. On the Metro **D-** is next to **5V** , whereas on the CH334F **D-** is next to **GND**. Be sure to connect  **D-** on the breakout to **D-** on the Metro, and **D+** on the breakout to **D+** on the Metro. ![Metro RP2350 with CH334F USB Hub breakout connected to the USB host pins. A USB keyboard is connected to the USB hub breakout.](https://cdn-learn.adafruit.com/assets/assets/000/136/464/medium640/learn_arduino_metro_rp2350_wiring_keyboard.png?1745434885) ![Metro RP2350 with CH334F USB Hub breakout connected to the USB host pins. A USB keyboard is connected to the USB hub breakout.](https://cdn-learn.adafruit.com/assets/assets/000/136/465/medium640/learn_arduino_metro_rp2350_usbhost_keyboard.png?1745434923) Warning: USB Host is under active development. As of Pico-PIO-USB version 0.7.1 and TinyUSB version 3.4.4, the wired USB Mouse only works on the Metro RP2350 with Arduino when connected through a USB hub such as the CH334F. ## Install the Libraries You can install the libraries for this project using the Library Manager in the Arduino IDE. Click the Library Manager icon, search for Adafruit TinyUSB Arduino, and select the Adafruit TinyUSB Library. If asked about dependencies click "Install All". ![Arduino IDE with library manager pane open and "tinyusb arduino" in the search box. The Adafruit TinyUSB Library appears in the results with the install button highlighted.](https://cdn-learn.adafruit.com/assets/assets/000/136/466/medium640/learn_arduino_arduino_library_manager.png?1745435168) ![Arduino IDE dialog asking if the user wants to install dependencies for Adafruit TinyUSB library. The install all button is highlighted.](https://cdn-learn.adafruit.com/assets/assets/000/136/467/medium640/learn_arduino_install_dependencies.png?1745435201) Then install the Pico PIO USB library. Click the **Library Manager** icon menu item again, search for  **PIO USB** , and select the **Pico PIO USB** library by sekigon-gonnoc. ![Arduino IDE with library manager pane open and "pio usb" in the search box. The Pico PIO USB library by sekingon-gonnoc appears in the results with the install button highlighted.](https://cdn-learn.adafruit.com/assets/assets/000/136/468/medium640/learn_arduino_piousb_install_libmanager.png?1745435250) ![Arduino IDE dialog asking if the user wants to install dependencies for Pico PIO USB library. The install all button is highlighted.](https://cdn-learn.adafruit.com/assets/assets/000/136/469/medium640/learn_arduino_piousb_dependencies_install.png?1745435366) ## Code Prep The code consists of a main **usbhost\_keyboard\_simpletest.ino** program file and a separate header file **usbh\_helper.h**. The header file stores configuration for USB host on the RP2040/RP2350. You'll need both of these files to properly compile and run the project. https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/USB_Host_Examples/Arduino_Metro_RP2350_USB_Host_Keyboard/usbhost_keyboard_simpletest.ino Warning: The character mapping in the code above is for a US 104 key QWERTY keyboard. Other keyboard layouts have different mappings. You can often get the USB value map for other keyboards online or just hook up your keyboard and enter keys to determine which key maps to which character. https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/USB_Host_Examples/Arduino_Metro_RP2350_USB_Host_Keyboard/usbh_helper.h ## Upload and Test Before uploading, you'll need to update some settings in the Boards menu. Select the appropriate board that you are using, either **Adafruit Feather RP2040 USB Host** , or **Adafruit Metro RP2350**. Under **USB Stack** select **Adafruit TinyUSB**. Then, upload the sketch to your board. You can use the Serial Monitor in the Arduino IDE for debugging any errors. ![Arduino IDE tools menu with Adafruit Feather RP2040 USB Host board, and TinyUSB stack selected and highlighted.](https://cdn-learn.adafruit.com/assets/assets/000/136/473/medium800/learn_arduino_tools_config.png?1745500742 ) ## Serial Output The code will connect to the USB keyboard and read data coming from it. The keys pressed along with any modifier keys applied will be printed to the serial monitor. ![Arduino serial output showing the USB device info and then the letters in the word "keyboard" as they are typed.](https://cdn-learn.adafruit.com/assets/assets/000/136/470/medium800thumb/learn_arduino_arduino_keyboard_simpletest_output.jpg?1745435564 ) ## Primary Products ### Mini Chiclet Keyboard - USB Wired - Black [Mini Chiclet Keyboard - USB Wired - Black](https://www.adafruit.com/product/1736) Add a good quality, slim keyboard to your Raspberry Pi, Beagle Bone Black, or other single-board-computer with this sleek black chiclet keyboard. It's a full QWERTY keyboard with a USB cable and is compatible with all operating systems. We tried many keyboards to find one that felt... In Stock [Buy Now](https://www.adafruit.com/product/1736) [Related Guides to the Product](https://learn.adafruit.com/products/1736/guides) ## Featured Products ### Adafruit Fruit Jam - Mini RP2350 Computer [Adafruit Fruit Jam - Mini RP2350 Computer](https://www.adafruit.com/product/6200) We were catching up on a recent [hackaday hackchat with eben upton](https://hackaday.io/event/202122-raspberry-pi-hack-chat-with-eben-upton) and learned some fun facts: such as the DVI hack for the RP2040 was inspired by Out of Stock [Buy Now](https://www.adafruit.com/product/6200) [Related Guides to the Product](https://learn.adafruit.com/products/6200/guides) ### Adafruit Feather RP2040 with USB Type A Host [Adafruit Feather RP2040 with USB Type A Host](https://www.adafruit.com/product/5723) You're probably really used to microcontroller boards with USB, but what about a dev board with two? Two is more than one, so that makes it twice as good! And the  **Adafruit Feather RP2040 with USB Host** is ** ** definitely double-the-fun of our other Feather... In Stock [Buy Now](https://www.adafruit.com/product/5723) [Related Guides to the Product](https://learn.adafruit.com/products/5723/guides) ### Adafruit Metro RP2350 [Adafruit Metro RP2350](https://www.adafruit.com/product/6003) Choo! Choo! This is the RP2350 Metro Line, making all station stops at "Dual Cortex M33 mountain", "528K RAM round-about" and "16 Megabytes of Flash town". This train is piled high with hardware that complements the Raspberry Pi RP2350 chip to make it an excellent... In Stock [Buy Now](https://www.adafruit.com/product/6003) [Related Guides to the Product](https://learn.adafruit.com/products/6003/guides) ### Adafruit CH334F Mini 2-Port USB Hub Breakout [Adafruit CH334F Mini 2-Port USB Hub Breakout](https://www.adafruit.com/product/5999) Sometimes, you've got something with a USB host, like an embedded Linux board, and you want to connect more than one thing. Or maybe you want to turn something like a keyboard into a multi-device USB peripheral. The  **Adafruit CH334F Mini 2-Port USB Hub...** In Stock [Buy Now](https://www.adafruit.com/product/5999) [Related Guides to the Product](https://learn.adafruit.com/products/5999/guides) ### USB Type A Jack Breakout Cable with Premium Female Jumpers [USB Type A Jack Breakout Cable with Premium Female Jumpers](https://www.adafruit.com/product/4449) If you'd like to connect a USB-host-capable chip to your USB peripheral, this cable will make the task very simple.  **There is no converter chip in this cable!**  It's basically a plain USB cable that's cut in half and with jumper sockets on the power and data... In Stock [Buy Now](https://www.adafruit.com/product/4449) [Related Guides to the Product](https://learn.adafruit.com/products/4449/guides) ### USB Type A to Type C Cable - approx 1 meter / 3 ft long [USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474) As technology changes and adapts, so does Adafruit. This   **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop. USB C is the latest industry-standard connector for... In Stock [Buy Now](https://www.adafruit.com/product/4474) [Related Guides to the Product](https://learn.adafruit.com/products/4474/guides) ## Related Guides - [Adafruit Feather RP2040 with USB Type A Host](https://learn.adafruit.com/adafruit-feather-rp2040-with-usb-type-a-host.md) - [Adafruit CH334F Mini USB Hub Breakouts](https://learn.adafruit.com/adafruit-ch334f-mini-4-port-usb-hub-breakout.md) - [Adafruit Metro RP2350](https://learn.adafruit.com/adafruit-metro-rp2350.md) - [Adafruit Fruit Jam](https://learn.adafruit.com/adafruit-fruit-jam.md) - [Breakout Game on the Metro RP2350 and Fruit Jam](https://learn.adafruit.com/breakout-game-on-metro-rp2350-and-fruit-jam.md) - [Using DVI Video in CircuitPython](https://learn.adafruit.com/using-dvi-video-in-circuitpython.md) - [Using a Mouse with USB Host](https://learn.adafruit.com/using-a-mouse-with-usb-host.md) - [How to Choose a Microcontroller](https://learn.adafruit.com/how-to-choose-a-microcontroller.md) - [USB Game Controller with SNES-like Layout](https://learn.adafruit.com/usb-game-controller-with-snes-like-layout.md) - [DOOM Keeb](https://learn.adafruit.com/doom-keeb.md) - [RP2040 RunCPM Emulator with USB Keyboard & HDMI screen](https://learn.adafruit.com/rp2040-runcpm-emulator-with-usb-keyboard-hdmi-screen.md) - [Case for Feather RP2040 USB Host](https://learn.adafruit.com/case-for-feather-rp2040-usb-host.md) - [Not A Typewriter](https://learn.adafruit.com/not-a-typewriter.md) - [Feather Guitar Hero Adapter](https://learn.adafruit.com/feather-guitar-hero-adapter.md) - [Flappy Nyan Cat Game on Fruit Jam and Metro RP2350](https://learn.adafruit.com/flappy-nyan-cat-game-on-metro-rp2350.md) - [Adafruit VCNL4030 Proximity and Lux Sensor](https://learn.adafruit.com/adafruit-vcnl4030-proximity-and-lux-sensor.md) - [CircuitPython Libraries on Linux and the 96Boards DragonBoard 410c](https://learn.adafruit.com/circuitpython-libraries-on-linux-and-the-96boards-dragonboard-410c.md) - [Bricktunes: LEGO Synthesizer Glove](https://learn.adafruit.com/bricktunes-lego-glove-synthesizer.md)