Creating a keyboard remapping tutorial

[jesse]

@Jennigma

Thanks! I think it will be more helpful in the long run for all concerned if you help me learn to fish rather than catching them for me.

Understood. At the same time, I promised that remapping would be easyish. And since we don’t have the tools & docs in place to make it easy enough for everybody, I feel like I have some obligations there

@Jennigma

Ok, so looked at that region of the code more closely. These are the things I think I’ve puzzled out that weren’t previously apparent to me:

It appears that there are three layered keymaps that are defined: QWERTY, GENERIC_FN2, and NUMPAD. This is sensible.

Correct

@Jennigma

I will take it on faith that there’s a reason GENERIC_FN2 gets used when “Key_Keymap1_Momentary” is held down in the QWERTY layout, and NUMPAD gets activated when “Key_ToggleNumlock” is toggled. Understanding how those are defined as the keys that activate the alternate layouts would be helpful, particularly if I wanted to add another layer myself.

‘GENERIC_FN2’ is a horrible name and a vestige of a time when we had a bunch more keymaps defined in the firmware.

Keymaps are numbered, starting from 0, in the order they’re defined here:

keyboardio/Model01-Firmware/blob/master/Model01-Firmware.ino#L85

The numpad keymap is defined to be keymap #2 here: https://github.com/keyboardio/Model01-Firmware/blob/master/Model01-Firmware.ino#L32
We use that later to tell the numlock implementation what’s going on:

keyboardio/Model01-Firmware/blob/master/Model01-Firmware.ino#L133

It might be better if the code could automatically figure that out somehow. Maybe.

A while back, the numpad layer code was a lot simpler, using Key_Keymap2 to switch to it, rather than the custom macro stuff. Seeing if we can get back to that some day is perhaps a topic for another thread.

@algernon - do you think it’d be plausible to move away from the custom code to toggle numlock? (Note that i’m not asking you to try to make the change, just whether you think it’s plausible

In most cases, you want Key_Keymap3 to change the active keymap to the next new keymap and “stay there” or Key_Keymap3_Momentary to change the active keymap just while the toggling key is held down.

@Jennigma

In each keymap all keys are defined in a comma separated list starting at the upper left of the left section, scanning across each row, and then up to the upper left of the right section.

Yes, though if you wanted the two hands worth of keys defined ‘side by side’, you can use KEYMAP instead of KEYMAP_STACKED. We used to do this. I think it looks nicer on a wide display, but it makes editing harder.

https://github.com/keyboardio/Kaleidoscope/blob/master/examples/Kaleidoscope/Kaleidoscope.ino#L51 is an example of this

@Jennigma

Keys not used in a keymap are still represented in the map as “___”

By defining them as ___, those keys have the behavior they had before the layer was activated. In the case of Numlock, that means that most of the left hand will typically have its QWERTY behavior. This makes it a little easier to create overlay layers that change just a little bit of the keymap.

If, instead, you want to mask out the key in question, Key_NoKey or XXX will make the key a dead key on that layer

@Jennigma

I am assuming that I can modify these maps by changing the order/locations of the key names, eg I could swap “Key_Backspace” and “Key_Spacebar” to get a layout that has Space on the left and Backspace on the right.

That is correct.

@Jennigma

I strongly recommend creating a reference chart for what the key definitions mean. Some are obvious, but others, like “Key_LeftGui” are completely opaque.

Yup. I think we can do that by adding comments to https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs_keyboard.h and letting Doxygen help us out.

(LeftGui is the HID spec name for the Windows key)

@Jennigma

So I believe I have the basics of how to modify the keymap; I’ll try tomorrow, schedule willing.

Awesome. Tell us how it goes. Keep asking lots of questions. Thank you for bearing with us and being friendly about it as you work your way through this.