{"id":19491206,"url":"https://github.com/urob/zmk-helpers","last_synced_at":"2025-05-15T23:02:52.493Z","repository":{"id":45695383,"uuid":"513259787","full_name":"urob/zmk-helpers","owner":"urob","description":"Convenience macros simplifying ZMK's keymap configuration","archived":false,"fork":false,"pushed_at":"2025-05-06T22:22:09.000Z","size":411,"stargazers_count":324,"open_issues_count":6,"forks_count":103,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-05-15T23:01:56.080Z","etag":null,"topics":["zmk","zmk-config","zmk-module"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urob.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-07-12T18:57:39.000Z","updated_at":"2025-05-02T16:34:22.000Z","dependencies_parsed_at":"2024-10-23T06:47:10.744Z","dependency_job_id":"c45c84c4-d1eb-47bc-9f8a-ab2abfce0535","html_url":"https://github.com/urob/zmk-helpers","commit_stats":{"total_commits":115,"total_committers":28,"mean_commits":4.107142857142857,"dds":"0.26956521739130435","last_synced_commit":"230c7e18ee3c82325352287db29b59f53f20fa2a"},"previous_names":["urob/zmk-helpers"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urob%2Fzmk-helpers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urob%2Fzmk-helpers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urob%2Fzmk-helpers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urob%2Fzmk-helpers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urob","download_url":"https://codeload.github.com/urob/zmk-helpers/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254436943,"owners_count":22070946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["zmk","zmk-config","zmk-module"],"created_at":"2024-11-10T21:16:08.624Z","updated_at":"2025-05-15T23:02:52.406Z","avatar_url":"https://github.com/urob.png","language":"C","funding_links":[],"categories":["Community firmware Modules and Behaviors"],"sub_categories":["Custom Behaviors"],"readme":"# ZMK-Helpers (Version 2)\n\nThis is a collection of helper macros (formerly `zmk-nodefree-config`), simplifying the\nconfiguration of ZMK keymaps. The [migration guide](docs/migration-to-v2.md) has instructions on how\nto migrate from v1. Version 1 continuous to be available\n[here](https://github.com/urob/zmk-helpers/tree/v1).\n\n## Installation\n\nTo use the helpers, it is recommended to add them as a module to your `config/west.yml` by adding a\nnew entry to `remotes` and `projects`:\n\n```yaml\nmanifest:\n  remotes:\n    - name: zmkfirmware\n      url-base: https://github.com/zmkfirmware\n    - name: urob\n      url-base: https://github.com/urob\n  projects:\n    - name: zmk\n      remote: zmkfirmware\n      revision: main\n      import: app/west.yml\n    - name: zmk-helpers\n      remote: urob\n      revision: main\n  self:\n    path: config\n```\n\nIf you are building locally, see the instructions for\n[building with external modules](https://zmk.dev/docs/development/build-flash#building-with-external-modules)\nin ZMK docs.\n\n\u003cdetails\u003e\u003csummary\u003eManual installation\u003c/summary\u003e\n\nAlternatively, copy `include/zmk-helpers` into your `config/` directory:\n\n```\nzmk-config\n├── config\n│   ├── corne.keymap\n│   ├── zmk-helpers\n│   │   ├── helper.h\n│   │   └── ...\n│   └── ...\n└── ...\n```\n\nInstead of copying, one could also add a `git-submodule`[^1]:\n\n```sh\ncd /path/to/zmk-config/\ngit submodule add -b v2 -- https://github.com/urob/zmk-helpers config/zmk-helpers-repo\nln -s zmk-helpers-repo/include/zmk-helpers config/zmk-helpers\n```\n\n\u003c/details\u003e\n\n## Usage\n\nSource `helper.h` near the top of your `.keymap` file. Optionally, source `key-labels` and\n`unicode-chars` as needed:\n\n```C++\n#include \"zmk-helpers/helper.h\"\n\n// Source desired key-position labels\n#include \"zmk-helpers/key-labels/glove80.h\"\n\n// Source unicode-chars for desired languages\n#include \"zmk-helpers/unicode-chars/german.dtsi\"\n```\n\nThe following subsections describe the available helpers. See the\n[example configuration](examples/zmk-config/config/cradio.keymap) or my\n[personal zmk-config](https://github.com/urob/zmk-config/blob/main/config/base.keymap) for a\ndemonstration.\n\n### Core helpers\n\nThe `helper.h` header provides a number of convenience macros for defining behaviors, combos,\nlayers, etc.\n\n| Macro                          | Purpose                                            |\n| ------------------------------ | -------------------------------------------------- |\n| [`ZMK_BEHAVIOR`]               | Create a new behavior instance (generic form)      |\n| [`ZMK_APPLY_MATRIX_TRANSFORM`] | Apply a `matrix_transform`                         |\n| [`ZMK_COMBO`]                  | Create a combo                                     |\n| [`ZMK_CONDITIONAl_LAYER`]      | Create a `tri-layer` condition                     |\n| [`ZMK_LAYER`]                  | Create a layer and add it to the keymap            |\n| [`ZMK_LEADER_SEQUENCE`]        | Create a leader key sequence (*)                   |\n| [`ZMK_UNICODE_SINGLE`]         | Create a unicode-char                              |\n| [`ZMK_UNICODE_PAIR`]           | Create a pair of lowercase/uppercase unicode-chars |\n\nIn addition to the generic `ZMK_BEHAVIOR` macro, there are also explicit variants for the following\nbehaviors.\n\n| Macro                   | Purpose                                                       |\n| ----------------------- | ------------------------------------------------------------- |\n| [`ZMK_AUTO_LAYER`]      | Create a new `auto-layer` behavior instance (*)               |\n| [`ZMK_CAPS_WORD`]       | Create a new `caps-word` behavior instance                    |\n| [`ZMK_HOLD_TAP`]        | Create a new `hold-tap` behavior instance                     |\n| [`ZMK_KEY_REPEAT`]      | Create a new `key-repeat` behavior instance                   |\n| [`ZMK_MACRO`]           | Create a new `key-macro` behavior instance                    |\n| [`ZMK_MACRO_ONE_PARAM`] | Create a new `macro-one-param` behavior instance              |\n| [`ZMK_MACRO_TWO_PARAM`] | Create a new `macro-two-param` behavior instance              |\n| [`ZMK_MOD_MORPH`]       | Create a new `mod-morph` behavior instance                    |\n| [`ZMK_STICKY_KEY`]      | Create a new `sticky-key` behavior instance                   |\n| [`ZMK_TAP_DANCE`]       | Create a new `tap-dance` behavior instance                    |\n| [`ZMK_TRI_STATE`]       | Create a new `tri-state` behavior instance (*)                |\n\n(*) Marked behaviors are implemented as modules and aren't part of ZMK core.\n\nThe explicit behavior helpers are inspired by the native ZMK implementation of `ZMK_MACRO`. They\ndiffer in that they automatically create all Devicetree nodes as needed. So instead of calling them\nfrom inside the Devicetree, they should be placed outside the root node.\n\n\u003e [!NOTE]\n\u003e\n\u003e By default, sourcing `helper.h` will replace the native implementation of `ZMK_MACRO`. To work\n\u003e reliably, `helper.h` should be included _after_ `behaviors.dtsi`. To keep the native\n\u003e implementation of `ZMK_MACRO`, set `#define ZMK_HELPER_KEEP_NATIVE 1` before including `helper.h`.\n\n### Key-labels collection\n\nThese layout headers define _easy to remember_ \"key-labels\" for many popular keyboards, which can be\nused instead of numeric key-positions to configure position-based properties (e.g., in combos).\n\nKey-labels are _standardized_ to make keymaps portable across keyboards. For instance, the labels\nfor the 60-key _Sofle_ nest the labels for the 34-key _Sweep_ as follows:\n\n![plot](docs/img/key_labels_example.png)\n\nThe following layouts are currently implemented.\n\n| Header                  | \\# of Keys       | Examples                                   |\n| ----------------------- | ---------------- | ------------------------------------------ |\n| `34.h`                  | 34               | Ferris, Hypergolic, Sweep                  |\n| `36.h`                  | 36               | Corne (5 cols), Corne-ish Zen (5 cols)     |\n| `42.h`                  | 42               | Corne, Corne-ish Zen                       |\n| `eyelash42.h`           | 42+              | Eyelash Corne with Joystick \u0026 Encoder      |\n| `4x12.h`, `4x12_wide.h` | 48               | Planck                                     |\n| `5x6.h`                 | 60               | Caldera                                    |\n| `adv360.h`              | 76               | Kinesis Advantage360 Pro                   |\n| `glove80.h`             | 80               | Glove80                                    |\n| `hillside_*.h`          | 46, 48, 52 or 56 | Hillside family                            |\n| `jian.h`                | 44               | Jian, Jorne                                |\n| `kyria.h`               | 50               | Kyria                                      |\n| `lily58.h`              | 58               | Lily58                                     |\n| `osprette.h`            | 34               | Osprette                                   |\n| `sofle.h`               | 60               | Sofle                                      |\n| `totem.h`               | 38               | Totem                                      |\n\n### Unicode-characters and language collection\n\nThis collection defines unicode behaviors for all relevant characters in a given language. For\ninstance, sourcing the German language file, one can add `\u0026de_ae` to the keymap, which will send\n\u003ckbd\u003eä\u003c/kbd\u003e/\u003ckbd\u003eÄ\u003c/kbd\u003e when pressed or shifted.\n\nSee the [unicode-chars directory](include/zmk-helpers/unicode-chars/) for a list of all currently\navailable languages. To use these language files, follow the instructions for your OS below.\n\n\u003cdetails\u003e\u003csummary\u003eWindows\u003c/summary\u003e\n\nOn your computer, install [WinCompose](https://github.com/samhocevar/wincompose). In your keymap,\nsource `helper.h` and the desired language files. For example:\n\n```c\n#include \"zmk-helpers/helper.h\"\n#include \"zmk-helpers/unicode-chars/german.dtsi\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eLinux\u003c/summary\u003e\n\nIn your keymap, set `HOST_OS` to `1`, **_then_** source `helper.h` and the desired language files.\nFor example:\n\n```c\n#define HOST_OS 1\n#include \"zmk-helpers/helper.h\"\n#include \"zmk-helpers/unicode-chars/german.dtsi\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003emacOS\u003c/summary\u003e\n\nOn your computer, enable unicode input in the system preferences by selecting `Unicode Hex Input` as\ninput source. In your keymap, set `HOST_OS` to `2`, **_then_** source `helper.h` and the desired\nlanguage files. For example:\n\n```c\n#define HOST_OS 2\n#include \"zmk-helpers/helper.h\"\n#include \"zmk-helpers/unicode-chars/german.dtsi\"\n```\n\n\u003c/details\u003e\n\n\u003e [!NOTE]\n\u003e\n\u003e Unicodes allow typing international characters without changing the OS keyboard layout. See\n\u003e [zmk-locale-generator](https://github.com/joelspadin/zmk-locale-generator) for a collection of\n\u003e headers that configure ZMK to work with non-US layouts set in the OS.\n\n[^1]:\n    To enable the submodule when building with Github Actions, replace\n    `zmk-config/.github/workflows/build.yml` with\n\n    ```\n    on: [push, pull_request, workflow_dispatch]\n\n    jobs:\n      build:\n        uses: urob/zmk/.github/workflows/build-user-config.yml@build-with-submodules\n    ```\n\n## Contributing\n\nContributions of any form are very welcome! New `key-labels` and `unicode-chars` should follow these\nguidelines:\n\n- Key-position labels should stick to the [label conventions](docs/key_labels.md#standardization)\n  whenever applicable.\n- Language headers should namespace all characters using\n  [two-letter ISO language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).\n\n[#1366]: https://github.com/zmkfirmware/zmk/pull/1366\n[`ZMK_BEHAVIOR`]: docs/core_helpers.md#zmk_behavior\n[`ZMK_APPLY_MATRIX_TRANSFORM`]: docs/core_helpers.md#apply_matrix_transform\n[`ZMK_COMBO`]: docs/core_helpers.md#zmk_combo\n[`ZMK_CONDITIONAL_LAYER`]: docs/core_helpers.md#zmk_conditional_layer\n[`ZMK_LAYER`]: docs/core_helpers.md#zmk_layer\n[`ZMK_LEADER_SEQUENCE`]: docs/core_helpers.md#zmk_leader_sequence\n[`ZMK_UNICODE_SINGLE`]: docs/core_helpers.md#zmk_unicode\n[`ZMK_UNICODE_PAIR`]: docs/core_helpers.md#zmk_unicode\n[`ZMK_AUTO_LAYER`]: docs/core_helpers.md#zmk_behavior-(explicit-variants)\n[`ZMK_CAPS_WORD`]: docs/core_helpers.md#zmk_behavior-(explicit-variants)\n[`ZMK_HOLD_TAP`]: docs/core_helpers.md#zmk_behavior-(explicit-variants)\n[`ZMK_KEY_REPEAT`]: docs/core_helpers.md#zmk_behavior-(explicit-variants)\n[`ZMK_MACRO`]: docs/core_helpers.md#zmk_behavior-(explicit-variants)\n[`ZMK_MACRO_ONE_PARAM`]: docs/core_helpers.md#zmk_behavior-(explicit-variants)\n[`ZMK_MACRO_TWO_PARAM`]: docs/core_helpers.md#zmk_behavior-(explicit-variants)\n[`ZMK_MOD_MORPH`]: docs/core_helpers.md#zmk_behavior-(explicit-variants)\n[`ZMK_STICKY_KEY`]: docs/core_helpers.md#zmk_behavior-(explicit-variants)\n[`ZMK_TAP_DANCE`]: docs/core_helpers.md#zmk_behavior-(explicit-variants)\n[`ZMK_TRI_STATE`]: docs/core_helpers.md#zmk_behavior-(explicit-variants)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furob%2Fzmk-helpers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furob%2Fzmk-helpers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furob%2Fzmk-helpers/lists"}