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.

In the past the only way to disable USB devices has been to make your own custom build of CircuitPython. But doing your own builds is not easy. And if you then wanted to edit your project's or connect to its REPL, you'd have to reload a regular CircuitPython build just to get access to them.

Enable and Disable Devices at Run-Time

As of CircuitPython 7.0.0, you don't need to make custom builds and swap them in and out. Instead, you can write code in the file which will disable or enable the devices you want to control. For example, this code disables CIRCUITPY and the REPL on startup, except when you press a button. (Be careful, don't disable both of these unconditionally; you will lock yourself out.)

if not button.value:
    storage.disable_usb_drive()    # Turn off CIRCUITPY.
    usb_cdc.disable()              # Turn off REPL.
These capabilities are available starting in CircuitPython 7.0.0.

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:

# Turn on both REPL and data serial connections.
usb_cdc.enable(console=True, data=True)

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.

# Create my own joystick.
joystick = usb_hid.Device(...)    # Details omitted.

 # Present a keyboard and joystick.
usb_hid.enable((usb_hid.Device.KEYBOARD, joystick))

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 2021-07-20 14:26:58 -0400.

This page (Overview) was last updated on Oct 15, 2021.

Text editor powered by tinymce.