# mintythecoder/ksp-macropad architecture

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

- Interactive diagram: https://gitdiagram.com/mintythecoder/ksp-macropad
- Repository: https://github.com/mintythecoder/ksp-macropad
- Video tour (about a minute): https://gitdiagram.com/mintythecoder/ksp-macropad/video

## Overview

KSP MacroPad is a physical control surface and companion Kerbal Space Program plugin: button presses and encoder turns travel from the CircuitPython pad over USB serial, trigger in-game procedures, and return game-state feedback for the pad’s LEDs and OLED. The README documents a broad set of flight macros, telemetry, and optional compatibility checks. Sampled firmware and mod excerpts support the serial, input, and feedback links; macro capabilities and hardware design are documented, but their full implementation was not sampled.

Main entry points: [`mod/KSPMacropad/KSPMacropad.cs`](https://github.com/mintythecoder/ksp-macropad/blob/main/mod/KSPMacropad/KSPMacropad.cs) (Port discovery and framing), [`PCB/KSPMacroPad.kicad_pcb`](https://github.com/mintythecoder/ksp-macropad/blob/main/PCB/KSPMacroPad.kicad_pcb) (MacroPad), [`Firmware/code.py`](https://github.com/mintythecoder/ksp-macropad/blob/main/Firmware/code.py) (USB serial protocol), [`mod/KSPMacropad`](https://github.com/mintythecoder/ksp-macropad/tree/main/mod/KSPMacropad) (Flight procedures)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hardware["Pad hardware"]
  node_pad["MacroPad"]
  node_pcb_design["PCB and components"]
end

subgraph group_firmware["Pad firmware"]
  node_firmware_input["Key and encoder input<br/>[code.py]"]
  node_firmware_serial["USB serial protocol<br/>[code.py]"]
  node_firmware_feedback["LED and OLED feedback<br/>[code.py]"]
  node_led_states["LED state constants<br/>[led_states.py]"]
  node_boot["USB CDC setup<br/>[boot.py]"]
end

subgraph group_plugin["KSP plugin"]
  node_mod_serial["Port discovery and framing<br/>[KSPMacropad.cs]"]
  node_mod_dispatch["Macro dispatch and queue<br/>[KSPMacropad.cs]"]
  node_flight_macros["Flight procedures"]
  node_flight_state["Game state and telemetry<br/>[KSPMacropad.cs]"]
  node_mod_feedback["LED and telemetry updates<br/>[KSPMacropad.cs]"]
  node_mod_led_states["LED state constants<br/>[LEDStates.cs]"]
end

subgraph group_design["Physical design"]
  node_case_design["Parametric case"]
  node_production_parts["Printable case parts<br/>[case_bottom.stl]"]
end

node_player(("Player"))
node_ksp(("Kerbal Space Program"))
node_optional_mods(("Optional KSP mods"))

node_player -->|"operates"| node_pad
node_pad -->|"provides inputs"| node_firmware_input
node_firmware_input -->|"sends events"| node_firmware_serial
node_boot -->|"enables data port"| node_firmware_serial
node_firmware_serial -->|"sends packets"| node_mod_serial
node_mod_serial -->|"dispatches events"| node_mod_dispatch
node_mod_dispatch -->|"starts procedures"| node_flight_macros
node_flight_macros -->|"controls vessel"| node_ksp
node_ksp -->|"provides live state"| node_flight_state
node_flight_state -->|"supplies telemetry"| node_mod_feedback
node_mod_feedback -->|"writes packets"| node_mod_serial
node_mod_serial -->|"sends updates"| node_firmware_feedback
node_firmware_feedback -->|"drives LEDs and OLED"| node_pad
node_mod_led_states -->|"defines states"| node_mod_feedback
node_led_states -->|"defines states"| node_firmware_feedback
node_optional_mods -.->|"may conflict"| node_flight_macros
node_pcb_design -->|"defines circuitry"| node_pad
node_case_design -->|"models parts"| node_production_parts

click node_pad "https://github.com/mintythecoder/ksp-macropad/blob/main/PCB/KSPMacroPad.kicad_pcb"
click node_firmware_input "https://github.com/mintythecoder/ksp-macropad/blob/main/Firmware/code.py"
click node_firmware_serial "https://github.com/mintythecoder/ksp-macropad/blob/main/Firmware/code.py"
click node_firmware_feedback "https://github.com/mintythecoder/ksp-macropad/blob/main/Firmware/code.py"
click node_led_states "https://github.com/mintythecoder/ksp-macropad/blob/main/Firmware/led_states.py"
click node_boot "https://github.com/mintythecoder/ksp-macropad/blob/main/Firmware/boot.py"
click node_mod_serial "https://github.com/mintythecoder/ksp-macropad/blob/main/mod/KSPMacropad/KSPMacropad.cs"
click node_mod_dispatch "https://github.com/mintythecoder/ksp-macropad/blob/main/mod/KSPMacropad/KSPMacropad.cs"
click node_flight_macros "https://github.com/mintythecoder/ksp-macropad/tree/main/mod/KSPMacropad"
click node_flight_state "https://github.com/mintythecoder/ksp-macropad/blob/main/mod/KSPMacropad/KSPMacropad.cs"
click node_mod_feedback "https://github.com/mintythecoder/ksp-macropad/blob/main/mod/KSPMacropad/KSPMacropad.cs"
click node_mod_led_states "https://github.com/mintythecoder/ksp-macropad/blob/main/mod/KSPMacropad/LEDStates.cs"
click node_pcb_design "https://github.com/mintythecoder/ksp-macropad/blob/main/PCB/KSPMacroPad.kicad_sch"
click node_case_design "https://github.com/mintythecoder/ksp-macropad/blob/main/CAD/ksp_macropad_case.scad"
click node_production_parts "https://github.com/mintythecoder/ksp-macropad/blob/main/production/case_bottom.stl"

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_pad,node_pcb_design toneBlue
class node_firmware_input,node_firmware_serial,node_firmware_feedback,node_led_states,node_boot toneAmber
class node_mod_serial,node_mod_dispatch,node_flight_macros,node_flight_state,node_mod_feedback,node_mod_led_states toneMint
class node_case_design,node_production_parts toneRose
class node_player,node_ksp,node_optional_mods toneIndigo
```

## Components

### Pad hardware

- [MacroPad](https://github.com/mintythecoder/ksp-macropad/blob/main/PCB/KSPMacroPad.kicad_pcb): `PCB/KSPMacroPad.kicad_pcb`
- [PCB and components](https://github.com/mintythecoder/ksp-macropad/blob/main/PCB/KSPMacroPad.kicad_sch): `PCB/KSPMacroPad.kicad_sch`

### Pad firmware

- [Key and encoder input](https://github.com/mintythecoder/ksp-macropad/blob/main/Firmware/code.py): `Firmware/code.py`
- [USB serial protocol](https://github.com/mintythecoder/ksp-macropad/blob/main/Firmware/code.py): `Firmware/code.py`
- [LED and OLED feedback](https://github.com/mintythecoder/ksp-macropad/blob/main/Firmware/code.py): `Firmware/code.py`
- [LED state constants](https://github.com/mintythecoder/ksp-macropad/blob/main/Firmware/led_states.py): `Firmware/led_states.py`
- [USB CDC setup](https://github.com/mintythecoder/ksp-macropad/blob/main/Firmware/boot.py): `Firmware/boot.py`

### KSP plugin

- [Port discovery and framing](https://github.com/mintythecoder/ksp-macropad/blob/main/mod/KSPMacropad/KSPMacropad.cs): `mod/KSPMacropad/KSPMacropad.cs`
- [Macro dispatch and queue](https://github.com/mintythecoder/ksp-macropad/blob/main/mod/KSPMacropad/KSPMacropad.cs): `mod/KSPMacropad/KSPMacropad.cs`
- [Flight procedures](https://github.com/mintythecoder/ksp-macropad/tree/main/mod/KSPMacropad): `mod/KSPMacropad`
- [Game state and telemetry](https://github.com/mintythecoder/ksp-macropad/blob/main/mod/KSPMacropad/KSPMacropad.cs): `mod/KSPMacropad/KSPMacropad.cs`
- [LED and telemetry updates](https://github.com/mintythecoder/ksp-macropad/blob/main/mod/KSPMacropad/KSPMacropad.cs): `mod/KSPMacropad/KSPMacropad.cs`
- [LED state constants](https://github.com/mintythecoder/ksp-macropad/blob/main/mod/KSPMacropad/LEDStates.cs): `mod/KSPMacropad/LEDStates.cs`

### Physical design

- [Parametric case](https://github.com/mintythecoder/ksp-macropad/blob/main/CAD/ksp_macropad_case.scad): `CAD/ksp_macropad_case.scad`
- [Printable case parts](https://github.com/mintythecoder/ksp-macropad/blob/main/production/case_bottom.stl): `production/case_bottom.stl`

### Other components

- **Player**
- **Kerbal Space Program**
- **Optional KSP mods**

## Connections

- Player → MacroPad: operates
- MacroPad → Key and encoder input: provides inputs
- Key and encoder input → USB serial protocol: sends events
- USB CDC setup → USB serial protocol: enables data port
- USB serial protocol → Port discovery and framing: sends packets
- Port discovery and framing → Macro dispatch and queue: dispatches events
- Macro dispatch and queue → Flight procedures: starts procedures
- Flight procedures → Kerbal Space Program: controls vessel
- Kerbal Space Program → Game state and telemetry: provides live state
- Game state and telemetry → LED and telemetry updates: supplies telemetry
- LED and telemetry updates → Port discovery and framing: writes packets
- Port discovery and framing → LED and OLED feedback: sends updates
- LED and OLED feedback → MacroPad: drives LEDs and OLED
- LED state constants → LED and telemetry updates: defines states
- LED state constants → LED and OLED feedback: defines states
- Optional KSP mods → Flight procedures: may conflict
- PCB and components → MacroPad: defines circuitry
- Parametric case → Printable case parts: models parts