# 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 .#<keyboard-name>
```

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.