# limitlabs/fw-glyph architecture

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

- Interactive diagram: https://gitdiagram.com/limitlabs/fw-glyph
- Repository: https://github.com/limitlabs/fw-glyph

## Overview

Glyph is controller firmware that scans physical controls, applies configurable game-specific mappings, and exposes controller reports over USB or console protocols. The tree also shows configuration/display, persistence, and RGB features. Sampled code confirms the input-state transformation and display-control behavior; the top-level runtime loop and several backend integrations were not sampled, so their wiring is represented only where the tree or code supports it.

Main entry points: [`include/core/state.hpp`](https://github.com/limitlabs/fw-glyph/blob/configurator/include/core/state.hpp) (Input State), [`src/core/ControllerMode.cpp`](https://github.com/limitlabs/fw-glyph/blob/configurator/src/core/ControllerMode.cpp) (Controller Mode), [`HAL/pico/src/comms/backend_init.cpp`](https://github.com/limitlabs/fw-glyph/blob/configurator/HAL/pico/src/comms/backend_init.cpp) (Backend Dispatch), [`config/glyph/common/include/glyph_overrides.hpp`](https://github.com/limitlabs/fw-glyph/blob/configurator/config/glyph/common/include/glyph_overrides.hpp) (Glyph Defaults)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input Hardware"]
  node_matrix["Switch Matrix"]
  node_gpio["GPIO Input"]
  node_gcinput["GameCube Input"]
end

subgraph group_mapping["Mode Processing"]
  node_state["Input State<br/>[state.hpp]"]
  node_selector["Mode Selection<br/>[mode_selection.cpp]"]
  node_mode["Controller Mode<br/>[ControllerMode.cpp]"]
  node_custom["Custom Mapping"]
  node_socd["SOCD Rules<br/>[socd.cpp]"]
  node_gamemodes["Game Modes"]
end

subgraph group_outputs["Controller Outputs"]
  node_backends["Backend Dispatch<br/>[backend_init.cpp]"]
  node_usb["USB HID<br/>[DInputBackend.cpp]"]
  node_console["Console Protocols"]
end

subgraph group_device["Configuration Device"]
  node_config["Glyph Defaults"]
  node_persistence["Config Persistence<br/>[Persistence.cpp]"]
  node_display["Integrated Display"]
  node_menus["Display Menus"]
  node_rgb["RGB Lighting<br/>[LEDTemplates.cpp]"]
end

node_player(("Player Controls"))
node_host(("Game Host"))
node_configurator(("Configurator"))

node_player -->|"presses"| node_matrix
node_matrix -->|"sets buttons"| node_state
node_player -->|"presses"| node_gpio
node_gpio -->|"scans buttons"| node_state
node_player -->|"uses controller"| node_gcinput
node_gcinput -->|"updates stick"| node_state
node_state -->|"provides inputs"| node_mode
node_mode -->|"resolves directions"| node_socd
node_mode -.->|"custom mode"| node_custom
node_selector -->|"selects mode"| node_gamemodes
node_config -->|"defines modes"| node_selector
node_config -->|"defines colors"| node_rgb
node_configurator -.->|"configures device"| node_backends
node_backends -->|"initializes"| node_usb
node_backends -->|"initializes"| node_console
node_usb -->|"sends reports"| node_host
node_console -->|"sends reports"| node_host
node_display -->|"updates display"| node_menus
node_menus -.->|"stores settings"| node_persistence

click node_matrix "https://github.com/limitlabs/fw-glyph/blob/configurator/include/input/SwitchMatrixInput.hpp"
click node_gpio "https://github.com/limitlabs/fw-glyph/blob/configurator/src/input/GpioButtonInput.cpp"
click node_gcinput "https://github.com/limitlabs/fw-glyph/blob/configurator/HAL/pico/src/input/GamecubeControllerInput.cpp"
click node_state "https://github.com/limitlabs/fw-glyph/blob/configurator/include/core/state.hpp"
click node_selector "https://github.com/limitlabs/fw-glyph/blob/configurator/src/core/mode_selection.cpp"
click node_mode "https://github.com/limitlabs/fw-glyph/blob/configurator/src/core/ControllerMode.cpp"
click node_custom "https://github.com/limitlabs/fw-glyph/blob/configurator/src/modes/CustomControllerMode.cpp"
click node_socd "https://github.com/limitlabs/fw-glyph/blob/configurator/src/core/socd.cpp"
click node_gamemodes "https://github.com/limitlabs/fw-glyph/tree/configurator/src/modes"
click node_config "https://github.com/limitlabs/fw-glyph/blob/configurator/config/glyph/common/include/glyph_overrides.hpp"
click node_persistence "https://github.com/limitlabs/fw-glyph/blob/configurator/HAL/pico/src/core/Persistence.cpp"
click node_display "https://github.com/limitlabs/fw-glyph/blob/configurator/src/comms/IntegratedDisplay.cpp"
click node_menus "https://github.com/limitlabs/fw-glyph/tree/configurator/HAL/pico/src/display"
click node_rgb "https://github.com/limitlabs/fw-glyph/blob/configurator/config/glyph/common/src/LEDTemplates.cpp"
click node_backends "https://github.com/limitlabs/fw-glyph/blob/configurator/HAL/pico/src/comms/backend_init.cpp"
click node_usb "https://github.com/limitlabs/fw-glyph/blob/configurator/HAL/pico/src/comms/DInputBackend.cpp"
click node_console "https://github.com/limitlabs/fw-glyph/tree/configurator/HAL/pico/src/comms"

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_matrix,node_gpio,node_gcinput toneBlue
class node_state,node_selector,node_mode,node_custom,node_socd,node_gamemodes toneAmber
class node_backends,node_usb,node_console toneMint
class node_config,node_persistence,node_display,node_menus,node_rgb toneRose
class node_player,node_host,node_configurator toneIndigo
```

## Components

### Input Hardware

- [Switch Matrix](https://github.com/limitlabs/fw-glyph/blob/configurator/include/input/SwitchMatrixInput.hpp): `include/input/SwitchMatrixInput.hpp`
- [GPIO Input](https://github.com/limitlabs/fw-glyph/blob/configurator/src/input/GpioButtonInput.cpp): `src/input/GpioButtonInput.cpp`
- [GameCube Input](https://github.com/limitlabs/fw-glyph/blob/configurator/HAL/pico/src/input/GamecubeControllerInput.cpp): `HAL/pico/src/input/GamecubeControllerInput.cpp`

### Mode Processing

- [Input State](https://github.com/limitlabs/fw-glyph/blob/configurator/include/core/state.hpp): `include/core/state.hpp`
- [Mode Selection](https://github.com/limitlabs/fw-glyph/blob/configurator/src/core/mode_selection.cpp): `src/core/mode_selection.cpp`
- [Controller Mode](https://github.com/limitlabs/fw-glyph/blob/configurator/src/core/ControllerMode.cpp): `src/core/ControllerMode.cpp`
- [Custom Mapping](https://github.com/limitlabs/fw-glyph/blob/configurator/src/modes/CustomControllerMode.cpp): `src/modes/CustomControllerMode.cpp`
- [SOCD Rules](https://github.com/limitlabs/fw-glyph/blob/configurator/src/core/socd.cpp): `src/core/socd.cpp`
- [Game Modes](https://github.com/limitlabs/fw-glyph/tree/configurator/src/modes): `src/modes`

### Controller Outputs

- [Backend Dispatch](https://github.com/limitlabs/fw-glyph/blob/configurator/HAL/pico/src/comms/backend_init.cpp): `HAL/pico/src/comms/backend_init.cpp`
- [USB HID](https://github.com/limitlabs/fw-glyph/blob/configurator/HAL/pico/src/comms/DInputBackend.cpp): `HAL/pico/src/comms/DInputBackend.cpp`
- [Console Protocols](https://github.com/limitlabs/fw-glyph/tree/configurator/HAL/pico/src/comms): `HAL/pico/src/comms`

### Configuration Device

- [Glyph Defaults](https://github.com/limitlabs/fw-glyph/blob/configurator/config/glyph/common/include/glyph_overrides.hpp): `config/glyph/common/include/glyph_overrides.hpp`
- [Config Persistence](https://github.com/limitlabs/fw-glyph/blob/configurator/HAL/pico/src/core/Persistence.cpp): `HAL/pico/src/core/Persistence.cpp`
- [Integrated Display](https://github.com/limitlabs/fw-glyph/blob/configurator/src/comms/IntegratedDisplay.cpp): `src/comms/IntegratedDisplay.cpp`
- [Display Menus](https://github.com/limitlabs/fw-glyph/tree/configurator/HAL/pico/src/display): `HAL/pico/src/display`
- [RGB Lighting](https://github.com/limitlabs/fw-glyph/blob/configurator/config/glyph/common/src/LEDTemplates.cpp): `config/glyph/common/src/LEDTemplates.cpp`

### Other components

- **Player Controls**
- **Game Host**
- **Configurator**

## Connections

- Player Controls → Switch Matrix: presses
- Switch Matrix → Input State: sets buttons
- Player Controls → GPIO Input: presses
- GPIO Input → Input State: scans buttons
- Player Controls → GameCube Input: uses controller
- GameCube Input → Input State: updates stick
- Input State → Controller Mode: provides inputs
- Controller Mode → SOCD Rules: resolves directions
- Controller Mode → Custom Mapping: custom mode
- Mode Selection → Game Modes: selects mode
- Glyph Defaults → Mode Selection: defines modes
- Glyph Defaults → RGB Lighting: defines colors
- Configurator → Backend Dispatch: configures device
- Backend Dispatch → USB HID: initializes
- Backend Dispatch → Console Protocols: initializes
- USB HID → Game Host: sends reports
- Console Protocols → Game Host: sends reports
- Integrated Display → Display Menus: updates display
- Display Menus → Config Persistence: stores settings