Zmk Config

Hardware Context

• Keyboard: Sofle (split, 5x6 + 5 thumb keys per side)
• Controller: Nice Nano v2 (nRF52840, Bluetooth + USB)
• Display: Nice OLED (via zmk-nice-oled module from mctechnology17)
• Encoders: EC11 rotary encoders (one per side)
• LEDs: WS2812 RGB underglow
• Total keys per side: 30 (6 columns × 4 rows + 5 thumb + 1 encoder button)

Configuration System Overview

ZMK configuration uses two file types:

1. Kconfig Files (.conf)

Kconfig controls global system settings. The file config/sofle.conf applies to both halves of the split keyboard.

Syntax: One CONFIG_<NAME>=<value> per line, no spaces around =.

Value types:

• bool: y (enable) or n (disable). Example: CONFIG_ZMK_SLEEP=y
• int: Integer value. Example: CONFIG_ZMK_IDLE_TIMEOUT=180000
• string: Double-quoted text. Example: CONFIG_ZMK_KEYBOARD_NAME="MySofle"

Important notes:

• All configuration is compile-time. After changes, firmware must be rebuilt and flashed.
• For split keyboards, a single sofle.conf (without _left/_right suffix) applies to both halves.
• Changing CONFIG_ZMK_KEYBOARD_NAME requires clearing stored settings on the controller.
• CONFIG_BT_MAX_CONN and CONFIG_BT_MAX_PAIRED should always match; on split keyboards set to desired BT profiles + 1.

Common Kconfig categories and settings:

General

HID

USB

Bluetooth

Power & Sleep

RGB Underglow

Encoders

Combos

Logging / Debugging

Debounce

2. Devicetree / Keymap Files (.keymap)

The keymap file config/sofle.keymap defines layers, key bindings, behaviors, combos, macros, and conditional layers using Devicetree syntax.

Required includes:

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

Layer definition pattern:

#define BASE 0
#define LOWER 1
#define RAISE 2

/ {
    keymap {
        compatible = "zmk,keymap";

        default_layer {
            display-name = "default";
            bindings = <
                // key bindings here, one per physical key
            >;
            sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN &inc_dec_kp PG_UP PG_DN>;
        };
    };
};

Key binding syntax:

• Simple key: &kp <KEYCODE> (e.g., &kp A, &kp N1, &kp LSHFT)
• Layer momentary: &mo <LAYER_NUM> (e.g., &mo 1)
• Layer toggle: &tog <LAYER_NUM>
• Transparent: &trans (passes through to lower layer)
• None: &none (blocks key)
• Bluetooth: &bt BT_CLR, &bt BT_SEL 0
• RGB: &rgb_ug RGB_TOG, &rgb_ug RGB_HUI, &rgb_ug RGB_BRI
• External power: &ext_power EP_TOG
• Encoder: &inc_dec_kp <CW_KEY> <CCW_KEY>

Conditional layers:

conditional_layers {
    compatible = "zmk,conditional-layers";
    adjust_layer {
        if-layers = <LOWER RAISE>;
        then-layer = <ADJUST>;
    };
};

Combos:

combos {
    compatible = "zmk,combos";
    combo_name {
        timeout-ms = <50>;
        key-positions = <POS1 POS2>;
        bindings = <&kp KEYCODE>;
        layers = <LAYER_NUM>;  // optional: restrict to specific layers
    };
};

Macros:

macros {
    macro_name: macro_name {
        compatible = "zmk,behavior-macro";
        #binding-cells = <0>;
        bindings = <&kp A &kp B &kp C>;
    };
};

Tap-dance:

behaviors {
    td_example: td_example {
        compatible = "zmk,behavior-tap-dance";
        #binding-cells = <0>;
        tapping-term-ms = <200>;
        bindings = <&kp A>, <&kp B>;
    };
};

Hold-tap (home row mods):

behaviors {
    hm: homerow_mods {
        compatible = "zmk,behavior-hold-tap";
        #binding-cells = <2>;
        tapping-term-ms = <200>;
        quick-tap-ms = <150>;
        flavor = "tap-preferred";
        bindings = <&kp>, <&kp>;
    };
};

Changing existing node properties (overlay pattern):

&kscan0 {
    debounce-press-ms = <0>;
};

3. Build Configuration (build.yaml)

Defines the build matrix for GitHub Actions firmware compilation.