How keychron/zmk works
Project Type and Purpose
• ZMK is an embedded firmware project for mechanical keyboards, built on the Zephyr RTOS.
• It provides a modular stack for handling key scanning, input processing, behaviors (layers, combos, macros), BLE/USB HID, displays, split-keyboard support, and hardware integration via devicetree overlays.
High‐Level Architecture Components
a. Hardware / Boards
• Physical MCU boards (nRF52840, RP2040, etc.) described by devicetree overlays and board files under app/boards.
• Shields / interconnects that extend or split keyboards (app/boards/shields, app/boards/interconnects).
b. Zephyr RTOS
• Kernel, scheduling, device driver framework underneath ZMK (configured via app/prj.conf, module/zephyr/module.yml).
c. ZMK Core (app/src, app/include)
• Input subsystem: kscan drivers → event_manager → behaviors → keymap.
• Output subsystem: usb.c (USB HID) and ble.c (Bluetooth Low Energy HID).
• Subsystems: backlight, underglow, display (app/src/display), split (app/src/split), studio RPC (app/src/studio).
• Settings persistence and reset handlers (app/src/settings).
• Event definitions and handlers (app/src/events, include/zmk/events).
d. ZMK Modules (app/module)
• Device‐specific drivers (GPIO expanders, displays, sensors in module/drivers).
• DTS bindings for custom peripherals (module/dts/bindings).
• Build hooks and Kconfig fragments to integrate into Zephyr build.
e. Keymap Modules (app/keymap-module)
• Provide a Zephyr module that lets end users drop in custom keymaps as overlays.
f. Build System / Configuration
• CMakeLists.txt and Kconfig files across app/, module/, keymap-module/.
• West (app/west.yml) for managing Zephyr and module dependencies.
g. Tests & CI
• Native POSIX “board” (app/boards/native_posix_64) to run automated tests under app/tests.
• CI workflows (.github/workflows) driving build, test, doc checks.
h. Documentation & Frontend
• Docs site (docs/) built with Docusaurus, separate from firmware.
Relationships & Data Flow
• Key press → kscan driver (Zephyr) → ZMK event_manager → behavior processing → HID report generator → Transport (USB or BLE).
• Devicetree overlays and Kconfig feed into Zephyr build; application code & modules compile down to a single firmware image.
• Split keyboards: central vs. peripheral code communicate over BLE or other interconnect.
• Status: ZMK display subsystem → driver (module/drivers/display) → e-ink screens.
• CI pipelines trigger builds for boards, run native tests, deploy docs.
Architectural Patterns & Principles
• Layered architecture: Hardware → RTOS → Middleware (ZMK core) → Application (behaviors, keymaps).
• Modular plugin pattern: device drivers and keymaps are added as Zephyr modules.
• Event‐driven design: input, behaviors, transport all communicate via events and queues.
• Use of devicetree (DTS) for hardware abstraction.
• Kconfig for compile‐time feature selection.
Practical Steps
1. Sketch base layers horizontally.
4. Use rounded rectangles for Zephyr subsystems and ZMK subsystems.
5. Callouts for module plug-points and board overlays.