Klipper splits printer firmware between a Linux host and one or more microcontrollers. The host interprets G-code, plans motion, and calculates when motors need to step. The MCU performs scheduled hardware operations, including step pulses and sensor reads. The printer’s configuration lives on the host, so most setup changes are text edits followed by a restart.
That architecture explains both the extra computer in the parts list and the short feedback loop when changing settings. This guide follows Klipper’s published code, protocol, and configuration documentation. For board choices and connection requirements, start with Klipper hardware requirements.
The host and MCU have different jobs
The host process is called Klippy. Much of it is Python, with C helpers for work such as generating and compressing step timings. It loads the printer configuration and builds software objects representing the toolhead, extruder, and other configured components. The microcontroller runs separately compiled firmware written in C. These are two cooperating programs with different responsibilities.
| Component | Responsibility | What a change usually affects |
|---|---|---|
| Linux host running Klippy | G-code interpretation, motion planning, configuration | Printer behavior and available host modules |
| MCU firmware | Timed pin operations, step generation, hardware communication | Supported MCU, clock, and transport |
printer.cfg and included files | Wiring assignments, kinematics, limits, macros | The machine definition loaded by Klippy |
| Browser interface | Displays status and sends user requests through its backend | Controls and presentation |
The browser is an access point, not the step scheduler. Klipper’s FAQ documents Mainsail, Fluidd, and OctoPrint as interface choices. Changing the interface does not change the physical board’s processor or make a mismatched pin map correct. This distinction helps locate a problem: a missing browser control and a controller connection failure belong to different parts of the system.
From G-code to a planned move
A move begins with a command such as G1. The host interprets its coordinates in the current G-code state, including absolute or relative positioning and the selected feed rate. It passes the resulting request to the toolhead and kinematics code. A coordinate in a file is therefore an instruction to interpret, not a raw instruction to toggle a motor pin.
Klipper’s kinematics documentation describes look-ahead: the planner considers adjacent moves when choosing speeds at their junctions. It describes each move using acceleration, cruising, and deceleration phases. On short moves, a phase may have zero duration. Setting a high maximum velocity does not guarantee that a short segment reaches that velocity.
The planner then needs a relationship between position and time for each motor. An iterative solver calculates the times at which that motor crosses successive step positions. The host compresses those timings into commands for the MCU. The code overview follows this path from G-code handling to the controller’s timer interrupt.
Kinematics translate head motion into motor motion
A Cartesian axis, a CoreXY belt system, and a delta mechanism require different mappings between the requested tool position and individual motor positions. On CoreXY, X and Y motion involve coordinated movement of both belt motors. On delta machines, the relationship depends on the tower geometry. Selecting a familiar-looking machine name is insufficient; the configured kinematics must match the mechanism.
This is why motor direction and travel checks come before performance tuning. A successful connection only proves that software can communicate. It does not prove that an X request moves the carriage in the intended direction or that a configured travel limit matches the frame. The official configuration checks cover these physical confirmations.
The extruder has its own motion calculation synchronized with the toolhead. Pressure advance adjusts extrusion timing to compensate for pressure changes; it does not replace the kinematics mapping. Use the pressure advance calibration procedure for the actual tuning workflow. Keep the machine definition and material-dependent extrusion tuning as separate decisions.
The host-to-MCU protocol
Klippy communicates with the controller using Klipper’s compact binary protocol. The controller does not receive the original text of every slicer movement and independently repeat the host’s planning. Instead, it receives encoded commands for operations it supports, and sends responses carrying status or measurements.
The protocol reference describes a data dictionary that identifies the commands, parameters, and responses available in a firmware build. The host obtains that dictionary when connecting. Message blocks also carry sequence information and a checksum, allowing the communication layer to detect transmission problems and manage delivery.
This is a local firmware protocol, separate from the browser-facing API. USB, a configured UART, or a supported CAN arrangement provides the connection to the controller. A working web page is not evidence that this lower-level connection is healthy. Conversely, refreshing a browser cannot change the firmware dictionary or repair a mismatched MCU build.
How the MCU turns a schedule into pulses
The controller stores scheduled work and uses hardware timer interrupts to execute it. A step sequence can describe a starting interval, a number of steps, and an interval adjustment. This compact representation lets the MCU produce the scheduled pulses without solving the full printer geometry again.
Startup also configures controller objects for the selected hardware. Klipper’s MCU command documentation explains how the host checks configuration state, allocates objects, and finalizes that configuration. The same compiled controller firmware can therefore serve different printer configurations when the required hardware capabilities and build settings match.
With multiple MCUs, the host synchronizes their clocks so operations can share a timing model despite clock drift. Each board still needs the correct firmware and its own configuration entry. Adding a toolhead controller does not create a second independent motion planner. It extends the hardware that the host coordinates.
printer.cfg defines the machine
Configuration sections associate readable names with machine components. A [printer] section selects kinematics and motion limits. A [stepper_x] section describes one configured stepper, while [mcu] identifies the controller connection. Heater and sensor sections describe their hardware and limits. The configuration reference defines each option.
A single file is convenient for a small setup, but Klipper also supports [include ...] sections. Separate files can hold macros or other configuration groups. The practical consequence for backups is straightforward: preserve every included file as well as printer.cfg. A copy of only the top-level file may omit the values needed to restore the printer.
Treat configuration as code by recording changes with a reason. Keep a known working copy, change one related group at a time, and compare the before-and-after text. This is an editorial workflow recommendation based on Klipper’s text configuration model, not a requirement to use any particular backup service. Record board revisions and firmware build settings alongside the files.
Restarting, saving, and reflashing are different
| Change | Normal action | Why |
|---|---|---|
| Adjust a supported configuration option or macro | Save files, then RESTART when idle | Klippy reloads the configuration |
| Apply a calibration result supported by autosave | SAVE_CONFIG | Klipper writes that result and restarts |
| Clear an MCU error after correcting its cause | FIRMWARE_RESTART | Also resets the MCU error state |
| Change MCU target, clock, or compiled transport | Rebuild and flash the matching firmware | These are firmware build choices |
| Update Klipper software | Follow the upgrade instructions; update MCU firmware as directed | Host and controller versions must remain compatible |
The G-code reference distinguishes these commands. FIRMWARE_RESTART is not a flashing command. SAVE_CONFIG is not a general mechanism for persisting every runtime setting. Inspect the generated configuration changes after calibration and keep them with the rest of the backup.
An MCU protocol error after an update is different from an invalid configuration option. Follow the project’s upgrade guidance for compatible firmware, and its configuration reference for renamed or unsupported settings. Reflashing cannot correct a typographical error in a host configuration file; repeatedly editing that file cannot change the MCU’s compiled communication interface.
Macros are host-side command templates
A [gcode_macro ...] section defines a command sequence using Klipper’s template system. Templates can read parameters and printer status and generate G-code. They are configuration-level automation, which is distinct from replacing the microcontroller program.
The command template guide highlights a subtle behavior: Klipper evaluates an entire macro before executing the generated commands. Reading a status value later in the same template therefore does not automatically observe a change caused by an earlier generated command. Design multi-stage behavior with that timing in mind.
Movement macros also inherit G-code state unless they explicitly manage it. The official guide demonstrates saving and restoring that state and selecting a positioning mode before requesting a move. Review copied macros for machine assumptions and coordinates, just as you would review copied pin assignments.
Verify the machine definition before tuning
Klipper’s configuration checks start with basic temperature and emergency-stop checks, then cover heaters, steppers, endstops, and homing. Complete them after installation or a material wiring change. A configuration that loads without a syntax error has not yet passed those physical checks.
Once the printer definition is correct, use the separate ADXL345 input shaper setup guide for resonance measurement. This keeps architecture decisions, hardware verification, and calibration results traceable to the part of the system they actually affect. If the extra host and maintenance remain a deciding factor, Klipper vs Marlin compares the firmware workflows.
