usb_hid usage 0x00 needed but not allowed

[akseidel]

CircuitPython version and board name

Adafruit CircuitPython 9.2.8 on 2025-05-28; Raspberry Pi Pico with rp2040

Code/REPL

# boot.py for pm2be_emulator

import supervisor
import usb_hid
...

PM2BE_REPORT_DESCRIPTOR = bytes((
0x05, 0x01,        # Usage Page (Generic Desktop Ctrls)
0x09, 0x00,        # Usage (Undefined)
0xA1, 0x01,        # Collection (Application)
0x05, 0x08,        #   Usage Page (LEDs)
0x09, 0x4B,        #   Usage (Generic Indicator)
0x15, 0x00,        #   Logical Minimum (0)
0x25, 0x01,        #   Logical Maximum (1)
0x95, 0x08,        #   Report Count (8)
0x75, 0x01,        #   Report Size (1)
0x91, 0x02,        #   Output (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
0x05, 0x09,        #   Usage Page (Button)
0x15, 0x00,        #   Logical Minimum (0)
0x25, 0x01,        #   Logical Maximum (1)
0x75, 0x01,        #   Report Size (1)
0x95, 0x08,        #   Report Count (8)
0x81, 0x01,        #   Input (Const,Array,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x19, 0x01,        #   Usage Minimum (0x01)
0x29, 0x0E,        #   Usage Maximum (0x0E)
0x15, 0x00,        #   Logical Minimum (0)
0x25, 0x01,        #   Logical Maximum (1)
0x95, 0x0E,        #   Report Count (14)
0x81, 0x02,        #   Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x95, 0x02,        #   Report Count (2)
0x81, 0x01,        #   Input (Const,Array,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x05, 0xFF,        #   Usage Page (Reserved 0xFF)
0x09, 0x00,        #   Usage (0x00)
0x15, 0x00,        #   Logical Minimum (0)
0x26, 0xFF, 0x00,  #   Logical Maximum (255)
0x75, 0x08,        #   Report Size (8)
0x95, 0x27,        #   Report Count (39)
0xB1, 0x00,        #   Feature (Data,Array,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
0xC0,              # End Collection
))

...

pm2be = usb_hid.Device(
    report_descriptor=PM2BE_REPORT_DESCRIPTOR,
    usage_page=0x01,           # Usage Page (Generic Desktop Ctrls)
    usage=0x00,                # Usage (Undefined)
    report_ids=(0,),           # Descriptor uses report ID 1
    in_report_lengths=(3,),    # This PM2BEL sends 3 bytes in its report.
    out_report_lengths=(8,),   #
)

Behavior

%Run -c $EDITOR_CONTENT
Traceback (most recent call last):
File "", line 88, in
ValueError: usage must be 1-65535

Line 88 is “0x09, 0x00, # Usage (Undefined)” within the PM2BE_REPORT_DESCRIPTOR.

Description

The intent is to emulate using Circuitpython a usb device that has a USB report descriptor that starts with:

0x05, 0x01, # Usage Page (Generic Desktop Ctrls)
0x09, 0x00, # Usage (Undefined)

Usage=0x00, supposedly means undefined but apparently is not prohibited since the the device to be emulated does function just fine. It appears there is an argument range check for “usage” that does not include 0x00 usage.

Additional information

No response

[FoamyGuy]

indeed usage is currently limited to the range 1-65535 from the code here:

circuitpython/shared-bindings/usb_hid/Device.c

Line 101 in 117b5d1

mp_arg_validate_int_range(usage_arg, 1, 0xFFFF, MP_QSTR_usage);

Page 32 of https://www.usb.org/sites/default/files/hut1_4.pdf does seem to indicate that 00 is a valid usage value for undefined.

If you want to try it out and are able to build circuitpython you could try changing the 1 here to a 0 and see if it allows proper emulation of your USB device.

[akseidel]

Thanks, editing mp_arg_validate_int_range() is my interim plan B. That is the function that shows up when searching through the source code. I can confirm changing the range validator to start at 0 appears to work and that the py device driver created to pair with this HID descriptor appears, via hidapitester, to send data as intended for this one application.

[dhalbert]

That change is exactly what I was going to do. If you want to submit a PR, go ahead. Otherwise I can do it.

[akseidel]

Please do, thank you. How would I know if the change is made?

[dhalbert]

Please do, thank you. How would I know if the change is made?

This issue will get closed when it's done. Then it will be in the "Absolute Newest" board builds, and eventually in the next 10.0.0-beta release.

[dhalbert]

Could you give a link to the actual USB device we are talking about? I found several "PM2BE" or "PM2BEL" but I'm not sure which one it is.

[akseidel]

Sorry, I do not have any link. PM2BE is just a name made up for the need to have some file name that makes some DIY context sense. It corresponds to Python Micro To Be Button Emulator where the number 2 means both “To” and “Two”. I do not currently know what the buttons do in context with the device’s real use. My impression is it is a controller with buttons. Why it is not using something like a game controller USB usage is a question.

[dhalbert]

So is it an actual device that you have, or some theoretical device someone is coding, and you don't have the code?

[akseidel]

I do not have the device that is to be emulated. I am investigating the emulation feasibility using Circuitpython on an RP2040/2350 class device. Thanks to you all and Frank Zhao it is possible to create the usb event driver side of the task needed to match the usb descriptor. Feasibility is being investigated on a pico with a few button switches. If successful, then the next platform will be an Adafruit Macropad running Circuitpython.

…

On Aug 20, 2025, at 11:45 PM, Dan Halbert ***@***.***> wrote: dhalbert left a comment (adafruit/circuitpython#10576) <#10576 (comment)> So is it an actual device that you have, or some theoretical device someone is coding, and you don't have the code? — Reply to this email directly, view it on GitHub <#10576 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABOYA44DKJWVVEQ6KNJMSRT3OU6EZAVCNFSM6AAAAACEJSDXGOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTEMBYHA4TCNBVGU>. You are receiving this because you authored the thread.