Is there an issue with the generated keyboard descriptor?

[bschwind]

Hi, I'm building a keyboard and am currently using this crate. I'm currently using it on MacOS.

I noticed I'm receiving phantom key inputs when I hold down 4 or more keys. Normally this would sound like ghosting, but my keyboard has diodes on every switch, and I verified with probe-run and defmt that I'm not adding these characters to the KeyboardReport struct.

• When 3 keys are held down and a fourth is pressed
  • The letter a gets inserted after the fourth press
• When 4 keys are held down and a fifth is pressed
  • The letter b gets inserted after the fifth press
• When 5 keys are held down and a sixth is pressed
  • The letter c gets inserted after the sixth press

For example:

• Held keys: q, w, e
  • Pressing r results in qwera instead of qwer
• Held keys: q, w, e, r
  • Pressing t results in qweratb instead of qwert
• Held keys: q, w, e, r, t
  • Pressing y results in qweratbyc instead of qwerty

I eventually narrowed this down to the keyboard HID descriptor. I swapped it out for one from another project, and now the keyboard works properly with the scenarios above:

bschwind/key-ripper#10

I don't yet know enough about USB HID descriptors to say what's going on, but it feels like a byte is out of place somewhere.

[twitchyliquid64]

How are you filling in the descriptor? There should be 6 slots for scancodes:

usbd-hid/src/descriptor.rs

Line 83 in d0a8000

pub keycodes: [u8; 6],

[bschwind]

I start with an array of 6 zeroes. Then as I walk over my key matrix I push up to 6 keycodes into that keycodes array.

You can see the code for that here:

https://github.com/bschwind/key-ripper/blob/main/firmware/src/main.rs#L222

[twitchyliquid64]

Gotcha!

I've got two possible theories right now:

1. The OSX HID parser is hardcoded or being needy - unfortunately stub HID implementations are all too common. Do you see the same behavior on Linux? The Linux parser is the only one i trust not to get all uppity.
2. The descriptor or the report is subtly malformed. Can you dump the bytes for the descriptor + a report-with-4-keys-pressed, and we can go through it manually to verify?

[bschwind]

I'll test this on a linux machine this Thursday when I have access to one, currently sitting out the rest of a quarantine period after covid 😅

Here's the descriptor I currently get from KeyboardReport::desc():

0x05,0x01
0x09,0x06
0xa1,0x01
0x05,0x07
0x19,0xe0
0x29,0xe7
0x15,0x00
0x25,0x01
0x75,0x01
0x95,0x08
0x81,0x02
0x19,0x00
0x29,0xff
0x26,0xff
0x00,0x75
0x08,0x95
0x01,0x81
0x03,0x05
0x08,0x19
0x01,0x29
0x05,0x25
0x01,0x75
0x01,0x95
0x05,0x91
0x02,0x95
0x03,0x91
0x03,0x05
0x07,0x19
0x00,0x29
0xdd,0x26
0xff,0x00
0x75,0x08
0x95,0x06
0x81,0x00
0xc0

Here's a report with 4 keys pressed:

INFO  Descriptor: modifier=0, reserved=0, leds=0, keycodes=[20, 26, 8, 21, 0, 0]

INFO  serialized: [0, 0, 20, 26, 8, 21, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

With a different HID (specified here), I get:

INFO  Descriptor: modifier=0, reserved=0, leds=0, keycodes=[20, 26, 8, 21, 0, 0]

INFO  serialized: [0, 0, 20, 26, 8, 21, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

[bschwind]

Hi @twitchyliquid64, sorry to get back to you so late on this.

I tested the keyboard with your descriptor on a linux machine and it functioned correctly, so this seems to be a quirk with macos.

[d3zd3z]

This report descriptor is indeed incorrect, and does seem to confuse MacOS. I haven't completely figured out what is wrong with it. But, if this is supposed to be claiming to be a "USB HID Boot Keyboard Report Descriptor" (and there is no particular reason on limit it to 6 keys if it isn't), the descriptor needs to be exactly as described in the USB HID Specification. At least on MacOS, the modifiers don't seem to work unless the scancodes also contain the modifiers.

For reference, the descriptor from the standard should be:

Usage Page (Generic Desktop),
Usage (Keyboard),
Collection (Application),
Report Size (1),
Report Count (8),
Usage Page (Key Codes),
Usage Minimum (224),
Usage Maximum (231),
Logical Minimum (0),
Logical Maximum (1),
Input (Data, Variable, Absolute), ;Modifier byte
Report Count (1),
Report Size (8),
Input (Constant), ;Reserved byte
Report Count (5),
Report Size (1),
Usage Page (LEDs),
Usage Minimum (1),
Usage Maximum (5),
Output (Data, Variable, Absolute), ;LED report
Report Count (1),
Report Size (3),
Output (Constant), ;LED report padding
Report Count (6),
Report Size (8),
Logical Minimum (0),
Logical Maximum(255),
Usage Page (Key Codes),
Usage Minimum (0),
Usage Maximum (255),
Input (Data, Array),
End Collection

I have also confirmed that using a more standard report descriptor, the protocol works great with MacOS:

  static USB_KEYB_HID_DESC: &[u8] = &[
      0x05, 0x01,   // Usage Page (Generic Desktop)
      0x09, 0x06,   // Usage (Keyboard)
      0xA1, 0x01,   // Collection (Application)
      0x05, 0x07,   // Usage Page (Key Codes)
      0x19, 0xE0,   // Usage Minimum (Left Control)
      0x29, 0xE7,   // Usage Maximum (Right GUI)
      0x15, 0x00,   // Logical Minimum (0)
      0x25, 0x01,   // Logical Maximum (1)
      0x75, 0x01,   // Report Size (1)
      0x95, 0x08,   // Report Count (8)
      0x81, 0x02,   // Input (Data, Variable, Absolute) - Modifier keys
      0x95, 0x01,   // Report Count (1)
      0x75, 0x08,   // Report Size (8)
      0x81, 0x01,   // Input (Constant) - Reserved byte
      0x95, 0x06,   // Report Count (6)
      0x75, 0x08,   // Report Size (8)
      0x15, 0x00,   // Logical Minimum (0)
      0x25, 0x65,   // Logical Maximum (101)
      0x05, 0x07,   // Usage Page (Key Codes)
      0x19, 0x00,   // Usage Minimum (0)
      0x29, 0x65,   // Usage Maximum (101)
      0x81, 0x00,   // Input (Data, Array)
      0xC0          // End Collection
  ];

[twitchyliquid64]

Whelp, sounds like MacOS is on the naughty list too

[d3zd3z]

There are only a few differences in the descriptor from the standard USB boot:

1. The padding is reserved as 0 in the standard, and this one allows arbitrary data there (both modifiers, and leds, and the reserved byte.
2. The possible scancode range is larger than the standard.
   For one or both of these reasons, MacOS seems to be deciding that this is a "non boot compliant" keyboard. It seems as a consequence:

• It ignores the modifier bits entirely. Modifiers as explicit scancodes do work, but is even more annoying with...
• It only seems to support 4 key NKRO.

There are various keyboard firmware projects out there that support extended keyboard reports that seem to work widely. Given that we have a standard report, I don't see any particular reason to make changes to the HID report.

[bschwind]

I ended up writing my own HID class implementation as an exercise to learn it more deeply:

https://github.com/bschwind/key-ripper/blob/main/firmware/src/hid_class.rs

It doesn't do NKRO for now, but it works well on MacOS and Linux, haven't tested Windows yet.