You can customize which USB devices to include in your CircuitPython build by adding some settings to the circuitpython/ports/port-choice/boards/board-choice/mpconfigboard.mk file.

Customizing USB Devices

You can enable or disable the different available USB devices by using these flags and setting them to 1 or 0. You do not need to specify all these settings, only the ones that are different from the defaults for your build. 

Download: file
# Enable second CDC (serial) channel (usually off; was on in 6.2.0-beta.3)
CIRCUITPY_USB_CDC = 1
  
# Disable composite HID device (usually on)
CIRCUITPY_USB_HID = 0  
  
# Disable MIDI (sometimes on)
CIRCUITPY_USB_MIDI = 0
  
# Disable mass storage (on by default)
CIRCUITPY_USB_MSC = 0
  
# Enable WEBUSB (off by default)
CIRCUITPY_USB_VENDOR = 1

Customizing USB HID Devices

Similarly, these flags control whether various USB HID devices are enabled or disabled. You only need to specify the ones that are different from the defaults for your build.

Download: file
# Disable Consumer Control (volume, etc.) (on by default)
CIRCUITPY_USB_HID_CONSUMER = 0

# Enable digitizer tablet (off by default)
CIRCUITPY_USB_HID_DIGITIZER = 1

# Disable HID gamepad (usually on)
CIRCUITPY_USB_HID_GAMEPAD = 0

# Disable keyboard (always on)
CIRCUITPY_USB_HID_KEYBOARD = 0

# Disable mouse (always on)
CIRCUITPY_USB_HID_MOUSE = 0

# Enable SysControl (power, etc.) (off by default)
CIRCUITPY_USB_HID_SYS_CONTROL = 1

# Enable Microsoft XAC gamepad (off by default)
CIRCUITPY_USB_HID_XAC_COMPATIBLE_GAMEPAD = 1

Side note: Don't put Makefile comments on the same line as Makefile assignments. I causes the variable value to include the trailing spaces before comment character

Customizing USB Devices Before 6.2.0-beta.3

If you are changing a build before 6.2.0-beta.3 (actually before PR 4215), use this older way of specifying which USB devices to include. Add a line like one of these:

Download: file
# This is the default if USB_DEVICES is not specified.
# AUDIO refers to MIDI capability.
USB_DEVICES = "CDC,MSC,AUDIO,HID"

# Here's an example of providing only HID devices
USB_DEVICES = HID

# Provide only CDC and HID
USB_DEVICES = "CDC,HID"

Of course, if you disable MSC, you will not be able to load and edit programs via the CIRCUITPY drive. So get your program running with a regular CircuitPython build, and when you are satisfied, replace it with your custom build. If you need to edit the program again, reload the regular build.

Customizing HID Devices Before 6.2.0-beta.3

Similarly, you can specify which HID devices are available:

Download: file
# This is the default if USB_HID_DEVICES is not specified
USB_HID_DEVICES = "KEYBOARD,MOUSE,CONSUMER,GAMEPAD"

# Provide only KEYBOARD and CONSUMER HID devices, for use as, say, a volume control.
USB_HID_DEVICES = "KEYBOARD,CONSUMER"

This guide was first published on Apr 26, 2018. It was last updated on Apr 26, 2018.

This page (Customizing USB Devices) was last updated on Apr 12, 2021.

Text editor powered by tinymce.