# kmkfw/kmk_firmware architecture

> Architecture diagram of the GitHub repository kmkfw/kmk_firmware, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kmkfw/kmk_firmware
- Repository: https://github.com/kmkfw/kmk_firmware

## Overview

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`](https://github.com/kmkfw/kmk_firmware/tree/main/boards) (Board keymap), [`kmk/keys.py`](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/keys.py) (Keys and handlers), [`kmk/hid.py`](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/hid.py) (HID reports), [`kmk/scanners/digitalio.py`](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/scanners/digitalio.py) (Matrix scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Board Configuration"]
  node_board_config["Board keymap"]
  node_keyboard_runtime["Keyboard runtime<br/>[kmk_keyboard.py]"]
end

subgraph group_input["Input and Key Behavior"]
  node_scanner["Matrix scanner<br/>[digitalio.py]"]
  node_keys["Keys and handlers<br/>[keys.py]"]
  node_layers["Layer behavior<br/>[layers.py]"]
  node_holdtap["Hold-tap keys<br/>[holdtap.py]"]
  node_macros["Macros<br/>[macros.py]"]
  node_tapdance["Tap dance<br/>[tapdance.py]"]
  node_encoder["Encoder input<br/>[encoder.py]"]
  node_split["Split coordination<br/>[split.py]"]
end

subgraph group_output["HID Output"]
  node_hid["HID reports<br/>[hid.py]"]
  node_scheduler["Task scheduler<br/>[scheduler.py]"]
end

subgraph group_extensions["Extensions"]
  node_media["Media keys<br/>[media_keys.py]"]
  node_rgb["RGB lighting<br/>[rgb.py]"]
  node_rgb_matrix["RGB matrix<br/>[peg_rgb_matrix.py]"]
  node_display["Display support<br/>[__init__.py]"]
  node_ssd1306["SSD1306 driver<br/>[ssd1306.py]"]
  node_led["LED backlights<br/>[led.py]"]
  node_unicode["International keys<br/>[international.py]"]
end

node_user(("Keyboard user"))
node_host(("Host computer"))

node_user -->|"configures"| node_board_config
node_board_config -.->|"starts"| node_keyboard_runtime
node_keyboard_runtime -.->|"scans input"| node_scanner
node_scanner -.->|"provides key events"| node_keys
node_layers -->|"extends"| node_holdtap
node_layers -->|"defines layer keys"| node_keys
node_holdtap -->|"defines hold-tap keys"| node_keys
node_macros -->|"uses keys"| node_keys
node_encoder -->|"uses scanner"| node_scanner
node_split -->|"coordinates HID"| node_hid
node_split -->|"uses keypad events"| node_scanner
node_keys -.->|"emits reports"| node_hid
node_hid -.->|"sends HID"| node_host
node_hid -->|"uses key definitions"| node_keys
node_hid -->|"schedules work"| node_scheduler
node_macros -->|"schedules actions"| node_scheduler
node_media -->|"registers media keys"| node_keys
node_board_config -.->|"enables"| node_media
node_board_config -.->|"enables"| node_rgb
node_board_config -.->|"enables"| node_rgb_matrix
node_board_config -.->|"enables"| node_display
node_display -->|"uses driver"| node_ssd1306
node_board_config -.->|"enables"| node_led
node_board_config -.->|"configures"| node_tapdance
node_board_config -.->|"configures"| node_macros
node_board_config -->|"configures"| node_split
node_board_config -->|"configures"| node_layers
node_board_config -->|"configures"| node_encoder
node_board_config -.->|"configures"| node_unicode

click node_board_config "https://github.com/kmkfw/kmk_firmware/tree/main/boards"
click node_keyboard_runtime "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/kmk_keyboard.py"
click node_scanner "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/scanners/digitalio.py"
click node_keys "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/keys.py"
click node_layers "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/modules/layers.py"
click node_holdtap "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/modules/holdtap.py"
click node_macros "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/modules/macros.py"
click node_tapdance "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/modules/tapdance.py"
click node_encoder "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/modules/encoder.py"
click node_split "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/modules/split.py"
click node_hid "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/hid.py"
click node_scheduler "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/scheduler.py"
click node_media "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/media_keys.py"
click node_rgb "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/rgb.py"
click node_rgb_matrix "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/peg_rgb_matrix.py"
click node_display "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/display/__init__.py"
click node_ssd1306 "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/display/ssd1306.py"
click node_led "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/led.py"
click node_unicode "https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/international.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_board_config,node_keyboard_runtime,node_user toneBlue
class node_scanner,node_keys,node_layers,node_holdtap,node_macros,node_tapdance,node_encoder,node_split toneAmber
class node_hid,node_scheduler toneMint
class node_media,node_rgb,node_rgb_matrix,node_display,node_ssd1306,node_led,node_unicode toneRose
class node_host toneIndigo
```

## Components

### Board Configuration

- [Board keymap](https://github.com/kmkfw/kmk_firmware/tree/main/boards): `boards`
- [Keyboard runtime](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/kmk_keyboard.py): `kmk/kmk_keyboard.py`

### Input and Key Behavior

- [Matrix scanner](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/scanners/digitalio.py): `kmk/scanners/digitalio.py`
- [Keys and handlers](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/keys.py): `kmk/keys.py`
- [Layer behavior](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/modules/layers.py): `kmk/modules/layers.py`
- [Hold-tap keys](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/modules/holdtap.py): `kmk/modules/holdtap.py`
- [Macros](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/modules/macros.py): `kmk/modules/macros.py`
- [Tap dance](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/modules/tapdance.py): `kmk/modules/tapdance.py`
- [Encoder input](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/modules/encoder.py): `kmk/modules/encoder.py`
- [Split coordination](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/modules/split.py): `kmk/modules/split.py`

### HID Output

- [HID reports](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/hid.py): `kmk/hid.py`
- [Task scheduler](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/scheduler.py): `kmk/scheduler.py`

### Extensions

- [Media keys](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/media_keys.py): `kmk/extensions/media_keys.py`
- [RGB lighting](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/rgb.py): `kmk/extensions/rgb.py`
- [RGB matrix](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/peg_rgb_matrix.py): `kmk/extensions/peg_rgb_matrix.py`
- [Display support](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/display/__init__.py): `kmk/extensions/display/__init__.py`
- [SSD1306 driver](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/display/ssd1306.py): `kmk/extensions/display/ssd1306.py`
- [LED backlights](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/led.py): `kmk/extensions/led.py`
- [International keys](https://github.com/kmkfw/kmk_firmware/blob/main/kmk/extensions/international.py): `kmk/extensions/international.py`

### Other components

- **Keyboard user**
- **Host computer**

## Connections

- Keyboard user → Board keymap: configures (evidence: `README.md`)
- Board keymap → Keyboard runtime: starts (evidence: `boards/tg4x/kb.py`)
- Keyboard runtime → Matrix scanner: scans input
- Matrix scanner → Keys and handlers: provides key events
- Layer behavior → Hold-tap keys: extends (evidence: `kmk/modules/layers.py`)
- Layer behavior → Keys and handlers: defines layer keys (evidence: `kmk/modules/layers.py`)
- Hold-tap keys → Keys and handlers: defines hold-tap keys (evidence: `kmk/modules/holdtap.py`)
- Macros → Keys and handlers: uses keys (evidence: `kmk/modules/macros.py`)
- Encoder input → Matrix scanner: uses scanner (evidence: `kmk/modules/encoder.py`)
- Split coordination → HID reports: coordinates HID (evidence: `kmk/modules/split.py`)
- Split coordination → Matrix scanner: uses keypad events (evidence: `kmk/modules/split.py`)
- Keys and handlers → HID reports: emits reports (evidence: `kmk/hid.py`)
- HID reports → Host computer: sends HID
- HID reports → Keys and handlers: uses key definitions (evidence: `kmk/hid.py`)
- HID reports → Task scheduler: schedules work (evidence: `kmk/hid.py`)
- Macros → Task scheduler: schedules actions (evidence: `kmk/modules/macros.py`)
- Media keys → Keys and handlers: registers media keys (evidence: `kmk/extensions/media_keys.py`)
- Board keymap → Media keys: enables (evidence: `README.md`)
- Board keymap → RGB lighting: enables (evidence: `README.md`)
- Board keymap → RGB matrix: enables (evidence: `boards/boardsource/unicorne/main.py`)
- Board keymap → Display support: enables (evidence: `boards/boardsource/unicorne/main.py`)
- Display support → SSD1306 driver: uses driver (evidence: `kmk/extensions/display/ssd1306.py`)
- Board keymap → LED backlights: enables (evidence: `README.md`)
- Board keymap → Tap dance: configures (evidence: `README.md`)
- Board keymap → Macros: configures (evidence: `README.md`)
- Board keymap → Split coordination: configures (evidence: `boards/boardsource/unicorne/main.py`)
- Board keymap → Layer behavior: configures (evidence: `boards/boardsource/unicorne/main.py`)
- Board keymap → Encoder input: configures (evidence: `boards/kyria/main.py`)
- Board keymap → International keys: configures (evidence: `README.md`)
