DOCSEARCHbyAlgolia
Submit Docs

ZMK-Helpers

repository·main·Indexed 19 days ago

https://github.com/urob/zmk-helpers

A collection of helper macros (Version 2) designed to simplify the configuration of ZMK keymaps. It provides convenience macros for defining behaviors, combos, layers, and leader sequences, as well as portable key-labels for various keyboard layouts and deprecated Unicode character helpers.

Tokens
6.1K
Snippets
20
Records
24
Agent score
65%

What's inside zmk-helpers

  1. Understand the key-label naming convention

    main

    Key-labels follow a standardized three-part structure: <side><row><column>.

    <side>-tag

    • L: Left side keys.
    • R: Right side keys.

    <row>-tag

    • N: The row above the core rows (typically numbers).
    • T: Top core row.
    • M: Middle core row.
    • B: Bottom core row.
    • H: Thumb row (the lowest row if there is only one below B, or the absolute lowest row if there are multiple).
    • EC: Encoder rows (regardless of location).
    • Custom: Other rows can be labeled as needed to fit the layout.

    <column>-tag

    • Columns are numbered from the inside to the outside.
    • 0 to 4: The five core columns (alpha keys), where 1 is the index finger homing position.
    • Thumbs: Numbered such that the homing position falls between 0 and 1.
    • Encoders: May omit the column number if the <side> and <row> uniquely identify them.

  2. Use Key-labels for portable layouts

    main

    Key-labels allow you to use easy-to-remember names instead of numeric key-positions for configuring position-based properties (like combos). These labels are standardized to make keymaps portable across different keyboards.

    Group Labels:

    • KEYS_L and KEYS_R: All B-row, M-row, and T-row keys on the left/right half.
    • THUMBS_L and THUMBS_R: All H-row keys on the left/right half.
    • THUMBS: All H-row keys.
    • NUMROW: All N-row keys.

    Supported Layouts:

    • 34.h (Ferris, Hypergolic, Sweep)
    • 36.h (Corne 5-col, Corne-ish Zen 5-col)
    • 42.h (Corne, Corne-ish Zen)
    • 54.h (Bug54)
    • 70.h (Viterbi)
    • 4x12.h, 4x12_wide.h (Planck)
    • 5x6.h (Caldera)
    • adv360.h (Kinesis Advantage360 Pro)
    • eyelash42.h (Eyelash Corne)
    • glove80.h (Glove80)
    • hillside_*.h (Hillside family)
    • hummingbird.h (Hummingbird, Tern, Phantom, Rufous)
    • jian.h (Jian, Jorne)
    • klor.h, klorkonrad.h (Klor, Klor Konrad)
    • kyria.h (Kyria)
    • lily58.h (Lily58)
    • osprette.h (Osprette)
    • redox.h (Redox)
    • rolio46.h (Rolio46)
    • sofle.h (Sofle)
    • totem.h (Totem)
    • zilpzalp.h (Zilpzalp)

    Special Note for Lily58: To use standard labels for Lily58, you must set the LILY58_STANDARD_LABELS flag before sourcing the header.

    #define LILY58_STANDARD_LABELS
#include <zmk-helpers/key-labels/lily58.h>

  3. Use the deprecated ZMK_UNICODE helpers

    main

    Deprecation Warning

    Note: The ZMK_UNICODE helpers are deprecated. It is recommended to use the zmk-unicode module instead.

    Overview

    ZMK_UNICODE allows you to create Unicode characters that can be added to your keymap using the &name syntax.

    • ZMK_UNICODE_SINGLE(name, L0, L1, L2, L3): Creates a single character.
    • ZMK_UNICODE_PAIR(name, L0, L1, L2, L3, U0, U1, U2, U3): Creates a pair of characters (typically unshifted and shifted versions).

    Parameters

    • name: A unique string used to reference the character in your keymap.
    • L0 to L3: A 4-digit sequence defining the Unicode string using standard ZMK key codes.
    • U0 to U3 (for ZMK_UNICODE_PAIR only): A 4-digit sequence defining the shifted Unicode string.
    // Single character example
ZMK_UNICODE_SINGLE(euro_sign, N2, N0, A, C)

// Pair example (unshifted and shifted)
ZMK_UNICODE_PAIR(de_ae, N0, N0, E, N4, N0, N0, C, N4)

  4. Use key-labels for position-based configuration

    main

    Key-labels allow you to use human-readable identifiers (e.g., LT0 or RB1) instead of numeric key positions when configuring ZMK behaviors like combos or positional hold-taps. This makes keymaps more portable across different keyboard layouts.

    To use them, you must source the specific layout header for your keyboard at the top of your keymap file.

    #include "zmk-helpers/key-labels/34.h"  // replace by the correct header for your keyboard

  5. Configure ZMK_UNICODE for Windows, Linux, or macOS

    main

    The ZMK_UNICODE helpers require OS-specific configuration to function correctly. You must define the HOST_OS macro before sourcing helper.h.

    Windows

    Install WinCompose on your computer. No specific HOST_OS definition is required in the code.

    Linux

    Set HOST_OS to 1 before including the helper header.

    Note: If your Linux system uses a non-standard Unicode input method, you may need to configure it to initialize by tapping LCTRL(LSHFT(U)) and terminating with SPACE, or use the Custom Configuration method below.

    macOS

    1. Enable Unicode Hex Input in your system's Input Sources preferences.
    2. Set HOST_OS to 2 before including the helper header.

    Custom Configuration

    For non-default input channels or other operating systems, define OS_UNICODE_LEAD and OS_UNICODE_TRAIL to specify the character sequences that initialize and terminate the Unicode input.

    Example: Initializing with LCTRL + LSHFT + U and terminating with SPACE (while releasing LCTRL and LSHFT):

    // Linux setup
#define HOST_OS 1
#include "zmk-helpers/helper.h"

// macOS setup
#define HOST_OS 2
#include "zmk-helpers/helper.h"

// Custom setup example
#define OS_UNICODE_LEAD &macro_press &kp LCTRL &kp LSHFT &macro_tap &kp U
#define OS_UNICODE_TRAIL &macro_tap &kp SPACE &macro_release &kp LCTRL &kp LSHFT
#include "zmk-helpers/helper.h"

  6. Manually install ZMK-Helpers

    main

    If you prefer not to use West modules, you can manually install the helpers using one of the following methods:

    Method 1: Copy files

    Copy the contents of include/zmk-helpers directly into your config/ directory so that the structure looks like this:

    zmk-config
├── config
│   ├── corne.keymap
│   ├── zmk-helpers
│   │   ├── helper.h
│   │   └── ...
│   └── ...
└── ...

    Method 2: Git Submodule

    Add the repository as a git submodule and create a symbolic link to the include directory:

    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

  7. Install ZMK-Helpers as a West module

    main

    The recommended way to install ZMK-Helpers is to add it as a module in your config/west.yml file. You must add a new entry to both the remotes and projects sections. Ensure the revision for zmk-helpers matches your desired ZMK release version to maintain compatibility.

    manifest:
  remotes:
    - name: zmkfirmware
      url-base: https://github.com/zmkfirmware
    - name: urob
      url-base: https://github.com/urob
  projects:
    - name: zmk
      remote: zmkfirmware
      revision: v0.3 # Set to desired ZMK release.
      import: app/west.yml
    - name: zmk-helpers
      remote: urob
      revision: v0.3 # Should match ZMK release.
  self:
    path: config

  8. Configure keymap-drawer to use zmk-helpers via GitHub Actions

    main

    To use zmk-helpers with keymap-drawer in an automated GitHub Actions workflow, you must tell the parser where to find the helper headers.

    1. Follow the standard keymap-drawer workflow setup instructions.
    2. In your keymap_drawer.config.yaml file (located at the repository root), add the zmk-helpers/include directory to the zmk_additional_includes list within the parse_config section.
    parse_config:
  zmk_additional_includes: ["zmk-helpers/include"]

  9. Configure keymap-drawer to use zmk-helpers locally

    main

    If you are running keymap-drawer locally (version 0.18.0 or later), you need to provide the path to the zmk-helpers/include directory in your configuration file. This file is typically passed to the command via keymap -c config.yaml parse ....

    • Absolute Paths: You can use the full path to the include directory.
    • Relative Paths: You can use relative paths, but they must be relative to the working directory from which you execute the keymap-drawer command.

    Example: If zmk-helpers is located at the root of your zmk-config directory and you are running the command from that root, use "zmk-helpers/include".

    parse_config:
  zmk_additional_includes: ["/path/to/zmk-helpers/include"]

  10. Configure Unicode-characters for different OSs

    main

    The Unicode collection allows typing international characters without changing the OS keyboard layout. Note: These helpers are deprecated in favor of the zmk-unicode module.

    To use them, source helper.h and the desired language file (e.g., german.dtsi). Configuration depends on your OS:

    Windows

    Install WinCompose on your computer.

    Linux

    Set HOST_OS to 1 before sourcing the headers.

    macOS

    Enable Unicode Hex Input in System Preferences. Set HOST_OS to 2 before sourcing the headers.

    Custom Method

    Define OS_UNICODE_LEAD and OS_UNICODE_TRAIL before sourcing the headers to specify your own sequence initialization and termination.

    // Linux Example
#define HOST_OS 1
#include "zmk-helpers/helper.h"
#include "zmk-helpers/unicode-chars/german.dtsi"

// macOS Example
#define HOST_OS 2
#include "zmk-helpers/helper.h"
#include "zmk-helpers/unicode-chars/german.dtsi"

// Custom Sequence Example
#define OS_UNICODE_LEAD &macro_press &kp LCTRL &kp LSHFT &macro_tap &kp U
#define OS_UNICODE_TRAIL &macro_tap &kp SPACE &macro_release &kp LCTRL &kp LSHFT
#include "zmk-helpers/helper.h"
#include "zmk-helpers/unicode-chars/german.dtsi"

  11. Use ZMK-Helpers in your keymap

    main

    To use the helpers, source helper.h at the top of your .keymap file. You can also optionally source key-labels and unicode-character collections as needed.

    Important Note on ZMK_MACRO: By default, sourcing helper.h replaces the native ZMK implementation of ZMK_MACRO. To ensure reliable behavior, include helper.h after behaviors.dtsi. If you wish to keep the native ZMK_MACRO implementation, define ZMK_HELPER_KEEP_NATIVE 1 before including helper.h.

    #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"

  12. Migrate from ZMK-Helpers v1 to v2

    main

    To upgrade from version 1 to version 2, follow these steps:

    1. Cleanup: Remove the old zmk-nodefree-config folder from your zmk-config directory.
    2. Installation: Add the new Zephyr Module (recommended) or manually copy include/zmk-helpers into zmk-config/config/.
    3. Update Include Paths: Update your C include statements to reflect the new directory structure:
      • Replace the root path ../zmk-nodefree-config/ with zmk-helpers/.
      • Replace the sub-path keypos_def/ with key-labels/.
      • Replace the sub-path international_chars/ with unicode-chars/.
      • Rename key-position headers as needed (e.g., keypos_34keys.h becomes 34.h).
    4. Update Unicode Prefixes: For Danish unicode characters, change the prefix from dk_ to the ISO language code da_.
    5. Update Conditional Layers: Add an identifier string to ZMK_CONDITIONAL_LAYER to match the new syntax.
    6. Optional: Replace ZMK_BEHAVIOR with explicit behavior helpers.
    // old:
#include "../zmk-nodefree-config/helper.h"
#include "../zmk-nodefree-config/keypos_def/keypos_34keys.h"
#include "../zmk-nodefree-config/international_chars/german.dtsi"

// new:
#include "zmk-helpers/helper.h"
#include "zmk-helpers/key-labels/34.h"
#include "zmk-helpers/unicode-chars/german.dtsi"