Skip to main content

Basic Setup

Prerequisites​

ZMK requires the following base packages to first be installed:

  • Git
  • Python 3
  • pip
  • wget
  • devicetree compiler
  • CMake
  • dfu-util
  • Various build essentials, e.g. gcc, automake, autoconf

On Debian and Ubuntu, we'll use apt to install our base dependencies:

First, if you haven't updated recently, or if this is a new install, you should update to get the latest package information:

sudo apt update

With the latest package information, you can now install the base dependencies:

sudo apt install -y \
    git \
    wget \
    autoconf \
    automake \
    build-essential \
    bzip2 \
    ccache \
    device-tree-compiler \
    dfu-util \
    g++ \
    gcc \
    libtool \
    make \
    ninja-build \
    cmake \
    python3-dev \
    python3-pip \
    python3-setuptools \
    xz-utils
note

Recent LTS releases of Debian and Ubuntu may include outdated CMake versions. If the output of cmake --version is older than 3.20, upgrade your distribution (e.g., from Ubuntu 20.04 LTS to Ubuntu 22.04 LTS), or else install CMake version 3.20 or newer manually (e.g, from Debian backports or from PyPI with pip install --user cmake).

Setup​

West Installation​

west is the Zephyr™ meta-tool used to configure and build Zephyr™ applications.

West can be installed by using the pip python package manager. The Zephyr™ instructions are summarized here:

pip3 install --user -U west
pip user packages

If you haven't done so yet, you may need to add the Python pip package directory to your PATH otherwise your computer will not be able to find the west command.

Run the following commands:
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc

Toolchain Installation​

The toolchain provides the compiler, linker, etc., necessary to build for the target platform.

Zephyr™ ARM SDK​

To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system:

export ZSDK_VERSION=0.13.2
wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-linux-x86_64-setup.run" && \
    sh "zephyr-toolchain-arm-${ZSDK_VERSION}-linux-x86_64-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \
    rm "zephyr-toolchain-arm-${ZSDK_VERSION}-linux-x86_64-setup.run"

The installation will prompt with several questions about installation location, and creating a default ~/.zephyrrc for you with various variables. The defaults should normally work as expected.

note

If you intend to build firmware straight away, make sure to correctly setup the current shell.

Notes on setting this up can be found in the Environment Variables section. The transient instructions can be used to setup the current shell, and the automatic instructions can setup any newly made shells automatically.

The transient instructions must be run to build firmware using the current shell.

Source Code​

Next, you'll need to clone the ZMK source repository if you haven't already. Navigate to the folder you would like to place your zmk directory in and run the following command:

git clone https://github.com/zmkfirmware/zmk.git

Initialize & Update Zephyr Workspace​

Since ZMK is built as a Zephyr™ application, the next step is to use west to initialize and update your workspace. The ZMK Zephyr™ application is in the app/ source directory:

Step into the repository​

cd zmk

Initialize West​

west init -l app/
Command Not Found?

If you encounter errors like command not found: west then your PATH environment variable is likely missing the Python 3 user packages directory. See the West Build Command section again for links to how to do this

Update To Fetch Modules​

west update
tip

This step pulls down quite a bit of tooling. Go grab a cup of coffee, it can take 10-15 minutes even on a good internet connection!

info

If you're using Docker, you're done with setup! You must restart the container at this point. The easiest way to do so is to close the VS Code window, verify that the container has stopped in Docker Dashboard, and reopen the container with VS Code.

Once your container is restarted, proceed to Building and Flashing.

Export Zephyr™ Core​

west zephyr-export

Install Zephyr Python Dependencies​

pip3 install --user -r zephyr/scripts/requirements-base.txt

Environment Variables​

For GNU ARM Embedded on Windows​

On Windows, only two environment variables need to be set for ZMK to build properly: ZEPHYR_TOOLCHAIN_VARIANT and GNUARMEMB_TOOLCHAIN_PATH.

  1. Open Start Menu and type 'env' to find the 'Edit the system environment variables' option. Open it.

Environment variables in Start Menu

  1. Click 'Environment Variables...'.

Environment variables button

  1. Click "New..." under System variables to create a new system variable.

Environment variables menu

  1. Set the variable name to 'ZEPHYR_TOOLCHAIN_VARIANT' and value to 'gnuarmemb'. Click OK to save.

Adding Zephyr toolchain variable

  1. Create another variable with variable name 'GNUARMEMB_TOOLCHAIN_PATH' and value set to wherever you installed your toolchain. Make sure this path does not contain any spaces. If it does, rename the folder and update here. Click OK to save.

Adding GNUARMEMB variable

  1. Close Command Prompt and reopen, or run refreshenv to apply the changes.