Circuitpython: Extending USB-HID Devices

[wallarug]

Hi there,

I would like to add some new custom HID devices in CircuitPython but have been blocked by usb_hid.devices not containing the device I created.

I have the device descriptors and reports all set - I am just blocked by this little problem.

How can I add custom USB HID devices in CircuitPython?

Or a better question: How can the usb_hid.devices list be extended easily?

[tannewt]

Hi @wallarug, HID descriptors are currently statically defined here: https://github.com/adafruit/circuitpython/blob/main/tools/hid_report_descriptors.py and used here: https://github.com/adafruit/circuitpython/blob/main/tools/gen_usb_descriptor.py You'll need to rebuild CircuitPython to include a new descriptor.

I'd love to move to dynamic USB descriptors but it's not a priority for us now.

[wallarug]

@tannewt thank you for the feedback.

I couldn't work out how the gen_usb_descriptor.py script works when I found it last night. I was discussing adding new devices with @dhalbert in the circuitpython chat about a month and a half ago.

I presume anyone can just add in the new devices on this line and rebuild CircuitPython https://github.com/adafruit/circuitpython/blob/main/tools/gen_usb_descriptor.py#L19

[dhalbert]

As @tannewt mentioned, you have to add new HID device descriptors to https://github.com/adafruit/circuitpython/blob/main/tools/hid_report_descriptors.py, and then modify https://github.com/adafruit/circuitpython/blob/main/tools/gen_usb_descriptor.py to include them.

Add the descriptors to the first file, and add them to the lookup table here: https://github.com/adafruit/circuitpython/blob/main/tools/hid_report_descriptors.py#L39. Then add the ones you want to https://github.com/adafruit/circuitpython/blob/main/tools/gen_usb_descriptor.py#L19, as you mentioned.

[wallarug]

Hey @dhalbert thank you for the advise.

First file I have already sorted out. Line 19 was the trick I was missing. Thanks again team!

[wallarug]

Hey @dhalbert ,

Sorry to bother you again on this one. I have one last issue / question.

How do you trigger / run the gen_usb_descriptor.py file? I tried building some boards but it doesn't trigger the updates / changes. The usb_hid.devices array still only has 4 devices.

Thought I would ask as it might be quicker than working it out myself 😄

[wallarug]

Have no fear! I figured it out. Notes below for reference (and for when I inevitably forget tomorrow 🤣 ).

ports/atmel-samd/boards//mpconfigboard.mk

USB_HID_DEVICES="KEYBOARD,MOUSE,CONSUMER,GAMEPAD,<custom>"

The gen_usb_descriptor.py script does check the defaults array as proposed by you Dan, however, only as an error checking mechanism. It takes the given value string as the source of truth. It takes the USB_HID_DEVICES from the individual board config or if that is missing, sets USB_HID_DEVICES by the supervisor.mk hard-coded values to the defaults on line 123.

This was slightly problematic because you end up having to trace the source of this from three different files.

• tools/gen_usb_descriptor.py
• supervisior/supervisor.mk
• ports/atmel-samd/boards//mpconfigboard.mk

I should be ok now - I have more than four devices in the array. All the problems will be on my side now when I get to testing my new USB_HID code.