Serenity

My personal QMK firmware: a shared userspace (users/serenity) plus a keymap per keyboard, built as a QMK external userspace.

This repo holds only my code. QMK itself lives in a separate, unmodified clone.

Layout reference: interactive diagrams of every layer, plus the feature list, are at serenity-layout.fyi/firmware (source).

Layers

The website uses friendlier names for some layers than the code does:

Code (serenity.h)	Website	Reached by
BASE	Base	default
QWRTY	Qwerty	hold TGL_LYT_LP on Hardware, or build with -e QWERTY_BASE=yes
NUMNAV	Num/Nav	left thumb, beside Space
SYMBL	Symbol	right thumb, beside Space
ACTN	Action	left, beside Num/Nav
HRDWR	Hardware	right, beside Symbol
OS	OS	Num/Nav + Symbol (tri-layer)
FUNC	Function	Action + Hardware (tri-layer)
MOUSE	Mouse	hold Escape

Layout

Path	What
users/serenity/	Shared layers, custom keycodes and features used by every keyboard
keyboards/<kb>/keymaps/serenity/	Per-keyboard layout (calls into the shared userspace)
modules/getreuer/	Getreuer's community modules (git submodule); custom_shift_keys and select_word are used
modules/wheredoesyourmindgo/	My own community modules, wheredoesyourmindgo/qmk-modules (git submodule); stackable_oneshot provides the one-shot mod keys (SOSM_LS etc.)
vendor/foostan/corneliuskbd/	foostan's Cornelius rev1/rev2 keyboard definitions (copied from foostan/kbd_firmware; see Cornelius)
scripts/format_keymaps.py	Aligns each LAYOUT(...) into a split grid (--check to verify)
scripts/update_foostan.sh, scripts/link_foostan.sh	Refresh the Cornelius definitions; link them into the QMK clone
qmk.json	List of keyboards to build (qmk userspace-list)

One-time setup

brew install uv
curl -fsSL https://install.qmk.fm | sh -s -- --skip-uv   # QMK CLI (via uv), compilers, and flashing tools
git clone --recurse-submodules https://github.com/wheredoesyourmindgo/serenity-qmk.git ~/Development/serenity-qmk
git clone https://github.com/qmk/qmk_firmware.git ~/Development/qmk_firmware
cd ~/Development/qmk_firmware && make git-submodule
qmk config user.qmk_home="$HOME/Development/qmk_firmware"
qmk config user.overlay_dir="$HOME/Development/serenity-qmk"
~/Development/serenity-qmk/scripts/link_foostan.sh   # makes the Cornelius buildable (see below)

--skip-uv keeps the installer from adding its own copy of uv alongside Homebrew's. The installer puts the compilers and flashing tools (avrdude, dfu-util, dfu-programmer, …) in ~/Library/Application Support/qmk, so they don't need to be installed with Homebrew; qmk adds that folder to its PATH when it runs.

The installer deletes and recreates that folder, and on macOS the QMK CLI keeps its settings (qmk.ini) there too. Re-running it (for example to update the compilers) erases qmk_home and overlay_dir, and qmk drops back to only config, clone, console, env, and setup. Run the two qmk config lines again afterwards.

Everyday use

qmk userspace-compile                                 # build every keyboard in qmk.json
qmk flash -kb foostan/corneliuskbd/rev1 -km serenity  # build + flash one keyboard

Build options go after -e, e.g. -e QWERTY_BASE=yes.

After editing a keymap, re-align its grid with scripts/format_keymaps.py.

Editor setup (VS Code + clangd)

On each computer, after the one-time setup above:

1. Accept VS Code's prompt to install the recommended extensions (includes clangd). If Microsoft's C/C++ extension is installed, leave it — its IntelliSense is disabled for this workspace so it won't conflict.

2. Generate a compile database covering every keyboard in qmk.json:

   scripts/compiledb.py                            # all keyboards (builds each one)
   scripts/compiledb.py foostan/corneliuskbd/rev1  # refresh just one, keeping the rest
   

compile_commands.json is gitignored and holds machine-specific paths, so every computer generates its own. Re-run the script after adding a keyboard or changing a rules.mk/config.h, then clangd: Restart language server. (Plain qmk compile --compiledb only covers one keyboard and overwrites the merged database.)

Updating QMK

cd ~/Development/qmk_firmware && git pull && make git-submodule

If a QMK change breaks the build, fix it here — there is nothing to merge.

Updating Getreuer's modules

modules/getreuer is a git submodule pinned to one commit of getreuer/qmk-modules, so upstream changes only arrive when you pull them:

cd ~/Development/serenity-qmk
git submodule update --remote modules/getreuer   # fetch the latest upstream
git -C modules/getreuer log --oneline -5         # see what changed
qmk userspace-compile                            # make sure everything still builds
git commit -am "Update getreuer modules" && git push

To undo an update before committing, run git submodule update modules/getreuer (goes back to the pinned commit).

If modules/getreuer is ever empty (e.g. after a plain git clone), run git submodule update --init.

Custom Shift Keys is enabled by the modules entry in each keymap's keymap.json. Its key table is in users/serenity/shift_keys.c and its options are set in users/serenity/config.h; they're documented in its README.

Select Word is enabled the same way and provides the SELWORD key on the Num/Nav layer. It's set to macOS hotkeys in users/serenity/config.h; its keys and options are documented in its README.

Editing my own modules

modules/wheredoesyourmindgo is its own repo. Submodules check out a detached commit and clone over https, so before the first edit on a computer:

cd ~/Development/serenity-qmk/modules/wheredoesyourmindgo
git switch main
git remote set-url --push origin git@github-personal:wheredoesyourmindgo/qmk-modules.git

Then commit and push inside the module first, and commit the new pointer here:

git -C modules/wheredoesyourmindgo commit -am "..." && git -C modules/wheredoesyourmindgo push
git commit -am "Update wheredoesyourmindgo modules" && git push

Stackable One-Shot is enabled by the modules entry in each keymap's keymap.json; its options are documented in its README.

Cornelius

Both Cornelius boards build from foostan's own definitions in foostan/kbd_firmware, not upstream QMK's foostan/cornelius. Upstream has only rev1, and foostan's rev1 is newer (it turns NKRO on, for example).

Target	Board	Output	Flash
foostan/corneliuskbd/rev1	Cornelius (ATmega32u4)	.hex	qmk flash -kb foostan/corneliuskbd/rev1 -km serenity
foostan/corneliuskbd/rev2	Cornelius Low-profile (RP2040)	.uf2	Hold the top-left key while plugging in, then copy the .uf2 onto the RPI-RP2 drive

QMK only reads keyboard definitions from its own tree, so scripts/link_foostan.sh links vendor/foostan/corneliuskbd into the QMK clone at keyboards/foostan/corneliuskbd and hides it from that clone's git status. Run it once per QMK clone (GitHub Actions runs it for you). If you see Invalid keyboard: foostan/corneliuskbd/..., run it again.

The keyboard files are a copy rather than a submodule, because foostan's repo has its own QMK and Vial submodules that --recurse-submodules would download. vendor/foostan/corneliuskbd/SOURCE records which foostan commit they came from. To pick up foostan's changes:

cd ~/Development/serenity-qmk
scripts/update_foostan.sh                  # fetch foostan's latest definitions
git diff vendor                            # see what changed
qmk userspace-compile                      # make sure everything still builds
git add vendor && git commit -m "Update foostan Cornelius definitions" && git push

To undo an update before committing, run git checkout vendor.

GitHub Actions

Every push builds all targets in qmk.json and publishes the firmware files on the Releases page.