#QMK Userspace Wiki

Personal QMK firmware configurations for multiple keyboards, managed via a Nix flake for reproducible builds.

#Keyboards

#ZSA Voyager

Split columnar keyboard with hotswap switches. Uses the ZSA QMK fork.

Three keymap variants:

• pers -- Primary layout. Home row mods (GACS), caps word (both shifts), symbol layer, nav/media layer with RGB controls.
• ball -- Trackball-enabled variant. Adds Navigator trackball driver with hi-res scroll, auto mouse layer, drag scroll toggle, CPI adjustment, and a numpad layer on hold-B.
• mod -- Modifier-focused variant. Similar to pers but with tap dance undo (double-tap U for Ctrl+Shift+-), combo caps word (D+K), numpad on hold-E, and a transparent toggle layer for GUI+N override.

All three share: QWERTY base, home row mods, symbol layer (braces/parens/operators), settings layer (RGB, nav arrows, boot), and caps word.

#Keyball39

39-key split keyboard with integrated trackball. Uses the Holykeebs QMK fork.

Keymap: init

• QWERTY base with home row mods (Alt/Shift/Ctrl on S/D/F and J/K/L)
• Tap dance undo on U (double-tap for Ctrl+Shift+-)
• Combo caps word (D+K)
• Auto mouse layer -- trackball movement activates the mouse/numpad layer
• Scroll mode auto-enables on the nav layer, with configurable scroll divisor and snap modes (vertical/horizontal/free)
• OLED display showing key info, ball state, and active layer
• RGB underglow
• Gaming layer (strips home row mods)
• Layers: Base, Transparent, Gaming, Mouse+Numpad, Symbols, Nav/Settings

#BastardKB Charybdis 4x6

Split ergodox-style keyboard with integrated trackball (RP2040/Splinky). Uses the BastardKB QMK fork.

Keymap: init

• QWERTY base with home row mods (Alt/Shift/Ctrl on S/D/F and J/K/L)
• Tap dance undo, combo caps word (D+K)
• Charybdis pointer features: drag scroll (hold/toggle), sniping mode, DPI scaling
• Auto sniping on the pointer layer
• Optional auto pointer layer trigger on trackball movement
• Gaming layer, numpad layer, symbol layer
• Settings layer with Wayfire tiling shortcuts (half/full), RGB controls, DPI tuning
• Layers: Base, Transparent, Gaming, Pointer, Symbol, Settings

#Ploopyco Trackball (rev1_005 / rev1_007)

Standalone trackball with 5 buttons. Uses upstream QMK.

Keymap: pers

• Button 1 (left click), Button 3 (middle), Button 4 (back), Button 2 (right, hold for layer 1), Button 5 (forward)
• Layer 1: drag scroll on Button 1, DPI config on Button 4
• Inverted drag scroll direction (PLOOPY_DRAGSCROLL_INVERT)
• Both rev1_005 and rev1_007 revisions share the same keymap

#Common Features Across Keymaps

• Home row mods -- Modifier keys on the home row (GACS or ACS depending on keyboard)
• Caps Word -- Activated by pressing both shifts or combo (D+K); auto-deactivates on non-alpha/number keys
• Tap dance undo -- Double-tap U sends Ctrl+Shift+- (editor undo)
• Symbol layer -- Consistent symbol layout across all split keyboards: backtick/tilde/hash/ampersand on top row, braces/parens on right, operators distributed logically
• Wayfire shortcuts -- GUI+Shift+D (half tile) and GUI+Shift+F (full tile) on nav layers
• GUI+N override -- Transparent toggle layer enabling GUI+N via HR_L tap when GUI is held

#Building with Nix

#Prerequisites

• Nix with flakes enabled

#Build a single keyboard

nix build .#<keyboard-name>

Available targets:

#Build all keyboards

nix build .#all

Firmware files (.bin, .hex, .uf2) will be in ./result/.

#Development shell

nix develop

Drops into a shell with all QMK toolchains (AVR + ARM), Python dependencies, and flashing utilities pre-configured.

#Flashing

#ZSA Voyager

nix run .#flash-voyager

This uses wally-cli to flash the voyager-pers firmware. To flash manually or use a different keymap, build the target and flash the .bin from ./result/ using Wally or wally-cli.

#Keyball39 / Charybdis (UF2)

1. Build: nix build .#keyball39-init or nix build .#charybdis-init
2. Put the keyboard into bootloader mode (double-tap reset or hold boot button)
3. Copy the .uf2 file from ./result/ to the USB mass storage device that appears

#Ploopyco Trackball (AVR)

1. Build: nix build .#ploopyco-trackball-rev1_005-pers
2. Put the trackball into bootloader mode (hold button while plugging in)
3. Flash using avrdude or copy the .hex file:

   avrdude -p atmega32u4 -c avr109 -P /dev/ttyACM0 -U flash:w:result/*.hex
   

#How the Nix Flake Works

The flake manages four separate QMK firmware sources as inputs, one per fork:

• qmk-firmware -- Upstream QMK (Ploopyco)
• zsa-qmk-firmware -- ZSA fork (Voyager)
• keyball-qmk-firmware -- Holykeebs fork (Keyball39)
• bastardkb-qmk-firmware -- BastardKB fork (Charybdis)

Each build target specifies which fork to use. The setupUserspace helper copies the fork's source tree, then overlays the keyboards, users, and layouts directories from this userspace repo on top. This lets custom keymaps coexist with the fork's built-in keyboard definitions.

Pin updates are managed through flake.lock -- run nix flake update to pull the latest from all forks.