fix(usb): detect USB power mode to fallback to BLE

[angweekiat]

Update zmk_usb_is_hid_ready to check that HID configuration from the host has been done, before allowing the keyboard to be used as a HID device.

This is done by adding bool is_configured and toggling it off when the device is disconnected, and enabling it when usb_status == USB_DC_CONFIGURED.

This is a naive solution for #841, where having a USB-power cable without data driving the keyboard, like a power bank, still has the firmware thinking that it's connected to a host and futilely sending data over USB.

When the cable to a power source is plugged in, the USB DC status (from Zephyr) goes through the following states:

USB_DC_CONNECTED -> USB_DC_SUSPEND

While for cables to a host machine:

USB_DC_CONNECTED -> USB_DC_SUSPEND -> USB_DC_RESUME -> USB_DC_RESET -> USB_DC_CONFIGURED

The status code list can be found at https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/drivers/usb/usb_dc.h#L33-L58

In the case of a power bank being plugged in, the code changes above allow zmk_usb_is_hid_ready to declare that HID isn't ready yet, and thus allows endpoints.c to fallback to BLE connection.

Steps to reproduce the original issue

1. (Setup) Have ZMK keyboard with Bluetooth profile enabled
2. Set the keyboard to prefer sending to USB (&out OUT_USB)
3. Power on the keyboard via USB via a power bank
4. Type, text should not show up anywhere ('consumed' by power bank)

Testing

• Built and flashed the firmware with the commit changes, ran the same steps above, and text showed up on the expected device.
• Tested using 2 laptops (Ubuntu / Windows) using 2 different power banks.
• Tested for regression, keyboard still works as expected for waking up the host machine (CONFIG_USB_DEVICE_REMOTE_WAKEUP=y) and for boot protocol (CONFIG_ZMK_USB_BOOT=y).

Concerns

• I can't find any USB or USB HID specifications that explicitly state that the host machine will do the USB configuration step before the USB HID connection is considered complete.
• It's my first time contributing to ZMK, please let me know how the pull request can be improved!

[petejohanson]

Thanks for the PR!

One major question about testing/statuses for another scenario.

[petejohanson]

Have you had a chance to confirm the state it enters when a host is connected but sleeps/requests the USB device sleep? We should also confirm this is set up properly when making changes here.

Also, are we sure this is consistent across all the Zephyr USB drivers?

[angweekiat]

Hi, I tested these additional scenarios:

1. Connecting the keyboard to my laptop, sleeping the laptop, and waking it via keyboard, this works
2. Sleeping the laptop, then connect the keyboard, then wake it via keyboard, this works as well

Strangely, the keyboard didn't transition to any suspended state with the laptop, which feels concerning. If it helps, the board I'm testing with is nice nano v2, but I'm uncertain if this behaviour should be expected across all USB drivers.

I was being dumb and locked my laptop instead of sleeping it properly, the state does get set into suspended. When suspended, I wasn't able to wake the laptop from the keyboard, but I want to also check if this is expected behavior even from main branch.

To account for other behaviors from other devices, perhaps a better approach is to revert the mapping changes, and keep track that the keyboard has at least gone through the USB_DC_CONFIGURED state once, before allowing it as a possible endpoint? (Need to see if this works with ZMK_USB_BOOT)

[petejohanson]

I was being dumb and locked my laptop instead of sleeping it properly, the state does get set into suspended. When suspended, I wasn't able to wake the laptop from the keyboard, but I want to also check if this is expected behavior even from main branch.

It should, if you have CONFIG_USB_DEVICE_REMOTE_WAKEUP=y and the USB driver supports it (which the nrfx one does). In particular, since "suspended" is still considered USB active, then any attempt to send will still pick the USB endpoint, which ultimately triggers this code: https://github.com/zmkfirmware/zmk/blob/main/app/src/usb_hid.c#L132

To account for other behaviors from other devices, perhaps a better approach is to revert the mapping changes, and keep track that the keyboard has at least gone through the USB_DC_CONFIGURED state once, before allowing it as a possible endpoint? (Need to see if this works with ZMK_USB_BOOT)

Yeah, I think "has gone through configured state but hasn't gone to disconnected" may be the best way to really track this?

[angweekiat]

Thanks for the pointers! I changed the code to what we mentioned above, and regression tested that both the wake and boot protocol functionality still works as expected, and also updated the PR description to match.

I did it by adding another is_configured bool, but if space is a concern, it's possible to change usb_status to store both the status code and this flag as a bitfield and parsing out the values separately, at the cost of readability.