How to deal with multiple deployments of keymaps

[cbbrowne]

The purpose of this repo appears to be to present The Standard Model 01 firmware, which is a perfectly fine thing.

But if we consider QMK, there are two other purposes that are not perfectly served:

1. There may be interest in sharing some set of keymaps, much as there are, for QMK/Planck, about 70 different keymap sets. There is thus some merit in this repo having a spot for Other Sample Implementations. That said, something that is a bit of a pain about QMK is that the repo is very "chatty" in that people keep adding changes for keymaps that most people don't care about.

2. Presumably many of us will want our own (singular) keymap, that's essentially a variation on The Standard firmware. If I do that by modifying Model01-Firmware.ino, then my changes will forever be fighting with those that others are making in their forks of this repo.

There's merit to the Standard Keymap being something we are intended to clone for ourselves; it seems like a fine thing to have some somewhat opinionated way of doing this.

I'm not sure what's best. The QMK "many keymaps" thing has merit, and there's merit to embracing something like that so that my keymap can coexist happily with the Sample Implementation. But #2 suggests we shouldn't jump straight there...

[Jennigma]

I surfaced more or less this topic yesterday on the forum, with respect to the Dvorak and Colemark keymaps:

https://community.keyboard.io/t/creating-a-keyboard-remapping-tutorial/343/46

Sounds like Jesse is noodling on how to support it. Ideas welcome. :-)

[algernon]

I don't think a comparison to QMK is reasonable here, because QMK does a lot of things differently: it's one single repository, with all functionality, all default keymaps, and all user-contributed keymaps packed into one single place. On the other hand, Kaleidoscope is split across a core firmware, a bunch of plugins, and a factory firmware sketch.

As Kaleidoscope is split into smaller pieces, I do not think it makes sense to have user-contributed keymaps in the factory firmware's repo. That'd be like QMK having user-contributed keymaps at the same directory as the default one (they used to share the same parent directory, but even QMK moved away from that, and puts user-contributed stuff in a clearly separated area now). We'd end up with the same amount of chatter, and so on.

If you fork the Model01-Firmware repo, and make your own changes, you will not be fighting with everyone else: you'll only need to follow upstream changes, and only if you want to. You can just fork off and never update, or only update to pull in stuff You want, or update to use better, newer, easier APIs.

Or, you can start from scratch, too, or from one of the many examples in the plugins (most of which are considerably simpler, albeit less commented) than the factory firmware.

For sharing full sketches, hosting it on GitHub would be one way. Putting the .ino file up somewhere else would be another. For discoverability, one can tag it with a few things like, kaleidoscope, keyboardio, keyboard-layout, or even model01-layout, and we could just search GitHub to discover shared sketches.

Sharing only keymaps, without the rest of the sketch, now that is something different, for which I don't have a proposal for yet.

But these are just my thoughts, someone's who's familiar with both git, Kaleidoscope, and a bunch of other things, so this may or may not be all that friendly for those who are less interested in these details.

[andrewgdotcom]

One problem with using git to track changes is that it is line-based, but the keymaps definition contains half a dozen configuration options per line. Now, there are good reasons for this, but it does mean that tracking individual changes as atomic commits becomes difficult - for example I wanted to swap RAlt and GUI, and also to make changes to the = and - keys. I can't keep these atomic, as they both modify the same line of code.

I already said this elsewhere, but I'll repeat it here as it is on topic. If the keymap definition were a variable rather than a constant, then we could #include files that make incremental changes to the keymap, and each of these files could be tracked and distributed independently. The base keymap definition itself could be one of these include files. As it stands, the keymap definitions are three screenfuls down in among other, unrelated code.

What I would suggest is:

• Split out keymaps from the main config file
• Have a keymap marshalling file that just includes a list of other include files. This could go something like:

// Include standard files here
#include "std_base.layer"
#include "std_fn.layer"
#include "std_num.layer"

// Include custom files here
#include "my_gaming.layer" 
#include "my_swap_cmd_alt.incr"

[algernon]

The keymap needs to be a constant, so that we can put it in PROGMEM (which is read-only). While a keymap could perhaps be split into smaller - still const - parts, in the end, it has to be a const.

[andrewgdotcom]

Understood. In that case, could we construct the PROGMEM const with preprocessor directives? We lose some expressiveness, but for most use cases I can’t imagine it would matter much...

[obra]

On Oct 24, 2017, at 1:57 PM, Andrew Gallagher ***@***.***> wrote: Understood. In that case, could we construct the PROGMEM const with preprocessor directives? We lose some expressiveness, but for most use cases I can’t imagine it would matter much...

I don’t actually expect it to be very common to have people wanting to overlay a few changes on a map versus just changing the map and making it their own. While I’d be happy to review any proposal, I’d be worried about additional infrastructure or overhead related to how we construct key maps that we might need to include to enable something like this.

…

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[andrewgdotcom]

I don’t actually expect it to be very common to have people wanting to overlay a few changes on a map

Well, for example we could add extra layers or modify just one layer without having to cut and paste all three default layers. Or rearrange the thumb keys regardless of what changes have been made elsewhere.

I’d be worried about additional infrastructure or overhead

Doesn't the code already use preprocessor macros? The only extra work here would be splitting the config into smaller files...

[gedankenexperimenter]

I've been thinking that I would rather have a script that generates the keymap section (an #include file) of my sketch, or better yet, the whole thing, rather than messing with the C++ code directly. Especially for simple versions of the firmware, that would be preferable, because then changes needed in the sketch file to enable certain code changes could be made invisible to the user. We could even make it aware of version dependencies on both Kaleidoscope and the plugins, and have it manage checking out repositories and doing the builds…

[andrewgdotcom]

It should be possible to make a friendly editor for the marshalling file. However, will this duplicate effort in chrysalis?

[algernon]

No, it won't, because Chrysalis does not generate firmware. It can flash, but that's about it, as far as firmware modifications go. Instead, Chrysalis talks with the existing firmware on the keyboard, and instructs it to do stuff, such as changing the keymap. This is more limited as creating one's own sketch, building it, and using one's own firmware, but for a lot of things, it is a much more accessible thing.

Personally, I'm not a big fan of firmware generators, because they feel like the wrong solution to the same problem Chrysalis is trying to solve: making it easier and more accessible for a novice to change their layout, and configure other properties of the keyboard. It has some use-cases, but I do not think it is a worthy goal to pursue. But that's just my opinion, if someone wants to do it, I'm not going to stand in their way. I'll likely even support them if I can. Perhaps I'll be proven wrong!

[andrewgdotcom]

All that the marshalling file in the linked PR does is hold keymaps. The entire point is to keep keymap and plugin configuration separated. So I think from your description a keymap configurator would be duplicate work.

Perhaps if we concentrated on making the keymap definitions portable, it would be possible to mock up a keymap using chrysalis, and then if necessary export it as a sketch include file?

[gedankenexperimenter]

I'm not thinking of it as a tool just for novices, but as something that also helps experts reduce errors and improves readability. For example, with a keymap generator, I could write my input file with the symbols A & ; instead of Key_A & Key_Semicolon, making it a lot easier to read, and maybe even making it possible to put alternate shifted symbols together with the unshifted symbols on the same key.

I'd still have to write my own macros, but maybe I could let the generator take care of putting together the switch statement. Or maybe it could have a library of contributed macros I could choose from.

What I'm imagining now would still be a text file input, CLI build system, not something like the QMK Firmware Builder.

[algernon]

Perhaps if we concentrated on making the keymap definitions portable, it would be possible to mock up a keymap using chrysalis, and then if necessary export it as a sketch include file?

That's... probably possible, but it has some complications. For example, Chrysalis should be able to set up OneShot and DualUse keys too, among other things. In this case, when exporting, we'd want to export some Kaleidoscope.use lines too. But then we are exporting more than a single header one can include. However, if that header provides a Chrysalis.setup() function for example, then the exported stuff can still be managed separately from the rest.

This (and @gedankenexperimenter's reasoning) makes sense.