Introduction

As I mentioned in my previous article, I purchased Planck EZ Glow keyboard. The feature that makes this keyboard extremely powerful, is the fact that it is powered with Quantum Mechanical Keyboard: an open-source firmware. As a result, one can easily customize not only the keymap but also any behavior of the keyboard. However, to fully utilize the potential of the keyboard, one needs to be able to flash the compiled binary to the device. QMK provides a set of utilities that make this process seamless. Also, ZSA Technology Labs, the manufacturer of Planck EZ, provides its own utility to flash its products: Wally.

Unfortunately, none of the above software is officially supported on OpenBSD. However, both QMK firmware and Wally are open-source. Furthermore, QMK scripts are just thin wrappers around other utilities used to program the microcontrollers powering the keyboards. Furthermore, QMK provides a Docker image with all the tools required to compile the firmware. Since I have already configured Docker runtime on OpenBSD, it was a no-brainer for me to use this approach to quickly get to flashing my new keyboard without the process of configuring required tools. The other part of the process is dfu-util to send the compiled binary to the bootloader. This utility can program the STM32F303 microcontroller, which is the heart of the Planck EZ.

The tutorial

Prerequisites

This tutorial is based on the Docker runtime for OpenBSD as described here. Secondly, the dfu-util package should be installed:

# pkg_add dfu-util

Finally, I strongly encourage you to use git to manage your keymap and download the repository with the base of the firmware.

Preparation of the firmware

To compile the firmware binary, a copy of the QMK firmware must be acquired. ZSA suggests using their fork for their boards, as this is the version that their online configurator Oryx uses underneath. I used git to obtain a copy of this repository in my workspace/personal directory:

$ git clone https://github.com/zsa/qmk_firmware.git

In the subdirectory for your keyboard, create a directory to hold your layout:

$ cd qmk_firmware/keyboards/planck/ez/glow/keymaps
$ mkdir struchu

Then, I downloaded the default layout for Planck EZ from the Oryx configurator as a source code package. Finally, initialize a git repository inside my keymap folder:

$ cd struchu
$ git init

As a result, you will be able to track changes in your keyboard layout and store them securely in a remote repository. Mine layout is available here.

Compiling the firmware

When the firmware is ready to be compiled, connect to the Docker virtual machine and navigate to the mounted directory that holds the repository for the QMK firmware. Then, start an interactive session with Docker image provided by QMK:

alpine $ docker run --rm -it -v $(pwd):/app -w /app qmkfm/base_container bash

Then, inside the container issue the make command to build a firmware from your configuration. The target name consists of the path to the root directory of the keyboard (in my case planck/ez/glow) and the name of the directory that holds my specific keymap (struchu), joined with a colon:

docker # make planck/ez/glow:struchu

If no errors are found, the compiled binary will be placed inside the .build directory, in the qmk_firmware. The name of the interesting file will contain the name of the keyboard and the name of the keymap. In my case, it would be: planck_ez_glow_struchu.bin. This is the file that should be flashed to the board.

Alternative: configure the layout with Oryx

The Oryx configurator from ZSA allows for the graphical configuration of the keymap. When the layout is ready, you can compile it online and download the resulting .bin file to be flashed to the board. Also, when you create an account with Oryx, you can store your layouts and track their revisions. If you decide to use this approach, you can simply proceed with the downloaded binary.

Flashing the firmware

When the binary file is ready, press the keyboard’s reset button to activate the bootloader flashing mode. When the keyboard is in this mode, you will be unable to use it. Thus, have some other keyboard at hand to issue the remaining commands. To check if the bootloader is detected correctly by the system, issue the following command to list all available bootloaders:

# dfu-util -L

If the keyboard is detected properly, you will see lines starting with Found DFU, followed by the identifiers of found devices. Then, to flash the keyboard, issue the following command, replace the path to the compiled binary with your own path:

# dfu-util -d 0483:DF11 \
    -a 0 -s 0x08000000:leave \
    -D .build/planck_ez_glow_struchu.bin

The flashing should take a couple of seconds. When the process is complete, the keyboard will reboot and you will be able to enjoy your new layout.

Conclusion

The process of flashing custom firmware might seem daunting at first. The lack of official support for OpenBSD might be deterring. However, it boils down to several easy steps. What is more, all the required tools are easily available and easy to use. So don’t think anymore, go get a QMK supported keyboard and flash it as soon as you get your hands on it.

After a couple of days spent with the Planck, I know one thing: it’s worth it. This board is absolutely fantastic. I will share my thoughts and opinions about this keyboard in a separate article soon.