4.0 KiB
System76 Launch 3 Custom Firmware
Custom QMK firmware for the System76 Launch 3 keyboard, built with Nix.
Features
OS Mode
The keyboard auto-detects the host OS on plug-in and rewrites shortcuts so that muscle memory from Linux (Ctrl-based shortcuts) works on macOS. Mode can also be cycled manually with FN+Del.
Four modes, indicated by RGB flash color:
| Mode | Color | Behavior |
|---|---|---|
| None | Red | No rewrites, all keys pass through |
| Linux | Green | Super+Up → Super+W (KDE overview) |
| Mac | Yellow | Full Ctrl→Cmd rewrite (see table below) |
| Windows | Blue | Super+Up → Super+Tab (Task View) |
Mac Mode Shortcut Rewrites
| Input (Linux muscle memory) | Output (macOS) | Action |
|---|---|---|
| Ctrl+C/V | Cmd+C/V | Copy/Paste (skipped in Terminal — Ctrl+C = SIGINT) |
| Ctrl+Shift+C/V | Cmd+C/V | Terminal copy/paste |
| Ctrl+X/A/S/F | Cmd+X/A/S/F | Cut, Select All, Save, Find |
| Ctrl+D | Cmd+D | Bookmark / select next occurrence (skipped in Terminal) |
| Ctrl+Shift+F | Cmd+Shift+F | Find in files |
| Ctrl+P | Cmd+Shift+O (Xcode) / Cmd+P (other) | Quick open |
| Ctrl+Shift+P | Cmd+Shift+A (Xcode) / Cmd+Shift+P (other) | Command palette / Quick Actions |
| Ctrl+W/L/R | Cmd+W/L/R | Close tab, Address bar, Reload |
| Ctrl+Z/T/N | Cmd+Z/T/N | Undo, New tab, New window |
| Ctrl+Shift+Z/T/N | Cmd+Shift+Z/T/N | Redo, Reopen tab, Incognito |
| Ctrl+Left/Right | Alt+Left/Right | Word navigation |
| Ctrl+Shift+Left/Right | Alt+Shift+Left/Right | Word selection |
| Ctrl+Alt+Left/Right | Ctrl+Left/Right | Switch workspace |
| Ctrl+Backspace | Alt+Backspace | Delete word |
| Home/End | Ctrl+A/E (Terminal) / Cmd+Left/Right (other) | Line start/end |
| Alt+F4 | Cmd+Q | Quit app |
| Alt+Tab | Cmd+Tab | App switcher |
| Super tap | Cmd+Space | Spotlight |
| Super+Up | Ctrl+Up | Mission Control |
| Ctrl hold (Xcode/VSCode) | Cmd hold | Ctrl-as-Cmd for mouse clicks (e.g. jump to symbol) |
App-Aware Remaps
Some rules are per-app: Terminal.app and iTerm2 let Ctrl+C/V/D pass through so signals and shell shortcuts work, while Xcode and VSCode get IDE-specific bindings for Ctrl+P and Ctrl+Shift+P.
App awareness requires the mac-agent (mac-agent/) running on the host. It sends the focused app name to the keyboard over Raw HID. Without it, all apps are treated as "unknown" and generic rules apply.
NOREMAP Key
The right FN key has been replaced with a dedicated NOREMAP key. Hold it to bypass all shortcut remaps — the keypress is sent exactly as typed. Useful when you need the original Ctrl+key behavior on macOS.
Layer 1 (FN Layer)
| Key | FN+ |
|---|---|
| ESC | Print Screen |
| F1/F2/F3 | Mute / Vol Down / Vol Up |
| 1/2/3 | Play-Pause / Prev / Next |
| 0/-/= | LED Toggle / LED Down / LED Up |
| Backspace | Cycle RGB Effect |
| Del | Cycle OS Mode |
| Arrows | Home / PgDn / PgUp / End |
Building
Requires Nix with flakes enabled.
nix build
The .uf2 firmware file is output to ./result/.
Flashing
- Put the keyboard into bootloader mode (press the reset button on the bottom)
- Copy the
.uf2file to the mounted USB drive
Development Shell
nix develop
qmk compile -kb system76/launch_3 -km custom
Project Structure
keymaps/custom/
├── keymap.c # Keymaps, remap rules engine, process_record_user
├── os_detect.c # OS auto-detection, RGB flash indicator
├── os_mode.h # OS mode enum and shared state
├── app_focus.c # Raw HID handler for focused-app notifications
├── app_focus.h # Focused app enum and extern
├── config.h # RGB matrix effect enables
└── rules.mk # QMK build flags
mac-agent/ # macOS daemon that sends focused app to keyboard (see mac-agent/README.md)
patches/ # Patches applied to QMK submodule at build time
qmk_firmware/ # System76 QMK fork (git submodule)
flake.nix # Nix build system