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_LEADER_SEQUENCE`	Create a leader key sequence
`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
`5x6.h`	60	Caldera
`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.

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

↩

bantonsson/zmk-helpers