# paulw/rp2040-keyboard-converter architecture

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

- Interactive diagram: https://gitdiagram.com/paulw/rp2040-keyboard-converter
- Repository: https://github.com/paulw/rp2040-keyboard-converter

## Overview

This firmware converts legacy keyboard and mouse input into USB HID reports on an RP2040. Its principal workflow is protocol-specific input handling, scancode translation, then HID reporting to the host; the main loop also services USB and command mode. README-listed features include persistent settings and multiple keyboard protocols. The excerpts establish main-loop setup and task responsibilities, while the source index supplies some module references; unsampled dispatch details are not inferred.

Main entry points: [`src/main.c`](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/main.c) (Firmware loop), [`src/common/lib/hid_interface.c`](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/common/lib/hid_interface.c) (USB HID reports), [`src/protocols/at-ps2/keyboard_interface.c`](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/protocols/at-ps2/keyboard_interface.c) (AT/PS2 keyboard), [`src/scancodes/set1/scancode.c`](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/scancodes/set1/scancode.c) (Set 1 translation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and controls"]
  node_main["Firmware loop<br/>[main.c]"]
  node_command["Command mode<br/>[command_mode.c]"]
  node_config[("Persistent settings<br/>[config_storage.c]")]
  node_keyboard_profiles["Keyboard profiles"]
end

subgraph group_interfaces["Input protocols"]
  node_at_keyboard["AT/PS2 keyboard"]
  node_at_mouse["AT/PS2 mouse<br/>[mouse_interface.c]"]
  node_at_common["AT/PS2 common<br/>[common_interface.c]"]
  node_xt["XT keyboard"]
  node_amiga["Amiga keyboard"]
  node_apple["Apple M0110"]
end

subgraph group_translation["Scan translation"]
  node_set1["Set 1 translation<br/>[scancode.c]"]
  node_set123["Set 1/2/3 translation<br/>[scancode.c]"]
  node_other_scans["Other scan sets"]
end

subgraph group_services["HID and support"]
  node_hid["USB HID reports<br/>[hid_interface.c]"]
  node_keymaps["Keymaps and layers<br/>[keymaps.c]"]
  node_led["Status LEDs<br/>[ws2812.c]"]
  node_flow["Flow tracking<br/>[flow_tracker.h]"]
end

node_user(("Keyboard or mouse"))
node_host(("USB host"))

node_user -->|"sends input"| node_at_keyboard
node_user -->|"sends input"| node_at_mouse
node_main -->|"initializes"| node_config
node_main -->|"initializes, tasks"| node_command
node_main -->|"sets up"| node_hid
node_main -->|"runs task"| node_at_keyboard
node_main -->|"runs task"| node_at_mouse
node_main -->|"services USB"| node_host
node_at_keyboard -->|"uses"| node_at_common
node_at_mouse -->|"uses"| node_at_common
node_at_keyboard -->|"processes with"| node_set1
node_at_keyboard -->|"processes with"| node_set123
node_xt -->|"processes with"| node_set1
node_amiga -->|"uses"| node_set1
node_apple -->|"uses"| node_set1
node_set1 -->|"submits scancodes"| node_hid
node_set123 -->|"submits scancodes"| node_hid
node_other_scans -.->|"submits scancodes"| node_hid
node_hid -->|"sends reports"| node_host
node_hid -->|"looks up keys"| node_keymaps
node_main -.->|"selects profile"| node_keyboard_profiles
node_main -->|"sets up"| node_led
node_main -->|"initializes"| node_flow

click node_main "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/main.c"
click node_command "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/common/lib/command_mode.c"
click node_config "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/common/lib/config_storage.c"
click node_keyboard_profiles "https://github.com/paulw/rp2040-keyboard-converter/tree/main/src/keyboards"
click node_at_keyboard "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/protocols/at-ps2/keyboard_interface.c"
click node_at_mouse "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/protocols/at-ps2/mouse_interface.c"
click node_at_common "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/protocols/at-ps2/common_interface.c"
click node_xt "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/protocols/xt/keyboard_interface.c"
click node_amiga "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/protocols/amiga/keyboard_interface.c"
click node_apple "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/protocols/apple-m0110/keyboard_interface.c"
click node_set1 "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/scancodes/set1/scancode.c"
click node_set123 "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/scancodes/set123/scancode.c"
click node_other_scans "https://github.com/paulw/rp2040-keyboard-converter/tree/main/src/scancodes"
click node_hid "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/common/lib/hid_interface.c"
click node_keymaps "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/common/lib/keymaps.c"
click node_led "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/common/lib/ws2812/ws2812.c"
click node_flow "https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/common/lib/flow_tracker.h"

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_main,node_command,node_config,node_keyboard_profiles toneBlue
class node_at_keyboard,node_at_mouse,node_at_common,node_xt,node_amiga,node_apple toneAmber
class node_set1,node_set123,node_other_scans toneMint
class node_hid,node_keymaps,node_led,node_flow toneRose
class node_user,node_host toneIndigo
```

## Components

### Runtime and controls

- [Firmware loop](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/main.c): `src/main.c`
- [Command mode](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/common/lib/command_mode.c): `src/common/lib/command_mode.c`
- [Persistent settings](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/common/lib/config_storage.c): `src/common/lib/config_storage.c`
- [Keyboard profiles](https://github.com/paulw/rp2040-keyboard-converter/tree/main/src/keyboards): `src/keyboards`

### Input protocols

- [AT/PS2 keyboard](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/protocols/at-ps2/keyboard_interface.c): `src/protocols/at-ps2/keyboard_interface.c`
- [AT/PS2 mouse](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/protocols/at-ps2/mouse_interface.c): `src/protocols/at-ps2/mouse_interface.c`
- [AT/PS2 common](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/protocols/at-ps2/common_interface.c): `src/protocols/at-ps2/common_interface.c`
- [XT keyboard](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/protocols/xt/keyboard_interface.c): `src/protocols/xt/keyboard_interface.c`
- [Amiga keyboard](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/protocols/amiga/keyboard_interface.c): `src/protocols/amiga/keyboard_interface.c`
- [Apple M0110](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/protocols/apple-m0110/keyboard_interface.c): `src/protocols/apple-m0110/keyboard_interface.c`

### Scan translation

- [Set 1 translation](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/scancodes/set1/scancode.c): `src/scancodes/set1/scancode.c`
- [Set 1/2/3 translation](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/scancodes/set123/scancode.c): `src/scancodes/set123/scancode.c`
- [Other scan sets](https://github.com/paulw/rp2040-keyboard-converter/tree/main/src/scancodes): `src/scancodes`

### HID and support

- [USB HID reports](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/common/lib/hid_interface.c): `src/common/lib/hid_interface.c`
- [Keymaps and layers](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/common/lib/keymaps.c): `src/common/lib/keymaps.c`
- [Status LEDs](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/common/lib/ws2812/ws2812.c): `src/common/lib/ws2812/ws2812.c`
- [Flow tracking](https://github.com/paulw/rp2040-keyboard-converter/blob/main/src/common/lib/flow_tracker.h): `src/common/lib/flow_tracker.h`

### Other components

- **Keyboard or mouse**
- **USB host**

## Connections

- Keyboard or mouse → AT/PS2 keyboard: sends input
- Keyboard or mouse → AT/PS2 mouse: sends input
- Firmware loop → Persistent settings: initializes (evidence: `src/main.c`)
- Firmware loop → Command mode: initializes, tasks (evidence: `src/main.c`)
- Firmware loop → USB HID reports: sets up (evidence: `src/main.c`)
- Firmware loop → AT/PS2 keyboard: runs task (evidence: `src/main.c`)
- Firmware loop → AT/PS2 mouse: runs task (evidence: `src/main.c`)
- Firmware loop → USB host: services USB (evidence: `src/main.c`)
- AT/PS2 keyboard → AT/PS2 common: uses (evidence: `src/protocols/at-ps2/keyboard_interface.c`)
- AT/PS2 mouse → AT/PS2 common: uses (evidence: `src/protocols/at-ps2/mouse_interface.c`)
- AT/PS2 keyboard → Set 1 translation: processes with (evidence: `src/protocols/at-ps2/keyboard_interface.c`)
- AT/PS2 keyboard → Set 1/2/3 translation: processes with (evidence: `src/protocols/at-ps2/keyboard_interface.c`)
- XT keyboard → Set 1 translation: processes with (evidence: `src/protocols/xt/keyboard_interface.c`)
- Amiga keyboard → Set 1 translation: uses (evidence: `src/protocols/amiga/keyboard_interface.c`)
- Apple M0110 → Set 1 translation: uses (evidence: `src/protocols/apple-m0110/keyboard_interface.c`)
- Set 1 translation → USB HID reports: submits scancodes (evidence: `src/scancodes/set1/scancode.c`)
- Set 1/2/3 translation → USB HID reports: submits scancodes (evidence: `src/scancodes/set123/scancode.c`)
- Other scan sets → USB HID reports: submits scancodes
- USB HID reports → USB host: sends reports
- USB HID reports → Keymaps and layers: looks up keys
- Firmware loop → Keyboard profiles: selects profile (evidence: `src/main.c`)
- Firmware loop → Status LEDs: sets up (evidence: `src/main.c`)
- Firmware loop → Flow tracking: initializes (evidence: `src/main.c`)
