-
Notifications
You must be signed in to change notification settings - Fork 258
Limitations of the Keymap Editor
For starters, it should be said that this is a keymap editor and not a general editor of all things "keyboard configuration". By this I mean, you can use it to manage your key binds across keymap, combos, and macros, but the application doesn't go to the depth of editing the layout itself or changing lower level details like enabling RGB or changing the bluetooth device name. It is expected that these are configured once early on (possibly by your keyboard's vendor) and won't need to change frequently.
Aside from that, this is a work in progress and a solo project so expect some things are missing or perhaps not as flexible as editing raw code would allow.
I would love to support this in the keymap editor, but the simple fact of the matter is that I'm not qualified to design or implement the firmware changes to support it. There is support currently for reading and writing keymap data as devicetree code to a variety of sources, and I hope to use this same interface for runtime updates when the supporting code exists in ZMK.
Although I support other ways of editing keymap data, the GitHub integration is the least effort way for general ZMK users to actually get firmware built.
Update 2023-09-29: This is basically feature complete now and the below writeup can be ignored except perhaps as an explanation for any unforeseen bugs that crop up.
This is my current burden. Parameterized macros are deceptively straightforward conceptually, but there are some cases that are more complicated to implement, and omitting them could break things in ways that aren't immediately obvious.
The problem deals with the manner in which parameters are normally supplied to the &bl, &bt, and &rgb_ug behaviors. Each of these behaviors has a number of "commands" that don't require parameters, and one more that accepts an additional value. Limitations in how behaviors are implemented means that they must always expect 2 parameters, and for convenience the "single parameter" commands are actually aliases for a single value plus a placeholder.
To work with parameters it must be possible to reference these values (even the placeholder) individually, so right now I'm working on a way to transparently convert from one form to another as needed and when that is ironed out I can use that to detect which parameter types are expected for a parameterized macro based on the composition of its bindings.
It's difficult, confusing work. I often go in circles trying to think of a way to describe this in terms of metadata so that when new behaviors are added with this same issue I don't have to write new code to handle it.
The editor has good support for editing sensor bindings, including behaviors for parameterized sensor rotation. There are limits to how far it will go to discover all device configuration in a repository, however, so it expects that sensors will be defined in appropriate keyboard definition file (<keyboard>.dts for boards, <keyboard>.overlay for unibody shields, and <keyboard>.dtsi for split shields) either locally or in the ZMK core repository. This means that keyboards like Kyria which splits this into a separate file won't correctly discover the available sensors.
For now it also assumes that if a sensor is referenced in the sensors { ... }; node that it is indeed enabled, ignoring status = "disabled"; properties.
ZMK's build system allows you to target specific versions of the core project including forks and branches for in-progress development. The keymap editor doesn't interfere with this but it also doesn't take it into consideration so it won't recognize behaviors like those relating to mouse movement until they land in the main branch (or possibly even a little later than that due to the manual work of importing behavior definitions).
There's some value in this, and I may at some time try to support these features by cataloguing the popular in-progress feature PRs and track the new/modified behaviors and properties in separate structures that can be selectively enabled. In the app a list of feature PRs could be displayed with individual toggles so the user can deliberately enable them with the expectation that the have their build process sorted out.
A lot can be said about this, so I said it on its own page Wiki: Preprocessor-support
This editor cannot be used to edit keymaps directly inside a clone/fork of the ZMK repository (e.g., with the directory structure apps/boards/shields/...). Instead it is meant to be used with repositories like those created by the User Config Setup Script.
As long as an appropriate layout definition is present under config/<keyboard>.json (or config/info.json is generally fine if you're only working with a single keymap) you're good to go, but to help onboard new users the editor will try to automatically generate a layout based on the kscan or matrix transformation data defined in the keyboard's devicetree source. If you want to take advantage of this you should know that it will only look for keyboard data in the local repo (under config/boards/shields/<keyboard> or config/boards/<arch>/<keyboard>) or the core ZMK repo if your keyboard is present there. It will not look at other repositories even if your build configuration links to one for those details.