[feature] add support for USB programmable buttons usage

[t-8ch]

Description

This adds the possibility to send "Programmable Button" events.
These are defined in the USB "Consumer Page" as
"The user defines the function of these buttons to control software
applications or GUI objects."

This allows QMK to emit events that can be handled by bespoke software
on the host without having to worry about other software trying to
handle them.

Open points:

• This is only implements for the VUSB backend, other backends will crash
• This creates a whole new USB report, as all the existing infrastructure is set up to work with 16bit records
  • This nicely fits with the fact that USB also allows 2**16 of these programmable buttons
• The interface should probably provide macros create programmable buttons with arbitrary IDs instead of having to hardcode macros for all of them
• Depending on the amount of programmable buttons that should be supported this will need better integration into the internal QMK keycode table
• Operating system support is limited
  • I have a patch for Linux that will add support, which I will publish (and link here)
  • Other operating systems should be tested, too
• All open points from the checklist below, this is meant as a basis for discussion

Types of Changes

• Core
• Bugfix
• New feature
• Enhancement/optimization
• Keyboard (addition or update)
• Keymap/layout/userspace (addition or update)
• Documentation

Checklist

• My code follows the code style of this project: C, Python
• I have read the PR Checklist document and have made the appropriate changes.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• I have tested the changes and verified that they work and don't break anything (as well as I can manage).

[t-8ch]

Patch to Linux: https://lore.kernel.org/linux-input/20210519160349.609690-1-linux@weissschuh.net/

[sigprof]

Is there any existing software that supports these usage codes, or maybe even some hardware that actually send these keycodes?

Did you test how would Windows behave when seeing a device with such HID descriptor?

[t-8ch]

Is there any existing software that supports these usage codes, or maybe even some hardware that actually send these keycodes?

I have no real hardware. For the implementation in Linux I first implemented a uhid program which implements a HID device in userspace. After that I implemented the support in QMK and tested it with the Linux implementation.

[t-8ch]

Maybe it would be better have these buttons only in the quantum keymap?

[t-8ch]

@sigprof Thanks for your reviews!
I converted the whole feature to use the quantum keycode table and support 32 keys now.

[t-8ch]

FYI the host side implementation for Linux has been accepted and is scheduled to end up in Linux 5.14:
https://git.kernel.org/pub/scm/linux/kernel/git/hid/hid.git/commit/?h=for-5.14/core&id=bcfa8d14570d85c998a9b706b074ab151b286edf

[t-8ch]

FYI I tested the latest rebase and it still works.

[drashna]

Thanks!

[t-8ch]

Thank you all :-)

[drashna]

well, fun... this is breaking a bunch of boards:
https://qmk.tzarc.io/

Compiling: tmk_core/common/avr/printf.c                                                             [OK]
Compiling: tmk_core/protocol/lufa/lufa.c                                                           tmk_core/protocol/lufa/lufa.c: In function ‘send_report’:
tmk_core/protocol/lufa/lufa.c:769:29: error: ‘SHARED_IN_EPNUM’ undeclared (first use in this function)                                                      
     Endpoint_SelectEndpoint(SHARED_IN_EPNUM);
                             ^                                                                                                                                  
tmk_core/protocol/lufa/lufa.c:769:29: note: each undeclared identifier is reported only once for each function it appears in                                    
tmk_core/protocol/lufa/lufa.c: At top level:                                                                                                                    
tmk_core/protocol/lufa/lufa.c:764:13: error: ‘send_report’ defined but not used [-Werror=unused-function]                                                   
 static void send_report(void *report, size_t size) {
             ^                                                                                                                                                  
cc1: all warnings being treated as errors
 [ERRORS]
 | 
 | 
 | 
make[1]: *** [tmk_core/rules.mk:443: .build/obj_0xc7_61key_via/lufa.o] Error 1

[t-8ch]

@drashna Want me to prepare a fix or are you working on it already?

[drashna]

@drashna Want me to prepare a fix or are you working on it already?

I haven't taken a look at where the issue is exactly, so please do!

[t-8ch]

@drashna #14454
Sorry for that...

[drashna]

no worries! That's part of why we have the develop branch