ZMK Firmware

https://github.com/zmkfirmware/zmk
Admin
ZMK Firmware Repository
Tokens:245,158
Snippets:2,108
Trust Score:7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### ARM Compiler Path Example

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/ide-integration.mdx

An example of the full path to the ARM GCC compiler based on the SDK installation directory.

```text
/home/marvin/.local/zephyr-sdk-0.15.2/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
```

--------------------------------

### Example Toolchain Output

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/ide-integration.mdx

The expected output from the verify-toolchain command, showing the SDK installation directory.

```text
-- ZEPHYR_TOOLCHAIN_VARIANT: zephyr
-- SDK_VERSION: 0.15.2
-- ZEPHYR_SDK_INSTALL_DIR  : /home/marvin/.local/zephyr-sdk-0.15.2
```

--------------------------------

### Expected output from pre-commit install

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/pre-commit.md

Example output showing the hooks installed at .git/hooks/pre-commit and .git/hooks/commit-msg.

```text
pre-commit installed at .git/hooks/pre-commit
pre-commit installed at .git/hooks/commit-msg
```

--------------------------------

### Initialize a new ZMK config repo

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/user-setup.mdx

Run these commands in a terminal to move to a folder where you want to place the ZMK files and start the `zmk init` interactive setup. The command will create a new folder in the current location.

```sh
cd ~/Documents
zmk init
```

--------------------------------

### Install dependencies

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/README.md

Run this command to install the project dependencies using npm.

```sh
$ npm ci
```

--------------------------------

### Point ZMK CLI to an existing cloned repo

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/user-setup.mdx

Use this command if you already have a ZMK config repo cloned, for example from the old setup script. Replace `/path/to/zmk-config` with the actual path to the repo folder.

```sh
zmk config user.home "/path/to/zmk-config"
```

--------------------------------

### Install uv on Windows

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/user-setup.mdx

Install uv using winget. If the output includes the highlighted text, close and reopen your terminal.

```sh
winget install --id astral-sh.uv -e --source winget
```

--------------------------------

### Install West Globally on Windows

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/setup/native.mdx

Install west globally using pip.

```sh
pip install -U west
```

--------------------------------

### Install West Globally on Ubuntu

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/setup/native.mdx

Install west globally for the user.

```sh
pip3 install --user -U west
```

--------------------------------

### Install West

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/setup/native.mdx

Install the west tool via pip.

```sh
pip install west
```

--------------------------------

### Devicetree file example

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/config/index.md

Example of a Devicetree file showing the root node, a chosen node, and a kscan node with a compatible property.

```dts
/ {
    chosen {
        zmk,kscan = &kscan0;
    };

    kscan0: kscan {
        compatible = "zmk,kscan-gpio-matrix";
    };
};
```

--------------------------------

### Kconfig file example

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/config/index.md

Example of a Kconfig file used to configure global settings such as enabling sleep and EC11 support. Each line is a CONFIG_XYZ=value assignment.

```ini
CONFIG_ZMK_SLEEP=y
CONFIG_EC11=y
CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y
```

--------------------------------

### Install ZMK CLI with uv

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/user-setup.mdx

The primary command to install the ZMK CLI tool using uv.

```sh
uv tool install zmk
```

--------------------------------

### west.yml manifest example

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/module-creation.md

Example west.yml file for a module with dependencies, defining a remote and a project with an import field.

```yaml
manifest:
  remotes:
    - name: remote-name
      url-base: https://github.com/remote-name
  projects:
    # Together with the above defined remote, this refers to a module located at
    # https://github.com/remote-name/repository-name
    - name: repository-name
      remote: remote-name
      # This points to a west manifest file in the remote module for further imports
      import: west.yml
```

--------------------------------

### Example repository URL prompt during zmk init

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/user-setup.mdx

When prompted by `zmk init` to clone an existing repo, enter the repository URL. This example shows the prompt and a sample URL.

```text
Repository URL: https://github.com/myusername/zmk-config
```

--------------------------------

### Install ZMK Tools extension in github.dev

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/blog/2024-01-05-zmk-tools.md

Run this command in the VS Code command palette (Ctrl+P) to install the ZMK Tools extension in github.dev. This is part of the browser-based user config setup workflow.

```text
ext install spadin.zmk-tools
```

--------------------------------

### Example build.yaml for multiple shields

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/customization.md

This YAML example shows how to configure GitHub Actions to build firmware for multiple keyboards by appending entries to build.yaml in the zmk-config folder. It includes boards for Corne and Lily58 shields with nice!nano variants.

```yaml
include:
  - board: nice_nano@1//zmk
    shield: corne_left
  - board: nice_nano@1//zmk
    shield: corne_right
  - board: nice_nano//zmk
    shield: lily58_left
  - board: nice_nano//zmk
    shield: lily58_right
```

--------------------------------

### Check Dev Container CLI version

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/setup/container.mdx

Run this command to verify that the Dev Container CLI is installed before starting the container.

```sh
devcontainer --version
```

--------------------------------

### Start local development server

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/README.md

Starts a local development server and opens a browser window. Most changes are reflected live without requiring a server restart.

```sh
$ npm start
```

--------------------------------

### Settings Reset Shield in build.yaml for GitHub Actions

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/troubleshooting/connection-issues.mdx

Configuration for the 'build.yaml' file in a zmk-config folder that adds a settings_reset shield to build a reset firmware for a split keyboard. The example assumes the config repo is setup for nice!nano v2 with Corne, appending the settings_reset shield to the existing include list.

```yaml
include:
  - board: nice_nano//zmk
    shield: corne_left
  - board: nice_nano//zmk
    shield: corne_right
  - board: nice_nano//zmk
    shield: settings_reset

```

--------------------------------

### Install pre-commit with pip3

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/pre-commit.md

Installs pre-commit using pip3. Requires Python to be installed.

```bash
pip3 install pre-commit
```

--------------------------------

### Create and Activate Virtual Environment on Ubuntu

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/setup/native.mdx

Create a new virtual environment and activate it.

```sh
python3 -m venv .venv
source .venv/bin/activate
```

--------------------------------

### Install uv on Linux

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/user-setup.mdx

Install uv using curl. If curl is not found, try wget. If both fail, install curl and retry. After installation, you may need to restart your shell to update PATH.

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```sh
wget -qO- https://astral.sh/uv/install.sh | sh
```

```sh
sudo apt update
sudo apt install curl
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install uv on macOS

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/user-setup.mdx

Install uv using curl. If the install script prints the PATH message, close and reopen your terminal.

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Example pinctrl dtsi file for out-of-tree board (nice_nano)

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/blog/2023-04-06-zephyr-3-2.md

Complete pinctrl configuration file for a board, defining uart0 and i2c0 default and sleep states with NRF_PSEL and low-power-enable.

```dts
/*
* Copyright (c) 2022 The ZMK Contributors
* SPDX-License-Identifier: MIT
*/

&pinctrl {
        uart0_default: uart0_default {
                group1 {
                        psels = <NRF_PSEL(UART_RX, 0, 8)>;
                        bias-pull-up;
                };
                group2 {
                        psels = <NRF_PSEL(UART_TX, 0, 6)>;
                };
        };

        uart0_sleep: uart0_sleep {
                group1 {
                        psels = <NRF_PSEL(UART_RX, 0, 8)>,
                                <NRF_PSEL(UART_TX, 0, 6)>;
                        low-power-enable;
                };
        };

        i2c0_default: i2c0_default {
                group1 {
                        psels = <NRF_PSEL(TWIM_SDA, 0, 17)>,
                                <NRF_PSEL(TWIM_SCL, 0, 20)>;
                };
        };

        i2c0_sleep: i2c0_sleep {
                group1 {
                        psels = <NRF_PSEL(TWIM_SDA, 0, 17)>,
                                <NRF_PSEL(TWIM_SCL, 0, 20)>;
                        low-power-enable;
                };
        };
};
```

--------------------------------

### Verify West Installation

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/setup/native.mdx

Verify that west is installed and accessible in the PATH.

```sh
west --version
```

--------------------------------

### Configure build.yaml for ZMK Studio

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/features/studio.md

Add the studio-rpc-usb-uart snippet and enable the ZMK_STUDIO Kconfig setting in your build.yaml file. For split keyboards, apply these settings only to the central or left side.

```yaml
---
include:
  - board: nice_nano//zmk
    shield: corne_left
    snippet: studio-rpc-usb-uart
    cmake-args: -DCONFIG_ZMK_STUDIO=y
  - board: nice_nano//zmk
    shield: corne_right
```

--------------------------------

### Build ZMK Studio locally with west

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/features/studio.md

Use the -S parameter to include the studio-rpc-usb-uart snippet and pass the ZMK_STUDIO Kconfig as a CMake argument during a local build.

```bash
west build -d build/cl_studio -b nice_nano//zmk \
  -S studio-rpc-usb-uart -- -DSHIELD=corne_left -DCONFIG_ZMK_STUDIO=y
```

--------------------------------

### Configure RP2040 Core Hardware

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/blog/2025-12-09-zephyr-4-1.md

Add these nodes to your board's .dts file to properly initialize the timer, RTC, and voltage regulator.

```dts
&timer {
    status = "okay";
};

&rtc {
    clocks = <&clocks RPI_PICO_CLKID_CLK_RTC>;
    status = "okay";
};

&vreg {
    regulator-always-on;
    regulator-allowed-modes = <REGULATOR_RPI_PICO_MODE_NORMAL>;
};
```

--------------------------------

### Pristine build for new board/shield

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/build-flash.mdx

Use --pristine or -p to remove existing build directory files before regenerating. Example builds for nice_nano with kyria_left shield.

```sh
west build -p -b nice_nano//zmk -- -DSHIELD=kyria_left
```

--------------------------------

### Install Zephyr Dependencies

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/setup/native.mdx

Install additional Zephyr dependencies using west.

```sh
west packages pip --install
```

--------------------------------

### Enable USB Logging with west build

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/usb-logging.mdx

Use the -S or --snippet flag when building locally to enable USB logging.

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

--------------------------------

### Mod-Tap Configuration Example

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/keymaps/behaviors/hold-tap.mdx

Example of adjusting the tapping-term-ms property of the mod-tap behavior.

```dts
&mt {
    tapping-term-ms = <200>; // This is the value already set by default
};
```

--------------------------------

### Install West Globally on Mac OS

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/setup/native.mdx

Install west globally using pip3.

```sh
pip3 install -U west
```

--------------------------------

### Install Python venv on Ubuntu

Source: https://github.com/zmkfirmware/zmk/blob/main/docs/docs/development/local-toolchain/setup/native.mdx

Install the Python venv package using apt.

```sh
sudo apt install python3-venv
```
Tokens:
Raw