/zmk-config

my personal zmk config

Primary LanguageShell

PM ZMK Sofle choc v2

Modifying the keymap

The ZMK documentation covers both basic and advanced functionality and has a table of OS compatibility for keycodes. Please note that the RGB Underglow, Backlight and Power Management sections are not relevant to the Advantage 360 Pro's custom ZMK fork. For more information see this note

There is a web based GUI available for editing the keymap. It is available at https://kinesiscorporation.github.io/Adv360-Pro-GUI. This repository is also compatible with certain other web based ZMK keymap editors however they may have keycodes or behaviours that are not implemented on the 360 Pro and could cause unusual behaviour or build failures. Furthermore changes made on other keymap editors may not be compatible if one goes back to using the Kinesis GUI.

Certain ZMK features (e.g. combos) require knowing the exact key positions in the matrix. They can be found in both image and text format here

Building the Firmware in a local container

Setup

Software

  • Either Podman or Docker is required, Podman is chosen if both are installed.
  • Make is also required

Windows specific

  • If compiling on Windows use WSL2 and Docker Docker Setup Guide.
  • Install make using sudo apt-get install make inside the WSL2 instance.
  • The repository can be cloned directly into the WSL2 instance or accessed through the C: mount point WSL provides by default (/mnt/c/path-to-repo).

macOS specific

On macOS brew can be used to install the required components.

  • docker
  • colima can be used as the docker engine
brew install docker colima
colima start

Note: On Apple Silicon (ARM based) systems you need to make sure to start colima with the correct architecture for the container being used.

colima start --arch x86_64

Ubuntu/Debian specific

sudo apt-get install docker make

Building the firmware

  1. Execute make to build firmware for both halves or make left to only build firmware for the left hand side.
  2. Check the firmware directory for the latest firmware build. The first part of the filename is the timestamp when the firmware was built.

Cleanup

The built docker container and compiled firmware files can be deleted with make clean. This might be necessary if you updated your fork from V2.0 to V3.0 and are encountering build failures.

Creating the docker container takes some time. Therefore make clean_firmware can be used to only clean firmware without removing the docker container. Similarly make clean_image can be used to remove the docker container without removing compiled firmware files.

Flashing firmware

Follow the programming instruction on page 8 of the Quick Start Guide to flash the firmware.

Overview

  1. Extract the firmwares from the archive downloaded from the GitHub build job (If using the cloud builder) or the firmware folder (If building locally).
  2. Connect the left side keyboard to USB.
  3. Press Mod+macro1 to put the left side into bootloader mode; it should attach to your computer as a USB drive.
  4. Copy left.uf2 to the USB drive and it will disconnect.
  5. Power off both keyboards (by unplugging them and making sure the switches are off).
  6. Turn on the left side keyboard with the switch.
  7. Connect the right side keyboard to USB to power it on.
  8. Press Mod+macro3 to put the right side into bootloader mode to attach it as a USB drive.
  9. Copy right.uf2 to the mounted drive.
  10. Unplug the right side keyboard and turn it back on.
  11. Enjoy!

Note: There are also physical reset buttons on both keyboards which can be used to enter and exit the bootloader mode. Their location is described in section 2.7 on page 9 in the User Manual and use is described in section 5.9 on page 14.

Note: Some operating systems wont always treat the drive as ejected after the settings-reset file is flashed or may throw a spurious error, this doesn't mean that the flashing process has failed.

Versioning

It will automatically record the compilation date, branch and Git commit hash in a macro that can be accessed with Mod+V. This will type out the following string: YYYYMMDD-XXXX-YYYYYY, where XXXX is the first 4 characters of the Git branch and YYYYYY is the Git commit hash. In addition to this the builds compiled by GitHub actions are now timestamped and also record the commit hash in the filename.