Standardize Keys

[innovaker]

• Revisit/refactor current dt-bindings/zmk/keys.h
• Include any useful values for USB or HOGP from HID Usage Tables v1.12:
  https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf
• Consider values and naming conventions found in existing KB firmware, Linux, Windows, Android, etc.
• Decide upon any conventions for ZMK.
• Open up consultation with the ZMK contributor community before finalizing.

[petejohanson]

Updated usage tables version: https://usb.org/sites/default/files/hut1_2.pdf

[tominabox1]

Add scope of #158 to this

[innovaker]

Let's make a concerted effort to nail this down, including @tominabox1's efforts on #161 and taking into account the effects of #86.

[innovaker]

It's RFC time!  Feedback, suggestions and discussions welcomed! Everything is still on the table at this point.

To facilitate this first pass, we're using Google Sheets as a living document.  It contains the proposed names (tags) and descriptions that are used for the key-press behavior (&kp, &cp):

RFC: https://docs.google.com/spreadsheets/d/1s6URDIL7pqcMiUvY8s0esWvLIA1dKNmHqp6jEUtrqTw/

• Feel free to make focused comments (per cell) in the sheet itself, but please use this GitHub issue for more general or cross-cutting discussions.
• Please let people know who you are, either by:
  • signing into Google with an account that has the same visible name as your Discord/GitHub name, OR ...
  • adding your Discord/GitHub name onto each comment (i.e. -innovaker).
• The white cells contain the stuff that will be put into ZMK. This is the focus of the RFC.
• The grey cells contain useful background information from other sources. Please don't comment on these cells.
• I'll be updating the document as each thread of discussion progresses, so it will change over time.
• Be sure to login to the sheet if you want to receive ongoing notifications to comments.
• Care was taken to ensure consistency, but there's bound to be some oversights.  So ... what can you spot!? :)

Design Considerations (thus far)

• There are many ways to slice the "keys cake" and everyone tends to have their own opinions/biases.  Taking this into consideration, I'm suggesting we support a variety of logical aliases for each code - both long and short forms.
• Due to C's namespace limitations and overlaps, the prefix naming conventions at time of writing this post are: 
  • Keyboard: none
  • Keypad: KP_
  • Consumer: C_ 
• I haven't included the entire consumer page as we don't yet have the capacity for that scale of experimenting or testing.  I filtered it down to those supported within existing smartphones or keyboards, plus a few more I thought might be useful.
• I've kept existing key codes unless it was there was a better alternative.  So there may be a few breaking changes, but we'll provide some deprecated compatibility (legacy) support for the foreseeable future.
• Support for each code depends on the operating system.
• The codes listed with (Linux/Android?) in their description appear to be extra keyboard page codes which are not in the HID specification, but they are in Android and Linux (I believe). I guess they're unofficial?

[innovaker]

For those wondering what the code might look like, here's a preview:

/* Keyboard Escape */
#define ESCAPE (HID_USAGE_KEY_KEYBOARD_ESCAPE)
#define ESC    (HID_USAGE_KEY_KEYBOARD_ESCAPE)

/* Keyboard Space */
#define SPACE (HID_USAGE_KEY_KEYBOARD_SPACEBAR)
#define SPC   (HID_USAGE_KEY_KEYBOARD_SPACEBAR)

We'll RFC the code itself as a PR after the initial sheets RFC is completed. Please hold off comments on style until then.
Note: The HID_USAGE_ variables - effectively HID Usage Table definitions - will soon appear as a prerequisite PR.

[innovaker]

I've a couple of general questions to kick off ...

1. Namespace pollution aside, can anyone foresee any potential issues with multiple aliases?

2. Should key names which have two words (e.g. VOLUME UP) be joined with an underscore (VOLUME_UP) or no gap (VOLUMEUP)?

3. Likewise to (2), should prefixes (e.g. for keypad KP_) use an underscore or no gap?

[innovaker]

Regarding interoperability support for other firmware (i.e. QMK, BlueMicro), I'm considering that a separate issue because it can be handled different ways, such as additional header files or key map conversion scripts.

[innovaker]

I'm particularly interested in suggestions for the consumer keys.
They currently follow the HID Usage Table conventions:
C_AL_: Application Launch
C_AC_: Application Control
because otherwise these namespaces conflict with the default consumer namespace C_. e.g.: C_STOP ≠ C_AC_STOP ???
I'd welcome a smarter, more intuitive approach though. Perhaps by using the MEDIA convention? I'll look into it further.

[tominabox1]

I've a couple of general questions to kick off ...

1. Namespace pollution aside, can anyone foresee any potential issues with multiple aliases?
2. Should key names which have two words (e.g. VOLUME UP) be joined with an underscore (VOLUME_UP) or no gap (VOLUMEUP)?
3. Likewise to (2), should prefixes (e.g. KP_) use an underscore or no gap?

1. I don't see the value of multiple aliases personally, but I don't see any reason it is a problem from my prospective anyway.
2. I think I would prefer _
3. Users coming from elsewhere will be accustomed to KP_, I would be inclined to offer this.

I'm particularly interested in suggestions for the consumer keys.
They currently follow the HID Usage Table conventions:
CSM_AL_: Application Launch
CSM_AC_: Application Control
because otherwise these namespaces conflict with the default consumer namespace CSM_. e.g.: CSM_STOP ≠ CSM_AC_STOP ???
I'd welcome a smarter, more intuitive approach though. Perhaps by using the MEDIA convention? I'll look into it further.

Do these Consumer keys even do anything on modern systems?

[innovaker]

Thanks!

Do these Consumer keys even do anything on modern systems?

Honestly I'm not 100% sure without checking them on all OS's. The vast majority that I've listed are documented on Android and Linux though. Plus they could always be intercepted and handled by other services.

[innovaker]

As an experiment, I dropped the C_ namespace from the entire consumer page and compared it against the keyboard/keypad namespace. To be clear, that leaves the AL_ and AC_ conventions intact but without C_. These were the conflicts:

0x000C 0x00B8 Consumer Eject
0x0007 0x00EC Keyboard Eject (Linux/Android?)

0x0007 0x007E Keyboard Find
0x0007 0x00F4 Keyboard Find (Linux/Android?)

0x0007 0x0075 Keyboard Help
0x000C 0x0095 Consumer Help

0x0007 0x0076 Keyboard Menu
0x000C 0x0040 Consumer Menu

0x0007 0x007F Keyboard Mute
0x000C 0x00E2 Consumer Mute
0x0007 0x00EF Keyboard Mute (Linux/Android?)

0x000C 0x00B5 Consumer Scan Next Track
0x0007 0x00EB Keyboard Next (Linux/Android?)

0x0007 0x004E Keyboard Page Down
0x0007 0x00F6 Keyboard Page Down (Linux/Android?)

0x0007 0x004B Keyboard Page Up
0x0007 0x00F5 Keyboard Page Up (Linux/Android?)

0x0007 0x0048 Keyboard Pause/Break
0x000C 0x00B1 Consumer Pause

0x000C 0x00CD Consumer Play/Pause
0x0007 0x00E8 Keyboard Play/Pause (Linux/Android?)

0x0007 0x0066 Keyboard Power
0x000C 0x0030 Consumer Power
0x0007 0x00F9 Keyboard Power (Linux/Android?)

0x000C 0x00B6 Consumer Scan Previous Track
0x0007 0x00EA Keyboard Previous (Linux/Android?)

0x000C 0x0034 Consumer Sleep Mode
0x000C 0x0032 Consumer Sleep (Linux/Android?)
0x0007 0x00F8 Keyboard Sleep (Linux/Android?)

0x0007 0x0078 Keyboard Stop
0x000C 0x00B7 Consumer Stop

0x0007 0x00E9 Keyboard Stop CD (Linux/Android?)
0x0007 0x00F3 Keyboard Stop (Linux/Android?)

0x0007 0x00EE Keyboard Volume Down (Linux/Android?)
0x0007 0x0081 Keyboard Volume Down
0x000C 0x00EA Consumer Volume Decrement

0x0007 0x00ED Keyboard Volume Up (Linux/Android?)
0x0007 0x0080 Keyboard Volume Up
0x000C 0x00E9 Consumer Volume Increment

0x000C 0x008A Consumer Media Select WWW
0x0007 0x00F0 Keyboard WWW (Linux/Android?)

Note: the Linux/Android? codes are not documented in the HID Usage Tables.

[innovaker]

As a second, independent experiment, this time I kept the C_ prefix but dropped the AL_ and AC_ conventions (inherited from the HID specification). These were the conflicts:

0x000C 0x025F Consumer AC Cancel
0x0007 0x009B Keyboard Cancel

0x000C 0x021B Consumer AC Copy
0x0007 0x007C Keyboard Copy

0x0007 0x007B Keyboard Cut
0x000C 0x021C Consumer AC Cut

0x000C 0x0094 Consumer Quit
0x000C 0x0204 Consumer AC Exit

0x0007 0x007E Keyboard Find
0x000C 0x021F Consumer AC Find

0x000C 0x0095 Consumer Help
0x000C 0x01A6 Consumer AL Integrated Help Center

0x000C 0x019E Consumer AL Terminal Lock/Screensaver
0x000C 0x026B Consumer AC Lock

0x0007 0x0076 Keyboard Menu
0x000C 0x0040 Consumer Menu

0x0007 0x007F Keyboard Mute
0x000C 0x00E2 Consumer Mute

0x0007 0x007D Keyboard Paste
0x000C 0x021D Consumer AC Paste

0x0007 0x0048 Keyboard Pause/Break
0x000C 0x00B1 Consumer Pause

0x0007 0x0066 Keyboard Power
0x000C 0x0030 Consumer Power

0x0007 0x0079 Keyboard Again
0x000C 0x0279 Consumer AC Redo/Repeat

0x000C 0x0034 Consumer Sleep Mode
0x000C 0x0032 Consumer Sleep

0x0007 0x0078 Keyboard Stop
0x000C 0x00B7 Consumer Stop
0x000C 0x0226 Consumer AC Stop

0x0007 0x007A Keyboard Undo
0x000C 0x021A Consumer AC Undo

0x0007 0x0081 Keyboard Volume Down
0x000C 0x00EA Consumer Volume Decrement

0x000C 0x00E9 Consumer Volume Increment
0x0007 0x0080 Keyboard Volume Up

0x000C 0x008A Consumer Media Select WWW
0x000C 0x0196 Consumer AL Internet Browser

0x0007 0x004E Keyboard Page Down
0x0007 0x00F6 Keyboard Page Down (Linux/Android?)

0x0007 0x004B Keyboard Page Up
0x0007 0x00F5 Keyboard Page Up (Linux/Android?)

0x0007 0x00E9 Keyboard Stop CD (Linux/Android?)
0x0007 0x00F3 Keyboard Stop (Linux/Android?)

Hopefully these experiments illustrate the complexities of finding a neat solution to the namespace dilemma.

[innovaker]

I'm currently leaning on keeping AL_ and AC_ until someone comes up with a smarter suggestion.

[okke-formsma]

Do we have information on how well supported all of these codepages and keycodes are on the various platforms? I think it makes sense to keep the prefixes on anything that's not widely supported and/or crossplatform.

[innovaker]

Everything listed so far is based on research (please see the sources sheet). It's tricky because we rely on documentation. But my understanding is that keyboard/keypad page is generally universal - except the Linux/Android codes 0xE8 - 0xFB. The consumer page - the ones I've shortlisted - depend on the platform. But they're listed in Android (and Linux), which covers the majority of non-Windows devices. As for iOS, I didn't find much but I'm not part of their developer network.

[innovaker]

To follow that up, I'm considering everything on the keyboard/keypad and consumer pages because you have to look at the big picture to identify workable (hopefully future-proof) naming conventions. But I've shortlisted the consumer page codes to those documented by existing platforms (that's what's on the RFC sheet).

In terms of testing, we don't currently have the capacity to methodically test the codes across all the various platforms. So for now, I'm going by available documentation on the basis that we'll test/fix and find cross-platform issues later.

That said, perhaps we shouldn't document the untested key codes until we empirically compare the platforms?

[innovaker]

Aside from the above, I've mostly confirmed that the unofficial keyboard keys (Linux/Android?) are duplicates of HID official keyboard keys. Weird. Perhaps there's OS nuances that we'll encounter later. For now I suggest we just number them, until we understand them better:
e.g. MUTE and MUTE2, FIND and FIND2, BACK and BACK2, etc.

[innovaker]

I've added a new column to the RFC sheet called Legacy. This shows which existing ZMK codes would be relegated to legacy status. The reasoning depends on each code, but its usually due to:

• being replaced by a convention (i.e. KP_)
• being superseeded by better alternatives
• because it requires a modifier (see Feature: "Shifted Keycodes", e.g. assigning ! to a key press or mod-tap behavior. #86)

Legacy codes will still be usable after the merge of this issue, but would not be documented and will eventually be phased out in the future. So if one of the relegations bothers you, please leave a comment on the associated row.