Keymap processes/management needs finalization

[zmkfirmware]

Keymap processes/management needs finalization

[petejohanson]

@Nicell

3. Yeah, many of the QMK keymaps use custom codes for these, when it seems you should be able to use either MO(layer) or LT(layer, kc) for lower/raise, and if you need a tri-state when both held, just a callback that handles that, maybe in a custom callback invoked on layer state changes.
4. ^ Yes, except maybe the tri-state scenario. We could maybe have other DT entities for defining "linked layers" for things like layer 1 + 2 then triggers layer 3.
5. Yeah, that could definitely happen. I suppose one plus would be, it would be easy to do either, and we can see which "wins" based on use.

[petejohanson]

I've created #29 just now for folks to evaluate. I also pushed a sample repo w/ a bunch of kinds of configs: https://github.com/petejohanson/zmk-config-examples

[petejohanson]

There's a decent VSCode extension that adds at least code highlighting with ID plorefice.devicetree and I actually just pushed a VSCode settings.json to ZMK that at least sets the *.overlay files to use that syntax.

No completion at this point. Usually, it's a matter of the build borking.

[petejohanson]

Thinking about this, I really think we start with only the default keymap "in tree" and we quickly tweak the CMake code to allow specifying a keymap dir directly, or use an out of tree full hierarchy of boards/shields/keymaps.

[petejohanson]

Oh! And we build a GH action to build ZMK for an out of tree keymap! There's a basic build service for free!

[petejohanson]

Ok, so thinking about this even more, I think we don't even have a "keymaps" (plural) directory anywhere in tree at all.

Proposal:

1. Each shield or full keyboard board includes a keymap subdirectory.
2. This directory has a DT overlay file that contains the default layers and keymap.
3. The directory has a keys.h file with required custom keycodes, if any (raise and lower ones, although eventually I think we can have standard codes that do this)
4. It contains a keymap.c file that has "standard keymap callbacks", for things like tri layer state changes. It is added by default, but user keymaps can override a Kconfig value and skip including it.
   1 User keymaps including:
5. If present, a keymap.overlay file added as a DT overlay. Doing so allows overriding just the keycodes for a specific layer, while keeping everything else from base keymap, e g. &raise { keys =<list of keucodes for raise layer>: *everything else is inherited from the base keymap.
   1.boards and shield specific overlays, if found, are added, e.f. if kyria.overlay and corne.overlay exist, one of those will be included depending on the selected shield.
6. CMakeList.txt that allows adding custom sources for things like callbacks, units to start timers, enable drivers, etc. These files can have conditional code using the DTC defines so if certain hardware is only present in one shield or board overlay, only then is that code enabled.
7. Some sort of optional defconfig file and/or .conf file for default or force Kconfig settings for things.

With the above:

• We get the "user" behavior, and "per board keymap" behavior from QMK, but all in one unified place for a specific user.
• Users control their entire keymap stuff, and simultaneously don't need to worry about forking, rebasing, etc.
• We use west to help users automate building for their keyboards. Works great to let people use it and not setup local dev environment, until we have a more flexible build service. Can be from a template, so no need for any West or Zephyr Fu to use it!
• Keymaps don't have to duplicate much, if anything, like the raise/lower stuff, or even the layers, and can tweak only the pieces they want to customize.

Thoughts? Will probably.pit together a branch with this to demo.

[Nicell]

Thoughts on some of the parts:

3. Definitely things like raise and lower and other special layer keys etc should be standard at least eventually
4. Would it be possible to have the layer changing auto generated in a way where we wouldn't need to explicitly write out the callbacks for changing layers? i.e. we feed an array of keymaps that then automatically act as layers numbered by their index?
5. This sounds really neat. I think it may be under-utilized because it's another layer of abstraction for someone to think about. Thinking relatively vs. seeing the concrete output in front of you is something to consider.

The other points sound good to me. Making a strong template system will help a lot too!

[innovaker]

It sounds great! Although I'm admittedly not understanding all the finer details yet. I think I'd have to fiddle with a prototype to get a proper feel for it.

How much of this can we confidently put in place without an understanding of the inner workings of the known outstanding features?

Whatever approach we settle on, my long-term priorities would be (in no particular order):

• keeping the ZMK repository maintainable and synced across the whole codebase
• not having to ask your everyday user to fork/pull/rebase/commit
• providing (intuitive?) discoverability and maintainability of popular configurations
• facilitating discoverability of other configurations
• keeping related configuration together in a single place (if possible)
• having an easy to grasp 'line' between stuff that can be configured easily (basic), and stuff which requires more understanding (intermediate & advanced)
• keeping the 'bar of entry' low where possible

I realise that some of these priorities probably contradict or compete with each other.

[innovaker]

Thank you for your continued hard work @petejohanson!

I do like the simplicity of smaller changes.

A slight aside, what tools are you using to edit the DT files? I'm wondering if there's any code completion support available because I found it a bit of a black box when I was using DT previously. Alternatively, does it provide useful feedback if you screw it up? This stuff might not be such an issue once there's a GUI tool to generate code/overlays, but could be important until then.

[petejohanson]

I'm going to mark this closed. We've pretty much settled in in keymap process, and it seems to be working well enough