# This is a full-line comment
[stepper_x]  # Inline comment


Use comments extensively to document your config, especially for non-obvious parameters.

### Section Headers

Sections are enclosed in square brackets:


[stepper_x]
[mcu]
[extruder]
[heater_bed]
[gcode_macro PRINT_START]


Section names are case-insensitive but convention is lowercase with underscores.

### Parameters

Each section contains key-value pairs separated by a colon or whitespace:


parameter_name: value
parameter_name = value
parameter_name value


All three forms are valid. The colon form is most common and recommended.

### Indentation and Whitespace

Klipper is **not** whitespace-sensitive — you don't need specific indentation. However, good indentation dramatically improves readability:


# Poor
[gcode_macro PRINT_START]
gcode:
G28
G29
M104 S{params.TEMP}
M140 S{params.BED}

# Good
[gcode_macro PRINT_START]
gcode:
G28
G29
M104 S{params.TEMP}
M140 S{params.BED}


Use 4 spaces or a tab for indentation within multi-line parameter values.

### Line Continuation

Long lines can be split using a backslash continuation:


[extruder]
pressure_advance_lookahead_time: 0.010 0.012 0.014


Or more commonly, use YAML-style lists where supported:


[temperature_fan chamber_fan]
temperature_sensor: temperature_sensor chamber
target_temp: 45.0
max_power: 1.0
shutdown_speed: 0.0
pid_kp: 50.0
pid_ki: 5.0
pid_kd: 1.0


## Section Types Overview

### Core System Sections

| Section | Purpose |
|---------|---------|
| [mcu] | Main controller MCU connection |
| [printer] | Printer name, kinematics, and limits |
| [stepper_x/y/z] | Stepper motor configuration |
| [extruder] | Extruder hotend and stepper |
| [heater_fan ...] | Cooling fans |
| [temperature_fan ...] | Temperature-controlled fans |

### Kinematics Configuration

Define your Voron's movement system:


[printer]
kinematics: corexy
max_velocity: 500
max_accel: 20000
max_z_velocity: 30
max_z_accel: 700
square_corner_velocity: 5.0


Voron V2.4 and Trident use corexy kinematics. Voron 0 uses corexz.

### Pin Naming Conventions

Pins are referenced differently depending on your MCU:

**Raspberry Pi GPIO:**

endstop_pin: gpio26
control_pin: gpio17


**STM32 (SKR, Octopus, Spider, Fysetc):**

endstop_pin: !PC1          # ! means inverted
enable_pin: !PD13          # Hardware PWM capable
dir_pin: PG0
step_pin: PG1


**RP2040 (RPi Pico, Pico-based boards):**

endstop_pin: gpio26
step_pin: gpio10


**Common pin modifiers:**

- ! prefix — Invert the signal (active low)
- ^ prefix — Enable internal pull-up resistor
- PC1, PD13, PG0 — Port/pin notation for STM32

**Voron-standard pin assignments:**

# X endstop — usually NC (Normally Closed) for Voron
endstop_pin: !PC1    # Inverted because NC goes high at trigger

# Probe (Voron TAP or Omron/PL-08N)
sensor_pin: ^PC2     # Pull-up enabled
control_pin: PC3


---

## The [include] Directive

Split complex configs into manageable files:


[include mainsail.cfg]            # UI settings and macros
[include macros/*.cfg]            # All macro files
[include "saved_variables.cfg"]   # Save_variables data
[include user_overrides.cfg]      # Your personal tweaks


The [include] directive supports wildcards (*) and can appear anywhere in the file. Included files are processed in order.

**Best practice:** Keep hardware definitions in printer.cfg and macros/tuning in separate included files.

---

## Macros in printer.cfg

G-Code macros are defined in [gcode_macro] sections:


[gcode_macro PRINT_START]
description: Start a print job
gcode:
# Homing
G28

# Heat soak if chamber is cold
{% if printer.heater_bed.temperature < 60 }
M106 S255  # Start chamber fan
G4 P300000  # Wait 5 minutes
{% endif }

# Set temperatures from slicer
M104 S{params.TEMP|default(220)}
M140 S{params.BED|default(60)}

# Mesh bed leveling
BED_MESH_CALIBRATE

# Load filament
ACTIVATE_FILAMENT

# Nozzle purge line
G92 E0
G1 X20 Y20 Z0.4 F3000
G1 X200 Y20 E30 F300
G92 E0


### Parameter Passing

Slicer parameters pass to macros via the params object:


{params.FIRST_LAYER_TEMP}    # From slicer
{params.FIRST_LAYER_BED_TEMP}
{params.TEMP|default(220)}  # With fallback


### Jinja2 Templates

Klipper uses a subset of Jinja2 for conditional logic, math, and data access within macros:

| Expression | Description |
|------------|-------------|
| { printer["heater_bed"].temperature } | Access printer state |
| {% if condition %} ... {% endif %} | Conditional execution |
| {% for item in list %} ... {% endfor %} | Loops |
| { (printer.toolhead.position.x * 2) } | Math operations |
| { printer.configfile.settings.extruder.max_extrude_only_distance } | Read config values |

---

## Best Practices for Voron Configs

### 1. Version Control

Keep your printer.cfg in git:


cd ~/printer_data/config
git init
git add printer.cfg
git commit -m "Initial Voron config"


### 2. Comment Everything Non-Obvious


# Why 375 rpm max? Stepper torque drops above 400 rpm with 48V
rotation_distance: 40
max_extrude_only_distance: 500


### 3. Use Descriptive Section Names


[heater_fan hotend_fan]
pin: PC8

[heater_fan chamber_circulation_fan]  
pin: PC9


### 4. Validate Your Config

Always run after changes:


RESTART                 # Reload config
FIRMWARE_RESTART        # Full MCU reset if needed


### 5. Keep a Backup System


# Copy before major changes
cp printer.cfg printer.cfg.backup

# Or use include structure with overrides
[include user_overrides.cfg]


---

## Common Mistakes and How to Avoid Them

### Missing or Duplicated Sections

Each section name must be unique. Duplicate sections cause the last one to override earlier ones — often silently.

### Incorrect Pin Numbers

Always double-check pinout diagrams for your specific board. An SKR 1.4 has different pin assignments than an Octopus Pro.

**How to verify:** Open the Klipper console and send QUERY_ENDSTOPS to test endstop pins.

### Indentation Errors in Macros

While Klipper is lenient with indentation, some Jinja2 constructs require proper nesting:


# WRONG — else indented wrong
{% if condition %}
G1 X100
{% else %}    # Wrong
G1 X200
{% endif %}

# RIGHT
{% if condition %}
G1 X100
{% else %}     # Correct
G1 X200
{% endif %}


### Trailing Whitespace in # Comments

Leading/trailing spaces in comments are fine, but ensure there's a space after # for readability.

### Case Sensitivity Issues

Section names are case-insensitive, but parameter names within sections often are too. However, string values are case-sensitive:


# These are equivalent
[gcode_macro MyMacro]
[gcode_macro mymacro]

# But this matters:
gcode:
M117 "Hello"   # Different from "hello"


---

## printer.cfg File Layout Example (Voron V2.4)


# ============================================
# Voron V2.4 350mm — Klipper Configuration
# ============================================

# --- MCU Configuration ---
[mcu]
serial: /dev/serial/by-id/usb-Klipper_stm32f446xx_...
restart_method: command

# --- Printer Definition ---
[printer]
kinematics: corexy
max_velocity: 500
max_accel: 20000
max_z_velocity: 30
max_z_accel: 700
square_corner_velocity: 5.0

# --- Stepper X ---
[stepper_x]
step_pin: PG1
dir_pin: PG0
enable_pin: !PD13
microsteps: 16
rotation_distance: 40
endstop_pin: !PC1
position_endstop: 0
position_min: -4
position_max: 350
homing_speed: 50

# --- Stepper Y ---
[stepper_y]
step_pin: PG3
dir_pin: PG2
enable_pin: !PD13
microsteps: 16
rotation_distance: 40
endstop_pin: !PC0
position_endstop: 0
position_min: -4
position_max: 350
homing_speed: 50

# --- Stepper Z (4 motors, quad gantry) ---
[stepper_z]
step_pin: PG5
dir_pin: PG4
enable_pin: !PD13
microsteps: 16
rotation_distance: 8
endstop_pin: !PC5
position_endstop: 0.5
position_min: -5
position_max: 350

[stepper_z1]
step_pin: PG7
dir_pin: PG6
enable_pin: !PD13
microsteps: 16
rotation_distance: 8

[stepper_z2]
step_pin: PG9
dir_pin: PG8
enable_pin: !PD13
microsteps: 16
rotation_distance: 8

[stepper_z3]
step_pin: PG11
dir_pin: PG10
enable_pin: !PD13
microsteps: 16
rotation_distance: 8

# --- Extruder ---
[extruder]
step_pin: PB13
dir_pin: PB12
enable_pin: !PB14
microsteps: 16
rotation_distance: 7.710
nozzle_diameter: 0.400
filament_diameter: 1.750
heater_pin: PC9
sensor_type: Generic 3950
sensor_pin: PC3
min_temp: 0
max_temp: 290
max_power: 1.0
min_extrude_temp: 170
control: pid
pid_kp: 28.413
pid_ki: 1.962
pid_kd: 102.856

# --- Heater Bed ---
[heater_bed]
heater_pin: PC8
sensor_type: Generic 3950
sensor_pin: PC4
min_temp: 0
max_temp: 130
max_power: 1.0
control: pid
pid_kp: 72.426
pid_ki: 1.527
pid_kd: 859.347

# --- Fans ---
[heater_fan hotend_fan]
pin: PC7
heater: extruder
heater_temp: 50.0

[controller_fan controller_fan]
pin: PB15
idle_timeout: 120

[heater_fan chamber_fan]
pin: PC6
heater: heater_bed
heater_temp: 50.0

# --- Probe (Voron TAP) ---
[probe]
pin: PC2
x_offset: 0.0
y_offset: 25.0
z_offset: 0.0
speed: 5.0