Standard CircuitPython USB Devices

When you plug a CircuitPython board into a host computer, it shows up as several USB devices. Normally, you see:

  • The CIRCUITPY drive, which is a USB "Mass Storage" (MSC) device.
  • A serial connection to the REPL, which shows up as a COM port on Windows, a /dev/tty device on Linux, or a /dev/cu device on MacOS.
  • MIDI in and out streams, which show up as a kind of audio device.
  • A mouse, keyboard, etc., all of which are different kinds of "Human Interface Devices" (HID). The HID devices are lumped together in a single "composite" device.

Can I Hide Some Devices?

It's great that CircuitPython provides all these USB capabilities, but sometimes you don't want to see all of them. For instance, you might build a volume control, macro keypad, or your own fancy keyboard that you want to leave plugged in all the time. You wouldn't want its CIRCUITPY and serial connection to be visible. If you plugged in another CircuitPython board, you couldn't be sure which was your permanent accessory and which was the new board.

So CircuitPython allows you to choose which devices are visible at run time. You add code to the file which will specifies which USB devices you want to enable or disable. You can make CIRCUITPY disappear or hide the standard REPL serial connection, for instance.

Add a Second Serial Port

In addition to just turning the standard devices on and off, you can also enable a second serial port. A second COM port or /dev/tty or /dev/cu device will appear. It is not connected to the REPL, so you can use it for unimpeded communication back and forth with the host computer. You can send and receive binary data, and not worry about having to escape ctrl-C characters or seeing print statements or errors in the data you read. For example:

Define Custom HID Devices

Finally, you can also create new HID devices, such as specialized game controllers, digitizers, custom mice, and so forth. You'll need to understand how to make HID report descriptors, but you can often copy existing ones.

Change USB Identification

The overall USB device reports manufacturer and device names when it is plugged in. You can change the default values if you wish. A particular USB interface (MIDI, CDC, etc.) also reports names, but as of this writing, it is not possible to change these without building a custom version of CircuitPython.

Try it!

Read the rest of the guide to find out how to take control of CircuitPython USB!

This guide was first published on May 20, 2021. It was last updated on Feb 14, 2024.

This page (Overview) was last updated on May 19, 2021.

Text editor powered by tinymce.