Kinesis is a company based near Seattle that offers computer keyboards with ergonomic designs as alternatives to the traditional keyboard design. Most widely known among these are the contoured Advantage line, which features recessed keys in two bucket-like hollows to allow the user’s fingers to reach keys with less effort

The Advantage 360 line was released in 2022 and is still insanely popular and challenging to get hold of. The pro edition allows you to customise the firmware, which is ZMK based. Kinesis have outsourced the actual job of compiling the firmware to GitHub Actions.

Resources⌗

ZMK firmware customisation workflow⌗

  1. Fork the repo
  2. Enable GitHub Actions on the fork
  3. Set the configuration UI to the fork
  4. (Optional) clone the forked repo and customise config/adv360.keymap e.g. for functionality the UI doesn’t current support such as mod-morph
  5. Make changes, then hit the big green Commit Changes button
  6. This will trigger the GitHub action on your fork, to compile the firmware
  7. Wait for the GitHub Action to complete, click into it, download the freshly baked firmware.zip, which contains two firmware blobs, left.uf2 and right.uf2
  8. Plug the left module in via USB C to the host machine and have it enter reset mode, using a paperclip double press the button tucked down in the middle of the thumb cluster (between the delete, home and end keys)
  9. This will cause the module to present as a mass storage device. Copy the file left.uf2 to it, as you would for any other storage device. The LEDs will flash. Wait for the module to reflash the firmware copied. Once its down it will automatically unmount itself from the host.
  10. Repeat the same steps, but for the right module, being careful to copy right.uf2 to it.

Alternatively to the paperclip method, with the respective key module connected over USB, use the shortcuts below to mount the removable drive named “Adv360 Pro”:

  • Left Module Bootloader: Mod + Hotkey 1
  • Right Module Bootloader: Mod + Hotkey 3

Customisations outside the UI⌗

The UI doesn’t allow you to configure the full gammit of ZMK functionality. For example, I really wanted a “Grave Escape” key, which makes use of the mod morph mode, a mode the will alter the keycode of a key while a modifier is active. Nice for keebs that are missing an entire row of keys, like the kinesis 360.

Pop this snippet into the behaviors section into a new file such as config/extra_morphs.dtsi. A new stand-alone file is needed as the GitHub build action will regenerate most of the config files. To get around this, we’ll get the build action to append the contents of this new file into config/macros.dtsi, so it can then be used by the configurator:

gresc: grave_escape {
    compatible = "zmk,behavior-mod-morph";
    label = "GRAVE_ESCAPE";
    #binding-cells = <0>;
    bindings = <&kp ESC>, <&kp GRAVE>;
    mods = <(MOD_LGUI|MOD_LSFT|MOD_RGUI|MOD_RSFT)>;
};

Next edit .github/workflow/build.yml

- name: Add custom behaviors
  run: |
        cat $GITHUB_WORKSPACE/config/extra_morphs.dtsi | tee -a $GITHUB_WORKSPACE/config/macros.dtsi
- name: Validate behaviors patched in
  run: |
        cat $GITHUB_WORKSPACE/config/macros.dtsi

Commit and push to the repo. Using the configurator UI, set a custom behavior to the escape key of &gresc

If unsure, refer to my working (as of late 2023) V3 fork.

Mode specific topics⌗

Daisy chaining key codes⌗

xx(code) adds modifier key to the code.

They can be combined. &kp LC(RA(B)) = Ctrl+Alt+b.

I’m a fan of the MEH and HYPER keys, which will enable this kind of key

  • MEH = &kp LC(LA(LS))
  • HYPER = &kp LC(LA(LS(LG)))

Modifier functions

  • LS(code) : Left Shift
  • RS(code) : Right Shift
  • LC(code) : Left Control
  • RC(code) : Right Control
  • LA(code) : Left Alt
  • RA(code) : Right Alt
  • LG(code) : Left GUI (Windows / Command / Meta)
  • RG(code) : Right GUI (Windows / Command / Meta)

Factory reset the firmware⌗

Fairly frequently the right-side module will misbehave, disconnect when flashing a customise firmware and/or just refuse to connect to its sibling left-hand module.

The only solution I’ve found is to dump the base factory configuration firmware onto both modules, then try re-flashing them both again.

If you run into problems with your build, or your modules are not syncing properly, it may be necessary to perform a Hard Reset by installing the “Settings Reset” firmware file on to each module.

  1. Navigate to the Code tab on your Adv360 Repo
  2. Click the settings-reset.uf2 link and then click the “download” button
  3. Follow the instructions above to install settings-reset.uf2 on to both the left and right key modules
  4. Once the settings-reset file has been installed on both modules, proceed to install the new firmware files of your choice. Proceed with the Left side first and then Right.
  5. The Left and Right modules will need to re-sync with each other after a Settings Reset. If it does not happen automatically, power-cycle the Left side and then the right in rapid succession.