Quacken ZMK Module

A Zephyr module to build your own ZMK firmware for the Quacken.

Build With GitHub Actions (GHA)

This is the recommended method for most users.

In a Nutshell

• create a GitHub account if you don’t already have one
• fork this repository
• modify the keymaps/quacken.keymap file (see the customizing ZMK documentation)
• save, commit, push

Your firmware will now be built automatically by GitHub’s CI:

• check the Actions tab
• wait for the latest action task to complete
• click on this task
• download the zmk_quacken_{flex,zero}.uf2 artifact matching your keyboard model
• flash

Using github.com

TODO

Using GitHub-Desktop

TODO

Using zmk-cli

See https://zmk.dev/docs/user-setup.

Build Locally

Advanced users and developers may prefer to build their firmware locally, especially for debugging purposes.

Setup

We need a local ZMK clone with its Zephyr toolchain. This requires about 15GB of disk space: 10GB for the Zephyr SDK, 5GB for ZMK/Zephyr and their dependencies.

First install all host Zephyr dependencies — for Ubuntu it’d be:

sudo apt install --no-install-recommends \
  git cmake ninja-build gperf ccache dfu-util device-tree-compiler wget \
  python3-dev python3-pip python3-setuptools python3-tk python3-wheel \
  xz-utils file make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1

Make sure uv is installed, then proceed with ZMK:

# clone ZMK
git clone https://github.com/zmkfirmware/zmk.git
cd zmk

# activate a venv, install west + ZMK dependencies
uv init
uv add west
source .venv/bin/activate
west init -l app
west update  # this installs Zephyr and other ZMK stuff (takes a while)

# install Zephyr's dependencies and SDK
cd zephyr
uv pip install -r scripts/requirements-base.txt
west sdk install  # (this takes a while)

When done, symlink the ZMK folder in the local zmk-keyboard-quacken folder, so that the build script can use this ZMK/Zephyr setup:

cd /path/to/zmk-keyboard-quacken
ln -s /path/to/zmk .

Build

Once the ZMK/Zephyr toolchain is set, the Quacken firmware is built as follows:

./build {flex,zero} [optional_C++_flags]

• flex or zero relates to the Quacken variant in use
• optional_C++_flags enables keymap options defined in keymap/quacken.keymap

Examples:

# build the default Quacken Zero firmware
./build zero

# build the default Quacken Flex firmware
./build flex

# build a Quacken Flex firmware with thumb-taps instead of homerow-mods
./build flex -DHT_THUMB_TAPS

The firmware (zmk_quacken_{flex,zero}.uf2) can be found in the current directory and is ready to be flashed.

Debug

To enable USB logging, uncomment the USB_LOGGING line in the build script: after flashing, you can track the USB logs for every keypress on a serial monitor (e.g. /dev/ttyACM0 on Linux).

You may also comment out the PRISTINE line in the build script to enable incremental builds.

Note: local builds use the zmk tree, no matter what’s specified in the config/west.yml file (which is used by GitHub Actions). Remember to run a west update when modifying the zmk tree (e.g. checking out another branch/commit).

Flash

See https://zmk.dev/docs/user-setup#flash-uf2-files.