zmk/docs/docs/user-setup.md

id	title	sidebar_label
user-setup	Installing ZMK	Installing ZMK

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Unlike other keyboard firmwares, ZMK Firmware has been built from the ground up to allow users to manage their own keyboard configurations, including keymaps, specific hardware details, etc. all outside of the core ZMK Firmware source repository.

In addition to this, most users do not need to install any complicated toolchains or tools to build ZMK, instead using GitHub Actions to automatically build the user's configured firmware for them.

Summary

The following steps can be taken to obtain an installable firmware image for your device, without the need to install any compiler or specialized toolchain. This is possible by leveraging GitHub Actions to build your firmware for you in the cloud, which you can then download and flash to your device.

Following the steps in this guide, you will:

1. Create a new repository in GitHub that will contain your user config.
2. Download and run a small shell script that will automate most of the setup. The script will:
   1. Prompt you for which board (e.g. nice!nano) and shield (e.g. Lily58 or Kyria) you want to create a configuration for.
   2. Prompt you for your GitHub username and repo where the config should be pushed.
   3. Use git to clone a template repository that will be the basis for your user's config repository.
   4. Use the given board and shield to update the included GitHub Action to build for the correct hardware.
   5. Commit the initial version.
   6. (If info was provided) Push the local repo to your GitHub repository.
3. Add your own keymap overlay (keymap.overlay) file to the repository, and change your keymap.
4. Update the configuration flags for your user config, to enable/disable any ZMK features you would like to include.
5. Commit and push the updates to trigger a new GitHub Action run.

Prerequisites

The remainder of this guide assumes the following prerequisites:

1. You have an active, working GitHub account.
2. You have installed and configured the git version control tool.

:::note If you need to, a quick read of Learn The Basics Of Git In Under 10 Minutes will help you get started. :::

GitHub Repo

Before running the setup script, you will first need to create a new GitHub repository to host the config.

1. Navigate to https://github.com/new
2. When prompted for the repo name, enter zmk-config.
3. The repository can be public or private
4. Do not check any of the options to initialize the repository with a README or other files.
5. Click "Create repository"

User Config Setup Script

To start the setup process, run the following from your command line prompt:

<Tabs defaultValue="curl" values={[ {label: 'Using curl', value: 'curl'}, {label: 'Using wget', value: 'wget'}, ]}>

bash -c "$(curl -fsSL https://zmkfirmware.dev/setup.sh)"

bash -c "$(wget https://zmkfirmware.dev/setup.sh -O -)"

MCU Board Selection

When prompted, enter the number for the corresponding MCU board you would like to target:

MCU Board Selection:
1) nice!nano
2) QMK Proton-C
3) Quit
Pick an MCU board:

Keyboard Shield Selection

When prompted, enter the number for the corresponding keyboard shield you would like to target:

Keyboard Shield Selection:
1) Kyria
2) Lily58
3) Quit
Pick an keyboard:

Keymap Customization

At the next prompt, you have an opportunity to decide if you want the stock keymap file copied in for further customization:

Copy in the stock keymap for customization? [Yn]:

Hit Enter or type yes/y to accept this. If you want to keep the stock keymap, or write a keymap from scratch, type in no/n.

GitHub Details

In order to have your new configuration automatically pushed, and then built using GitHub Actions, enter some information about your particular GitHub info:

GitHub Username (leave empty to skip GitHub repo creation): petejohanson
GitHub Repo Name: zmk-config
GitHub Repo: https://github.com/petejohanson/zmk-config.git

Only the GitHub username is required; if you are happy with the defaults offered in the square brackets, you can simply hit Enter.

Confirming Selections

The setup script will confirm all of your selections one last time, before performing the setup:

Preparing a user config for:
* MCU Board: nice_nano
* Shield: kyria
* GitHub Repo To Push (please create this in GH first!): https://github.com/petejohanson/zmk-config.git

Continue? [Yn]:

After hitting Enter or typing y, the script will create an initial config in a directory named after the repo name, update the GitHub Action YAML file, commit the initial version, and then push to your repo.

:::info

If you used the default GitHub repo URL using the https:// scheme, you may be prompted for your username + password in order to push the initial commit.

:::

Installing The Firmware

Download The Archive

Once the setup script is complete and the new user config repository has been pushed, GitHub will automatically run the action to build your keyboard firmware files. You can view the actions by clicking on the "Actions" tab on your GitHub repository.

Once you have loaded the Actions tab, select the top build from the list. Once you load it, the right side panel will include a link to download the firmware upload:

Once downloaded, extract the zip and you can verify it should contain one or more uf2 files, which will be copied to your keyboard.

Installing UF2 Files

To flash the firmware, first put your board into bootloader mode by double clicking the reset button (either on the MCU board itself, or the one that is part of your keyboard). The controller should appear in your OS as a new USB storage device.

Once this happens, copy the correct UF2 file (e.g. left or right if working on a split), and paste it onto the root of that USB mass storage device. Once the flash is complete, the controller should automatically restart, and load your newfly flashed firmware.

Customization

Configuration Changes

The setup script creates a config/<shield>.conf file that allows you to add additional configuration options to control what features and options are built into your firmware. Opening that file with your text editor you should see various config settings that can be commented/uncommented to modify how your firmware is built.

Keymap

Once you have the basic user config completed, you can find the file in config/<shield>.keymap and customize from there. Refer to the Keymap documentation to learn more.

Publishing

After making any changes you want, you should commit the changes and then push them to GitHub. That will trigger a new GitHub Actions job to build your firmware which you can download once it completes.

:::note If you need to, a review of Learn The Basics Of Git In Under 10 Minutes will help you get these steps right. :::