A highly optimized QMK firmware configuration for the Svalboard split ergonomic keyboard featuring dual trackballs, COLEMAK layout, and Miryoku-inspired layer design.
- COLEMAK Layout: Modern, ergonomic letter arrangement optimized for finger rolls
- Miryoku-Inspired Layers: Single-hand layer activation with all functional keys on the opposite hand
- Dual Trackball Support: Independent sensors with configurable DPI (200-2400)
- Home Row Modifiers: Standard QMK modifiers on Double-South keys for instant, reliable modifier access without tap-dance interference
- Special Mouse Keys: Dual-function modifier/mouse button keys with intelligent context switching
- RGB Layer Indicators: Visual feedback for active layers
- Vial/Keybard Support: Runtime customization without reflashing
- 8 Thoughtfully Designed Layers:
BASE,NAV,NUM,SYM,FUN,MED,SYS, and auto-activated mouse layer
- Layer Reference - Complete visual guide to all 8 keyboard layers
- Advanced Features - Home row modifiers, special mouse keys, trackball configuration, and more
- Changelog - Version history and release notes
| Layer | Name | Activation | Purpose |
|---|---|---|---|
| 0 | BASE | Default | COLEMAK letters with common symbols |
| 1 | NAV | Hold left thumb inward (Backspace) | Vim-style navigation and window management |
| 2 | NUM | Hold right thumb inward (Space) | Numeric keypad with operators |
| 3 | SYM | Hold left thumb outward (Tab) | Programming symbols and brackets |
| 4 | FUN | Hold right thumb outward (Back-tab) | Function keys F1-F20 |
| 5 | MED | Hold left thumb knuckle outward | Multimedia keys |
| 6 | SYS | Hold right thumb knuckle outward | System keys (keyboard firmware and OS) |
| 7 | MBO | Auto on trackball movement | Mouse buttons with modifiers |
For detailed layer diagrams with all key positions, see the Layer Reference.
- Python 3.9 (later versions of Python won't work until Svalboard/Vial merge latest changes from QMK)
- QMK CLI
- Git with submodules support
-
Clone this repository:
git clone --recurse-submodules https://github.com/Townk/qmk-config.git cd qmk-config -
Set up QMK (first time only):
qmk setup
-
Configure QMK userspace to point to this directory:
qmk config user.overlay_dir="$(realpath .)"
Build firmware for both keyboard halves:
qmk userspace-compileThis generates versioned firmware files:
svalboard-colemak-dh-townk-{VERSION}.left.uf2- Left half firmwaresvalboard-colemak-dh-townk-{VERSION}.right.uf2- Right half firmware
Or build a specific half:
qmk compile -kb svalboard/trackball/pmw3389/left -km townk
qmk compile -kb svalboard/trackball/pmw3389/right -km townk- Put the keyboard half into bootloader mode (consult your Svalboard manual)
- Copy the corresponding
.uf2file to the mounted drive - The keyboard will automatically reboot with the new firmware
- Repeat for the other half
This repository is configured to automatically build firmware on every push:
- Fork this repository
- Enable GitHub Actions in your fork's settings
- Push your changes
- Download built firmware from the Actions artifacts tab
- Firmware is automatically published to the Releases page with semantic versioning (v1.0.1, v1.0.2, etc.)
This firmware supports Vial and Keybard (recommended) for runtime configuration. Just access one of these web applications using a Chrome-based browser to connect your keyboard and modify its layers and keys.
Key files to modify:
keyboards/svalboard/keymaps/townk/keymap.c: Layer definitions and key mappingsusers/townk/townk_mouse.c: Mouse button behaviorusers/townk/townk_layers.c: RGB layer colorsusers/townk/townk_keycodes.h: Custom key code definitionskeyboards/svalboard/keymaps/townk/config.h: Hardware settings (DPI, timeouts, etc.)
After making changes, rebuild and flash:
qmk userspace-compileDefault settings:
- Left Trackball: Scroll mode enabled, 400 DPI
- Right Trackball: Cursor mode, 1200 DPI
- Auto Mouse Layer: Enabled
- DPI Options: 200, 400, 800, 1200, 1600, 2400
For detailed configuration instructions and Sniper mode documentation, see Advanced Features - Trackball Configuration.
.
├── docs/ # Documentation
│ ├── layer-reference.md # Complete layer visual reference
│ └── advanced-features.md # Special features and configuration
│
├── keyboards/svalboard/keymaps/townk/ # Keyboard-specific keymap
│ ├── keymap.c # Main layer definitions
│ ├── config.h # Hardware configuration
│ ├── vial.json # Vial definitions
│ └── rules.mk # Build flags
│
├── users/townk/ # Shared user code
│ ├── townk_keycodes.h # Custom keycodes
│ ├── townk_layers.h/c # RGB layer indicators
│ ├── townk_mouse.h/c # Special mouse keys
│ ├── townk_overrides.h/c # Key overrides
│ └── townk_smtd.c # SM_TD integration
│
├── modules/stasmarkin/sm_td/ # SM_TD library (submodule)
├── .github/workflows/ # CI/CD configuration
├── .devcontainer/ # Docker dev environment
├── VERSION # Semantic version (major.minor)
├── CHANGELOG.md # Version history
└── qmk.json # Build targetsStandard QMK modifiers placed on Double-South keys (accessible via downward flick). Provides instant modifier activation without tap-dance timing delays that can interfere with fast typing.
Thumb cluster keys use the SM_TD
(Stasmarkin Tap Dance) library for intelligent tap/hold behavior: tap for a key
(Backspace, Tab, Space, etc.), hold to activate a layer (NAV, SYM, NUM,
FUN). SM_TD adapts to your typing speed to prevent false triggers.
The MB_SFT, MB_ALT, MB_GUI, and MB_CTL keys provide intelligent dual
behavior for mouse operations with modifiers. They act as mouse buttons,
keyboard modifiers, or held mouse buttons depending on context.
Double-tap the Double-Down thumb key to enable Caps Word - type in CAPS without holding shift. Automatically deactivates on space, punctuation, or layer change.
RGB lighting automatically changes color based on the active layer, providing instant visual feedback.
This project includes a .devcontainer configuration for development:
# With VS Code
1. Install the "Remote - Containers" extension
2. Open this folder in VS Code
3. Click "Reopen in Container" when prompted
# With Docker directly
docker run -v $(pwd):/workspace ghcr.io/qmk/qmk_cli-
C code follows Google style (see
.clang-format) -
Format code before committing:
clang-format -i **/*.c **/*.h
- Build locally to check for compilation errors
- Flash to keyboard and test functionality
- Check RGB indicators for each layer
- Verify trackball behavior and DPI settings
- Test special mouse keys in various scenarios
- QMK Userspace Version: 1.0
- Base Firmware: vial-qmk (Svalboard fork)
- Keyboard: Svalboard with PMW3389 dual-trackballs
- Layout: COLEMAK (46-key split)
- Features: Vial, RGB Lighting, Pointing Device, Mouse Keys
- Svalboard Official Site
- QMK Documentation
- Vial Documentation
- COLEMAK Layout
- Miryoku Layout Philosophy
- SM_TD Library
Contributions are welcome! This is a personal keyboard configuration, but if you have improvements or find bugs:
- Fork this repository
- Create a feature branch
- Make your changes
- Test thoroughly on hardware
- Submit a pull request with a clear description
This project is licensed under the GNU General Public License v3.0 or later. See individual file headers for copyright information.
Copyright (C) 2025 Thiago Alves
- QMK Firmware - The foundation of this configuration
- Svalboard - For creating an incredible ergonomic keyboard
- stasmarkin - For the SM_TD tap dance library
- Miryoku - For layer design inspiration