urob/zmk-helpers

Convenience macros simplifying ZMK's keymap configuration

ZMK-Helpers (Version 2)

This is a collection of helper macros (formerly zmk-nodefree-config), simplifying the configuration of ZMK keymaps. The migration guide has instructions on how to migrate from v1. Version 1 continuous to be available here.

Installation

To use the helpers, it is recommended to add them as a module to your config/west.yml by adding a new entry to remotes and projects:

manifest:
  remotes:
    - name: zmkfirmware
      url-base: https://github.com/zmkfirmware
    - name: urob
      url-base: https://github.com/urob
  projects:
    - name: zmk
      remote: zmkfirmware
      revision: main
      import: app/west.yml
    - name: zmk-helpers
      remote: urob
      revision: main
  self:
    path: config

If you are building locally, see the instructions for building with external modules in ZMK docs.

Manual installation

Alternatively, copy include/zmk-helpers into your config/ directory:

zmk-config
├── config
│   ├── corne.keymap
│   ├── zmk-helpers
│   │   ├── helper.h
│   │   └── ...
│   └── ...
└── ...

Instead of copying, one could also add a git-submodule¹:

cd /path/to/zmk-config/
git submodule add -b v2 -- https://github.com/urob/zmk-helpers config/zmk-helpers-repo
ln -s zmk-helpers-repo/include/zmk-helpers config/zmk-helpers

Usage

Source helper.h near the top of your .keymap file. Optionally, source key-labels and unicode-chars as needed:

#include "zmk-helpers/helper.h"

// Source desired key-position labels
#include "zmk-helpers/key-labels/glove80.h"

// Source unicode-chars for desired languages
#include "zmk-helpers/unicode-chars/german.dtsi"

The following subsections describe the available helpers. See the example configuration or my personal zmk-config for a demonstration.

Core helpers

The helper.h header provides a number of convenience macros for defining behaviors, combos, layers, etc.

Macro	Purpose
ZMK_BEHAVIOR	Create a new behavior instance (generic form)
ZMK_APPLY_MATRIX_TRANSFORM	Apply a matrix_transform
ZMK_COMBO	Create a combo
ZMK_CONDITIONAl_LAYER	Create a tri-layer condition
ZMK_LAYER	Create a layer and add it to the keymap
ZMK_UNICODE_SINGLE	Create a unicode-char
ZMK_UNICODE_PAIR	Create a pair of lowercase/uppercase unicode-chars

In addition to the generic ZMK_BEHAVIOR macro, version 2 also provides the following explicit variants.

Macro	Purpose
ZMK_AUTO_LAYER	Create a new auto-layer behavior instance
ZMK_CAPS_WORD	Create a new caps-word behavior instance
ZMK_HOLD_TAP	Create a new hold-tap behavior instance
ZMK_KEY_REPEAT	Create a new key-repeat behavior instance
ZMK_MACRO	Create a new key-macro behavior instance
ZMK_MACRO_ONE_PARAM	Create a new macro-one-param behavior instance
ZMK_MACRO_TWO_PARAM	Create a new macro-two-param behavior instance
ZMK_MOD_MORPH	Create a new mod-morph behavior instance
ZMK_STICKY_KEY	Create a new sticky-key behavior instance
ZMK_TAP_DANCE	Create a new tap-dance behavior instance
ZMK_TRI_STATE	Create a new tri-state behavior instance (requires #1366)

The explicit behavior helpers are inspired by the native ZMK implementation of ZMK_MACRO. They differ in that they automatically create all Devicetree nodes as needed. So instead of calling them from inside the Devicetree, they should be placed outside the root node.

Note

By default, sourcing helper.h will replace the native implementation of ZMK_MACRO. To work reliably, helper.h should be included after behaviors.dtsi. To keep the native implementation of ZMK_MACRO, set #define ZMK_HELPER_KEEP_NATIVE 1 before including helper.h.

Key-labels collection

These layout headers define easy to remember "key-labels" for many popular keyboards, which can be used instead of numeric key-positions to configure position-based properties (e.g., in combos).

Key-labels are standardized to make keymaps portable across keyboards. For instance, the labels for the 60-key Sofle nest the labels for the 34-key Sweep as follows:

The following layouts are currently implemented.

Header	# of Keys	Examples
34.h	34	Ferris, Hypergolic, Sweep
36.h	36	Corne (5 cols), Corne-ish Zen (5 cols)
42.h	42	Corne, Corne-ish Zen
4x12.h, 4x12_wide.h	48	Planck
adv360_custom.h	76	Advantage360 Pro (custom matrix transform)
glove80.h	80	Glove80
hillside_*.h	46, 48, 52 or 56	Hillside family
jian.h	44	Jian, Jorne
kyria.h	50	Kyria
lily58.h	58	Lily58
osprette.h	34	Osprette
sofle.h	60	Sofle
totem.h	38	Totem

Unicode-characters and language collection

This collection defines unicode behaviors for all relevant characters in a given language. For instance, sourcing the German language file, one can add &de_ae to the keymap, which will send ä/Ä when pressed or shifted.

See the unicode-chars directory for a list of all currently available languages. To use these language files, follow the instructions for your OS below.

Windows

On your computer, install WinCompose. In your keymap, source helper.h and the desired language files. For example:

#include "zmk-helpers/helper.h"
#include "zmk-helpers/unicode-chars/german.dtsi"

Linux

In your keymap, set HOST_OS to 1, then source helper.h and the desired language files. For example:

#define HOST_OS 1
#include "zmk-helpers/helper.h"
#include "zmk-helpers/unicode-chars/german.dtsi"

macOS

On your computer, enable unicode input in the system preferences by selecting Unicode Hex Input as input source. In your keymap, set HOST_OS to 2, then source helper.h and the desired language files. For example:

#define HOST_OS 2
#include "zmk-helpers/helper.h"
#include "zmk-helpers/unicode-chars/german.dtsi"

Note

Unicodes allow typing international characters without changing the OS keyboard layout. See zmk-locale-generator for a collection of headers that configure ZMK to work with non-US layouts set in the OS.

Contributing

Contributions of any form are very welcome! New key-labels and unicode-chars should follow these guidelines:

• Key-position labels should stick to the label conventions whenever applicable.
• Language headers should namespace all characters using two-letter ISO language codes.

Footnotes

1. To enable the submodule when building with Github Actions, replace zmk-config/.github/workflows/build.yml with

   on: [push, pull_request, workflow_dispatch]
   
   jobs:
     build:
       uses: urob/zmk/.github/workflows/build-user-config.yml@build-with-submodules
   

   ↩

zmk-helpers's Issues

Unable to build due to missing helper.h

I'm trying to use your amazing timeless homerow mod on my Kinesis 360 by using your adv360-demo-config repository as a base and as a first step trying to add zmk-nodefree-config.

I've added the zmk-nodefree-config repository as a submodule to the adv360-demo-config root but builds fail with:
/__w/adv360-demo-config/adv360-demo-config/config/adv360pro.keymap:8:10: fatal error: ../zmk-nodefree-config/helper.h: No such file or directory

Here is the build: https://github.com/tymm/adv360-demo-config/actions/runs/5708421380/job/15466158281
And here is the underlying commit: urob/adv360-demo-config@e2182fe

Thank you for your great work.

Unicode pair using correct OS setting mistakenly uses Alt-codes method

Working from this repo (https://github.com/urob/zmk-config) and trying to use unicode pair functions through my Glove80, I followed the instructions and set the correct OS in base.keymap as such:

#include <behaviors.dtsi>
#include <dt-bindings/zmk/keys.h>
#include <dt-bindings/zmk/bt.h>

#define HOST_OS 1 // Linux
#include "../zmk-nodefree-config/helper.h"
#include "../zmk-nodefree-config/international_chars/greek.dtsi"

But upon pressing one of the keys with the greek letters, this is what gets inputted by my keyboard (as recorded by xev):

108 Alt_R
30  u
19  0
12  3
54  c
16  7
36  Return

This looks like the correct way to input unicode using Alt-codes, so perhaps the OS setting isn't being read?

Is there a command to preview the preprocessed code?

I tried gcc -E corne.keymap but nothing happened

add submodule to custom-shield

Hello urob,

i have created a custom shield for my 3d printed handwired corne keyboard. That works until I would like to integrate the nodefree submodule and build it via github actions. Build error when building it tries to find "3dpcorne" shield from the official keyboards. It does not recognize the shield within the repository for building the firmware. How can i build the firmware with the custom shield?

Unable to use international helper

I have a tried a few things, but nothing work for now.
I am on Windows 11, using a nice!nanov2 Corne 42 keys.

First try: macros are printed on screen but not the char.
Second try: I use WinCompose but it does not solves the problem.
Third try: I set the HOST_OS variable to 2. Now macros are not printed, but nothing is at all. When not on an input field, I have a typical Windows sound, but I don't really know which shortcut it is trying to do.

Here is a snippet with relevant code from my config:

#include <behaviors.dtsi>
#include <dt-bindings/zmk/keys.h>
#include <dt-bindings/zmk/bt.h>

#define HOST_OS 2 // To use "press LALT"

#include "../zmk-nodefree-config/helper.h"
#include "../zmk-nodefree-config/keypos_def/keypos_42keys.h"              // keyposition helpers
#include "../zmk-nodefree-config/international_chars/french.dtsi"

...

/ {
   keymap {
      compatible = "zmk,keymap";
         
         ...
         
         accents {
            bindings = <
___ ___              ___             &fr_ae          &fr_oe        ___              /**/ ___ ___ ___ ___ ___ ___
___ &fr_a_circumflex &fr_a_grave     &fr_e_grave     &fr_e_acute   &fr_e_circumflex /**/ ___ ___ ___ ___ ___ ___
___ &fr_o_circumflex &fr_i_diaeresis &fr_e_diaeresis &fr_c_cedilla ___              /**/ ___ ___ ___ ___ ___ ___
                                                                        ___ ___ ___ /**/ ___ ___ ___
            >;
         };
   };
};

Link to my config in case it helps : https://github.com/lou-bi/zmk-config/blob/8130b7838f5ea5f3f71ea4a0fea252d06ca8b821/config/corne.keymap#L82

Sorry if its just a huge nooby problem, already solved, and that i just didn't try hard enough.

Unicode input for Linux doesn't work for all applications

Depending on the application, CTRL and SHIFT might need to be pressed for the whole sequence (except for the terminating SPACE). Here's the script I'm using right now,

ZMK_BEHAVIOR(iris_sep, macro,
    wait-ms = <5>;
    tap-ms = <5>;
    bindings = <&macro_press &kp LCTRL &kp LSHFT> ,
               <&macro_tap &kp U &kp N2 &kp N2 &kp N1 &kp N7 &kp SPACE> ,
               <&macro_release &kp LSHFT &kp LCTRL>;
)

For my limited test (well, Firefox, thunderbird, and Emacs), "pressing throughout" style works for all of them, but the current macro doesn't work in Emacs.

Build fails because of malformed value

I tried to implement the unicode function for german umlaute and just can't get the build done. It always fails with the following message:
devicetree error: /__w/zmk-config/zmk-config/config/german.dtsi:2 (column 84): parse error: malformed value

Any idea what I'm doing wrong?

Homerow Mods make dead key working intermittently

On my Corne 42, for french accents, I've notice that when using dead key, it works intermittently.
Xudongz on Discord did help me tracking the issue, and it works well when using the &kp APOS + &kp x code, but sometimes works, sometimes not with &kp APOS + &hmr x x.
Is there some kind of setting to adjust to be able to use both your timeless HRM and the dead key ?
I can give more details if needed, but I don't think the debug process was relevant

Support for switching unicode method/OS

It would be useful the be able to have a windows and linux version of a unicode macro at the same time, so you can toggle depending on what system the keyboard is connected to

Bluetooth connection sometimes lost when sending unicode to M1 Mac

I have setup zmk-nodefree-config to work with HOST_OS 2 / macOS and I'm using the Unicode Hex Input. The keyboard is connected via bluetooth, I have CONFIG_ZMK_BLE_PASSKEY_ENTRY enabled.

Now every once in a while, when typing my ZMK_UNICODE_PAIR the connection suddenly closes. The Mac shows that the keyboard is disconnected and the computer does not take any inputs from either halve.

I then have to remove the connection on the Mac "Forget...", remove the profile on the keyboard and connect again. It then works again.

This only happens sometime and cannot be reproduced consistently, however, it often occurs when I press another letter immediately after the ZMK_UNICODE_PAIR. It seems to me, that while sending the unicode sequence, inbetween it tries to send the other letter I pressed and then is stuck.

Does anyone else have this problem and is there a solution to it?

Thanks.

ZMK_BEHAVIOR Macro no longer working after update

ZMK_BEHAVIOR(tmux_left, macro,
    wait-ms = <0>;
    tap-ms = <5>;
    bindings = <&kp LC(A) &kp H>;
)

https://github.com/lsshawn/corne-zmk/blob/f9514af7ffbd0659245a88ec1488e9c4fd61bf7c/config/corne.keymap#L188 here's my keymap.

I noticed that the macro only register the first keypress.

Encountered an error while using ZMK_UNICODE_SINGLE

When I use ZMK_UNICODE_SINGLE(euro_sign, N2, N0, A, C), the output of the keyboard is u20ac instead of €.

My chip is Seeed Studio XIAO nRF52840 Sense, my computer is a Mac mini with macOS 14.

Any help is appreciated.

My profile.

ZMK_COMBO does not work with home row mod buttons

I'm trying to get Norwegian/Danish unicode letters æøå working on the home row as combos instead of using a layer. Non-homerow keys work well, but home row mod buttons seem to conflict.

It it possible?

a+e=æ   (LGUI+RSHIFT)
o+e=ø   (RGUI+RSHIFT)
a+o=å   (LGUI+RGUI)

My setup, with unicode defined by unicode-chars/danish.dtsi:

ZMK_COMBO(combo_da_ae,  &da_ae,    LM4 RM2,     DEF NAV NUM, COMBO_TERM_SLOW, COMBO_IDLE_SLOW) // BAD, a+e prints 'ae'
ZMK_COMBO(combo_da_oe,  &da_oe,    RM4 RM2,     DEF NAV NUM, COMBO_TERM_FAST, COMBO_IDLE_FAST) // BAD, o+e prints 'oe'
ZMK_COMBO(combo_da_ao,  &da_aa,    LM4 RM4,     DEF NAV NUM, COMBO_TERM_SLOW, COMBO_IDLE_SLOW) // OK, a+o prints 'å'

Interestingly, a+o (LGUI+RGUI) does work, probably due to both mapping to GUI.
This is on Windows with WinCompose installed. Using v2 of zmk-helpers.

some international characters seem not to be available via compose mechanism

I'm trying to create a full layout of Ukrainian characters, creating ukrainian.dtsi similar to the ones in this repo (should be available https://github.com/vlnn/samoklava-zmk-config/blob/test-zmk-nodefree-config/zmk-nodefree-config/international_chars/ukrainian.dtsi). It mostly works -- except several, well, exceptions:

ZMK_UNICODE_PAIR(ua_a, N0, N4, N3, N0, N0, N4, N1, N0) // а/А
and
ZMK_UNICODE_PAIR(ua_r, N0, N4, N4, N0, N0, N4, N2, N0) // р/Р

They are just ignored on my MacBook. Any hints/ideas/proposals on how to work this through/around?

Unicode for Windows 10

I would like to use the german umlauts with Windows 10.

To achive this, I added with #include the files helper.h and german.dtsi to the keymap-file.
I would then expect &de_ae to be recognized as an ä, but I get u00e4 instead. So basicly the Unicode, but not the character for it.

Any idea what I have misconfigured?

Missing LICENSE

Thank you for these macros, they looks great. Would you mind adding a LICENSE like MIT?

Error building through Github workflows

trying to build using Github workflows, I get the following error:

 devicetree error: /__w/zmk-config/zmk-config/config/kyria_rev3.keymap:85 (column 132): parse error: expected number or parenthesized expression
CMake Error at /__w/zmk-config/zmk-config/zephyr/cmake/dts.cmake:205 (message):
  gen_defines.py failed with return code: 1
Call Stack (most recent call first):
  /__w/zmk-config/zmk-config/zephyr/cmake/app/boilerplate.cmake:542 (include)
-- Configuring incomplete, errors occurred!
  /__w/zmk-config/zmk-config/zephyr/share/zephyr-package/cmake/ZephyrConfig.cmake:24 (include)
  /__w/zmk-config/zmk-config/zephyr/share/zephyr-package/cmake/ZephyrConfig.cmake:35 (include_boilerplate)
  CMakeLists.txt:15 (find_package)


FATAL ERROR: command exited with status 1: /usr/local/bin/cmake -DWEST_PYTHON=/usr/bin/python3 -B/__w/zmk-config/zmk-config/build -S/__w/zmk-config/zmk-config/zmk/app -GNinja -DBOARD=nice_nano_v2 -DZMK_CONFIG=/__w/zmk-config/zmk-config/config -DSHIELD=kyria_rev3_left
Error: Process completed with exit code 1.

I was able to successfully build using a default keymap

ZMK_UNICODE_PAIR not working in Linux

The shifted version of behaviors created with ZMK_UNICODE_PAIR for Linux does not work correctly.

As a workaround, one can replace helper.h from the main branch with helper.h from the unicode_linux branch. Caveat: One must use LEFT_SHIFT to trigger the shifted version of behaviors created with the unicode_linux version of ZMK_UNICODE_PAIR. Using RIGHT_SHIFT will result in garbled unicode sequences.

Cant implent the german umlaute

So after long while I could refrence the files, but I can not get them to work, every time i try to build with them I get this error
devicetree error: /tmp/zmk-config/config/german.dtsi:6 (column 1): parse error: expected '/' or label reference (&foo)
When I remove the unicode, there is no problem building it and my repo: https://github.com/haShinui/zmk_test
Any idea how to fix this?

Add support for layer labels

Thanks a lot for sharing your setup, it is extremely helpful! One thing I noticed is that if you use an OLED widget, it pulls the name of the current layer from the zmk layer label. I know adding this would be a breaking change, so I could see adding this as either:

1. a new param to ZMK_LAYER
2. a copy of ZMK_LAYER w/ the new param but named ZMK_LAYER_LABELED instead like this

If you want this added, I'm happy to put up a PR for whichever fits better with your direction.

error unicode macro

When I try to write unicode macros, I get this error during the update: macro "ZMK_UNICODE_PAIR" requires 9 arguments, but ...

what's wrong here? I can't figure it out ... thx