Custom QMK keymap for the ZSA Voyager. It uses the external userspace pattern. The firmware is mainline QMK, not ZSA's fork.
ZSA-specific features come from community modules. The
firmware repo is cloned separately and never modified. This repo has the keymap, the community
modules and the heatmap/ report tool.
The Voyager has 4 rows and 6 columns per half. This keymap uses 3 rows and 5 columns, plus both thumb clusters: 34 keys total (30 main + 4 thumbs). The top row and outer column are unused.
6 layers, QWERTY base:
- BASE - letters, home-row mods, bottom-row mods. Thumbs hold into the other layers.
- NAV - arrows, macOS app/tab shortcuts, clipboard, brackets.
- NUM - operators and modifiers on the left, numpad on the right where hold = F1-F12.
- SYM - symbols for typing code, plus vim (
:w,:wq,:q!), markdown code fence, and~/macros. - MOUSE - pointer, buttons, scroll.
- SYS - RGB, volume, brightness, media, lock, DND, jiggler, bootloader.
RGB uses Lumino for brightness and PaletteFx for effects and palettes.
Prerequisites:
brew install qmk/qmk/qmk
brew install dos2unixClone mainline QMK firmware and init its submodules:
qmk setup -H ~/<path-to>/qmk-firmware
cd ~/<path-to>/qmk-firmware
make git-submoduleClone this repo with submodules:
git clone --recurse-submodules <this-repo> ~/<path-to>/qmk-keymapOr if already cloned:
cd ~/<path-to>/qmk-keymap
git submodule update --init --recursivePoint QMK at both directories (config at ~/Library/Application Support/qmk/qmk.ini on macOS).
qmk config user.qmk_home=~/<path-to>/qmk-firmware
qmk config user.overlay_dir=~/<path-to>/qmk-keymapHomebrew's ARM and AVR compilers aren't on PATH by default:
fish_add_path /opt/homebrew/opt/arm-none-eabi-gcc@8/bin
fish_add_path /opt/homebrew/opt/arm-none-eabi-binutils/bin
fish_add_path /opt/homebrew/opt/avr-gcc@8/bin
fish_add_path /opt/homebrew/opt/avr-binutils/binVerify with qmk doctor.
Bare make does not work with external userspace. Always use qmk compile / qmk flash.
Compile (add --compiledb to generate compile_commands.json for LSP cross-file navigation):
qmk compile -kb zsa/voyager -km alexkrupaCompile and flash:
qmk flash -kb zsa/voyager -km alexkrupaThen enter bootloader mode: press the physical reset button on the bottom of the left half. Or hold
* (activates layer 5), then press the top-right key (QK_BOOT).
cd ~/<path-to>/qmk-firmware
git pull
make git-submoduleThen rebuild.
| I want to... | File | What to edit |
|---|---|---|
| Change key positions / layers | keymap.c |
keymaps[] array |
| Add custom shift mappings | keymap.c |
custom_shift_keys[] array |
| Add macros | keymap.c |
enum custom_keycodes + process_record_user() |
| Tune tapping term per key | keymap.c |
get_tapping_term() |
| Add/change combos | keymap.c |
combo arrays + key_combos[] |
| Enable/disable QMK features | rules.mk |
e.g. COMBO_ENABLE = yes |
| Tune timing, mouse speed, RGB | config.h |
#define overrides |
| Add/remove community modules | keymap.json |
"modules" array |
All keymap files are in keyboards/zsa/voyager/keymaps/alexkrupa/.
heatmap/heatmap.py reads key press counts from the Keymapp database and labels them from
keymap.c. See heatmap/README.md.
| Module | Purpose |
|---|---|
alexkrupa/tap_hold_stats |
Tap-hold press durations for tapping term tuning |
zsa/oryx |
Keymapp live view and Oryx live training |
zsa/mousejiggler |
Mouse jiggler toggle |
getreuer/cyclotab |
Cmd+Tab cycling that auto-releases on layer change |
getreuer/custom_shift_keys |
Custom Shift+key behavior (,; .: *!) |
getreuer/lumino |
Brightness cycling (0 / 40 / 100%) |
getreuer/palettefx |
RGB effects and palettes |
- Pascal Getreuer's FAQs and QMK keymap repo - the largest source of ideas here
- precondition's home row mods guide - the best introduction to the topic
- urob's timeless home row mods - the standard for home row mod timing
- sunaku's Glove80 keymap - layers, combos and the reasons for them. It started my interest, although I no longer use the Glove80
- Moosy's TailorKey - sunaku's ideas in a simpler form
- r/ErgoMechKeyboards - ideas and discussion