How kmkfw/kmk_firmware works
KMK is CircuitPython keyboard firmware configured by a board-specific Python file. The principal workflow configures a keyboard and keymap, scans physical input, applies key and layer behaviors, then emits keyboard or consumer HID; split keyboards coordinate across halves. Extensions add displays, lighting, and media keys. The README also documents macros, tap dance, and Bluetooth HID. The runtime core is partly unsampled, so the graph omits uncertain call links; module relationships shown are supported by the README or SOURCE INDEX references.
Main entry points: boards Board keymap · keys.py Keys and handlers · hid.py HID reports · digitalio.py Matrix scanner
Components 21
Board Configuration
- Board keymap
boards - Keyboard runtime
kmk/kmk_keyboard.py
Input and Key Behavior
- Matrix scanner
kmk/scanners/digitalio.py - Keys and handlers
kmk/keys.py - Layer behavior
kmk/modules/layers.py - Hold-tap keys
kmk/modules/holdtap.py - Macros
kmk/modules/macros.py - Tap dance
kmk/modules/tapdance.py - Encoder input
kmk/modules/encoder.py - Split coordination
kmk/modules/split.py
HID Output
- HID reports
kmk/hid.py - Task scheduler
kmk/scheduler.py
Extensions
- Media keys
kmk/extensions/media_keys.py - RGB lighting
kmk/extensions/rgb.py - RGB matrix
kmk/extensions/peg_rgb_matrix.py - Display support
kmk/extensions/display/__init__.py - SSD1306 driver
kmk/extensions/display/ssd1306.py - LED backlights
kmk/extensions/led.py - International keys
kmk/extensions/international.py
Other components
- Keyboard user
- Host computer
Connections 29
- Keyboard user → Board keymap: configures
README.md - Board keymap → Keyboard runtime: starts
boards/tg4x/kb.py - Keyboard runtime → Matrix scanner: scans input
- Matrix scanner → Keys and handlers: provides key events
- Layer behavior → Hold-tap keys: extends
kmk/modules/layers.py - Layer behavior → Keys and handlers: defines layer keys
kmk/modules/layers.py - Hold-tap keys → Keys and handlers: defines hold-tap keys
kmk/modules/holdtap.py - Macros → Keys and handlers: uses keys
kmk/modules/macros.py - Encoder input → Matrix scanner: uses scanner
kmk/modules/encoder.py - Split coordination → HID reports: coordinates HID
kmk/modules/split.py - Split coordination → Matrix scanner: uses keypad events
kmk/modules/split.py - Keys and handlers → HID reports: emits reports
kmk/hid.py - HID reports → Host computer: sends HID
- HID reports → Keys and handlers: uses key definitions
kmk/hid.py - HID reports → Task scheduler: schedules work
kmk/hid.py - Macros → Task scheduler: schedules actions
kmk/modules/macros.py - Media keys → Keys and handlers: registers media keys
kmk/extensions/media_keys.py - Board keymap → Media keys: enables
README.md - Board keymap → RGB lighting: enables
README.md - Board keymap → RGB matrix: enables
boards/boardsource/unicorne/main.py - Board keymap → Display support: enables
boards/boardsource/unicorne/main.py - Display support → SSD1306 driver: uses driver
kmk/extensions/display/ssd1306.py - Board keymap → LED backlights: enables
README.md - Board keymap → Tap dance: configures
README.md - Board keymap → Macros: configures
README.md - Board keymap → Split coordination: configures
boards/boardsource/unicorne/main.py - Board keymap → Layer behavior: configures
boards/boardsource/unicorne/main.py - Board keymap → Encoder input: configures
boards/kyria/main.py - Board keymap → International keys: configures
README.md