# unified-retro-keyboard/asdf-firmware architecture

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

- Interactive diagram: https://gitdiagram.com/unified-retro-keyboard/asdf-firmware
- Repository: https://github.com/unified-retro-keyboard/asdf-firmware

## Overview

ASDF is modular keyboard-scanning firmware: hardware ports scan a key matrix, the core handles key transitions and actions, selected application keymaps translate row/column positions into codes, and buffered codes reach the configured output routine. Major capabilities include debounce, N-key rollover, modifier modes, repeat, DIP-switch keymap selection, virtual outputs, and multiple retrocomputer layouts. Architecture variants and keymap families are grouped to keep the map readable. Relationships are based on the excerpts, SOURCE INDEX references, and README; unsampled implementation details are not assumed.

Main entry points: [`src/asdf_keymaps.c`](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_keymaps.c) (Map registry), [`src/asdf.c`](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf.c) (Scan and actions), [`src/main.c`](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/main.c) (Scheduler loop), [`src/Arch/asdf_arch_atmega2560.c`](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Arch/asdf_arch_atmega2560.c) (Matrix hardware ports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime core"]
  node_mainloop["Scheduler loop<br/>[main.c]"]
  node_scanner["Scan and actions<br/>[asdf.c]"]
  node_debounce["Debounce scanner<br/>[asdf_physical.c]"]
  node_modifiers["Modifier state<br/>[asdf_modifiers.h]"]
  node_repeat["Key repeat<br/>[asdf_repeat.c]"]
end

subgraph group_mapping["Keymap selection"]
  node_keymap_engine["Map registry<br/>[asdf_keymaps.c]"]
  node_classic_maps["Classic maps"]
  node_apple_maps["Apple II maps"]
  node_apple_matrix["Apple II layout"]
  node_ace_maps["ACE 1000 maps"]
  node_sol_maps["Sol-20 map<br/>[asdf_keymap_sol.c]"]
  node_dip_defs["DIP switch actions"]
end

subgraph group_platform["Hardware ports"]
  node_architecture["Matrix hardware ports"]
end

subgraph group_io["Output and resources"]
  node_buffer["Code buffer<br/>[asdf_buffer.c]"]
  node_output_hook["Output hooks<br/>[asdf_hook.c]"]
  node_virtual_io["Virtual outputs<br/>[asdf_virtual.c]"]
  node_physical_io["Physical resources<br/>[asdf_physical.c]"]
end

node_keyboard(("Physical keyboard"))
node_host(("Host computer"))

node_keyboard -.->|"matrix signals"| node_architecture
node_mainloop -->|"initializes and scans"| node_scanner
node_mainloop -->|"checks tick"| node_architecture
node_architecture -.->|"provides row reads"| node_debounce
node_scanner -->|"reads key states"| node_debounce
node_scanner -->|"looks up codes"| node_keymap_engine
node_scanner -->|"uses modifier state"| node_modifiers
node_scanner -->|"manages repeat"| node_repeat
node_scanner -->|"buffers codes"| node_buffer
node_scanner -->|"activates outputs"| node_virtual_io
node_keymap_engine -->|"resets resources"| node_virtual_io
node_keymap_engine -->|"resets hooks"| node_output_hook
node_classic_maps -->|"registers maps"| node_keymap_engine
node_apple_maps -->|"registers maps"| node_keymap_engine
node_apple_matrix -.->|"defines layout"| node_apple_maps
node_ace_maps -->|"registers maps"| node_keymap_engine
node_sol_maps -.->|"registers maps"| node_keymap_engine
node_dip_defs -.->|"selects map"| node_keymap_engine
node_mainloop -->|"reads next code"| node_buffer
node_mainloop -->|"dispatches output"| node_output_hook
node_output_hook -.->|"sends codes"| node_host
node_virtual_io -->|"assigns resources"| node_physical_io
node_physical_io -.->|"drives hardware"| node_architecture

click node_mainloop "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/main.c"
click node_scanner "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf.c"
click node_debounce "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_physical.c"
click node_modifiers "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_modifiers.h"
click node_repeat "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_repeat.c"
click node_keymap_engine "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_keymaps.c"
click node_classic_maps "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Keymaps/asdf_keymap_classic_add_map.c"
click node_apple_maps "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Keymaps/asdf_keymap_apple2_add_map.c"
click node_apple_matrix "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Keymaps/asdf_keymap_apple2_matrix.c"
click node_ace_maps "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Keymaps/asdf_keymap_ace1000_add_map.c"
click node_sol_maps "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Keymaps/asdf_keymap_sol.c"
click node_dip_defs "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Keymaps/asdf_keymap_defs_dipswitch.h"
click node_architecture "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Arch/asdf_arch_atmega2560.c"
click node_buffer "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_buffer.c"
click node_output_hook "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_hook.c"
click node_virtual_io "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_virtual.c"
click node_physical_io "https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_physical.c"

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_mainloop,node_scanner,node_debounce,node_modifiers,node_repeat toneBlue
class node_keymap_engine,node_classic_maps,node_apple_maps,node_apple_matrix,node_ace_maps,node_sol_maps,node_dip_defs toneAmber
class node_architecture toneMint
class node_buffer,node_output_hook,node_virtual_io,node_physical_io toneRose
class node_keyboard,node_host toneIndigo
```

## Components

### Runtime core

- [Scheduler loop](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/main.c): `src/main.c`
- [Scan and actions](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf.c): `src/asdf.c`
- [Debounce scanner](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_physical.c): `src/asdf_physical.c`
- [Modifier state](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_modifiers.h): `src/asdf_modifiers.h`
- [Key repeat](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_repeat.c): `src/asdf_repeat.c`

### Keymap selection

- [Map registry](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_keymaps.c): `src/asdf_keymaps.c`
- [Classic maps](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Keymaps/asdf_keymap_classic_add_map.c): `src/Keymaps/asdf_keymap_classic_add_map.c`
- [Apple II maps](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Keymaps/asdf_keymap_apple2_add_map.c): `src/Keymaps/asdf_keymap_apple2_add_map.c`
- [Apple II layout](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Keymaps/asdf_keymap_apple2_matrix.c): `src/Keymaps/asdf_keymap_apple2_matrix.c`
- [ACE 1000 maps](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Keymaps/asdf_keymap_ace1000_add_map.c): `src/Keymaps/asdf_keymap_ace1000_add_map.c`
- [Sol-20 map](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Keymaps/asdf_keymap_sol.c): `src/Keymaps/asdf_keymap_sol.c`
- [DIP switch actions](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Keymaps/asdf_keymap_defs_dipswitch.h): `src/Keymaps/asdf_keymap_defs_dipswitch.h`

### Hardware ports

- [Matrix hardware ports](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/Arch/asdf_arch_atmega2560.c): `src/Arch/asdf_arch_atmega2560.c`

### Output and resources

- [Code buffer](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_buffer.c): `src/asdf_buffer.c`
- [Output hooks](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_hook.c): `src/asdf_hook.c`
- [Virtual outputs](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_virtual.c): `src/asdf_virtual.c`
- [Physical resources](https://github.com/unified-retro-keyboard/asdf-firmware/blob/main/src/asdf_physical.c): `src/asdf_physical.c`

### Other components

- **Physical keyboard**
- **Host computer**

## Connections

- Physical keyboard → Matrix hardware ports: matrix signals
- Scheduler loop → Scan and actions: initializes and scans (evidence: `src/main.c`)
- Scheduler loop → Matrix hardware ports: checks tick (evidence: `src/main.c`)
- Matrix hardware ports → Debounce scanner: provides row reads
- Scan and actions → Debounce scanner: reads key states (evidence: `src/asdf.c`)
- Scan and actions → Map registry: looks up codes (evidence: `src/asdf.c`)
- Scan and actions → Modifier state: uses modifier state (evidence: `src/asdf.c`)
- Scan and actions → Key repeat: manages repeat (evidence: `src/asdf.c`)
- Scan and actions → Code buffer: buffers codes (evidence: `src/asdf.c`)
- Scan and actions → Virtual outputs: activates outputs (evidence: `src/asdf.c`)
- Map registry → Virtual outputs: resets resources (evidence: `src/asdf_keymaps.c`)
- Map registry → Output hooks: resets hooks (evidence: `src/asdf_keymaps.c`)
- Classic maps → Map registry: registers maps (evidence: `src/Keymaps/asdf_keymap_classic_add_map.c`)
- Apple II maps → Map registry: registers maps (evidence: `src/Keymaps/asdf_keymap_apple2_add_map.c`)
- Apple II layout → Apple II maps: defines layout
- ACE 1000 maps → Map registry: registers maps (evidence: `src/Keymaps/asdf_keymap_ace1000_add_map.c`)
- Sol-20 map → Map registry: registers maps
- DIP switch actions → Map registry: selects map
- Scheduler loop → Code buffer: reads next code (evidence: `src/main.c`)
- Scheduler loop → Output hooks: dispatches output (evidence: `src/main.c`)
- Output hooks → Host computer: sends codes
- Virtual outputs → Physical resources: assigns resources (evidence: `src/asdf_virtual.c`)
- Physical resources → Matrix hardware ports: drives hardware