willem's zmk-config

This is my personal ZMK firmware configuration, based in decent amounts on the works of urob, kdb424, and klardotsh. It powers my "smol boards" like Sam Mohr's Osprette.

Layout Image

Created with keyboard-layout-editor.com, see my layout here. Slightly modified copy of urob's.

Setup

Pre-requisites

Install the nix package manager:

# Install Nix with flake support enabled
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix |
   sh -s -- install --no-confirm

# Start the nix daemon without restarting the shell
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh

Install direnv (and optionally but recommended nix-direnv[^5]) using your package manager of choice. E.g., using the nix package manager that we just installed[^6]:
```
nix profile install nixpkgs#direnv nixpkgs#nix-direnv
```

Set up the direnv shell-hook for your shell. E.g., for bash:

# Install the shell-hook
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

# Enable nix-direnv (if installed in the previous step)
mkdir -p ~/.config/direnv
echo 'source $HOME/.nix-profile/share/nix-direnv/direnvrc' >> ~/.config/direnv/direnvrc

# Optional: make direnv less verbose
echo '[global]\nwarn_timeout = "2m"\nhide_env_diff = true' >> ~/.config/direnv/direnv.toml

# Source the bashrc to activate the hook (or start a new shell)
source ~/.bashrc

Set up the workspace

Clone your fork of this repository. I like to name my local clone zmk-workspace as it will be the toplevel of the development environment.
```
# Replace `urob` with your username
git clone https://github.com/urob/zmk-config zmk-workspace
```

Enter the workspace and set up the environment.

# The first time you enter the workspace, you will be prompted to allow direnv
cd zmk-workspace

# Allow direnv for the workspace, which will set up the environment
direnv allow

# Initialize the Zephyr workspace and pull in the ZMK dependencies
# (same as `west init -l config && west update && west zephyr-export`)
just init

Usage

After following the steps above your workspace should look like this:

zmk-workspace
├── config
├── firmware (created after building)
├── modules
│   ├── auto-layer
│   ├── helpers
│   └── tri-state
└── zmk
    └── ...

Building the firmware

To build the firmware, simply type just build all from anywhere within the workspace. This will parse build.yaml and build the firmware for all board and shield combinations listed there.

To only build the firmware for a specific target, use just build <target>. This will build the firmware for all matching board and shield combinations. For instance, to build the firmware for my Corneish Zen, I can type just build zen, which builds both corneish_zen_v2_left and corneish_zen_v2_right. (just list shows all valid build targets.)

Additional arguments to just build are passed on to west. For instance, a pristine build can be triggered with just build all -p.

(For this particular example, there is also a just clean recipe, which clears the build cache. To list all available recipes, type just. Bonus tip: just provides completion scripts for many shells.)

Drawing the keymap

The build environment packages keymap-drawer. just draw parses base.keymap and draws it to draw/base.svg. I haven't gotten around to tweaking the output yet, so for now this is just a demonstration of how to set things up.

Hacking the firmware

To make changes to the ZMK source or any of the modules, simply edit the files or use git to pull in changes.

To switch to any remote branches or tags, use git fetch inside a module directory to make the remote refs locally available. Then switch to the desired branch with git checkout <branch> as usual. You may also want to register additional remotes to work with or consider making them the default in config/west.yml.

Updating the build environment

To update the ZMK dependencies, use just update. This will pull in the latest version of ZMK and all modules specified in config/west.yml. Make sure to commit and push all local changes you have made to ZMK and the modules before running this command, as this will overwrite them.

To upgrade the Zephyr SDK and Python build dependencies, use just upgrade-sdk.

willemml/zmk-config