# klipper3d/klipper architecture

> Architecture diagram of the GitHub repository klipper3d/klipper, 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/klipper3d/klipper
- Repository: https://github.com/klipper3d/klipper
- Video tour (about a minute): https://gitdiagram.com/klipper3d/klipper/video

## Overview

Klipper controls 3D printers by pairing host-side printer orchestration with one or more MCU firmware runtimes. The main workflow accepts printer configuration and G-code, plans motion, translates it into timed stepper activity, and communicates commands to MCU firmware that drives hardware. Host extensions add sensing, temperature control, calibration, and user-facing status features. The README establishes the host-plus-MCU product boundary; sampled sources confirm selected extension and MCU runtime behavior, while detailed host wiring and most extension interactions are inferred only at subsystem level.

Main entry points: [`klippy/klippy.py`](https://github.com/klipper3d/klipper/blob/master/klippy/klippy.py) (Printer runtime), [`klippy/extras`](https://github.com/klipper3d/klipper/tree/master/klippy/extras) (Printer extensions), [`klippy/mcu.py`](https://github.com/klipper3d/klipper/blob/master/klippy/mcu.py) (MCU transport), [`klippy/gcode.py`](https://github.com/klipper3d/klipper/blob/master/klippy/gcode.py) (G-code)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host control"]
  node_config["Configuration<br/>[configfile.py]"]
  node_hostcore["Printer runtime<br/>[klippy.py]"]
  node_gcode["G-code<br/>[gcode.py]"]
end

subgraph group_motion["Motion execution"]
  node_toolhead["Motion planner<br/>[toolhead.py]"]
  node_kinematics["Kinematics<br/>[__init__.py]"]
  node_stepper["Stepper control<br/>[stepper.py]"]
  node_chelper["Motion engine<br/>[itersolve.c]"]
end

subgraph group_hardware["Printer features"]
  node_extras["Printer extensions"]
  node_heaters["Heater control<br/>[heaters.py]"]
  node_sensors["Sensors"]
  node_display["Display and menu<br/>[display.py]"]
end

subgraph group_firmware["MCU firmware"]
  node_mcu["MCU transport<br/>[mcu.py]"]
  node_serial["Serial protocol<br/>[serialhdl.py]"]
  node_clocks["Clock synchronization<br/>[clocksync.py]"]
  node_mcu_runtime["MCU scheduler<br/>[main.c]"]
end

node_operator(("Printer operator"))
node_printer["Printer hardware"]

node_operator -->|"configures"| node_config
node_operator -->|"submits commands"| node_gcode
node_config -->|"configures runtime"| node_hostcore
node_hostcore -->|"dispatches commands"| node_gcode
node_gcode -->|"requests motion"| node_toolhead
node_toolhead -->|"plans axes"| node_kinematics
node_kinematics -->|"maps movement"| node_stepper
node_stepper -->|"queues steps"| node_chelper
node_hostcore -->|"manages MCU"| node_mcu
node_mcu -->|"sends commands"| node_serial
node_mcu -->|"synchronizes clocks"| node_clocks
node_serial -->|"transfers protocol"| node_mcu_runtime
node_mcu_runtime -->|"drives hardware"| node_printer
node_hostcore -->|"loads extensions"| node_extras
node_extras -->|"provides control"| node_heaters
node_extras -->|"provides sensing"| node_sensors
node_extras -->|"provides interface"| node_display
node_heaters -->|"controls temperature"| node_printer
node_sensors -->|"reads measurements"| node_printer
node_display -->|"shows status"| node_operator

click node_config "https://github.com/klipper3d/klipper/blob/master/klippy/configfile.py"
click node_hostcore "https://github.com/klipper3d/klipper/blob/master/klippy/klippy.py"
click node_gcode "https://github.com/klipper3d/klipper/blob/master/klippy/gcode.py"
click node_toolhead "https://github.com/klipper3d/klipper/blob/master/klippy/toolhead.py"
click node_kinematics "https://github.com/klipper3d/klipper/blob/master/klippy/kinematics/__init__.py"
click node_stepper "https://github.com/klipper3d/klipper/blob/master/klippy/stepper.py"
click node_chelper "https://github.com/klipper3d/klipper/blob/master/klippy/chelper/itersolve.c"
click node_mcu "https://github.com/klipper3d/klipper/blob/master/klippy/mcu.py"
click node_serial "https://github.com/klipper3d/klipper/blob/master/klippy/serialhdl.py"
click node_clocks "https://github.com/klipper3d/klipper/blob/master/klippy/clocksync.py"
click node_mcu_runtime "https://github.com/klipper3d/klipper/blob/master/src/rp2040/main.c"
click node_extras "https://github.com/klipper3d/klipper/tree/master/klippy/extras"
click node_heaters "https://github.com/klipper3d/klipper/blob/master/klippy/extras/heaters.py"
click node_sensors "https://github.com/klipper3d/klipper/tree/master/klippy/extras"
click node_display "https://github.com/klipper3d/klipper/blob/master/klippy/extras/display/display.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_config,node_hostcore,node_gcode toneBlue
class node_toolhead,node_kinematics,node_stepper,node_chelper toneAmber
class node_extras,node_heaters,node_sensors,node_display toneMint
class node_mcu,node_serial,node_clocks,node_mcu_runtime toneRose
class node_operator,node_printer toneIndigo
```

## Components

### Host control

- [Configuration](https://github.com/klipper3d/klipper/blob/master/klippy/configfile.py): `klippy/configfile.py`
- [Printer runtime](https://github.com/klipper3d/klipper/blob/master/klippy/klippy.py): `klippy/klippy.py`
- [G-code](https://github.com/klipper3d/klipper/blob/master/klippy/gcode.py): `klippy/gcode.py`

### Motion execution

- [Motion planner](https://github.com/klipper3d/klipper/blob/master/klippy/toolhead.py): `klippy/toolhead.py`
- [Kinematics](https://github.com/klipper3d/klipper/blob/master/klippy/kinematics/__init__.py): `klippy/kinematics/__init__.py`
- [Stepper control](https://github.com/klipper3d/klipper/blob/master/klippy/stepper.py): `klippy/stepper.py`
- [Motion engine](https://github.com/klipper3d/klipper/blob/master/klippy/chelper/itersolve.c): `klippy/chelper/itersolve.c`

### Printer features

- [Printer extensions](https://github.com/klipper3d/klipper/tree/master/klippy/extras): `klippy/extras`
- [Heater control](https://github.com/klipper3d/klipper/blob/master/klippy/extras/heaters.py): `klippy/extras/heaters.py`
- [Sensors](https://github.com/klipper3d/klipper/tree/master/klippy/extras): `klippy/extras`
- [Display and menu](https://github.com/klipper3d/klipper/blob/master/klippy/extras/display/display.py): `klippy/extras/display/display.py`

### MCU firmware

- [MCU transport](https://github.com/klipper3d/klipper/blob/master/klippy/mcu.py): `klippy/mcu.py`
- [Serial protocol](https://github.com/klipper3d/klipper/blob/master/klippy/serialhdl.py): `klippy/serialhdl.py`
- [Clock synchronization](https://github.com/klipper3d/klipper/blob/master/klippy/clocksync.py): `klippy/clocksync.py`
- [MCU scheduler](https://github.com/klipper3d/klipper/blob/master/src/rp2040/main.c): `src/rp2040/main.c`

### Other components

- **Printer operator**
- **Printer hardware**

## Connections

- Printer operator → Configuration: configures
- Printer operator → G-code: submits commands
- Configuration → Printer runtime: configures runtime
- Printer runtime → G-code: dispatches commands
- G-code → Motion planner: requests motion
- Motion planner → Kinematics: plans axes
- Kinematics → Stepper control: maps movement
- Stepper control → Motion engine: queues steps
- Printer runtime → MCU transport: manages MCU
- MCU transport → Serial protocol: sends commands
- MCU transport → Clock synchronization: synchronizes clocks
- Serial protocol → MCU scheduler: transfers protocol
- MCU scheduler → Printer hardware: drives hardware
- Printer runtime → Printer extensions: loads extensions
- Printer extensions → Heater control: provides control
- Printer extensions → Sensors: provides sensing
- Printer extensions → Display and menu: provides interface
- Heater control → Printer hardware: controls temperature
- Sensors → Printer hardware: reads measurements
- Display and menu → Printer operator: shows status
