Difficulties in understanding sombolic key names

Help and Getting Started
1

I am still learning how to use Kaleidoscope. Therefore my question may seem silly and obvious. Sorry for that.

In the existing Model100.ino some symbolic key names are used, like Key_Equals, Key_Slash, etc. More can be found in the files below src/kaleidoscope/key_defs/.

But I am not sure how they should be used. I expected them to match the actual keycodes, so I can use them to specify the keycode that should be produced by a certain key. But I found, that they are totally dependend on the keyboard layout selected in the OS. For example if I define my custom keymap with a QWERTY keymap on the OS side in mind it works. But if the keyboard layout on the OS is e.g. QWERTZ, the resulting characters are mostly different.

This makes it rather hard to use them. What is the intended way to use such symbolic names if one intends to use the keymap with a host layout different than QWERTY?

Also, I noticed that a lot of symbolic key names are missing. Those are mostly the ones that are shifted variants in QWERTY. For example Key_Colon does not exist. It could be created by LSHIFT(Key_Semicolon) when using a QWERTY layout. But I noticed that e.g. Key_Pipe already is defined in aliases.h. Why have some symbolic names been predefined and others are not?

Also, as they depend on QWERTY being the OS keyboard layout, they mostly do not work with other layouts.

Sorry for the dumb questions, but I am not used to programming my keyboard and have a few difficulties understanding the concepts behind it.

1 Like
2

As far as the OS is concerned, “keycode” usually means the number associated with a physical key location on a keyboard. What user-visible letter or symbol it produces is a matter of mapping done by the OS. The keycode sent by Kaleidoscope is the key usage number defined by the USB HID specification. The symbolic name of the key usage might not correspond to how the OS interprets the key, especially in a non-US locale.

In the HID specification, the names of the key usage numbers are based on their typical use on an ANSI (North American or US English) keyboard. The spec gives the example of the key labeled “Z” on a German keyboard (which is in the same location as “Y” on a North American keyboard) producing the key usage number for “Y”, which the OS interprets as “Z”. This is to help manufacturers produce keyboards sharing the same electronics, only vary the key caps on a per-locale basis.

As you noticed, there are some aliases defined in key_defs/aliases.h, such as:

#define Key_LeftCurlyBracket  LSHIFT(Key_LeftBracket)

but some other aliases are missing. I’m not sure of the rationale for the choice of which aliases were defined. It might be that those happen to be the symbols that are used in the default keymaps.

Yes, this makes it harder to define a custom key map if your OS key layout isn’t QWERTY. It isn’t feasible to create and maintain header files with alternative symbolic name mappings for every possible OS keyboard layout. If you are editing a keymap in a custom sketch, you will probably have to look up the correct symbols to use, referring to a QWERTY keyboard layout.

In Chrysalis, this is easier. If you set the OS key layout in Preferences, the key picker and the keyboard preview will both show remapped key labels corresponding to how your OS would interpret the keys. The key usage numbers sent to the OS by your keyboard remain the same until you edit the layout.

Note that there’s currently a small bug: after you change your OS keymap in Preferences, you will have to go back to “Select another keyboard”, click “Disconnect”, and then reconnect, before the editor will show the updated key labels in the preview.

2 Likes
3

Thank you for your explanations!

Yes, it’s a rather complicated topic. That’s probably what confused me. I didn’t know that the HID specification already defines such key names.

So, as I intend to use a non-QWERTY host keymap, I will problably have to avoid or redefine those symbolic key names. Otherwise the keymaps will be a bit hard to read.

4

It’s probably easier to use Chrysalis to edit keymaps for a non-US OS key layout.

If you intend to define your own aliases for custom firmware sketches, I suggest using a different prefix, to avoid conflicts with the existing aliases. For example, for a German OS key layout, you might try using a Key_DE_ prefix instead of Key_:

#define Key_DE_Y       Key_Z
#define Key_DE_Z       Key_Y
#define Key_DE_OUmlaut Key_Semicolon

You could write those #defines at the top of your sketch, or in a new local header file that you include.

1 Like
5

OK, I mainly managed to map the keys correctly. But there is one key I can’t reference, because I don’t know which symbolic name is referring to it. It is the key between the left shift and the Z (on a european QWERTY keyboard). An image of it can be seen here. In that link it is named as “IntlBackslash”. But what is the correct name in keyboard.h for it?

I need it, because in a german layout that is the position of the keys <, > and |.

Can someone help me here?

6

I think it is this one:

#define Key_NonUsBackslashAndPipe Key(HID_KEYBOARD_NON_US_BACKSLASH_AND_PIPE, KEY_FLAGS)
1 Like
7

As I have to do some definitions in the .ino file anyways, I thought it would be easier to define everything in it and not split it between the .ino file and Chrysalis.

I would be happy to create my layout in Chrysalis first, and then transfer it to the .ino file, but I have no idea how to map the Chrysalis layout to the keymap definition in the .ino file.

That leaves me with the problem now, that I don’t know how to refer to the “IntlBackslash” key mentioned above.

Yes, that was my first idea, too. At the moment I haven’t done so and therefore overrode some preexisting ones, but I will change it to use such a prefix. It will be much more readable then.

1 Like
8

You are right! That’s the one!

Many thanks. You really helped me here.

1 Like
9

There is an open feature request in Chrysalis to export the keymap as a .ino file fragment Output keymaps as code for pasting into an ino · Issue #77 · keyboardio/Chrysalis · GitHub
If you have a GitHub account, you might like to add your opinions and ideas to that. (If not, one of us could relay your comments, or maybe link to this forum thread.)