Ferris Sweep	Urchin	Forager

This repo contains my personal ZMK keymap for three different 34-key boards. The logical layout is shared, while board-specific firmware targets and shields are handled in build.yaml.

Shared layout logic lives in config/includes/:

• base.dtsi for layers, hold-taps, and core behaviors
• combos.dtsi for combo definitions
• mouse.dtsi for mouse movement and scroll behavior

Changes in these files apply to all three boards (Sweep, Urchin, and Forager).

Each keyboard supports two connection modes:

• <keyboard>_dongle -> flash to dongle
• <keyboard>_left_peripheral -> flash to left half
• <keyboard>_right -> flash to right half

• <keyboard>_left_central -> flash to left half (central)
• <keyboard>_right -> flash to right half

• GitHub Actions builds the full matrix from build.yaml, including all boards and both dongle + dongleless profiles.

• Use local Docker when you want to iterate on one board only.
• Build one board locally with make build KEYBOARD=<sweep|urchin|forager>.
• Build dongle profile locally with make build KEYBOARD=<...> DONGLE=1.
• Prerequisite: Docker daemon must be running.

make help

make build KEYBOARD=sweep
make build KEYBOARD=urchin
make build KEYBOARD=urchin DONGLE=1
make build KEYBOARD=forager

make draw KEYBOARD=sweep
make draw KEYBOARD=urchin
make draw KEYBOARD=forager

Notes:

• Local firmware builds read build.yaml directly, so board/shield/snippet/cmake options stay aligned with CI builds.
• Firmware output files are written to build/local/:
  • Dongleless (DONGLE=0): build/local/<keyboard>_right.uf2, build/local/<keyboard>_left_central.uf2
  • Dongle (DONGLE=1): build/local/<keyboard>_left_peripheral.uf2, build/local/<keyboard>_right.uf2, build/local/<keyboard>_dongle.uf2
• Keymap-drawer output files are written to tools/keymap-drawer/.
• First keymap draw builds a pinned local Docker image for keymap-drawer.

• The layout is intentionally close to standard QWERTY, so muscle memory still transfers well.
• Number keys stay on the top row, similar to a regular keyboard.
• The symbol layer also follows familiar top-row QWERTY positions where possible.
• Navigation follows Vim-like movement patterns.
• High-usage programming symbols are placed closer to home row for faster access ({}, [], _, -, =, :).

• BASE: QWERTY + home-row mods
• SYM: symbols and punctuation in familiar QWERTY-style positions
• NAV: Vim-style navigation, number row, word navigation, Delete, back/forward
• FNC: function keys, media controls (volume, brightness, playback)
• SYS: Bluetooth profiles, output switching (USB/BLE), reset/bootloader, ZMK Studio unlock
• MSE: mouse movement, scroll, clicks, drag helpers
• MSE_FAST: faster temporary mouse/scroll behavior

FNC is a tri-layer: it activates when both SYM and NAV are active. SYS is toggled from the FNC layer, intentionally harder to reach to avoid accidental taps

• Home-row mods are tuned with custom hold-tap settings for reliable mod/tap distinction.
• Thumb keys are used heavily for layer access and core keys (Space, Backspace, Tab, Enter).
• Common coding symbols are kept close to home row to reduce finger travel while programming.
• Combos are intentional and practical (defined in config/includes/combos.dtsi), including:
  • Editing: Delete, Cut, Copy, Paste
  • Control: Escape (including a left-hand escape combo), Enter, Caps Word
  • Navigation aid: fast scroll combos (UIO for up, M,. for down)
  • Utility (on FNC): Soft Off, battery/connection indicator combos

• urob/zmk-config for home-row mod philosophy and layout ideas
• caksoylar/zmk-config for layout structure and keymap-drawer integration