Adv360 Pro ZMK: building custom firmware for a split keyboard

A keymap repository, not a keyboard firmware project

The repository describes itself as the production repository for the all-new Advantage360 Professional using the ZMK engine, and it is named after the keyboard. So the scope is narrow by design. It is the authoritative source for how this particular keyboard is configured, and the README is written for someone who wants to modify that configuration.

The starting point is the ZMK documentation, which covers both basic and advanced functionality and includes a table of OS compatibility for keycodes. The README flags one important exclusion. The RGB Underglow, Backlight and Power Management sections of the ZMK documentation are not relevant to the Advantage360 Pro's custom ZMK fork, and there is a note in the README explaining why. Anyone who follows the upstream guides blindly will lose time on settings that do not apply to this hardware.

There are then two ways to work with the keymap, and the choice determines how much of the toolchain you keep.

If you would like to continue using GitHub, the README recommends Nick Coutsos's keymap editor, a browser based editor for ZMK keymaps. If you would prefer to leave GitHub and firmware flashing behind you, you can perform a one-time firmware update to gain access to Clique, with the upgrade path linked from the README. That is a meaningful fork in the road: the first path keeps you in control of the keymap, the second hands the configuration over to a graphical tool and removes the flashing step from your life.

The third thing to know is the keymap editor is not the only input. Certain ZMK features, combos for example, require knowing the exact key positions in the matrix, and those are recorded in both image and text format in assets/key-positions.md.

Two build paths, and the container is the same either way

The cloud build is almost trivial. You fork the repository, enable GitHub Actions on your fork, push a commit to trigger the build, and download the artifact. There is no build script for you to learn and no toolchain to install.

The local build is the same build in a container, and it needs more setup. Either Podman or Docker is required, and Podman is chosen if both are installed. Make is also required.

On macOS, brew can install the required components, docker and colima, and colima can serve as the docker engine.

brew install docker colima
colima start

There is an Apple Silicon caveat. On ARM based systems you need to make sure you start colima with the correct architecture for the container being used.

The README gives the exact command for that case, colima start with the x86_64 architecture flag.

That is not a formality. The container image used for the build is an ARM build of the ZMK build environment, and the keyboard ships as a split device, so the architecture of the container has to line up with what you are flashing.

On Ubuntu and Debian the two packages are all you need.

sudo apt-get install docker make

On Windows, compiling means using WSL2 with Docker, following the Docker setup guide, and installing make with `sudo apt-get install make` inside the WSL2 instance. The repository can be cloned directly into WSL2 or reached through the C: mount point WSL provides by default at /mnt/c/path-to-repo.

make builds both halves, and the artifacts are timestamped

The build itself is two targets. `make` builds firmware for both halves of the split keyboard, and `make left` builds only the left hand side. The output lands in the firmware directory, and the first part of the filename is the timestamp when the firmware was built.

That naming is not cosmetic. The README explains that starting on 11/15/2023 the Advantage360 Pro automatically records the compilation date, branch and Git commit hash in a macro that can be accessed with Mod+V, and that this types out the string YYYYMMDD-XXXX-YYYYYY, where XXXX is the first four characters of the Git branch and YYYYYY is the Git commit hash. Builds compiled by GitHub Actions are also timestamped and record the commit hash in the filename. So you can always tell which build is on a keyboard, which matters when a keymap change turns out to be the wrong one.

Cleanup is split for a reason. `make clean` deletes the built container and the compiled firmware files, and the README says this might be necessary if you updated your fork from V2.0 to V3.0 and are encountering build failures. If you only want to drop the firmware, `make clean_firmware` does that without removing the container, and if you only want to reclaim the container image, `make clean_image` does that without touching the compiled files.

The container itself is a single stage on top of the official ZMK build image.

FROM docker.io/zmkfirmware/zmk-build-arm:stable

WORKDIR /app

COPY config/west.yml config/west.yml

# West Init
RUN west init -l config
# West Update
RUN west update
# West Zephyr export
RUN west zephyr-export

West is the Zephyr build system manager, and the Dockerfile initialises the manifest from the repository's own config/west.yml, updates the modules, exports Zephyr and then runs the build script that was copied in.

Flashing means visiting the bootloader twice

The flashing procedure is a sequence of physical steps rather than a command, and the README points at page 8 of the Quick Start Guide for the programming instruction.

For the left side, connect the keyboard to USB, press Mod+macro1 to put it into bootloader mode, and it attaches to your computer as a USB drive. Copy left.uf2 to the drive and it disconnects. Then power off both keyboards by unplugging them and making sure the switches are off, turn on the left side with the switch, connect the right side to USB to power it on, press Mod+macro3 to put the right side into bootloader mode so it attaches as a USB drive, and copy right.uf2 to the mounted drive before unplugging it and turning it back on.

Two notes soften the sharp edges. There are physical reset buttons on both keyboards which can be used to enter and exit bootloader mode, and their location is described in section 2.7 on page 9 of the user manual. And some operating systems will not always treat the drive as ejected after the settings-reset file is flashed, or may throw a spurious error, which the README says does not mean the flashing process has failed.

That last note matters for the upgrade path as well. Moving from V2.0 based firmwares to V3.0 based firmwares is described as a rather complex process, with reset files for every major firmware revision and documentation on the update process published by the manufacturer. If you hit a git conflict while updating your repository to V3.0, the README points at UPGRADE.md for the resolution steps, and the repository carries a settings-reset.uf2 file at the top level.

Three defconfig switches you are likely to want

Most configuration changes for this keyboard happen in the board defconfig files, and the README calls out three that come up repeatedly.

The first is N-Key Rollover. By default the keyboard has NKRO enabled, but for compatibility reasons the higher ranges are not enabled. If you want to use F13 to F24 or the INTL1 to INTL9 keys with NKRO enabled, you change `CONFIG_ZMK_HID_KEYBOARD_EXTENDED_REPORT=n` to `CONFIG_ZMK_HID_KEYBOARD_EXTENDED_REPORT=y` in adv360_left_defconfig.

The second is battery reporting. Reporting the battery level over BLE is disabled by default, because the README says this can cause some computers to spontaneously wake up repeatedly. Enabling it means changing `CONFIG_BT_BAS=n` to `CONFIG_BT_BAS=y` in adv360_left_defconfig.

The third is the modifier indicator colour. The colour of the CAPS, NUM and SCROLL lock indicator LEDs may be set with a hexadecimal RGB code, and `CONFIG_ZMK_RGB_UNDERGLOW_MOD_COLOR=0xFF0000` would give red indicator colours. In order to set the indicator colour on both modules, both adv360_left_defconfig and adv360_right_defconfig have to be updated, which is the recurring theme here: the keyboard is two independent devices and every setting has to be applied twice.

The layer system has its own rule. A total of 32 layers are supported by ZMK, with the highest currently active layer displayed using the layer LEDs on each of the left and right modules. For the first 8 layers the same colour is displayed on both modules, and after that only the right module colour cycles through until it rolls over, at which point the left module colour changes as well and the pattern repeats.

Where a keymap fork stops being the right answer

The clearest case is a user who does not want to flash firmware at all. The README is direct that a one-time firmware update can grant access to Clique and remove the need for GitHub and firmware flashing. If your goal is to remap a few keys and never think about it again, a graphical configuration tool is a better fit than a fork, a build container and a .uf2 file.

The second case is anyone building a keyboard project from scratch. This repository is not a ZMK distribution and not a keymap library. The upstream ZMK project is the engine, and this repository is one board's configuration, its defconfig and its build plumbing, tuned to one piece of hardware. The value here is that it is the production configuration for a shipped product, but the value does not transfer to a different keyboard.

The third case is a fork that has drifted. The build is a Docker container around a stable tag of the ZMK ARM build image, and the repository does not pin that image to a digest or publish releases, so the tag is a moving point. Combined with a V2 to V3 transition that required reset files and an upgrade document, a fork that has not been rebuilt in a while can fail in ways that are annoying to diagnose, which is exactly why the README tells you to run make clean after a major branch update.

The licence is MIT, with the terms in the LICENSE file at the repository root, and there are no GitHub releases. Every build you flash is a build you made, which is the point.

Editorial conclusion

This repository suits an owner of an Advantage360 Professional who wants to change the keymap, the layer behaviour or the indicator colours, and who is prepared to flash firmware to both halves of the keyboard. It does not suit someone looking for a general purpose ZMK keymap library, and it does not suit a user who would rather not flash at all, since the README points to a one-time update that grants access to Clique and removes the need to touch GitHub or firmware flashing. Verify first which branch you are on, because the default branch is V3.0 and the V2 to V3 move has its own reset files and an upgrade document.

Frequently asked questions

Official sources

1. Issues
2. KinesisCorporation/Adv360-Pro-ZMK on GitHub
3. License: MIT
4. README