usb_hid: Ability to look further inside device descriptors

[jepler]

I developed two device descriptors that support NRKO (https://emergent.unpythonic.net/01625944378). While doing so, I noticed that the standard adafruit_keyboard class had no way of knowing that the report didn't match what it expected, until it encountered an exception trying to send a wrong-sized report.

I don't know exactly what is necessary or useful, but it seems like it would be nice if Keyboard could instead say "this descriptor isn't quite what I need"; this might consist of looking at the descriptor bytes themselves, or getting other information like the length of the report. However, the length of the report alone might not be enough to distinguish exactly what the descriptor does.

I did prototype adding a ".descriptor" property to Device objects but I'm not sure that's the direction to go either, so I'm putting this in as a feature request rather than a PR.

[deshipu]

I wonder if going the other way, and generating a string for struct.pack from the descriptor to ensure it's correct wouldn't be easier? It would let you avoid the error in advance.

[jepler]

ah but (as I understand it) the descriptor has to be created in boot.py and cannot be accessed later in code.py.

[deshipu]

But it's stored, isn't it?

[dhalbert]

The raw bytes of the descriptor are stored indefinitely, because we're not sure when USB enumeration is complete. I did not provide a read-only property for the descriptor because the descriptor is known to the the creator and I was try to save code space in the API.

See #4868 for my idea of how the API will change in the near future, before 7.0.0 final.

[jepler]

iirc my branch that added the descriptor as a property increased binary size by 100ish bytes so it wasn't something to add lightly.

The hack I arrived at was that I could tell the difference between the two descriptors by trying to send an all-zeros report and see which length succeeded. This is OK for keyboards since all-zeros is "no keys pressed". It's probably not a general solution.

[dhalbert]

usb_hid.devices should be in the order that boot.py added the devices with usb_hid.enable. So you don't need to use find_devices to search; just index directly.

[jepler]

OK, so the solution is possibly to share some underlying module between boot.py and code.py, where the actual descriptor data resides!

[ThomasAtBBTF]

So, do I understand correctly, that if I want to add a BrailleDevice HID descriptor, I better do that in boot.py?

[dhalbert]

You have to do usb_hid.enable(sequence of devices) in boot.py. You can't add it after USB has been enumerated. THis is explained in the Guide: https://learn.adafruit.com/customizing-usb-devices-in-circuitpython/