From 171212c092d7ab41df1675bb2d2dc6c62c81c5d0 Mon Sep 17 00:00:00 2001 From: Andrew Reisner Date: Mon, 18 May 2026 23:16:25 -0400 Subject: [PATCH] Begin wiki. --- index.md | 146 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 index.md diff --git a/index.md b/index.md new file mode 100644 index 0000000000000000000000000000000000000000..83f092eef13dddeb63d0b9e6acc832efcbd594d0 --- /dev/null +++ b/index.md @@ -0,0 +1,146 @@ +# 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](https://github.com/zsa/qmk_firmware). + +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](https://github.com/holykeebs/qmk_firmware). + +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](https://github.com/Bastardkb/bastardkb-qmk). + +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](https://github.com/qmk/qmk_firmware). + +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](https://nixos.org/download) with flakes enabled + +### Build a single keyboard + +```sh +nix build .# +``` + +Available targets: + +| Nix target | Keyboard | Keymap | QMK Fork | +|---|---|---|---| +| `voyager-pers` | `zsa/voyager` | `pers` | ZSA | +| `voyager-ball` | `zsa/voyager` | `ball` | ZSA | +| `voyager-mod` | `zsa/voyager` | `mod` | ZSA | +| `keyball39-init` | `keyball/keyball39` | `init` | Holykeebs | +| `charybdis-init` | `bastardkb/charybdis/4x6` | `init` | BastardKB | +| `ploopyco-trackball-rev1_005-pers` | `ploopyco/trackball/rev1_005` | `pers` | Upstream | +| `ploopyco-trackball-rev1_007-pers` | `ploopyco/trackball/rev1_007` | `pers` | Upstream | + +### Build all keyboards + +```sh +nix build .#all +``` + +Firmware files (`.bin`, `.hex`, `.uf2`) will be in `./result/`. + +### Development shell + +```sh +nix develop +``` + +Drops into a shell with all QMK toolchains (AVR + ARM), Python dependencies, and flashing utilities pre-configured. + +## Flashing + +### ZSA Voyager + +```sh +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](https://www.zsa.io/flash) 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: + ```sh + 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.