USB HID LEDs

[oldgraydev]

I'm want to follow the state of the Caps Lock LED using the great new USB support. I've modded-up a minimal script and HID descriptor with a toggle switch-type OOC that half-works. My script sees all of the off-to-on transitions, but none of the on-to-off ones. All the documentation and examples I've found imply this should work. What might I be doing wrong?

It's exactly the same on a Wio Terminal (SEEED_WIO_TERMINAL-20240602-v1.23.0.uf2) and Raspberry Pi Pico (RPI_PICO-20240602-v1.23.0.uf2).

Code:

# Derived from MicroPython USB HID custom Keypad example
# MIT license; Copyright (c) 2023 Dave Wickham, 2023-2024 Angus Gratton
#from micropython import const
import time
import usb.device
from usb.device.hid import HIDInterface

# HID Report descriptor for Caps Lock LED
#
# fmt: off
_REPORT_DESC = (
    b'\x05\x01' # UsagePage(Generic Desktop[0x0001])
    b'\x09\x06' # UsageId(Keyboard[0x0006])
    b'\xA1\x01' # Collection(Application)
    b'\x85\x01' #   ReportId(1)
    b'\x05\x08' #   UsagePage(LED[0x0008])
    b'\x09\x02' #   UsageId(Caps Lock[0x0002])
    b'\x15\x00' #   LogicalMinimum(0)
    b'\x25\x01' #   LogicalMaximum(1)
    b'\x95\x01' #   ReportCount(1)
    b'\x75\x01' #   ReportSize(1)
    b'\x91\x22' #   Output(Data, Variable, Absolute, NoWrap, Linear, NoPreferredState, NoNullPosition, NonVolatile, BitField)
    b'\x75\x07' #   ReportSize(7)
    b'\x91\x03' #   Output(Constant, Variable, Absolute, NoWrap, Linear, PreferredState, NoNullPosition, NonVolatile, BitField)
    b'\xC0'    # EndCollection()
)
# fmt: on


class LEDInterface(HIDInterface):
    def __init__(self):
        super().__init__(
            _REPORT_DESC,
            set_report_buf=bytearray(1),
            interface_str="MicroPython Num Lock LED",
        )

    def on_set_report(self, report_data, _report_id, _report_type):
        print('set_report:', report_data, _report_id, _report_type)
        return True


# Main entry point

iface = LEDInterface()

usb.device.get().init(iface, builtin_driver=True)

while not iface.is_open():
    time.sleep_ms(100)

while True:
    time.sleep(1)

Run with mpremote run capslockled.py followed by mpremote to reconnect the console. Runtime output:

set_report: bytearray(b'\x01') 1 2
set_report: bytearray(b'\x01') 1 2
set_report: bytearray(b'\x01') 1 2

[oldgraydev]

I've traced this back to _control_xfer_cb in usb.device-core.py firing only on the Caps Lock LED off-to-on change, never the on-to-off one. This is called directly from the low-level machine.USBDevice device. Tracing in to that looks a bit less straightforward...

[oldgraydev]

I narrowed this down to HIDInterface not firing on_set_report when the report data is 0. Is this a bug?

I put both LED-CapsLock and LED-NumLock in the output report descriptor. When NumLock=1 I saw both CapsLock 0-1 and 1-0 events, and with CapsLock=1 I saw NumLock 0-1 and 1-0 events. But when the report resulted in both being=0, the callback never fired. Example sequences:

1. CapsLock 0-1 followed by unseen 1-0:

on_set_report:  _report_id=1  _report_type=2  report_data=[00000001 00000001]

2. NumLock 0-1 followed by CapsLock 0-1 and 1-0:

on_set_report:  _report_id=1  _report_type=2  report_data=[00000001 00000010]
on_set_report:  _report_id=1  _report_type=2  report_data=[00000001 00000011]
on_set_report:  _report_id=1  _report_type=2  report_data=[00000001 00000010]

3. CapsLock 0-1 followed by NumLock 0-1 and 1-0:

on_set_report:  _report_id=1  _report_type=2  report_data=[00000001 00000001]
on_set_report:  _report_id=1  _report_type=2  report_data=[00000001 00000011]
on_set_report:  _report_id=1  _report_type=2  report_data=[00000001 00000001]

New code generating these examples:

# Derived from MicroPython USB HID custom Keypad example
# MIT license; Copyright (c) 2023 Dave Wickham, 2023-2024 Angus Gratton

# from micropython import const
import time
import usb.device
from usb.device.hid import HIDInterface

# HID Report descriptor for Caps Lock LED
#
# fmt: off
_REPORT_DESC = (
    b'\x05\x01' #....UsagePage(Generic Desktop[0x0001])
    b'\x09\x06' #....UsageId(Keyboard[0x0006])
    b'\xA1\x01' #....Collection(Application)
    b'\x85\x01' #........ReportId(1)
    b'\x05\x08' #........UsagePage(LED[0x0008])
    b'\x09\x02' #........UsageId(Caps Lock[0x0002])
    b'\x09\x01' #........UsageId(Num Lock[0x0001])
    b'\x15\x00' #........LogicalMinimum(0)
    b'\x25\x01' #........LogicalMaximum(1)
    b'\x95\x02' #........ReportCount(2)
    b'\x75\x01' #........ReportSize(1)
    b'\x91\x22' #........Output(Data, Variable, Absolute, NoWrap, Linear, NoPreferredState, NoNullPosition, NonVolatile, BitField)
    b'\x95\x01' #........ReportCount(1)
    b'\x75\x06' #........ReportSize(6)
    b'\x91\x03' #........Output(Constant, Variable, Absolute, NoWrap, Linear, PreferredState, NoNullPosition, NonVolatile, BitField)
    b'\xC0' #.......EndCollection()
)
# fmt: on

class LEDInterface(HIDInterface):
    def __init__(self):
        super().__init__(
            _REPORT_DESC,
            set_report_buf=bytearray(64),
            interface_str="MicroPython Caps Lock LED",
        )

    def on_set_report(self, report_data, _report_id, _report_type):
        print('on_set_report:  _report_id={}  _report_type={}  report_data=[{}]'.format(_report_id, _report_type, ' '.join(['{:08b}'.format(b) for b in report_data])))
        return True

# Main entry point

iface = LEDInterface()

usb.device.get().init(iface, builtin_driver=True)

while not iface.is_open():
    time.sleep_ms(100)

while True:
    time.sleep(1)

[projectgus]

Hey @oldgraydev, sorry I didn't see this earlier. Did you make much progress with this?

Are you sure about your HID Report descriptor? It looks quite different to the LED section of a typical keyboard example, i.e. https://github.com/micropython/micropython-lib/blob/master/micropython/usb/usb-device-keyboard/usb/device/keyboard.py#L95 . However, HID is very flexible so it might be fine - I'm not sure.

What host OS are you connecting the keyboard to?

[oldgraydev]

Oh, wow @projectgus, thank you for resurrecting this! I've cracked it just today with a bump from your questions, and Windows gets the blame. I added an IN report to my minimal descriptor so I could fire CapsLock from the same device, and tested on Linux and Android (only Windows treats CapsLock as global state - setting it on any one keyboard sets it on all). What I found:

• Linux (Raspberry Pi OS) - Works as expected: Every CapsLock keycode IN results in a new LED OUT report, for both off-to-on and on-to-off transitions.
• Windows - Malfunctions: does not send LED reports with all usage values = 0. Reports with non-zero usage values do send.
• Android - Ignores the whole device: No keys, no LEDs, no indication it sees the device...just nothing.

Here's my new testing descriptor, adding an IN report for a few keycodes and some other junk. I was trying to create something minimal and HID-compliant from first principles.

_REPORT_DESC = (
    b'\x05\x01' #....UsagePage(Generic Desktop[0x0001])
    b'\x09\x06' #....UsageId(Keyboard[0x0006])
    b'\xA1\x01' #....Collection(Application)
    b'\x85\x01' #........ReportId(1)
    b'\x05\x07' #........UsagePage(Keyboard/Keypad[0x0007])
    b'\x09\x50' #........UsageId(Keyboard LeftArrow[0x0050])
    b'\x09\x4F' #........UsageId(Keyboard RightArrow[0x004F])
    b'\x09\x52' #........UsageId(Keyboard UpArrow[0x0052])
    b'\x09\x51' #........UsageId(Keyboard DownArrow[0x0051])
    b'\x09\x39' #........UsageId(Keyboard CapsLock[0x0039])
    b'\x15\x00' #........LogicalMinimum(0)
    b'\x25\x01' #........LogicalMaximum(1)
    b'\x95\x05' #........ReportCount(5)
    b'\x75\x01' #........ReportSize(1)
    b'\x81\x02' #........Input(Data, Variable, Absolute, NoWrap, Linear, PreferredState, NoNullPosition, BitField)
    b'\x05\x01' #........UsagePage(Generic Desktop[0x0001])
    b'\x09\xA7' #........UsageId(System Speaker Mute[0x00A7])
    b'\x95\x01' #........ReportCount(1)
    b'\x81\x06' #........Input(Data, Variable, Relative, NoWrap, Linear, PreferredState, NoNullPosition, BitField)
    b'\x75\x02' #........ReportSize(2)
    b'\x81\x03' #........Input(Constant, Variable, Absolute, NoWrap, Linear, PreferredState, NoNullPosition, BitField)
    b'\x05\x08' #........UsagePage(LED[0x0008])
    b'\x09\x06' #........UsageId(Power[0x0006])
    b'\x09\x1C' #........UsageId(Battery OK[0x001C])
    b'\x09\x02' #........UsageId(Caps Lock[0x0002])
    b'\x09\x01' #........UsageId(Num Lock[0x0001])
    b'\x09\x09' #........UsageId(Mute[0x0009])
    b'\x09\x29' #........UsageId(Camera Off[0x0029])
    b'\x09\x28' #........UsageId(Camera On[0x0028])
    b'\x95\x07' #........ReportCount(7)
    b'\x75\x01' #........ReportSize(1)
    b'\x91\x22' #........Output(Data, Variable, Absolute, NoWrap, Linear, NoPreferredState, NoNullPosition, NonVolatile, BitField)
    b'\x09\x3A' #........UsageId(Usage Selected Indicator[0x003A])
    b'\xA1\x02' #........Collection(Logical)
    b'\x05\x0B' #............UsagePage(Telephony Device[0x000B])
    b'\x09\x2F' #............UsageId(Phone Mute[0x002F])
    b'\x95\x01' #............ReportCount(1)
    b'\x91\x22' #............Output(Data, Variable, Absolute, NoWrap, Linear, NoPreferredState, NoNullPosition, NonVolatile, BitField)
    b'\xC0' #...........EndCollection()
    b'\xC0' #.......EndCollection()
)

To complete the experiment, I re-built the application with the "normal" full-fat n-key rollover descriptor shown below and tried it on the same three OSes. It worked perfectly on all. I guess either (a) my original descriptor missed the HID spec and Linux tolerated it anyway, or (b) Windows and Android have slightly more brittle HID implementations.

# HID Report descriptor, derived from...
# https://learn.adafruit.com/custom-hid-devices-in-circuitpython/n-key-rollover-nkro-hid-device
_REPORT_DESC = bytes((
        0x05, 0x01,                     # Usage Page (Generic Desktop),
        0x09, 0x06,                     # Usage (Keyboard),
        0xA1, 0x01,                     # Collection (Application),
        0x85, 0x04,           
                  #   Report ID
        # bitmap of modifiers
        0x75, 0x01,                     #   Report Size (1),
        0x95, 0x08,                     #   Report Count (8),
        0x05, 0x07,                     #   Usage Page (Key Codes),
        0x19, 0xE0,                     #   Usage Minimum (224),
        0x29, 0xE7,                     #   Usage Maximum (231),
        0x15, 0x00,                     #   Logical Minimum (0),
        0x25, 0x01,                     #   Logical Maximum (1),
        0x81, 0x02,                     #   Input (Data, Variable, Absolute), ;Modifier byte
        # LED output report
        0x95, 0x05,                     #   Report Count (5),
        0x75, 0x01,                     #   Report Size (1),
        0x05, 0x08,                     #   Usage Page (LEDs),
        0x19, 0x01,                     #   Usage Minimum (1),
        0x29, 0x05,                     #   Usage Maximum (5),
        0x91, 0x02,                     #   Output (Data, Variable, Absolute),
        0x95, 0x01,                     #   Report Count (1),
        0x75, 0x03,                     #   Report Size (3),
        0x91, 0x03,                     #   Output (Constant),
        # bitmap of keys
        0x95, 0x78,                     #   Report Count ((16-1)*8 = 120),
        0x75, 0x01,                     #   Report Size (1),
        0x15, 0x00,                     #   Logical Minimum (0),
        0x25, 0x01,                     #   Logical Maximum(1),
        0x05, 0x07,                     #   Usage Page (Key Codes),
        0x19, 0x00,                     #   Usage Minimum (0),
        0x29, 0x77,                     #   Usage Maximum ((16-1)*8-1 = 119),
        0x81, 0x02,                     #   Input (Data, Variable, Absolute),
        0xc0                            # End Collection
))

[projectgus]

To complete the experiment, I re-built the application with the "normal" full-fat n-key rollover descriptor shown below and tried it on the same three OSes. It worked perfectly on all. I guess either (a) my original descriptor missed the HID spec and Linux tolerated it anyway, or (b) Windows and Android have slightly more brittle HID implementations.

I think it's one of the curses of complex protocols like HID is that they can express near infinite possibilities, but only a tiny subset are ever tested in host implementations. Glad you made some progress there!

Don't forget that you can possibly send a "normal" descriptor from the device and then never actually send any keypresses to the host.

only Windows treats CapsLock as global state - setting it on any one keyboard sets it on all

FWIW in my experience this is also true on Linux. However, I guess there's a chance it depends on the Desktop Environment or some other variable.