omnixient/docs/moonlander.md

Flashing the ZSA Moonlander

How to flash firmware to the ZSA Moonlander Mark I on bohm.

What's wired into the config

Two pieces, both committed:

• configuration.nix → hardware.keyboard.zsa.enable = true; — installs ZSA's udev rules. Required so the keyboard is reachable for flashing and for Oryx in-browser live-training without root.
• home.nix → keymapp in home.packages — ZSA's official flashing GUI.

After editing those you must omni-rebuild switch (a system switch, not just home-manager — the udev rules live at the NixOS layer).

Gotcha: after the rebuild that first enables the udev rules, unplug and replug the keyboard so the new rules bind to the device. Otherwise Keymapp won't see it.

Flashing flow (normal path)

The Moonlander runs QMK. You don't compile anything locally for the normal path — ZSA's Oryx configurator produces the firmware.

1. Build/edit your layout in Oryx (https://configure.zsa.io) and download the firmware .bin.
2. Launch keymapp.
3. Press the small reset button on the keyboard (top-left, reachable with the included tool or a paperclip).
4. Flash the .bin from Keymapp.

CLI alternative

wally-cli (nixpkgs attribute wally-cli, not wally — that's a Roblox package manager) flashes from the terminal:

nix-shell -p wally-cli --run 'wally-cli firmware.bin'

Same reset-button step applies. Add wally-cli to home.packages if you want it permanently.

Troubleshooting

• Keyboard not detected — confirm the rebuild applied (hardware.keyboard.zsa.enable), then unplug/replug. Check the device shows up: lsusb | grep -i zsa (or look for 3297: vendor id).
• Permission denied on flash — udev rules aren't active for this plug-in; replug, or sudo udevadm control --reload && sudo udevadm trigger.
• Reset button does nothing — it's recessed; use the keycap-puller tool ZSA ships, or a straightened paperclip.