circuitpython: Unable to use HID keyboard in boot OS (macOS boot screen)

I am starting to implement dynamic control over USB and USB HID descriptors right now. I may not get to boot keyboard immediately, but it will be possible. So I would say not to start on it yourself right now, because the underlying code is going to change a lot in the near future.

All that we really need is a separate USB descriptor (separate endpoint) with an appropriate USB HID descriptor. Almost any commercial keyboard does this and we can vet our choices against the descriptors from such keyboards.

I am adding the hid_boot_interface example here if anyone is interested to test https://github.com/hathach/tinyusb/pull/1025 . I don’t have any legacy bios PC to test with though. Therefore it may have an issue or two. For implementation it uses 1 interface for keyboard, and 1 for mouse. Per HID specs, device is default to report mode, Bios PC will send control request SET_PROTOCOL to change it to boot mode which cause this callback to invoked https://github.com/hathach/tinyusb/pull/1025/files#diff-197babc2310c6d123603f9f2df568b1c1f1857cee19037e747408f146a847d4fR170-R176

You could also use tud_hid_n_get_protocol() to get the current mode and send construct the report accordingly.

• If report mode: report is sent accordingly to descriptor like we are currently doing (can be composite)
• If boot mode: only send 8 bytes of keyboard report (no ID) since we implement boot keyboard.

I have just downloaded the automatic build and it seems to fix my problems on Windows. The keyboard can be used right after booting. Thanks a lot for the great work.

The HID keyboard currently presented by CircuitPython is not a boot device keyboard, with its own endpoint(s), which is what the Mac Open Firmware (“BIOS”) and regular PC BIOSes expect. It’s part of a composite HID device that includes mouse, multimedia keys, and a gamepad. This was to save endpoints for other purposes.

We’ve had one other person who wants a boot-compatible keyboard and we’re thinking about that - we have to count up the available endpoints and what we want for the future (e.g. USB MIDI). Also, in the long run, we are thinking about how to provide user-configurable HID devices.

When I set boot_device=1, the KVM doesn’t work unless I supply your descriptor as a parameter. I don’t think it’s ignoring it.

You do need a descriptor. How it works is a bit more complicated than one might expect. If you set boot_device=1, then CircuitPython says it is capable of being a boot keyboard. But it doesn’t do so unless the host asks for it to be a boot keyboard. If the host doesn’t ask, then the supplied descriptor is used. If the host does ask, then the supplied descriptor is sent but ignored, and the host assumes the “standard” one.

Thank you for the analysis on the descriptor, and your corrections to mine also work with my KVM, as you probably expected!

When I set boot_device=1, the KVM doesn’t work unless I supply your descriptor as a parameter. I don’t think it’s ignoring it.

#usb_hid.enable((usb_hid.Device.KEYBOARD,), boot_device=1 )
# above line does not work with Belkin SOHO KVM

#usb_hid.enable((reference_keyboard,), boot_device=1 )
# above line works fine with Belkin SOHO KVM

"""CircuitPython Essentials Storage logging boot.py file"""
import board
import digitalio
import storage
import usb_cdc
import usb_midi
import usb_hid
from time import sleep

switch = digitalio.DigitalInOut(board.D5)

switch.direction = digitalio.Direction.INPUT
switch.pull = digitalio.Pull.UP
sleep(0.1)

REFERENCE_BOOT_KEYBOARD_DESCRIPTOR=bytes((
0x05, 0x01,        # Usage Page (Generic Desktop Ctrls)
0x09, 0x06,        # Usage (Keyboard)
0xA1, 0x01,        # Collection (Application)
0x05, 0x07,        #   Usage Page (Kbrd/Keypad)
0x19, 0xE0,        #   Usage Minimum (0xE0)
0x29, 0xE7,        #   Usage Maximum (0xE7)
0x15, 0x00,        #   Logical Minimum (0)
0x25, 0x01,        #   Logical Maximum (1)
0x75, 0x01,        #   Report Size (1)
0x95, 0x08,        #   Report Count (8)
0x81, 0x02,        #   Input (Data,Var,Abs,No Wrap,Linear,Pr
0x95, 0x01,        #   Report Count (1)
0x75, 0x08,        #   Report Size (8)
0x81, 0x01,        #   Input (Const,Array,Abs,No Wrap,Linear
0x95, 0x03,        #   Report Count (3)
0x75, 0x01,        #   Report Size (1)
0x05, 0x08,        #   Usage Page (LEDs)
0x19, 0x01,        #   Usage Minimum (Num Lock)
0x29, 0x05,        #   Usage Maximum (Kana)
0x91, 0x02,        #   Output (Data,Var,Abs,No Wrap,Linear,P
0x95, 0x01,        #   Report Count (1)
0x75, 0x05,        #   Report Size (5)
0x91, 0x01,        #   Output (Const,Array,Abs,No Wrap,Linea
0x95, 0x06,        #   Report Count (6)
0x75, 0x08,        #   Report Size (8)
0x15, 0x00,        #   Logical Minimum (0)
0x26, 0xFF, 0x00,  #   Logical Maximum (255)
0x05, 0x07,        #   Usage Page (Kbrd/Keypad)
0x19, 0x00,        #   Usage Minimum (0x00)
0x2A, 0xFF, 0x00,  #   Usage Maximum (0xFF)
0x81, 0x00,        #   Input (Data,Array,Abs,No Wrap,Linear,
0xC0,              # End Collection
))

reference_keyboard = usb_hid.Device(
    report_descriptor=REFERENCE_BOOT_KEYBOARD_DESCRIPTOR,
    usage=0x06,
    usage_page=0x01,
    report_ids=(0,),
    in_report_lengths=(8,),
    out_report_lengths=(1,),
    )
    
maintenance_mode = not switch.value
if not maintenance_mode:
    storage.disable_usb_drive()
    usb_cdc.disable()
    usb_midi.disable()
    usb_hid.enable((reference_keyboard,), boot_device=1 )
else:
    usb_hid.enable((usb_hid.Device.KEYBOARD,))

#usb_hid.enable((usb_hid.Device.KEYBOARD,), boot_device=1 )
# above line does not work with Belkin SOHO KVM

#usb_hid.enable((reference_keyboard,), boot_device=1 )
# above line works fine with Belkin SOHO KVM

"""output from this boot.py
Adafruit CircuitPython 7.1.0-rc.1 on 2021-12-25; Adafruit Feather M4 Express with samd51j19
Board ID:feather_m4_express
boot.py output:
"""

Again, thanks for your time, let me know if I can test anything else for you, as I am super-thankful of all of your time and effort spent on making CircuitPython work for us (especially for first-time Python programmers like myself!)

I am not implementing boot keyboard in the first pass of dynamic USB descriptors, which I am working on right now. But internally the implementation is flexible enough to add later. Once I get the first version working it can be revisited.

@hathach Are you sure about the not needed extra endpoint? I tried a few times getting this to work with the arduino environment and to have an idea where the issue is i used this tool https://www.thesycon.de/eng/usb_descriptordumper.shtml and a real keyboard always used an extra endpoint.

@dhalbert during my research i never found someone asking for a boot mouse. Most BIOSes are configured by keyboard and Hotkeys in KVMs are also done with a keyboard

But when in boot mode, you don’t need MSC and CDC and MIDI, no?

Good point - it’s more a question of having code space on the smallest builds to switch back and forth.

@dhalbert boot keyboard doesn’t need to be on its own interface and/or take extra endpoint. It can be used with existing HID device. Basically the HID device has 2 mode (or protocol): boot mode, and report mode (default).

• In report mode: it is composite (keyboard + mouse + media key)
• In boot mode: it only report 8 bytes of keyboard report (no report ID)

Most bios will always start with SET_PROTOCOL = BOOT upon enumeration. We only need to handle the callback, set the mode correctly then skip all other report except keyboard. I will update my hid_composite example in my repo so that you could have a clear example to follow in circuitpython later on. Will tag you on the modification later on, may try to submit PR myself as well. Though for the flash size, it may indeed increase a bit of space.