Version 2

[urob]

EDIT: Version 2 is now the main branch. See below for what changed compared to v1.

Context

This project originally started as a proof of concept. Some of the design and naming choices made early on weren't ideal. Now that the project is used by a few more people than myself, I would like to reconsider some of these choices.

To prevent existing configurations from breaking, I am creating a new v2 branch. The plan is to eventually make v2 the main branch. The current main branch will continue to be available as v1.

New features and changes

For now, version 2 is only an early-stage draft. So far, the big changes are:

• Availability as a ZMK module. See the revised install instructions for how to load the module.
• Various refactors of the repo structure that are needed for the new ZMK module and address an upstream issue that affects this project (#2059).
• Additional refactors and renaming of the key-labels and unicode-chars headers.
• New explicit behavior macros such as ZMK_MOD_MORPH etc.
• New ZMK_APPLY_MATRIX_TRANSFORM helper
• A few additional languages added to the Unicode-character collection

There will likely be (more) breaking changes going forward. There is a migration guide that keeps track of all breaking changes and provides instructions on how to upgrade from v1.

New repo name

The original zmk-nodefree-config name reflected that the project started out with the aim to eliminate the need to explicitly manage Devicetree nodes. In the meantime, the helper collection has grown in scope and the original name no longer seems the best fit. Reflecting the broader scope, I renamed the repo to zmk-helpers (all links and references using the original name will continue to work.)

Call for feedback and suggestions

This is very much a community project. Any feedback and suggestions on the contents of v2 and the transition are very welcome, especially while things are still in flux.

[saitamandl]

I was using the old zmk-nodefree-config and was in need of currency signs (specifically Euro). Maybe, everyone can benefit from some currency chars.
Ignore my comment if it's out of the scope of this project. I am currently using my fork for the currency support.

[urob]

I was using the old zmk-nodefree-config and was in need of currency signs (specifically Euro). Maybe, everyone can benefit from some currency chars.

I like that idea. We could include some header files similar to the language ones that pre-define common symbols that aren't part of the standard US layout, and maybe also a header with a collection of common emojies.

In the meantime, you can manually define unicode chars using the ZMK_UNICODE_* helpers. E.g., for a euro sign:

ZMK_UNICODE_SINGLE(euro_sign, N2, N0, A, C)  // €

Once defined, you can add it to the keymap with &euro_sign.

[saitamandl]

That sounds great.
Thank you
I already added some currency in the fork. But I couldn't test them because my keyboard is still in progress.
I can maybe do a pull request and you can check if that's up to the standard

[urob]

Thanks! Just one minor comment. Otherwise the PR looks great.

[JeffDess]

Hi! All of this makes a lot a sense, very happy with the changes you are implementing. I will try to migrate my config to see how it goes.

I do have an additional suggestion: matrix transforms. I used to have a 6 columns Corne, but snapped off the last column and added a new helper based on ZMK_LAYER_2_ARGS in my config instead of changing the base layout:

#define ZMK_LAYER_5COL(name, layout) \
    / { \
        chosen { \
            zmk,matrix_transform = &five_column_transform; \
        }; \
        keymap { \
            compatible = "zmk,keymap"; \
            layer_ ## name { \
                label = ZMK_HELPER_STRINGIFY(name); \
                bindings = <layout>; \
            }; \
        }; \
    };

I wrote that just for myself back then, but I guess it could be improved so it would be possible to pass additional values for the 'chosen' node in ZMK_LAYER. ZMK seems to have a few similar built-in transforms for Corne, Jorne, Jian and Kyria, perhaps more keyboards also make use of it?

[JeffDess]

Mmmh still getting errors. I just triggered a new build without updating anything, I assume the modules updates themselves on each run?

[JeffDess]

I think your commit of unguarding the explicit parametrized explicit macro is good, I was about to suggest that (since they can coexist with the native ZMK_MACRO).

But my error seems to be the undef that is not applied somehow?

[JeffDess]

I confirm it was built using the latest commit:

 * branch            v2         -> FETCH_HEAD
HEAD is now at 7be4ec5 Fix links in migration guide (#44)

[urob]

Ok, I think I figured out what's happening. The issue is the result of (i) helper.h being called with #pragma once and (ii) that you are including all the headers in all the files. As a result, even though helper.h is loaded last in each header, it gets eventually overwritten by behaviors.dtsi, reverting back to the native ZMK_MACRO.

There's two solutions:

1. You could only include each header once (e.g., from your root config file), making sure that helper.h is included after behaviors.dtsi. This is probably the cleanest, as there shouldn't be a need to include any of the headers more than once.
2. We could drop the #pragma once directive from header.h. I still have to assess a bit more the pros & cons of doing that in the main branch. But if you want to go that route, you could use the no-pragma-once branch for now that I just pushed.

In either case, we should probably document this better.

[JeffDess]

Got it, you are absolutely right.

A quick update on the issue:

• I updated my config to do all of the #include from the keymap files and removed the unneeded #pragma once and now I am getting a lot of green checkmarks, no more builds errors.
• I rolled back these changes, then built with no-pragma-once branch. The build also completed without errors.

Personally I don't mind either implementations, but as you said it will be best to document this caveat if it can break the build.

Thanks, great work!

[stijnveenman]

I spent some time looking into keymap drawer. In this discussion you mentioned it works locally, but looking at the date of this discussion and the mention of submodules, i think this refers to v1 or main. I indeed got it to work using submodules, but not using a ZMK module.

I am running into keymap_drawer.parse.parse.ParseError: Could not find any keymap nodes with "zmk,keymap" compatible property, i think this is because the includes of helpers files are not being expanded for modules.

Have you gotten keymap drawer to work using a ZMK module?

Update: I found mentions on the keymap-drawer config repo of this question, which validated my assumption that v2 is not supported. So i started working on adding support: caksoylar/keymap-drawer#105
With this change, running generating the image works locally. As long as west is initialised.

[JeffDess]

Got it, so I failed to meet both conditions:

1. Seems like the PR are merged but not yet released, I was using the latest version upgraded with pip. I'll try the latest commit.
2. I do not generate keymap drawing during a Github Action, I am doing it manually on my local machine. I usually have minor tweaks before pushing a commit so I like generating quickly with my user config, without building the firmware itself. (this works with v1, so if it ends up requiring new dependencies/setup for v2 it would be great to add to the migration guide?)

What are the options to make it work outside the CI workflow? Would installing the ZMK dev environment or just cloning zmk-helpers as a submodule work?

[urob]

Re 2: If you have a copy of the zmk-helpers repo somewhere locally, things are pretty straightforward.

Option 1: If the the repo is located inside your zmk-config as detailed in the "manual installation" setup instructions, you can just run keymap-drawer as it used to be.

Option 2: If you access the helpers as Zephyr module from some other location on your hard-drive, you can indicate that path in the new config option

parse_config:
  zmk_additional_includes:
    - "/path/to/zmk-helpers/include"

As mentioned by @stijnveenman, this currently requires building keymap-drawer from source. But once #105 is released should be straightforward.

I am planning to add some documentation about the different options (locally without Zephyr module, locally with Zephyr module, remotely using the GHA workflow added in #107, anything else?) once the two relevant PRs are merged and released.

[JeffDess]

I got it working! I cloned keymap-drawer, installed python dependencies, added zmk-helper as a submodule in my repo. Then it worked like a charm, no need for west it seems.

# Needed only until > v0.17 is released
git clone https://github.com/caksoylar/keymap-drawer.git
cd keymap-drawer
pipx install poetry
poetry install
poetry shell

cd ../zmk-config 

# Needed to work with v2
# Add `zmk_additional_includes: ["zmk-helpers/include"]` to keymap-drawer config file
git submodule add -b v2 https://github.com/urob/zmk-helpers

scripts/generate-keymay-images.sh
# Keymap Parsed
# Keymap Drawn

Success! 🚀
Thanks to you both!

[urob]

I added a short readme on how to use zmk-helper as a module alongside keymap-drawer:

https://github.com/urob/zmk-helpers/blob/main/docs/keymap_drawer.md

[urob]

Thanks again to @stijnveenman for implementing all of this. Let me know if something in the readme is off or could be clearer!