zmk/docs/blog/2023-12-17-nodefree-config.md

---
title: "Community Spotlight Series #2: Node-free Config"
author: Cem Aksoylar
author_title: Documentation maintainer
author_url: https://github.com/caksoylar
author_image_url: https://avatars.githubusercontent.com/u/7876996
tags: [keyboards, firmware, community]
---

This blog continues our series of posts where we highlight projects within the ZMK ecosystem
that we think are interesting and that the users might benefit from knowing about them. You might
be aware that ZMK configurations in the [Devicetree format](/docs/config#devicetree-files)
use the [C preprocessor](https://en.wikipedia.org/wiki/C_preprocessor) so that directives like
`#define RAISE 2` or `#include <behaviors.dtsi>` can be used in them. In this installment we are
highlighting the [`zmk-nodefree-config` project](https://github.com/urob/zmk-nodefree-config)
by [urob](https://github.com/urob) that contains helper methods that utilizes this fact
for users who prefer editing and maintaining their ZMK config directly using the Devicetree
syntax format.

In the rest of the post we leave it to urob to introduce and explain the motivations of the
project, and various ways it can be used to help maintain ZMK keymaps. Stay tuned for future
installments in the series!

## Overview

Loosely speaking the _nodefree_ repo -- more on the name later -- is a
collection of helper functions that simplify configuring keymap files. Unlike
the graphical keymap editor covered in the [previous spotlight
post](https://zmk.dev/blog/2023/11/09/keymap-editor), it is aimed at users who
edit and maintain directly the source code of their keymap files.

The provided helpers fall into roughly one of three categories:

1. Helpers that eliminate boilerplate, reduce the complexity of keymaps, and improve readability.
2. Helpers that improve portability of "position-based" properties such as combos.
3. Helpers that define international and other unicode characters.

The reminder of this post details each of these three categories.

## Eliminating Boilerplate

In ZMK, keymaps are configured using so-called _Devicetree_ files. Devicetree files
define a collection of nested _nodes_, whereas each node in turn specifies a variety of
_properties_ through which one can customize the keymap.

For example, the following snippet sets up a
[mod-morph](https://zmk.dev/docs/behaviors/mod-morph) behavior that sends <kbd>.</kbd>
("dot") when pressed by itself and sends <kbd>:</kbd> ("colon") when shifted:

```dts {6-7} showLineNumbers
/ {
    behaviors {
        dot_colon: dot_colon_behavior {
            compatible = "zmk,behavior-mod-morph";
            #binding-cells = <0>;
            bindings = <&kp DOT>, <&kp COLON>;
            mods = <(MOD_LSFT|MOD_RSFT)>;
        };
    };
};
```

Adding this snippet to the keymap will create a new node `dot_colon_behavior`
(nested underneath the `behaviors` and root `/` nodes), and assigns it four
properties (`compatible`, `#binding-cells`, etc). Here, the crucial properties are `bindings`
and `mods`, which spell out the actual functionality of the new behavior. The rest
of the snippet (including the nested node-structure) is boilerplate.

The idea of the _nodefree_ repo is to use C preprocessor macros to improve
readability by eliminating as much boilerplate as possible. Besides hiding
redundant behavior properties from the user, it also automatically creates and
nests all required behavior nodes, making for a "node-free" and less
error-prone user experience (hence the name of the repo).

For example, using `ZMK_BEHAVIOR`, one of the repo's helper functions, the
above snippet simplifies to:

```dts showLineNumbers
ZMK_BEHAVIOR(dot_colon, mod_morph,
    bindings = <&kp DOT>, <&kp COLON>;
    mods = <(MOD_LSFT|MOD_RSFT)>;
)
```

For complex keymap files, the gains from eliminating boilerplate can be
enormous. To provide a benchmark, consider my [personal
config](https://github.com/urob/zmk-config), which uses the _nodefree_ repo to
create various behaviors, set up combos, and add layers to the keymap. Without
the _nodefree_ helpers, the total size of my keymap would have been 41 kB. Using
the helper macros, the actual size is instead reduced to a more sane 12 kB.[^1]

[^1]:
    To compute the impact on file size, I ran `pcpp
--passthru-unfound-includes` on the `base.keymap` file, comparing two
    variants. First, I ran the pre-processor on the actual file. Second, I ran
    it on a version where I commented out all the _nodefree_ headers,
    preventing any of the helper functions from getting expanded. The
    difference isolates precisely the size gains from eliminating boilerplate,
    which in my ZMK config are especially large due to a vast number of
    behaviors used to add various Unicode characters to my keymap.

## Simplifying "Position-based" Behaviors

In ZMK, there are several features that are position-based. As of today, these
are [combos](/docs/features/combos) and [positional
hold-taps](/docs/behaviors/hold-tap#positional-hold-tap-and-hold-trigger-key-positions),
with behaviors like the ["Swapper"](https://github.com/zmkfirmware/zmk/pull/1366) and [Leader
key](https://github.com/zmkfirmware/zmk/pull/1380) currently
developed by [Nick Conway](https://github.com/nickconway) in pull requests also utilizing them.

Configuring these behaviors involves lots of key counting, which can be
cumbersome and error-prone, especially on larger keyboards. It also reduces the
portability of configuration files across keyboards with different layouts.

To facilitate configuring position-based behaviors, the _nodefree_ repo comes
with a community-maintained library of "key-position labels" for a variety of
popular layouts. The idea is to provide a standardized naming convention that
is consistent across different keyboards. For instance, the labels for a 36-key
layout are as follows:

```
    ╭─────────────────────┬─────────────────────╮
    │ LT4 LT3 LT2 LT1 LT0 │ RT0 RT1 RT2 RT3 RT4 │
    │ LM4 LM3 LM2 LM1 LM0 │ RM0 RM1 RM2 RM3 RM4 │
    │ LB4 LB3 LB2 LB1 LB0 │ RB0 RB1 RB2 RB3 RB4 │
    ╰───────╮ LH2 LH1 LH0 │ RH0 RH1 RH2 ╭───────╯
            ╰─────────────┴─────────────╯
```

The labels are all of the following form:

- `L/R` for **L**eft/**R**ight side
- `T/M/B/H` for **T**op/**M**iddle/**B**ottom and t**H**umb row.
- `0/1/2/3/4` for the finger position, counting from the inside to the outside

The library currently contains definitions for 17 physical
layouts, ranging from the tiny [Osprette](https://github.com/smores56/osprette) to the large-ish
[Glove80](https://www.moergo.com/collections/glove80-keyboards).
While some of these layouts contain more keys than others, the idea behind the
library is that keys that for all practical purposes are in the "same" location
share the same label. That is, the 3 rows containing the alpha keys are
always labeled `T/M/B` with `LM1` and `RM1` defining the home position of
the index fingers. For larger boards, the numbers row is always labeled
`N`. For even larger boards, the function key row and the row below `B` are
labeled `C` and `F` (mnemonics for **C**eiling and **F**loor), etc.

Besides sparing the user from counting keys, the library also makes it easy to
port an entire, say, combo configuration from one keyboard to the next by simply
switching layout headers.

## Unicode and International Keycodes

The final category of helpers is targeted at people who wish to type international characters
without switching the input language of their operation system. To do so, the repo comes with
helper functions that can be used to define Unicode behaviors.

In addition, the repo also ships with a community-maintained library of
language-files that define Unicode behaviors for all relevant characters in a
given language. For instance, after loading the German language file, one can
add `&de_ae` to the keymap, which will send <kbd>ä</kbd>/<kbd>Ä</kbd> when pressed or shifted.

## About Me

My path to ZMK and programmable keyboards started in the early pandemic, when I
built a [Katana60](https://geekhack.org/index.php?topic=88719.0) and learned
how to touch-type Colemak. Soon after I purchased a Planck, which turned out
to be the real gateway drug for me.

Committed to making the best out of the Planck's 48 keys, I have since
discovered my love for tinkering with tiny layouts and finding new ways of
[squeezing out](https://xkcd.com/2583/) a bit more ergonomics. Along the way, I
also made the switch from QMK to ZMK, whose "object-oriented" approach to
behaviors I found more appealing for complex keymaps.[^2]

[^2]:
    I am using the term object-oriented somewhat loosely here. What I mean by
    that is the differentiation between abstract behavior classes (such as
    hold-taps) and specific behavior instances that are added to the keymap.
    Allowing to set up multiple, reusable instances of each behavior has been a
    _huge_ time-saver compared to QMK's more limited behavior settings that are
    either global or key-specific.

These days I mostly type on a Corne-ish Zen and are waiting for the day when I
will finally put together the
[Hypergolic](https://github.com/davidphilipbarr/hypergolic) that's been sitting
on my desk for months. My current keymap is designed for 34 keys, making
liberal use of combos and [timerless homerow
mods](https://github.com/urob/zmk-config#timeless-homerow-mods) to make up for
a lack of keys.