# Using a Mouse with USB Host
## Overview
This is a mouse. A nice, simple mouse. No bells or whistles. Just a mouse.
But that doesn't mean it's not the best simple mouse! We compared a few and liked this one quite a bit. It's optical for good resolution and precision, it has two buttons for use with any kind of OS, and it has a pretty sturdy USB connector. The track wheel has a good spin and click action. The right and left clicks also make a nice, satisfactory sound, which we always enjoy. It's small but not too small.
It comes in a nice Adafruit black as seen in the beautiful photos above. It's also big enough to fit your hand comfortably.
This will work well with Raspberry Pi and any other kind of computer, as it's a standard HID mouse!
**This guide will show how to use the mouse via USB Host on a microcontroller with CircuitPython and Arduino.**
## Parts
### USB Wired Mouse - Two Buttons plus Wheel
[USB Wired Mouse - Two Buttons plus Wheel](https://www.adafruit.com/product/2025)
This is a mouse. A nice, simple mouse. No bells or whistles. Just a mouse.
But that doesn't mean it's not the best simple mouse! We compared a few and liked this one quite a bit. It's optical for good resolution and precision, has two...
In Stock
[Buy Now](https://www.adafruit.com/product/2025)
[Related Guides to the Product](https://learn.adafruit.com/products/2025/guides)
### 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)
# Using a Mouse with USB Host
## CircuitPython
To read data from a mouse in CircuitPython, you must use a device that supports USB Host, such as the [Metro RP2350](https://www.adafruit.com/product/6003) or [Feather RP2040 USB Host](https://www.adafruit.com/product/5723).
### Feather RP2040 USB Host Wiring
Connecting to the Feather RP2040 USB Host requires plugging in a USB mouse to the Feather's Host port.
### 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
### Fruit Jam Mini Computer
Connecting to the Fruit Jam requires plugging in a USB mouse to one of the Fruit Jam's USB Host ports.
Warning: As of CircuitPython version 10.0.0-beta.3, the wired USB mouse 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: Read Data
This example uses the USB Host API to read data from the mouse and prints out the relevant values to the serial console. The CircuitPython USB Host API is made to mimic PyUSB from CPython.
To read data from the mouse, the code must first scan the connected devices and find one with a boot mouse endpoint. Once a mouse device and endpoint are found, the code will try to read data from them in the main loop. If no data is sent, it will timeout and simply keep trying again until data is present. Once it reads data from the mouse, it will print any buttons that are pressed along with the delta X and delta Y values that represent how far the mouse has been moved and in which directions.
The list `BUTTONS` is created with values `"left"`, `"right"`, and `"middle"`. The order and indexes of these values align with the mouse protocol, which will use bits in the same positions to denote whether each button is being pressed or not.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/USB_Host_Examples/CircuitPython_Mouse_Basic/code.py
Here is a sample output using the Adafruit mouse. If you have a different mouse, the identification information will likely be different, but the functionality should be the same.
# Using a Mouse with USB Host
## CircuitPython Displayio Cursor
To use a mouse to draw and move a visible cursor on a display in CircuitPython requires a device that supports both USB Host and displayio. The Fruit Jam, or the Metro RP2350 with its HSTX connection for DVI display output are two supported devices.
### 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
Connect to a DVI compatible display with an HDMI cable from the HSTX breakout to the display.
### 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.
Connect to a DVI compatible display with an HDMI cable from the Fruit Jam's DVI output to the display.
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: Displayio Mouse Cursor
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/USB_Host_Examples/CircuitPython_Mouse_Displayio_Cursor/code.py
## Code Explanation
The example code contains comments for the line or section of code that details its purpose. Read the comments along with a summary below to understand how the demo works.
This demo scans for and reads data from the USB mouse in the same way as the basic demo on the previous page. The code uses the default built-in display with `supervisor.runtime.display`. For the Metro RP2350, that is the HSTX / DVI connected display.
### Visual Elements Setup
The code creates a displayio `main_group` to put all visual elements into and sets it as the `root_group` on the display so it is shown on the screen. Then it creates an `OnDiskBitmap` to load the **mouse\_cursor.bmp** file.
This files contains a pink color in the palette index 0 which is treated as transparency by calling `mouse_bmp.pixel_shader.make_transparent(0)`. A TileGrid is created and stored in the variable `mouse_tg`. Later, when reading mouse data, the program will use the data to move `mouse_tg` around the screen. The mouse cursor is put into the center of the screen to start with.
A `Label` named `output_lbl` is created and added to the `main_group` after being placed in the top left corner of the screen. This will be used to show the current mouse coordinates and any buttons that are pressed.
The `mouse_tg` is added to `main_group` last so that it will be visually in front of everything else.
### Main Loop
Inside the main loop, `mouse.read(0x81, buf, timeout=20)` is called to read data from the mouse. `0x81` is the default endpoint address for basic HID mice, `buf` is the 8-byte buffer array that will get filled with the data that is read. `timeout` is how many milliseconds to wait before raising a `USBTimeoutError` if there is no data to read. This code uses a low value of `20` milliseconds to illustrate how the main loop can do other things if the timeout is kept low. Higher timeout values result in the `read()` call blocking other code execution for longer times.
If there is no data, the `USBTimeoutError` is raised, and the code skips to the next iteration with `continue`.
If there is data, the code reads the delta x and y values from buffer indexes `1` and `2`. These delta values represent how far the mouse has moved in each direction. It will have negative values for up/left, and positive values for right/down.
The delta values are used to move the `mouse_tg` to a new location. `min()` and `max()` are used to clamp the mouse cursor to the bounds of the display. The mouse itself is not aware of these bounds, the code enforces staying on the display after reading raw data from the mouse.
The `out_str` is updated with the current x and y coordinates of the `mouse_tg`.
Next, the code checks for button presses by looping over the `BUTTONS` list and checking the bits in the respective positions within the byte at an index `0` of the buffer. Any buttons that are pressed have their name added to the `out_str`.
Finally `out_str` is set as the text on the `output_lbl` to show the current values on the screen.
# Using a Mouse with USB Host
## Arduino
To read data from a mouse in Arduino, you must use a device which supports USB Host such as the Metro RP2350 or Feather RP2040 USB Host. Right now the Metro RP2350 only works when the wired mouse is connected through a USB hub such as the CH334F.
### Feather RP2040 USB Host Wiring
Simply plug the mouse into the USB Host port on the Feather RP2040 USB Host
### 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.
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".
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.
## Code Prep
The code consists of a main **.ino** program file and two header files. The header files store configuration for USB host on the RP2040/RP2350 and HID device reports for the mouse. You'll need all three of these files to properly compile and run the project.
### **usbhost\_mouse\_simpletest.ino**
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/USB_Host_Examples/Arduino_Metro_RP2350_Mouse_USB_Host/usbhost_mouse_simpletest/usbhost_mouse_simpletest.ino
### **usbh\_helper.h**
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/USB_Host_Examples/Arduino_Metro_RP2350_Mouse_USB_Host/usbhost_mouse_simpletest/usbh_helper.h
### **hid\_mouse\_reports.h**
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/USB_Host_Examples/Arduino_Metro_RP2350_Mouse_USB_Host/usbhost_mouse_simpletest/hid_mouse_reports.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.
## Serial Output
The code will connect to the USB mouse and read data coming from it. Delta X and Y values are printed to the serial output, when it detects that buttons are pressed it will print which ones are down into the serial output as well..
## Primary Products
### USB Wired Mouse - Two Buttons plus Wheel
[USB Wired Mouse - Two Buttons plus Wheel](https://www.adafruit.com/product/2025)
This is a mouse. A nice, simple mouse. No bells or whistles. Just a mouse.
But that doesn't mean it's not the best simple mouse! We compared a few and liked this one quite a bit. It's optical for good resolution and precision, has two...
In Stock
[Buy Now](https://www.adafruit.com/product/2025)
[Related Guides to the Product](https://learn.adafruit.com/products/2025/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)
- [Using DVI Video in CircuitPython](https://learn.adafruit.com/using-dvi-video-in-circuitpython.md)
- [Breakout Game on the Metro RP2350 and Fruit Jam](https://learn.adafruit.com/breakout-game-on-metro-rp2350-and-fruit-jam.md)
- [USB Game Controller with SNES-like Layout](https://learn.adafruit.com/usb-game-controller-with-snes-like-layout.md)
- [DIY Turbo Button Controller - HID Remapper](https://learn.adafruit.com/diy-turbo-button-controller-hid-remapper.md)
- [DOOM Keeb](https://learn.adafruit.com/doom-keeb.md)
- [Feather Guitar Hero Adapter](https://learn.adafruit.com/feather-guitar-hero-adapter.md)
- [Using a Keyboard with USB Host](https://learn.adafruit.com/using-a-keyboard-with-usb-host.md)
- [Not A Typewriter](https://learn.adafruit.com/not-a-typewriter.md)
- [CircuitPython Text Editor On The Go](https://learn.adafruit.com/circuitpython-text-editor-on-the-go.md)
- [Flappy Nyan Cat Game on Fruit Jam and Metro RP2350](https://learn.adafruit.com/flappy-nyan-cat-game-on-metro-rp2350.md)
- [RP2040 RunCPM Emulator with USB Keyboard & HDMI screen](https://learn.adafruit.com/rp2040-runcpm-emulator-with-usb-keyboard-hdmi-screen.md)
- [Create a Memory Game on Fruit Jam Metro RP2350](https://learn.adafruit.com/create-a-memory-game-on-metro-rp2350.md)
- [Adafruit SCD-40 and SCD-41](https://learn.adafruit.com/adafruit-scd-40-and-scd-41.md)