How am-zed/kbd_firmware works
1. This repository is a split-keyboard firmware project for the Corne/crkbd, built on QMK with a Vial-enabled fork alongside a plain QMK build. The core architectural boundary is between upstream firmware code and this repo’s keyboard-specific overlays, keymaps, and feature headers.
2. The repo is organized around two firmware variants:
- keyboards/crkbd/qmk/qmk_firmware for a standard QMK build
- keyboards/crkbd/vial-kb/vial-qmk for the Vial runtime-configurable build
Both sit on top of vendor firmware submodules and contain only the project-specific keyboard definition, keymaps, and custom behavior.
3. The build boundary is managed from the repo root with Makefile plus the QMK toolchain. Build outputs are checked in under .build as firmware artifacts such as .hex and .uf2, which indicates the firmware is intended to be compiled externally and then flashed onto the keyboard controller.
4. Hardware-wise, the target is a split Corne board revision (rev4_1) with a left master half, TRRS serial split communication, and pin-based handedness detection. The firmware also assumes per-key RGB on 46 LEDs total, so the hardware layer includes both matrix scanning and LED control as first-class concerns.
5. The input pipeline starts at the physical matrix scan, then flows through QMK’s split transport and into the keymap logic. Project code then intercepts events in the custom keymap layer to implement macros, Unicode typing, swap-hands behavior, sentence case, smart backspace, and other behaviors before final USB HID events are sent to the host.
6. The main behavior surface is the layered keymap. The README describes eight layers: base, navigation, function/RGB, symbols, mouse, macros, ErgoArabic, and RGB control. Tri-layer logic turns the symbols/adjust layer on when the navigation and function layers are both active, and layer lock can hold a layer without continuous key pressure.
7. The Vial build adds a runtime configuration boundary. Files like keymap.json and vial.json define what the Vial GUI can edit, while rules.mk and the Vial-specific keymap structure enable features such as dynamic macros and live key remapping without reflashing firmware.
8. Custom command behavior is centralized in the feature headers under features/ in the Vial tree. The important ones are leader-key handling, custom keycodes, smart backspace, RGB matrix behavior, pin/layout definitions, and modifier-layer helpers. These headers are the main extension points that turn a stock keymap into a feature-rich firmware.
9. The leader-key system is a separate command layer on top of normal typing. A leader sequence can trigger host shortcuts, text insertion, bootloader entry, or layer changes. Architecturally, this is a firmware-side command router that maps short chorded sequences to higher-level actions.
10. Unicode and Arabic support form a distinct typing subsystem. The ErgoArabic layer maps keys to Arabic letters, diacritics, and punctuation, while Unicode mode selection adapts output for Linux, Windows, WinCompose, or macOS-style input methods. This means the firmware is responsible not just for keycodes, but for host-specific text entry workflows.
11. RGB lighting is both a status channel and an effect engine. rgb_matrix.h and related helpers drive per-layer LED indicators, caps-lock state, reactive typing effects, suspend behavior, and brightness control. In the architecture diagram, this should be shown as a parallel output path from firmware state to the keyboard’s LED matrix.
12. The lib/ directory in the QMK tree contains support utilities such as readers and loggers for layer state, host LED state, RGB state, timing, and key logging. These act as shared presentation helpers for firmware status features, separate from the keymap logic itself.
13. Overall, the system has three main external interaction points: the host computer over USB HID, the split-half link over serial/TRRS, and the configuration/build toolchain via QMK and Vial. The repo’s architecture is therefore a layered firmware stack: upstream firmware base, keyboard board support, custom feature modules, keymaps, and generated binaries.
Main entry points: vial-qmk Vial tree · keymap.c Vial keymap · qmk_firmware QMK tree · Makefile Makefile
Components 18
Repo root
Build entry points and top-level documentation
- Makefile · Top-level build entry that drives firmware compilation
Makefile - README · Project overview and build/usage guidance
README.md - Firmware bins · Checked-in build outputs such as HEX and UF2 images
keyboards/crkbd/qmk/qmk_firmware/.build
QMK build
Plain QMK firmware subtree for the Corne board
- QMK tree · Plain QMK firmware fork for the Corne board
keyboards/crkbd/qmk/qmk_firmware - Default keymap · Main QMK keymap implementation
keyboards/crkbd/qmk/qmk_firmware/keymaps/default/keymap.c - Board code · Keyboard-specific board integration code
keyboards/crkbd/qmk/qmk_firmware/crkbd.c
Vial build
Vial-enabled firmware subtree with runtime configuration
- Vial tree · Vial-enabled QMK fork for runtime-configurable firmware
keyboards/crkbd/vial-kb/vial-qmk - Vial keymap · Vial keymap implementation with live remapping support
keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/keymap.c - Vial rules · Feature flags and build settings for the Vial keymap
keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/rules.mk - Vial schema · Metadata consumed by the Vial GUI for editable behavior
keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/vial.json - Keymap data · Editable keymap layout and feature metadata for Vial
keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/keymap.json
Hardware support
Board revision and split-transport hardware definitions
- rev4_1 defs · Corne rev4_1 hardware configuration and post-config hooks
keyboards/crkbd/qmk/qmk_firmware/rev4_1 - Standard rev · Standard firmware variant metadata for the rev4_1 board
keyboards/crkbd/qmk/qmk_firmware/rev4_1/standard/keyboard.json - Split link · TRRS/serial communication between keyboard halves
Feature modules
Reusable behavior and UI helpers inside the firmware trees
- Support lib · Shared readers and loggers for layers, host LEDs, RGB, timing, and key logging
keyboards/crkbd/qmk/qmk_firmware/lib - Feature headers · Custom behavior headers that extend the Vial keymap
keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/features - RGB hooks · RGB matrix user hook implementation for the Vial build
keyboards/crkbd/vial-kb/vial-qmk/keymaps/vial/rgb_matrix_user.inc
Other components
- USB host · Computer receiving HID reports and text input from the firmware
Connections 25
- Makefile → QMK tree: builds · Invokes the plain QMK firmware build
- Makefile → Vial tree: builds · Invokes the Vial-enabled firmware build
- README → Makefile: documents · Explains build and flashing workflow
- QMK tree → Board code: contains · Keyboard-specific board integration
- QMK tree → Default keymap: contains · Default keymap implementation
- QMK tree → rev4_1 defs: targets · Board revision hardware configuration
- rev4_1 defs → Split link: uses · Split transport and handedness behavior
- rev4_1 defs → Standard rev: defines · Standard rev4_1 variant metadata
- Default keymap → Support lib: uses · Shares firmware state readers and loggers
- Default keymap → USB host: reports to · Sends HID output and typing events
- Support lib → USB host: observes · Reads host LED and state feedback
- Firmware bins → Makefile: produced by · Checked-in compiled firmware artifacts
- Vial tree → Vial keymap: contains · Runtime-configurable keymap implementation
- Vial tree → Vial rules: contains · Build flags for the Vial variant
- Vial tree → Vial schema: contains · Vial runtime configuration schema
- Vial tree → Keymap data: contains · Editable keymap metadata and layout
- Vial tree → Feature headers: contains · Project-specific behavior extensions
- Vial tree → RGB hooks: contains · RGB user hook integration
- Feature headers → USB host: types to · Implements host-facing typing and command behaviors
- Feature headers → Split link: uses · Relies on split hardware definitions and matrix pins
- Vial keymap → Feature headers: includes · Pulls in custom command and behavior headers
- Vial keymap → USB host: reports to · Sends HID output and text entry
- RGB hooks → USB host: indicates · Drives LED state and effects as status output
- Vial schema → Vial keymap: describes · Exposes runtime-editable behaviors to Vial GUI
- Keymap data → Vial keymap: describes · Defines the editable keymap surface