Zmk

ZMK Firmware リファレンス

ZMK Firmware — Zephyr RTOS 上に構築されたオープンソース (MIT) のキーボードファームウェア。 省電力・無線・分割キーボード対応を主眼に設計され、devicetree ベースの宣言的設定により多様な MCU（nRF52/RP2/SAMD21/STM32 等）と shield をサポートする。 公式ドキュメント (zmk.dev/docs) の全 11 カテゴリを構造化。 keymap 設計・behaviors 選択・config 設定・新規 board/shield 作成・ローカルビルド時に参照する。

ディレクトリ構造

skills/zmk/
├── SKILL.md                                          ← このファイル（エントリーポイント）
└── references/
    ├── getting-started/README.md                     ← Getting Started 索引（5 ページ）
    ├── troubleshooting/README.md                     ← Troubleshooting 索引（5 ページ）
    ├── features/README.md                            ← Features 索引（12 ページ）
    ├── keymaps/README.md                             ← Keymaps overview 索引（6 ページ）
    ├── behaviors/README.md                           ← Behaviors 索引（23 ページ）
    ├── input-processors/README.md                    ← Input Processors 索引（7 ページ）
    ├── config/README.md                              ← Configuration 索引（19 ページ）
    ├── development/README.md                         ← Development core 索引（6 ページ）
    ├── contributing/README.md                        ← Contributing 索引（3 ページ）
    ├── hardware-integration/README.md                ← Hardware Integration 索引（12 ページ）
    │   ├── bootloader/README.md                      ← Bootloader 索引（6 ページ）
    │   └── lighting/README.md                        ← HW Lighting 索引（4 ページ）
    └── local-toolchain/README.md                     ← Local Toolchain 索引（8 ページ）

探索手順

1. ユーザーのタスクに最も関連するカテゴリを特定する 2. そのカテゴリの README.md を読む 3. README.md 内の一覧から必要な個別ファイルを選んで読む 4. 必要に応じて関連ページのリンクを辿る

カテゴリ → README.md マッピング

Backlight

Controls per-key or single-color LED backlight: power state and brightness level.

Signature / Usage

#include <dt-bindings/zmk/backlight.h>

&bl BL_TOG         // toggle on/off
&bl BL_INC         // increase brightness
&bl BL_SET 50      // set brightness to 50

Parameters: A BL_* command constant, and optionally a brightness value for BL_SET.

Options / Props

Notes

• Settings persist across restarts and firmware flashes (saved to flash storage).
• Once changed, the new values override the CONFIG_ZMK_BACKLIGHT_*_START defaults.
• On split keyboards this is a global behavior: changes affect both central and peripheral sides.

Related

• RGB Underglow
• Power

Bluetooth

Manages Bluetooth connection profiles between the keyboard and host devices. ZMK supports up to five BT profiles by default.

Signature / Usage

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

&bt BT_CLR         // clear bond on current profile
&bt BT_NXT         // switch to next profile
&bt BT_PRV         // switch to previous profile
&bt BT_SEL 0       // select profile 0 (0-indexed)
&bt BT_DISC 1      // disconnect profile 1
&bt BT_CLR_ALL     // clear bonds on all profiles

Parameters: A BT_* command constant, and optionally a profile index for BT_SEL / BT_DISC.

Options / Props

Notes

• Multiple hosts can appear "connected" simultaneously; only the active profile receives keystrokes.
• To fully remove a bond, clear it on the keyboard and on the host device to prevent connection failures.
• The active profile reconnects immediately if disconnected, even when USB output is selected.
• Profile selection persists across restarts (saved to flash); debounce controlled by CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE.
• Adjust max profiles via CONFIG_BT_MAX_CONN and CONFIG_BT_MAX_PAIRED in the .conf file.

Related

• Output Selection
• Reset

Caps Word

A smart caps-lock variant that capitalizes alphabetic keys and automatically deactivates when a key outside the continue list is pressed, or when the behavior is triggered again.

Signature / Usage

&caps_word

Custom configuration:

&caps_word {
    continue-list = <UNDERSCORE MINUS>;
};

Custom named instance:

/ {
    behaviors {
        prog_caps: prog_caps {
            compatible = "zmk,behavior-caps-word";
            #binding-cells = <0>;
            continue-list = <UNDERSCORE>;
        };
    };
};
// Usage: &prog_caps

Options / Props

Notes

• The shift modifier applies only to alphabetic keycodes (A–Z); numbers and symbols pass through unmodified.
• Useful with mod-tap on home-row keys to avoid alternating holds when typing all-caps words.
• Multiple instances with different continue-list values enable distinct caps-word modes on the same keyboard.

Related

• Tap-Dance
• Key Repeat
• Hold-Tap / Mod-Tap

Hold-Tap

Sends one behavior when a key is held and a different behavior when it is tapped. ZMK ships two pre-configured instances: &mt (mod-tap) and &lt (layer-tap).

Signature / Usage

// Pre-built instances
&mt <MODIFIER> <keycode>   // e.g. &mt LSHIFT A
&lt <layer>    <keycode>   // e.g. &lt 1 SPACE

// Custom instance defined in behaviors {}
/ {
    behaviors {
        hm: homerow_mods {
            compatible = "zmk,behavior-hold-tap";
            #binding-cells = <2>;
            tapping-term-ms = <150>;
            flavor = "balanced";
            bindings = <&kp>, <&kp>;
        };
    };
};
// Usage: &hm LSHIFT A

Parameters: Two values — (1) behavior/keycode for hold, (2) behavior/keycode for tap.

Pre-built Instances

Options / Props

Flavors

Notes

• Hold-tap cannot directly bind behaviors requiring multiple parameters (e.g., &bt BT_SEL 1); wrap them in a macro first.
• Key positions are zero-indexed, sequentially numbered from the first key in the keymap.
• hold-while-undecided interacts with combos — combo timeouts must expire before hold activates.
• Common pattern: homerow mods using balanced flavor with hold-trigger-key-positions and require-prior-idle-ms.

Related

• Key Press
• Layers
• Macros

Key Press

Sends a standard HID keycode on press and releases it on key release. This is the most fundamental ZMK behavior.

Signature / Usage

&kp <keycode>

Parameter: A keycode constant from dt-bindings/zmk/keys.h (e.g., A, N1, LSHIFT, C_VOL_UP).

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

/ {
    keymap {
        default_layer {
            bindings = <&kp A &kp LSHIFT &kp C_VOL_UP>;
        };
    };
};

Notes

• Keycodes span multiple HID usage pages: keyboard keys, modifiers, keypad, media/consumer controls, power, and application shortcuts.
• Include <dt-bindings/zmk/keys.h> for human-readable constants.
• Raw HID usage IDs can be used directly if the constant is not defined in the header.

Related

• Hold-Tap
• Sticky Key
• Mod-Morph

Key Repeat

Resends whatever keycode was last sent. Useful for keyboards that lack a dedicated repeat key.

Signature / Usage

&key_repeat

No parameters needed for basic use.

Custom configuration to also track consumer keys:

&key_repeat {
    usage-pages = <HID_USAGE_KEY HID_USAGE_CONSUMER>;
};

Options / Props

Notes

• By default, only HID Key usage page events are tracked; consumer page events (media keys) are ignored unless HID_USAGE_CONSUMER is added.
• Multiple usage pages can be listed together.

Related

• Caps Word
• Key Press

Key Toggle

Toggles a key between pressed and released state. Pressing when the key is up holds it down; pressing again releases it. Useful for shift-lock or sustained modifier keys.

Signature / Usage

&kt <keycode>
// e.g. &kt LALT

Parameter: Any keycode compatible with &kp (e.g., LALT, DOWN_ARROW).

Custom one-directional instance:

/ {
    behaviors {
        kt_on: key_toggle_on_only {
            compatible = "zmk,behavior-key-toggle";
            #binding-cells = <1>;
            display-name = "Key Toggle On";
            toggle-mode = "on";
        };
    };
};
// Usage: &kt_on LSHIFT

Options / Props

Notes

• Modified keys like LA(A) toggle based on the base keycode only; the modifier wrapper is disregarded when checking press state.

Related

• Key Press
• Sticky Key

Layer Behaviors

ZMK provides several behaviors for activating, toggling, and switching keyboard layers. Multiple layers can be active simultaneously; layer numbers start at 0 in keymap definition order.

Signature / Usage

&mo <layer>    // Momentary: active while held
&to <layer>    // To: enable one layer, disable all others (except default)
&tog <layer>   // Toggle: flip current on/off state
&lt <layer> <keycode>  // Layer-Tap: layer on hold, keycode on tap (see hold-tap.md)

Behaviors

Momentary Layer — &mo

Activates a layer while the key is held; deactivates on release.

&mo 3   // hold to activate layer 3

To Layer — &to

Enables the specified layer and disables all others except the default (layer 0).

&to 3

Toggle Layer — &tog

Flips the layer between enabled and disabled.

&tog 3

Custom one-directional variant:

/ {
    behaviors {
        tog_on: toggle_layer_on {
            compatible = "zmk,behavior-toggle-layer";
            #binding-cells = <1>;
            display-name = "Toggle Layer On";
            toggle-mode = "on";
        };
    };
};

Options / Props (&tog)

Notes

• &to and &tog with locking property prevent momentary behaviors from deactivating those layers.
• Define layer number constants for readability: #define LOWER 1, then use &mo LOWER.
• Layer-Tap (&lt) is documented in detail under Hold-Tap.
• Conditional Layers (activate a layer when two other layers are both active) are configured separately in the conditional_layers node.

Related

• Hold-Tap / Layer-Tap
• Sticky Layer
• Misc (trans / none)

Macros

Defines a sequence of behaviors to invoke when the macro key is pressed and/or released.

Signature / Usage

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

/ {
    macros {
        zed_em_kay: zed_em_kay {
            compatible = "zmk,behavior-macro";
            #binding-cells = <0>;
            bindings =
                <&macro_press &kp LSHFT>,
                <&macro_tap &kp Z &kp M &kp K>,
                <&macro_release &kp LSHFT>;
        };
    };
};

// Usage in keymap bindings:
// &zed_em_kay

Options / Props

Macro Control Behaviors

Parameterized Macros

Parameter forwarding controls: &macro_param_1to1, &macro_param_1to2, &macro_param_2to1, &macro_param_2to2. Use MACRO_PLACEHOLDER as a dummy value where parameters will be substituted.

Notes

• Behavior queue size defaults to 64; increase with CONFIG_ZMK_BEHAVIORS_QUEUE_SIZE.
• Maximum bindings per bindings field: 256.
• Use macros to wrap multi-parameter behaviors (e.g., &bt BT_SEL 1) for use inside hold-tap.

Related

• Key Press
• Hold-Tap

Miscellaneous Behaviors

Two utility behaviors for controlling key event propagation between layers.

Signature / Usage

&trans   // pass event to next active layer
&none    // swallow and block event

No parameters for either behavior.

Behaviors

Transparent — &trans

Ignores the key press/release at this layer position, allowing the event to fall through to the next active layer in the stack.

bindings = <&trans &kp A &trans>;

None — &none

Swallows the key press/release at this layer position, preventing it from reaching any lower layer.

bindings = <&none &kp A &none>;

Notes

• &trans is the standard placeholder for keys that should "inherit" their binding from a lower layer.
• &none explicitly blocks a key position, useful for disabling keys on a specific layer without accidentally activating bindings from lower layers.

Related

• Layers
• Overview

Mod-Morph

Invokes one of two behaviors depending on whether specified modifier keys are held at the time of the key press. ZMK ships a pre-configured &gresc (Grave Escape) instance.

Signature / Usage

#include <dt-bindings/zmk/keys.h>
#include <dt-bindings/zmk/mod-morph.h>

/ {
    behaviors {
        gresc: grave_escape {
            compatible = "zmk,behavior-mod-morph";
            #binding-cells = <0>;
            bindings = <&kp ESC>, <&kp GRAVE>;
            mods = <(MOD_LGUI|MOD_LSFT|MOD_RGUI|MOD_RSFT)>;
        };
    };
};

// Usage: &gresc

Parameters: None (zero-parameter behavior; behavior is fixed at definition time).

Options / Props

Available Modifier Constants

MOD_LSFT, MOD_RSFT, MOD_LCTL, MOD_RCTL, MOD_LALT, MOD_RALT, MOD_LGUI, MOD_RGUI

Combine with |: (MOD_LSFT|MOD_RSFT)

Notes

• Mod-morphs can be nested for complex multi-modifier logic.
• macOS users may need to disable "Modify Events" in Karabiner-Elements to avoid conflicts.

Related

• Key Press
• Hold-Tap
• Macros

Mouse Emulation

Three behaviors for controlling the mouse pointer, buttons, and scroll wheel from the keyboard. Requires the pointing feature to be enabled.

Signature / Usage

#include <dt-bindings/zmk/pointing.h>

// Mouse button press
&mkp MB1         // left click
&mkp RCLK        // right click

// Mouse movement
&mmv MOVE_UP
&mmv MOVE_X(500)

// Scroll
&msc SCRL_DOWN

Enable feature: Add CONFIG_ZMK_POINTING=y to your .conf file.

Behaviors

Mouse Button Press — &mkp

Input listener: &mkp_input_listener

Mouse Move — &mmv

Transmits X/Y movement events to the host.

Custom speed: MOVE_X(value) / MOVE_Y(value) (signed 16-bit integer).

Advanced listener properties: x-input-code, y-input-code, time-to-max-speed-ms, acceleration-exponent.

Input listener: &mmv_input_listener

Mouse Scroll — &msc

Sends vertical and horizontal scroll events.

Input listener: &msc_input_listener

Notes

• Enabling CONFIG_ZMK_POINTING=y modifies the HID report descriptor; the host OS must re-enumerate the device (replug or re-pair after firmware flash).
• The uint32 parameter for &mmv and &msc encodes X velocity in the upper 16 bits and Y velocity in the lower 16 bits.

Output Selection

Selects which connection (USB or Bluetooth) receives keyboard input when both are simultaneously active.

Signature / Usage

#include <dt-bindings/zmk/outputs.h>

&out OUT_USB   // route to USB
&out OUT_BLE   // route to current BT profile
&out OUT_TOG   // toggle between USB and BLE
&out OUT_NONE  // disable all output

Parameter: One of the OUT_* command constants.

Options / Props

Notes

• USB is the default output when both connections exist.
• The selected output persists across restarts and firmware flashes (saved to flash storage).
• Settings are saved after CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE ms to minimize flash wear.

Related

• Bluetooth
• RGB Underglow

Behaviors Overview

Behaviors are the actions assigned to key positions, sensors, and combos in ZMK keymaps. They define what happens when a key is pressed or released, or when an encoder rotates. Behaviors can also invoke other behaviors recursively (e.g., inside macros).

Signature / Usage

Behaviors are referenced in keymap bindings using an ampersand prefix:

/ {
    keymap {
        compatible = "zmk,keymap";
        default_layer {
            bindings = <
                &kp A   &mo 1   &bt BT_NXT
            >;
        };
    };
};

Behavior Categories

Notes

• Trigger types: key press/release on a layer, sensor rotation event, combo activation.
• Behaviors requiring multiple parameters (e.g., &bt BT_SEL 1) cannot be used directly as hold-tap bindings; use a macro wrapper instead.
• Custom behavior instances (e.g., custom hold-tap flavors) are defined in the devicetree behaviors {} block and referenced by their label.

Related

• Key Press
• Hold-Tap
• Layers
• Macros

External Power Control

Enables or disables the VCC power output to external devices (e.g., RGB LEDs) to extend battery life on supported controllers.

Signature / Usage

#include <dt-bindings/zmk/ext_power.h>

&ext_power EP_ON    // enable external power
&ext_power EP_OFF   // disable external power
&ext_power EP_TOG   // toggle external power

Parameter: One of the EP_* (or full EXT_POWER_*_CMD) constants.

Options / Props

Notes

• Supported hardware: nRFMicro, nice!nano.
• Settings persist across restarts and firmware flashes (saved to flash).
• On split keyboards this is a global behavior: changes affect both central and peripheral sides.
• Changes are saved after CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE ms to reduce flash wear.

Related

• Backlight
• RGB Underglow
• Soft Off

Keymap Behaviors

Reset

Two behaviors for restarting the keyboard firmware or entering bootloader mode for flashing.

Signature / Usage

&sys_reset    // restart firmware
&bootloader   // enter bootloader mode

No parameters for either behavior.

Behaviors

System Reset — &sys_reset

Resets the keyboard and re-runs the firmware currently flashed to the device.

Bootloader Reset — &bootloader

Resets the keyboard into bootloader mode, making it appear as a mass-storage device for firmware flashing.

Notes

• Both behaviors are source-specific on split keyboards: they only affect the half where the binding is activated.
• To reset both halves, place the bindings on both sides of the split.
• Combos always invoke reset behavior bindings on the central part of the split keyboard, regardless of which side physically triggers the combo.

Related

• Bluetooth
• Soft Off

Sensor Rotation

Triggers different behaviors depending on the direction (clockwise or counter-clockwise) of an encoder rotation. Two variants exist: a fixed-binding standard form and a parameterized variable form.

Signature / Usage

Standard — zmk,behavior-sensor-rotate (#sensor-binding-cells = <0>)

Behaviors are fully defined in the behaviors {} node:

/ {
    behaviors {
        rgb_encoder: rgb_encoder {
            compatible = "zmk,behavior-sensor-rotate";
            #sensor-binding-cells = <0>;
            bindings = <&rgb_ug RGB_BRI>, <&rgb_ug RGB_BRD>;
        };
    };
    keymap {
        default_layer {
            sensor-bindings = <&rgb_encoder>;
        };
    };
};

Variable — zmk,behavior-sensor-rotate-var (#sensor-binding-cells = <2>)

Two parameters are supplied at the keymap binding site:

/ {
    behaviors {
        rot_kp: rot_kp {
            compatible = "zmk,behavior-sensor-rotate-var";
            #sensor-binding-cells = <2>;
            bindings = <&kp>, <&kp>;
        };
    };
    keymap {
        default_layer {
            sensor-bindings = <&rot_kp PG_UP PG_DN>;
        };
    };
};

Options / Props

Notes

• Clockwise rotation invokes the first binding; counter-clockwise invokes the second.
• The variable variant passes its two keymap-site parameters directly to the behaviors defined in bindings.

Related

• Key Press
• RGB Underglow

Soft Off

Forces the keyboard into a deep low-power off state. The device can be reactivated with a dedicated on/off button (if present) or the reset button.

Signature / Usage

&soft_off

Optional hold-to-activate configuration:

&soft_off {
    hold-time-ms = <5000>;
};

Options / Props

Notes

• Requires soft-off to be enabled in the device configuration.
• On split keyboards, peripheral halves always activate immediately when the behavior triggers for reliability; the /delete-property/ directive can remove split-peripheral-off-on-press if you accept the reliability trade-off.

Related

• Power
• Reset

Sticky Key

Keeps a key (typically a modifier) active until the next non-modifier key is pressed, then releases it automatically. Equivalent to QMK "one-shot mods".

Signature / Usage

&sk <keycode>
// e.g. &sk LSHIFT

Parameter: A keycode (typically a modifier such as LSHIFT, LCTRL, or a chained modifier like LG(LS(LA(LCTRL)))).

Custom instance example:

/ {
    behaviors {
        skq: sticky_key_quick_release {
            compatible = "zmk,behavior-sticky-key";
            #binding-cells = <1>;
            bindings = <&kp>;
            release-after-ms = <1000>;
            quick-release;
            ignore-modifiers;
        };
    };
};

Options / Props

Notes

• Sticky keys can be chained: tap &sk LCTRL, tap &sk LSHIFT, tap &kp A → produces Ctrl+Shift+A.
• lazy sticky keys don't trigger other behavior releases without additional configuration.

Related

• Sticky Layer
• Key Press

Sticky Layer

Activates a layer temporarily without requiring the key to be held. The layer stays active until another (non-modifier) key is pressed, then deactivates. Equivalent to QMK "one-shot layers".

Signature / Usage

&sl <layer>
// e.g. &sl 1

Parameter: Layer index to activate (0-based).

Custom configuration example:

&sl {
    release-after-ms = <2000>;
};

Options / Props

Notes

• Can be chained with sticky keys: tap &sl 1, then &sk LSHIFT, then &kp A → produces Shift+A on layer 1.

Related

• Sticky Key
• Layers
• Tap-Dance

ZMK Studio Unlock

Unlocks the device for live editing via ZMK Studio. The device remains unlocked until an inactivity timeout or disconnection occurs.

Signature / Usage

&studio_unlock

No parameters.

Notes

• Unlock duration is controlled by the inactivity timeout configured in studio settings.
• Disconnecting from ZMK Studio automatically re-locks the device.
• This is a development/experimental feature; see the ZMK Studio documentation for setup requirements.

Related

• Soft Off
• Reset

Tap-Dance

Activates different behaviors based on how many times the key is tapped in quick succession.

Signature / Usage

/ {
    behaviors {
        td0: tap_dance_0 {
            compatible = "zmk,behavior-tap-dance";
            #binding-cells = <0>;
            tapping-term-ms = <200>;
            bindings = <&kp N1>, <&kp N2>, <&kp N3>;
        };
    };
};

// Usage in keymap: &td0
// 1 tap → N1, 2 taps → N2, 3 taps → N3

Parameters: None (zero-parameter; behavior is fully defined at the behaviors node).

Options / Props

Notes

• Tap-dances resolve immediately when interrupted by another keypress.
• When the maximum tap count is reached, the last binding fires immediately.
• Modifier keys held during a tap-dance remain active until the tap-dance is released, affecting subsequent keypresses.

Related

• Hold-Tap
• Sticky Key
• Mod-Morph

RGB Underglow

Controls RGB underglow LEDs: power, hue, saturation, brightness, animation speed, and color selection.

Signature / Usage

#include <dt-bindings/zmk/rgb.h>

&rgb_ug RGB_TOG                        // toggle on/off
&rgb_ug RGB_BRI                        // increase brightness
&rgb_ug RGB_COLOR_HSB(128, 100, 100)   // set green

Parameters: An RGB_* action constant, and optionally an HSB value for RGB_COLOR_HSB.

Options / Props

HSB Value Ranges

Notes

• RGB settings persist across restarts and firmware flashes; they override CONFIG_ZMK_RGB_*_START defaults.
• Changes are saved after CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE ms to reduce flash wear.
• On split keyboards this is a global behavior: changes affect both central and peripheral sides.

Related

• Backlight
• Power
• Output Selection

Battery

Enables detection and reporting of keyboard battery status, including peripheral battery levels for wireless split keyboards.

Kconfig

Devicetree

/chosen node

Battery Voltage Divider Sensor

Compatible: zmk,battery-voltage-divider

Reads battery voltage via ADC and voltage divider. Follows Zephyr's voltage divider documentation for properties.

nRF VDDH Battery Sensor

Compatible: zmk,battery-nrf-vddh

Reads battery voltage using Nordic nRF52's VDDH pin. No additional configuration required.

Notes

• Battery reporting is automatically enabled when BLE is active, unless explicitly disabled.
• On macOS, battery reporting packets can wake the computer from sleep. Disable with CONFIG_BT_BAS=n to prevent this while retaining monitoring.
• For wireless split keyboards, enable both CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_PROXY=y and CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_FETCHING=y to report levels from both halves.

Related

• Split
• Power
• System

Behaviors

Configurable properties that adjust how keyboard actions function. Behaviors serve as templates for custom actions; built-in nodes can be overridden in your keymap file.

Kconfig

Devicetree

Common Property

Hold-Tap (zmk,behavior-hold-tap)

Default nodes: &lt (layer-tap), &mt (mod-tap).

Macro (zmk,behavior-macro / zmk,behavior-macro-one-param / zmk,behavior-macro-two-param)

Control behaviors: &macro_tap, &macro_press, &macro_release, &macro_pause_for_release, &macro_wait_time, &macro_param_*

Sticky Key (zmk,behavior-sticky-key)

Default nodes: &sk (sticky key), &sl (sticky layer).

Tap Dance (zmk,behavior-tap-dance)

Caps Word (zmk,behavior-caps-word)

Two Axis Input (zmk,behavior-input-two-axis)

Notes

• Binding definitions are in app/dts/bindings/behaviors/ in the ZMK repository.
• All behavior configuration is compile-time; re-flash after changes.

Related

• Keymap
• Combos
• Overview

Bluetooth

Configuration for Bluetooth connectivity, pairing security, and device appearance in ZMK.

Kconfig

Notes

• After enabling CONFIG_ZMK_BLE_PASSKEY_ENTRY, all previously paired devices must be re-paired.
• CONFIG_BT_DEVICE_APPEARANCE accepts the decimal equivalent of Bluetooth appearance hex codes (e.g., 0x03C1 = 961 for keyboard).
• For system-level BLE settings (max connections, paired devices), see System.

Related

• System
• Split
• Settings

Bootloader

Configuration for bootloader integration, including double-tap reset entry, STM32 option byte setup, and magic value bootmode mapping.

Kconfig

Double Tap To Bootloader

STM32 nBOOT_SEL Option Byte Setup

Manages the nBOOT_SEL option byte on STM32C0/STM32G0 chips that can block system ROM bootloader access.

Bootmode Magic Value Mapper

For SoCs using magic value mappings to select bootloader mode.

Notes

• Definition file: zmk/app/src/boot/Kconfig
• Double-tap bootloader is automatically enabled for STM32, RP2040, and RP2350 targets; explicitly disable if not desired.

Related

• System
• Overview

Combos

Configuration for key combos, which trigger a single action when multiple keys are pressed simultaneously within a time window.

Kconfig

Devicetree

Compatible: zmk,combos

The parent node has no properties itself; it contains child nodes for each combo.

Combo Child Node Properties

Example

/ {
    combos {
        compatible = "zmk,combos";
        combo_esc {
            timeout-ms = <50>;
            key-positions = <0 1>;
            bindings = <&kp ESC>;
        };
    };
};

Notes

• Omitting layers enables the combo on all layers.
• require-prior-idle-ms is useful to prevent accidental combo activation during fast typing.

Related

• Behaviors
• Keymap

Displays

Configuration for keyboard display support, including widgets, screen type, threading, and LED blanking.

Kconfig

Core Display Settings

Widgets

Screen Type (select one)

Work Queue / Threading (select one)

Dedicated Thread Parameters

Devicetree

/chosen node

Supported Drivers

Notes

• CONFIG_ZMK_DISPLAY_INVERT may not work as expected with custom status screens that use images.
• Using CONFIG_ZMK_DISPLAY_WORK_QUEUE_DEDICATED prevents slow-updating displays from blocking keyboard responsiveness, at a memory overhead cost.

Related

• Power
• Battery
• LED Indicators
• Lighting

Encoders

Configuration for EC11 rotary encoders, including thread settings and per-sensor rotation triggers.

Kconfig

Trigger Mode (required when CONFIG_EC11=y, select one)

Devicetree

Keymap Sensor Configuration

Global settings apply to all sensors. Per-sensor overrides use ordered child nodes inside the zmk,keymap-sensors node; child node naming is arbitrary and order-based.

EC11 Node Properties

Compatible: alps,ec11

Notes

• Per-sensor overrides in zmk,keymap-sensors apply in sequential order to the listed sensors; child node names are ignored.

Related

• Keymap
• Kscan

Keymap

Configuration for keyboard layer definitions and sensor bindings using Devicetree syntax.

Devicetree

Primary Node: zmk,keymap

Compatible: zmk,keymap

The keymap node itself has no properties. It contains child nodes representing keyboard layers, starting with the default layer (layer 0).

Layer Child Node Properties

Example

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

        default_layer {
            display-name = "Base";
            bindings = <
                &kp Q &kp W &kp E
            >;
        };
    };
};

Secondary Node: zmk,keymap-sensors

Compatible: zmk,keymap-sensors

Supported sensor types: EC11 encoders (alps,ec11).

Notes

• Binding order in bindings is critical and must match the keyboard scan configuration.
• sensor-bindings order must match the order of sensors declared in zmk,keymap-sensors.
• Binding file: zmk/app/dts/bindings/zmk,keymap.yaml

Related

• Behaviors
• Combos
• Encoders
• Kscan
• Layout

Kscan (Keyboard Scan)

Configuration for key detection drivers supporting direct GPIO, matrix, demux, charlieplex, composite, mock, and sideband behavior configurations.

Kconfig

Driver-Specific Kconfig

Devicetree

/chosen node

Direct GPIO Driver

Matrix Driver

Demux Driver

Charlieplex Driver

Composite Driver

Child nodes specify individual drivers with optional row-offset and col-offset.

Mock Driver

Kscan Sideband Behavior Driver

Child nodes specify row, col, and bindings for each key to intercept.

Notes

• When global CONFIG_ZMK_KSCAN_DEBOUNCE_* values are set, they override per-device debounce settings uniformly.
• The demux driver does not honor CONFIG_ZMK_KSCAN_DEBOUNCE_* global overrides.
• GPIO flags differ between row2col and col2row matrix configurations.

Related

• Keymap
• Layout
• Encoders

Layout

Configuration for mapping the physical keyboard matrix to logical key positions, supporting matrix transforms, physical layouts, and multi-layout position mapping for ZMK Studio.

Kconfig

Devicetree

Matrix Transform

Compatible: zmk,matrix-transform

Maps logical keymap positions to physical keyboard scan (kscan) coordinates.

The map array uses the RC(row, column) macro from dt-bindings/zmk/matrix_transform.h, with one entry per logical keymap position.

#include <dt-bindings/zmk/matrix_transform.h>

/ {
    default_transform: keymap_transform_0 {
        compatible = "zmk,matrix-transform";
        columns = <3>;
        rows = <2>;
        map = <
            RC(0,0) RC(0,1) RC(0,2)
            RC(1,0) RC(1,1) RC(1,2)
        >;
    };
};

Physical Layout

Compatible: zmk,physical-layout

Combines matrix transform, keyboard scan, and physical key attributes.

Key Physical Attributes

Each key entry: <&key_physical_attrs width height x y rotation rotation_x rotation_y>

Physical Layout Position Map

Compatible: zmk,physical-layout-position-map

Preserves key mappings across different physical layouts when switching in ZMK Studio.

Notes

• key_physical_attrs must be imported from dts/physical_layouts.dtsi.
• Multiple matrix transforms can be defined; select the active one via the /chosen node.
• Matrix row-offset / col-offset allow adjustment without modifying individual RC() entries.
• Position maps enable seamless layout switching in ZMK Studio without remapping keys.

Related

• Kscan
• Keymap
• Studio

LED Indicators

Configuration for mapping HID indicator states (Caps Lock, Num Lock, etc.) to LED devices.

Kconfig

The initialization priority must be greater than CONFIG_LED_INIT_PRIORITY.

Devicetree

Compatible: zmk,indicator-leds

Properties

Notes on indicator Property

The indicator property must reference HID_INDICATOR_* definitions. Multiple indicator states can be combined with the pipe operator (|) to trigger the LED when any specified condition is active.

Notes

• Requires CONFIG_ZMK_HID_INDICATORS=y (system setting) to receive LED state from the host.

Related

• System
• Displays
• Lighting

Lighting

Configuration for RGB underglow and backlight LED features. Changes made through lighting behaviors are saved to flash after a one-minute delay.

Kconfig

RGB Underglow

Backlight

Devicetree

RGB Underglow

ZMK uses Zephyr's LED strip driver bindings. No ZMK-specific Devicetree properties are required; configure the LED strip driver per Zephyr documentation.

Backlight (/chosen node)

Notes

• Lighting state (brightness, color, effect) persists to flash storage after a 1-minute debounce delay.

Related

• Power
• Settings
• LED Indicators

Configuration Overview

ZMK's configuration system allows compile-time customization through Kconfig and Devicetree files. All configuration is set at compile time; changes require building and flashing new firmware.

Configuration File Locations

For split keyboards, use shared filenames without _left / _right suffixes to configure both sides.

Kconfig Files

Text files containing CONFIG_XYZ=value assignments for global settings (keyboard name, hardware enablement).

Devicetree Files

Changing Properties

Use the ampersand reference syntax to modify existing nodes:

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

Notes

• All configuration is compile-time only; re-flash to apply changes.
• Investigate the final combined Devicetree output during builds to diagnose issues.

Related

• Battery
• Behaviors
• Bluetooth
• Keymap
• Settings

Pointing

Configuration for pointing device (mouse) functionality, including input listeners, input processors, and split peripheral input routing.

Kconfig

Devicetree

Input Listener

Compatible: zmk,input-listener

Connects an input device to ZMK's input processing pipeline.

Layer-Specific Override Child Nodes

Input Split

Compatible: zmk,input-split

Routes pointing device input from a split keyboard peripheral to the central.

Notes

• CONFIG_ZMK_POINTING_SMOOTH_SCROLLING requires HID Resolution Multiplier support on the host OS.
• Layer-specific overrides in zmk,input-listener child nodes take precedence over the parent input-processors for the specified layers.

Related

• Behaviors
• Split
• System

Power

Configuration for low power states (idle/sleep/soft-off), external power control, GPIO wakeup triggers, and soft-off wakeup sources.

Kconfig

Low Power States

External Power Control

Devicetree

External Power Control

Compatible: zmk,ext-power-generic

GPIO Key Wakeup Trigger

Compatible: zmk,gpio-key-wakeup-trigger

Enables GPIO-based wakeup from soft off state.

Soft Off Wakeup Sources

Compatible: zmk,soft-off-wakeup-sources

Notes

• wakeup-source should always be present on the zmk,gpio-key-wakeup-trigger node.
• extra-gpios on the wakeup trigger should reference column pins for matrix keyboards to ensure keys are scannable during soft off.

Related

• Battery
• Displays
• Lighting
• Settings

Configuration

Settings

Configuration for persistent runtime settings stored in the controller's flash memory, including save debounce and reset behavior.

Kconfig

Features Using Persistent Storage

The following ZMK capabilities store data in flash and persist across power cycles and firmware updates:

Notes

• Regular ZMK firmware flashes intentionally preserve persistent settings to avoid losing Bluetooth pairings when keymaps are updated.
• To reset all settings: build with the settings_reset shield, flash it, then reflash normal firmware.
• For split keyboards, clear settings on both halves before re-pairing.
• ZMK Studio users can use "Restore Stock Settings" in the client interface as an alternative reset method.
• The save debounce (CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE) reduces flash wear by batching writes.

Related

• Bluetooth
• Lighting
• Power
• Split
• Studio

Split

Configuration for split keyboard behavior, supporting both Bluetooth and wired (UART) connections between keyboard halves.

Kconfig

Core Split Settings

Bluetooth Split

Wired Split

Devicetree

Wired Split

Compatible: zmk,wired-split

/ {
    wired_split {
        compatible = "zmk,wired-split";
        device = <&pro_micro_serial>;
    };
};

Notes

• CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS and BT connection/pairing counts (CONFIG_BT_MAX_CONN, CONFIG_BT_MAX_PAIRED) must be set one greater than the desired number of Bluetooth profiles on the central side.
• For BLE peripheral battery reporting, enable both CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_FETCHING and CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_PROXY.
• Async/DMA mode offers best performance; interrupt mode is suitable for RP2040/nRF52; polling mode is the universal fallback.

Related

• Bluetooth
• Battery
• Settings
• System

Studio

Configuration for ZMK Studio, including keymap layer name limits, session locking, and BLE transport tuning.

Kconfig

Keymaps

Locking

Transport / RPC

Notes

• ZMK Studio stores runtime keymap modifications and layout selections in persistent flash storage.
• Users can reset Studio changes via the "Restore Stock Settings" button in the ZMK Studio client interface.
• No Devicetree properties are defined for this feature.

Related

• Settings
• Keymap
• Layout
• Bluetooth

System

General system settings controlling keyboard identity, HID report types, USB descriptors, Bluetooth stack, and logging.

Kconfig

General

HID Configuration

USB

Bluetooth

Logging

Build Snippets (nRF boards)

Notes

• Changing CONFIG_ZMK_KEYBOARD_NAME requires clearing stored controller settings for the new name to take effect over BLE.
• On split keyboards, CONFIG_BT_MAX_CONN and CONFIG_BT_MAX_PAIRED must be set to one greater than the desired number of Bluetooth profiles, on the central only.
• The nrf52*-nosd snippets erase the SoftDevice. Flashing incompatible firmware afterward can permanently brick the board; bootloader re-flashing requires specialized recovery.

Related

• Bluetooth
• Split
• Settings
• Bootloader

Clean Room Implementation

ZMK is a clean room design firmware inspired by QMK/TMK, rewritten entirely under MIT license without copying any GPL-licensed code.

Notes

• All contributors MUST read and follow this policy before submitting code.
• Do NOT reuse, copy, or reference code from GPL-licensed projects (e.g., QMK, TMK).
• You MAY read documentation from GPL projects to understand feature behavior for reimplementation.
• You MAY inspect existing layouts/keymaps via the QMK Configurator and recreate them for ZMK — but never copy source code.
• Violating this policy would compromise ZMK's MIT license.

Related

• Clean Room Design (Wikipedia)
• QMK Configurator
• Pull Requests
• Documentation

Documentation

Guide for contributing documentation changes to ZMK, which uses Docusaurus as its documentation framework.

Signature / Usage

# From the docs/ folder
npm ci                    # Install dependencies (first time or after source updates)
npm start                 # Launch local dev server at http://localhost:3000

# Before submitting
npm run prettier:format   # Auto-format
npm run prettier:check    # Verify formatting
npm run lint              # Run linter
npm run build             # Full build check — all must pass

Notes

• Read the Clean Room Policy before contributing.
• Node.js/npm is required; already included in the ZMK dev container.
• VS Code + Docker users: the local server requires a manual restart after saving changes; auto-reload is not available in that environment.
• Use American English spelling and grammar.
• Heading case: Title Case for the first three heading levels; sentence case for all levels below.
• Prettier and lint cannot enforce language conventions — manual review is required.
• All checks (prettier:check, lint, build) must pass before opening a PR.

Related

• Clean Room Policy
• Pull Requests

Pull Requests

All changes to ZMK's main branch — including those from core committers — require a pull request.

Commit Message Format

<type>[optional scope]: <short summary>

<body — paragraph or bulleted list>

[optional git trailers]

Types

Common Scopes

hid, usb, ble, power, split, studio, display, underglow, backlight, behaviors, core, boards, shields

Notes

• Follow Conventional Commits format for all commit messages.
• Keep commits discrete and cohesive; use git commit --amend or interactive rebase to combine related changes.
• Do not use merge commits — rebase against upstream/main to maintain linear history.
• Fill out the auto-populated PR template completely when opening a PR on GitHub.
• Reviewers assess based on area of expertise; maintainers verify CI, inspect commit quality, and use squash-merge.

Related

• Clean Room Policy
• Documentation
• ZMK Pull Requests on GitHub

Contributing

Devicetree Overview

ZMK uses devicetree as a declarative way to describe hardware, keymaps, behaviors, and board configuration. It is the primary mechanism for both defining and customizing ZMK firmware.

Signature / Usage

Basic node syntax:

[label:] name {
    compatible = "zmk,behavior-mod-morph";
    #binding-cells = <0>;
    bindings = <&kp SPACE>, <&kp UNDERSCORE>;
    mods = <(MOD_LSFT|MOD_RSFT)>;
};

Overriding an existing node by phandle:

&existing_node {
    property = <2>;
};

Deleting nodes or properties:

/delete-node/ &node_label;
/delete-property/ property-name;

Options / Props

Property value types:

Notes

• File types: .dtsi (shared includes), .dts (board base), .overlay (board modifications), .keymap (ZMK-specific final overlay)
• Preprocessing happens in two passes: the C preprocessor and devicetree's own merge system. Later files overwrite earlier properties.
• Binding files in app/dts/bindings/ are authoritative for valid properties per compatible value.
• Phandle-based node overrides must not place the override block inside the root node /.
• Use /omit-if-no-ref/ &node_label; to drop unreferenced nodes from the build output.

Related

• new-behavior
• ZMK Bindings Directory
• Zephyr Devicetree Guide

ZMK Events

ZMK's event manager decouples behaviors and peripherals from core firmware by providing a pub/sub system for typed events. Modules subscribe to specific event types and receive callbacks when those events are raised.

Signature / Usage

Declare an event type (header file):

struct zmk_endpoint_changed {
    struct zmk_endpoint_instance endpoint;
};
ZMK_EVENT_DECLARE(zmk_endpoint_changed);

Register a listener and subscription:

ZMK_LISTENER(combo, behavior_combo_listener);
ZMK_SUBSCRIPTION(combo, zmk_keycode_state_changed);

Listener callback:

int behavior_hold_tap_listener(const zmk_event_t *eh) {
    if (as_zmk_position_state_changed(eh) != NULL) {
        return my_position_state_handler(eh);
    }
    return ZMK_EV_EVENT_BUBBLE;
}

Raising and freeing events:

raise_zmk_specific_thing_happened(struct zmk_specific_thing_happened event);
ZMK_EVENT_RAISE(ev);
ZMK_EVENT_FREE(ev);

Options / Props

Listener return values:

Common built-in event types (from `app/include/zmk/events/`):

Notes

• External module listeners have the highest priority because they are linked first.
• Listeners should return ZMK_EV_EVENT_BUBBLE whenever possible; only capture events when strictly necessary.
• Listener priority within ZMK is determined by the order of source files in CMakeLists.txt.
• Priority between external modules is determined by west.yml project order—avoid creating order-dependent designs.
• as_<event_type>(eh) returns NULL if the event does not match the type, enabling safe type checks.

Related

• new-behavior
• module-creation
• ZMK Event Header Files

Module Creation

ZMK modules are the recommended way to extend ZMK firmware with new keyboards, behaviors, drivers, or features without modifying the ZMK core repository.

Signature / Usage

`zephyr/module.yml` — minimum required file:

name: <your-module-name>

`west.yml` — dependency manifest:

manifest:
  remotes:
    - name: remote-name
      url-base: https://github.com/remote-name
  projects:
    - name: repository-name
      remote: remote-name
      import: west.yml

Options / Props

Module naming convention: zmk-<type>-<description>

`zephyr/module.yml` build properties:

Notes

• Start from the official ZMK Module Template repository.
• The module name in zephyr/module.yml may differ from the GitHub repository name.
• Place public header files under include/zmk_<type>_<description>/ so paths are unambiguous.
• Every module must include a README.md and a LICENSE file.

Related

• new-behavior
• events
• ZMK Module Template
• Zephyr Module Documentation

New Behavior

Step-by-step guide for creating a custom ZMK behavior—the action invoked when a key is pressed or released. Behaviors are implemented as Zephyr RTOS devices and distributed as ZMK modules.

Signature / Usage

Minimal behavior source file (`src/behaviors/behavior_<name>.c`):

#define DT_DRV_COMPAT zmk_behavior_<name>

#include <zephyr/device.h>
#include <zephyr/logging/log.h>
#include <drivers/behavior.h>
#include <zmk/behavior.h>

static int on_<name>_binding_pressed(struct zmk_behavior_binding *binding,
                                     struct zmk_behavior_binding_event event) {
    return ZMK_BEHAVIOR_OPAQUE;
}

static int on_<name>_binding_released(struct zmk_behavior_binding *binding,
                                      struct zmk_behavior_binding_event event) {
    return ZMK_BEHAVIOR_OPAQUE;
}

static const struct behavior_driver_api <name>_driver_api = {
    .binding_pressed  = on_<name>_binding_pressed,
    .binding_released = on_<name>_binding_released,
};

BEHAVIOR_DT_INST_DEFINE(0, <name>_init, NULL, NULL, NULL,
                        POST_KERNEL, CONFIG_KERNEL_INIT_PRIORITY_DEFAULT,
                        &<name>_driver_api);

Devicetree binding (`dts/bindings/behaviors/zmk,behavior-<name>.yaml`):

description: My custom behavior
compatible: "zmk,behavior-<name>"
include: zero_param.yaml   # or one_param.yaml / two_param.yaml
properties:
  my-option:
    type: int
    default: 0

Kconfig (`Kconfig`):

config ZMK_BEHAVIOR_<NAME>
    bool
    default y
    depends on DT_HAS_ZMK_BEHAVIOR_<NAME>_ENABLED

CMakeLists.txt (split-keyboard safe):

if ((NOT CONFIG_ZMK_SPLIT) OR CONFIG_ZMK_SPLIT_ROLE_CENTRAL)
    target_sources(app PRIVATE src/behaviors/behavior_<name>.c)
endif()

Options / Props

Repository structure:

zmk-behavior-<name>/
├── CMakeLists.txt
├── Kconfig
├── LICENSE
├── README.md
├── dts/bindings/behaviors/zmk,behavior-<name>.yaml
├── dts/behaviors/<name>.dtsi          # optional predefined instances
├── include/dt-bindings/zmk/<name>.h   # optional HID/constant headers
├── src/behaviors/behavior_<name>.c
├── tests/<name>/
└── zephyr/module.yml

Behavior locality (`.locality` field in `behavior_driver_api`):

Useful ZMK API functions:

Notes

• Read the ZMK clean room policy before starting development.
• Behaviors must access system state via the event manager (#include <zmk/event_manager.h>); see events.
• Predefined behavior instances in .dtsi files: node names must be ≤ 8 characters if locality is not BEHAVIOR_LOCALITY_CENTRAL, so the node is addressable from split peripheral halves.
• Use USB logging for hardware testing since Zephyr does not support logging over Bluetooth.
• Run west test from the module root to execute virtual test suites.
• C source files submitted to ZMK must be formatted with clang-format.
• Code from QMK/TMK may not be used as source material for ZMK due to GPL license restrictions.
• Use MIT SPDX headers for ZMK contributions: SPDX-License-Identifier: MIT.

Related

• module-creation
• devicetree
• events
• usb-logging
• ZMK Module Template

Development

Studio RPC Protocol

The ZMK Studio UI communicates with ZMK devices over a custom RPC protocol built on Protocol Buffers with a simple byte-framing scheme, transmitted over USB serial or BLE.

Signature / Usage

Message framing control bytes:

When a payload byte matches a control byte value, it is escaped by prefixing it with 0xAC.

Message flow:

Client → Device : Request  (protobuf-encoded, framed)
Device → Client : Response → RequestResponse  (reply to a request)
Device → Client : Response → Notification     (unsolicited state update)

Options / Props

BLE Transport (GATT):

USB Transport:

• USB class: CDC/ACM (serial port over USB)
• Framed messages are sent over the CDC/ACM UART interface.

Notes

• Protocol Buffer message definitions live in the zmk-studio-messages repository.
• Review the ZMK clean room policy before contributing to protocol-related code.

Related

• usb-logging
• zmk-studio-messages

USB Logging

USB logging redirects ZMK's printk, console output, and Zephyr log messages to a USB CDC ACM serial device, enabling debugging on keyboards that have no UART interface.

Signature / Usage

GitHub Actions `build.yaml` (add snippet to a shield build):

---
include:
  - board: nice_nano
    shield: corne_left
    snippet: zmk-usb-logging

Local build with `west`:

west build -b nice_nano -S zmk-usb-logging -- -DSHIELD="corne_left"

Connect on Linux:

sudo tio /dev/ttyACM0

Connect on macOS:

sudo tio /dev/tty.usbmodem14401

Notes

• USB logging increases power consumption and can noticeably reduce battery life; disable it when not debugging.
• Standard boards such as the nice!nano and Seeed Studio XIAO are pre-configured; no extra board-level changes are needed.
• Custom boards must expose the USB device node with: zephyr_udc0: &usbd { status = "okay"; }
• Legacy configurations may use CONFIG_ZMK_USB_LOGGING=y in a Kconfig file instead of the snippet.
• Bluetooth logging is not supported by Zephyr; USB logging is the only practical on-device log output method.

Related

• new-behavior
• Zephyr Logging Documentation
• Zephyr CDC-ACM Console

Battery Level

Reports battery level to connected Bluetooth hosts and optionally to the keyboard's display. Boards using ZMK's officially supported hardware have battery sensing pre-configured.

Notes

• Only the central side's battery is reported over Bluetooth by default; peripheral battery monitoring requires additional setup and host support.
• Windows may not properly request battery updates, which can result in stale readings.
• Custom boards must follow the hardware integration guide to implement battery sensing.

Related

• config/battery
• split-keyboards

Bluetooth

Enables wireless keyboard connectivity via Bluetooth Low Energy (BLE), supporting both host connections and split keyboard communication. Requires Bluetooth 4.2 or newer on the host.

Notes

• ZMK supports up to 5 bonded device profiles by default; profiles must be selected manually when pairing new devices.
• Multiple hosts may show as "connected" simultaneously, but only the active profile receives keystrokes.
• Security uses Elliptic Curve Diffie Hellman (ECDH) for key generation. Numeric Comparison association model (for stronger pairing) is experimental.
• After enabling features that modify the HID descriptor (e.g., mouse keys, NKRO), remove and re-pair the device on the host to refresh the cached descriptor.
• Mismatched bond keys between profiles can cause unexpected behavior.

Related

• behaviors/bluetooth
• split-keyboards
• troubleshooting/connection-issues

Debouncing

ZMK uses a cycle-based debounce algorithm where each key is debounced independently. By default a key must remain stable for 5 ms before a state change is registered.

Signature / Usage

# .conf — global overrides
CONFIG_ZMK_KSCAN_DEBOUNCE_PRESS_MS=5
CONFIG_ZMK_KSCAN_DEBOUNCE_RELEASE_MS=5

/* per-driver devicetree override */
&kscan0 {
    debounce-press-ms = <3>;
    debounce-release-ms = <3>;
};

Options / Props

Notes

• Supported by zmk,kscan-gpio-matrix and zmk,kscan-gpio-direct drivers only.
• Global Kconfig options override per-driver devicetree settings.
• Timers round up to the next multiple of debounce-scan-period-ms.
• For minimum latency, set DEBOUNCE_PRESS_MS=0 or 1 with a higher release value.
• debounce-period devicetree property is deprecated.
• Equivalent to QMK's sym_defer_pk algorithm; eager mode mirrors asym_eager_defer_pk.

Displays

Proof-of-concept support for OLED and ePaper displays on ZMK-powered keyboards. Not yet production-ready; full documentation is pending.

Notes

• Current status: proof of concept — not recommended for production use.
• Known bug: display remains blank after resuming from an external power cutoff (tracked in zmkfirmware/zmk#674).
• No Kconfig symbols or devicetree properties are publicly documented for this feature yet.

Related

• lighting
• pointing

Encoders

Support for EC11 rotary encoders with push buttons. Push button and rotation behaviors are configured independently.

Signature / Usage

# .conf
CONFIG_EC11=y
CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y

/* keymap — rotation bindings */
sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN &inc_dec_kp PG_UP PG_DN>;

Options / Props

Notes

• The encoder push button connects to the keyboard matrix and is mapped like any standard key.
• sensor-bindings accepts one entry per encoder; &inc_dec_kp is the built-in behavior for sending keycodes on rotation.
• After editing .conf, push and flash the updated firmware to activate the changes.

Related

• behaviors/sensor-rotate
• development/hardware-integration/encoders

LED Indicators

Displays the five standard HID indicator states (Num Lock, Caps Lock, Scroll Lock, Compose, Kana) via LEDs when the hardware supports them.

Signature / Usage

&caps_lock_indicator {
    active-brightness = <0>;
    inactive-brightness = <100>;
    disconnected-brightness = <50>;
};

Options / Props

Available node labels: num_lock_indicator, caps_lock_indicator, scroll_lock_indicator, compose_indicator, kana_indicator.

Notes

• Default behavior: off when idle on battery, off when disconnected, on at full brightness when active.
• Brightness values greater than 0 default to maximum on LEDs that lack PWM support.
• PWM brightness control is available but slightly increases power consumption.

Related

• development/hardware-integration/lighting/led-indicators

Lighting

ZMK supports two independent lighting systems: RGB Underglow (addressable RGB LEDs) and Backlight (single-color parallel LEDs). The choice between them depends on the LED driver, not the physical LED position.

Signature / Usage

# RGB Underglow
CONFIG_ZMK_RGB_UNDERGLOW=y

# Backlight
CONFIG_ZMK_BACKLIGHT=y

/* Set number of LEDs in the RGB strip */
&led_strip {
    chain-length = <21>;
};

Options / Props

Notes

• Supported RGB LED families: WS2812, APA102, LPD880x.
• For split keyboards, set chain-length to the LED count per half, not the total.
• Backlight cannot control individual LED brightness; all LEDs share the same power level.
• Full configuration options are documented at /docs/config/lighting.

Related

• config/lighting
• led-indicators

Low Power States

ZMK provides three low-power modes to extend battery life: Idle, Deep Sleep, and Soft Off.

Options / Props

Notes

• Deep Sleep must be explicitly enabled in power configuration settings.
• kscan nodes require the wakeup-source devicetree property to serve as wake sources; this is recommended even when deep sleep is not used.
• Deep Sleep clears any unsaved ZMK Studio changes.
• Soft Off is more restrictive in wake sources than Deep Sleep (typically only a designated GPIO pin or the reset button).
• For split keyboards, the reset button must be pressed on each half to wake from Soft Off.

Related

• behaviors/soft-off
• development/hardware-integration/soft-off-setup
• config/power

Modules

ZMK leverages Zephyr modules to incorporate external source code or configuration into builds — similar to plugins or themes. Common uses include adding support for keyboards outside the main ZMK repo and adding custom drivers or behaviors.

Signature / Usage

# zmk-config/config/west.yml — adding an external module
manifest:
  remotes:
    - name: zmkfirmware
      url-base: https://github.com/zmkfirmware
    - name: my-module-owner
      url-base: https://github.com/my-module-owner
  projects:
    - name: zmk
      remote: zmkfirmware
      revision: main
      import: app/west.yml
    - name: my-zmk-module
      remote: my-module-owner
      revision: main
  self:
    path: config

Notes

• A typical ZMK build involves three components: the user ZMK config, ZMK modules, and the core ZMK firmware.
• For GitHub Actions builds, edit west.yml to add remotes and project entries; use the import property for modules that have their own dependencies.
• For local builds, clone the module into your local file tree and pass it as an external module during west build.
• Unreleased features from open pull requests can be tested by pointing west.yml to the developer's fork and branch instead of the official repository.

Related

• development/module-creation
• Zephyr West Manifests

Pointing Devices

Supports physical pointing devices (trackpads, trackballs) and mouse emulation behaviors for sending HID pointing events to connected hosts.

Signature / Usage

# .conf
CONFIG_ZMK_POINTING=y

/* keymap — mouse emulation behavior */
&mmv MOVE_UP

Notes

• Enabling this feature modifies the HID report descriptor. Remove and re-pair Bluetooth hosts after enabling to ensure they pick up the updated descriptor.
• Two implementation paths are available:
• Mouse emulation: use keymap behaviors (e.g., &mmv) to send mouse events without dedicated hardware.
• Physical pointing devices: integrate actual hardware via the pointer hardware integration guide.
• Input Processors can modify pointing behavior (scaling, scroll mode conversion, temporary layer activation).
• Input Listeners connect low-level input devices to ZMK's HID system and apply processors.

Related

• config/pointing
• behaviors/mouse-emulation
• bluetooth

Features

Split Keyboards

Enables keyboards split into multiple physical parts with independent controllers. One part acts as the "central" (manages keymap logic and host communication); others are "peripherals" that forward key and sensor events to the central.

Signature / Usage

# Central .conf
CONFIG_ZMK_SPLIT=y
CONFIG_ZMK_SPLIT_ROLE_CENTRAL=y
CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS=1

/* Wired (full-duplex UART) transport */
compatible = "zmk,wired-split";

Options / Props

Notes

• BLE transport increases average latency by ~3.75 ms (worst case ~7.5 ms).
• Wired UART transport supports only a single peripheral and is experimental.
• Safety: never insert or remove the TRRS/UART cable while a controller is powered by USB or battery — this can permanently damage controllers.
• Split keyboards require separate firmware files per part (e.g., <keyboard>_left, <keyboard>_right).
• Keymap changes typically only require flashing the central; configuration changes may require flashing all parts.
• Some behaviors have locality constraints that affect which side executes them.

Related

• bluetooth
• battery
• troubleshooting/connection-issues
• config/split

ZMK Studio

Enables runtime keymap updates without reflashing firmware. Users can modify keyboard layers while the device is in use via USB or Bluetooth at https://zmk.studio/ or through native desktop apps.

Signature / Usage

# build.yaml (GitHub Actions)
- board: <your_board>
  shield: <your_shield>
  snippet: studio-rpc-usb-uart
  cmake-args: -DCONFIG_ZMK_STUDIO=y

# Local build
west build -S studio-rpc-usb-uart -- -DCONFIG_ZMK_STUDIO=y

/* keymap — add unlock binding */
&studio_unlock

/* Reserve extra layers for Studio */
/ {
    keymap {
        compatible = "zmk,keymap";
        extra_layer {
            status = "reserved";
        };
    };
};

Options / Props

Notes

• Once Studio has written keymap changes to the device, future edits to the .keymap source file will not be applied unless a factory reset is performed via the Studio UI.
• Keyboards must have physical layouts with a keys property defined.
• Boards using chosen zmk,matrix-transform are not compatible with Studio.
• Some MCUs (e.g., STM32F072) require RAM optimization tuning.
• Deep Sleep clears unsaved Studio changes.
• Currently supported: layer renaming, enabling extra layers, key binding assignment, alternative physical layout selection.
• Planned (not yet available): behavior property configuration, combos, conditional layers, host locale selection, keymap import/export.

Related

• low-power-states
• bluetooth

Customizing ZMK

ZMK configuration lives in a personal zmk-config repository, keeping user settings separate from the ZMK firmware source. Changes are committed and pushed to GitHub, where Actions automatically build updated firmware.

Configuration Files

Each keyboard in a zmk-config has two primary files under the config/ subfolder:

The build.yaml file at the repository root specifies which board/shield combinations to build.

Workflow

1. Edit config/<keyboard>.conf to enable or disable firmware features. 2. Edit config/<keyboard>.keymap to define your key layout and layers. 3. Update build.yaml if adding or removing a keyboard. 4. Commit and push — GitHub Actions builds and publishes firmware artifacts. 5. Download and flash the firmware to your keyboard.

Multi-Keyboard Support

To manage multiple keyboards in one repository, add entries to build.yaml and place each keyboard's .conf and .keymap files in the config/ subfolder.

Notes

• For split keyboards, only the central (left) half needs to be reflashed when updating keymaps.
• Local builds are supported for users who prefer not to rely on GitHub Actions — follow the toolchain setup documentation.
• The zmk code command (ZMK CLI) opens keymap and config files in your preferred editor.

Related

• Installing ZMK
• ZMK CLI

FAQ

Frequently asked questions about ZMK Firmware.

General

Why Zephyr? Zephyr is a best-in-class RTOS offering cross-architecture support, low-power optimization, DeviceTree/Kconfig configuration, a qualified BLE stack, multi-processor support, Apache 2.0 licensing, and LTS security updates.

Why create ZMK? ZMK offers a Zephyr foundation, permissive MIT licensing (enabling integration of non-GPL-compatible libraries), and a wireless-first design prioritizing power efficiency.

What is the license? ZMK uses the MIT license.

What does "ZMK" stand for? "Zephyr Mechanical Keyboard" — inspired by the naming convention of TMK/QMK.

Who created ZMK? Pete Johanson.

Is ZMK related to TMK/QMK? Inspired by them, but it is an entirely separate and unrelated project.

Hardware

What hardware is supported? ZMK can theoretically run on any Zephyr-supported platform; contributors test a limited subset of configurations. See Supported Hardware.

Does ZMK support AVR? No. Zephyr only supports 32-bit and 64-bit platforms.

What are boards vs. shields? Zephyr terminology that enables modularity — different compatible controllers can be combined with different keyboard PCBs (shields) at build time.

Features

Does ZMK support wired split keyboards? Currently, ZMK only supports wireless split keyboards. Experimental wired support exists for advanced users with specific hardware.

What is the input latency? Comparable to other keyboard firmware; varies by scanning method and debounce algorithm.

Is there a 2.4 GHz dongle option? No current plans. Nordic's proprietary 2.4 GHz protocols require restrictive licensing. BLE dongles are available with approximately 3.75 ms theoretical latency.

Is ZMK bootloader-specific? No. ZMK supports multiple flash utilities including OpenOCD and nrfjprog.

Community

How do I contribute? Use the developer documentation to get started.

Where do I discuss ideas or new keyboard support? Join the Discord community.

Is there a Code of Conduct? Yes, available on GitHub.

Notes

• The project team is small; support capacity is limited while development is ongoing.
• Community channels: Discord, Mastodon, Twitter, GitHub.

Related

• Supported Hardware
• Installing ZMK

Supported Hardware

ZMK supports a wide range of microcontroller platforms built on Zephyr RTOS, including Nordic nRF52, Raspberry Pi RP2040/RP2350, ST STM32, and Microchip SAMD21. Hardware is organized into two main categories: onboard controller keyboards and composite keyboards.

Hardware Categories

Onboard Controller Keyboards

Single-PCB keyboards where the controller is integrated directly on the board. Examples include Advantage 360 Pro, Glove80, and Planck Rev6.

Composite Keyboards

Separate controller boards paired with keyboard PCBs (shields), organized by interconnect type:

Notes

• ZMK does not support AVR 8-bit processors (e.g., original Arduino Uno, SparkFun Pro Micro) because Zephyr only supports 32-bit and 64-bit platforms.
• All in-tree boards use a zmk board variant for consistency.
• Any Zephyr-supported platform can theoretically run ZMK, but only a subset has been tested by contributors.
• New keyboard shield support requires following the contributor documentation and clean room design requirements.

Related

• FAQ
• Installing ZMK

Getting Started

Installing ZMK

ZMK uses GitHub Actions to build firmware in the cloud, eliminating the need to set up a local toolchain. Users create a personal zmk-config repository that holds their keyboard configuration, then push changes to trigger automated builds.

Prerequisites

Setup Steps

1. Install the ZMK CLI via uv (see ZMK CLI). 2. Run zmk init to create and clone a GitHub repository for your configuration. 3. Edit build.yaml to specify your keyboard board and shield. 4. Customize your <keyboard>.keymap and <keyboard>.conf files. 5. Commit and push changes — GitHub Actions will build the firmware automatically. 6. Download the compiled firmware artifact from the GitHub Actions run.

Flashing Firmware

Notes

• When Git prompts for credentials, do not enter your password. Paste your GitHub personal access token (with workflow scope) in the password field instead. GitHub CLI can be used as an alternative for authentication.
• For split keyboards, test the central half (typically the left side) over USB before attempting wireless pairing.
• Only the central half needs to be reflashed when updating keymaps on a split keyboard.
• Local builds are possible by following the toolchain setup documentation.

Related

• ZMK CLI
• Customizing ZMK
• Supported Hardware

ZMK CLI

The ZMK CLI is a command-line utility that streamlines creation and management of ZMK configuration repositories. It automates common tasks such as initializing a repo, adding keyboards, and downloading firmware.

Installation

The ZMK CLI is installed as part of the user setup process using uv. To update to the latest version:

uv tool upgrade zmk

Commands

Repository

Keyboard

Module

Editing & Download

Configuration Settings

Notes

• zmk init handles GitHub authentication and repository creation interactively.
• Modules extend ZMK with additional features beyond the core firmware.

Related

• Installing ZMK
• Customizing ZMK