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.

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.

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

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.

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.

[!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.

[^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
```

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.