105 lines
4.0 KiB
Markdown
105 lines
4.0 KiB
Markdown
# System76 Launch 3 Custom Firmware
|
|
|
|
Custom QMK firmware for the [System76 Launch 3](https://system76.com/accessories/launch) 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/`](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](https://nixos.org/) with flakes enabled.
|
|
|
|
```sh
|
|
nix build
|
|
```
|
|
|
|
The `.uf2` firmware file is output to `./result/`.
|
|
|
|
### Flashing
|
|
|
|
1. Put the keyboard into bootloader mode (press the reset button on the bottom)
|
|
2. Copy the `.uf2` file to the mounted USB drive
|
|
|
|
### Development Shell
|
|
|
|
```sh
|
|
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
|
|
```
|