search

zmkfirmware / zmk

ZMK Firmware Repository
https://zmk.dev/
MIT License
2.82k stars 2.85k forks source link

Standardize Keys #21

Closed innovaker closed 4 years ago

innovaker commented 4 years ago
petejohanson commented 4 years ago

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

tominabox1 commented 4 years ago

Add scope of #158 to this

innovaker commented 4 years ago

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 commented 4 years ago

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/

Design Considerations (thus far)

innovaker commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

okke-formsma commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

I need some help please! You'll need a working ZMK development build and keyboard.

You'll need to change line 18 in hid.h from: #define ZMK_HID_MAX_KEYCODE GUI to #define ZMK_HID_MAX_KEYCODE 0xFB

Please could you test the differences within these sets of codes with your OS? I expect them to work on Linux, maybe Android. I'm not sure about Windows/iOS.

Set 1 These should be page/scroll down codes, so you can probably use a long webpage. But there might be subtle differences in the scrolling style? I'm not sure. &kp 0x4E &kp 0xF6

Set 2 These should be page/scroll up codes, so you can probably use a long webpage. But there might be subtle differences in the scrolling style? I'm not sure. &kp 0x4B &kp 0xF5

Set 3 These should be stop codes. But they might be "stop browser/activity" or "stop media". So I'd suggest playing a song on the OS's default music player, and then test the key whilst trying to reload a webpage (i.e. stop). If you know of any application that also accepts a stop command, that would be a useful test too. &kp 0x78 &kp 0xE9 &kp 0xF3

Thanks!

innovaker commented 4 years ago

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 commented 4 years ago

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:

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.

innovaker commented 4 years ago

Until someone has a better idea, I've applied the 2 suffixes as described by: https://github.com/zmkfirmware/zmk/issues/21#issuecomment-696704156 for the keys that don't need further identification

Remaining conflicts are those described by: https://github.com/zmkfirmware/zmk/issues/21#issuecomment-696700763

petejohanson commented 4 years ago

One comment: I think it's good to prefix the consumer page stuff. We should keep those "clean" and then consider helpful aliases/shorthands from there for a subset.

innovaker commented 4 years ago

@petejohanson, have you any thoughts on the strategy for introducing/testing the new codes please? I've previously suggested that we throw them out there and see what sticks (because it's based on documentation they should all just depend on the OS), but that does leave open the possibility of potentially having to pull some codes ... for whatever reason once testing is done. It's akin to throwing out the alpha/beta to everyone vs. drip feeding after thorough testing.

petejohanson commented 4 years ago

This really does need user testing on a variety of OS's to really understand what works/doesn't. I would suggest we move forwards with this, and then test, and refactor as needed. I think as long as the "core" still works, then minor tweaks/breakage for consumer keys, etc we can handle and fix.

innovaker commented 4 years ago

Following up my earlier request: https://github.com/zmkfirmware/zmk/issues/21#issuecomment-696700763

I've tested:

on Windows, Linux and Android. iOS wasn't tested.

Support

Linux

Tested using evtest:

So I've named the ZMK aliases following this convention.

innovaker commented 4 years ago

Following up my earlier request: https://github.com/zmkfirmware/zmk/issues/21#issuecomment-696700763

I've tested:

on Windows, Linux and Android. iOS wasn't tested.

Windows

Tested using VLC, Windows Media Player, Chrome and Firefox:

Linux

Tested with evtest:

Android

Tested with Google Music, Chrome and Firefox:

innovaker commented 4 years ago

Based on the above results, I've gone with ...

which means most users will want to use &cp C_STOP for media/music controls, and &cp C_AC_STOP for internet browsers.

This works well, because the other media controls seem to be (not tested) C_PLAY, C_PAUSE_PLAY, C_PAUSE, C_RECORD, C_NEXT, C_PREVIOUS, C_STOP, C_EJECT and C_REPEAT, C_MUTE, C_VOLUME_UP and C_VOLUME_DOWN. I'd bet these also work on some TVs. For anyone wondering, the current M_ aliases point to some of these codes. The M_ prefix is currently destined to be deprecated.

The keyboard (&kp) STOP, STOP2, STOP3 keys don't seem to be so widely supported and frankly I don't know the true intended meaning behind them beyond the description Keyboard Stop.

This decision brings all outstanding conflicts to a close.

innovaker commented 4 years ago

Whilst working through the documentation (#218), this occurred to me regarding the keyboard page 0x07.

Solution?

So that this current issue can move forward in safety, I'm going to add a K_ prefix to anything that:

We can then decide prefix-less codes once the system has matured and OS testing is complete.

This would include ...

0x0007 0x0066   Keyboard Power
0x0007 0x0074   Keyboard Execute
0x0007 0x0075   Keyboard Help
0x0007 0x0076   Keyboard Menu
0x0007 0x0077   Keyboard Select
0x0007 0x0078   Keyboard Stop
0x0007 0x0079   Keyboard Again
0x0007 0x007A   Keyboard Undo
0x0007 0x007B   Keyboard Cut
0x0007 0x007C   Keyboard Copy
0x0007 0x007D   Keyboard Paste
0x0007 0x007E   Keyboard Find
0x0007 0x007F   Keyboard Mute
0x0007 0x0080   Keyboard Volume Up
0x0007 0x0081   Keyboard Volume Down
0x0007 0x009B   Keyboard Cancel
0x0007 0x00E8   Keyboard Play/Pause
0x0007 0x00E9   Keyboard Stop
0x0007 0x00EA   Keyboard Previous
0x0007 0x00EB   Keyboard Next
0x0007 0x00EC   Keyboard Eject
0x0007 0x00ED   Keyboard Volume Up
0x0007 0x00EE   Keyboard Volume Down
0x0007 0x00EF   Keyboard Mute
0x0007 0x00F0   Keyboard WWW
0x0007 0x00F1   Keyboard Back
0x0007 0x00F2   Keyboard Forward
0x0007 0x00F3   Keyboard Stop
0x0007 0x00F4   Keyboard Find
0x0007 0x00F5   Keyboard Scroll Up
0x0007 0x00F6   Keyboard Scroll Down
0x0007 0x00F7   Keyboard Edit
0x0007 0x00F8   Keyboard Sleep
0x0007 0x00F9   Keyboard Lock
0x0007 0x00FA   Keyboard Refresh
0x0007 0x00FB   Keyboard Calculator

It's not a perfect approach, but I think it's better for the future.

Any thoughts welcomed.

okke-formsma commented 4 years ago

As discussed on Discord, I think we should try to limit ourselves to one or two names for a specific keycode. For example, there are six writings for slash in the file:

I think it's important to have preferably one way to write a keycode. In some cases a short (8 chars or less) and verbose version would be in order, but that seems to be enough for all purposes.

I don't have strong opinions on which codes are picked as long as we make a choice and stick to it. In the case of slash, I think just SLASH would be perfectly fine. Short versions are not required for keys outside of the default keyboard/keypad HID, as they are used less often. People can always define their own short versions for a few keys if they care about these things.

@petejohanson has agreed to pick one or two spellings for each key in his role as BDFL.

innovaker commented 4 years ago

Thanks for the input @okke-formsma. That sounds along the same lines that we have in mind.

I've prepared the RFC sheet for @petejohanson to review for the purpose when he gets a chance.

innovaker commented 4 years ago

Just to add to that for anyone watching who wants to be involved ... please add comments on specific keys to the RFC sheet so that we can track per item comments in a single location! 👍