Voron Klipper printer.cfg from Scratch — Complete Configuration Template

Klipper Configuration Firmware

The printer.cfg file is the heart of any Klipper-based printer. It defines every motor, sensor, heater, and behavior of your Voron. A mistake here can cause skipped steps, failed prints, or even damaged hardware. This guide walks through every section of a complete printer.cfg for a Voron V2.4 350mm build on a BTT Octopus v1.1 board, explaining each parameter and why it matters. Last updated: May 2025.

This configuration works as a template. Adapt the pin numbers for your specific mainboard (BTT Octopus, Fysetc Spider, Manta, etc.) and adjust position endpoints for your build size (250mm, 300mm, or 350mm). Always verify pin mappings against your board's schematic before applying.

MCU Section

The [mcu] section tells Klipper how to communicate with your mainboard. On a BTT Octopus v1.1 with a stock firmware flashed via USB:


[mcu]
serial: /dev/serial/by-id/usb-Klipper_stm32f446xx_12345-if00
restart_method: command
baud: 250000

Find your serial ID with ls /dev/serial/by-id/* in SSH. The restart_method determines how Klipper resets the MCU — "command" works for most boards, "rpi_usb" for Raspberry Pi connected boards, and "deactivate" for boards that need a power cycle.

Stepper X — X-Axis Motion


[stepper_x]
step_pin: PF13
dir_pin: !PF12
enable_pin: !PF14
microsteps: 16
rotation_distance: 40
full_steps_per_rotation: 200  # 1.8 degree stepper
endstop_pin: ^PG6
position_endstop: 0
position_min: -5
position_max: 355
homing_speed: 100
homing_retract_dist: 5

The step_pin, dir_pin, and enable_pin map to your board's stepper driver outputs. The "!" prefix inverts the signal (active low). rotation_distance of 40mm corresponds to a 20-tooth pulley with 2mm GT2 belt pitch (20 * 2 = 40). microsteps of 16 gives a resolution of 0.0125mm per step with 1.8-degree motors. position_min and position_max define the physical travel range — for a 350mm V2.4, the rail is ~360mm long but usable travel is 355mm with 5mm of over-travel for homing.

Stepper Y — Y-Axis Motion


[stepper_y]
step_pin: PG0
dir_pin: !PG1
enable_pin: !PG2
microsteps: 16
rotation_distance: 40
full_steps_per_rotation: 200
endstop_pin: ^PG3
position_endstop: 0
position_min: -5
position_max: 355
homing_speed: 100
homing_retract_dist: 5

On the V2.4, the Y axis uses the same belt/pulley setup as X. The position_max of 355mm leaves a small safety margin at the end of the rail. The endstop_pin uses "^" to enable the internal pull-up resistor — critical for mechanical endstops that connect the signal pin to ground when triggered.

Stepper Z — Gantry Z Motors

The V2.4 uses four Z motors for quad gantry leveling. Each motor gets its own stepper driver:


[stepper_z]
step_pin: PG4
dir_pin: !PG5
enable_pin: !PG7
microsteps: 16
rotation_distance: 8
full_steps_per_rotation: 200
endstop_pin: probe:z_virtual_endstop
position_min: -5
position_max: 350
homing_speed: 15
second_homing_speed: 5
homing_retract_dist: 3

[stepper_z1]
step_pin: PH2
dir_pin: !PH3
enable_pin: !PH5
microsteps: 16
rotation_distance: 8
full_steps_per_rotation: 200

[stepper_z2]
step_pin: PH6
dir_pin: !PH7
enable_pin: !PH8
microsteps: 16
rotation_distance: 8
full_steps_per_rotation: 200

[stepper_z3]
step_pin: PH10
dir_pin: !PH11
enable_pin: !PH12
microsteps: 16
rotation_distance: 8
full_steps_per_rotation: 200

rotation_distance of 8mm corresponds to an 8mm lead on a 2-start lead screw (4mm pitch * 2 starts = 8mm per rotation). On a Trident with a fixed bed, you'd use [stepper_z] and [stepper_z1] with [z_tilt] instead. The endstop is set to "probe:z_virtual_endstop" — this tells Klipper to use the probe for Z homing instead of a physical Z endstop.

Extruder


[extruder]
step_pin: PB4
dir_pin: !PB5
enable_pin: !PB6
microsteps: 16
rotation_distance: 22.678  # For Clockwork 2 / Galileo 2 with 20T gear
full_steps_per_rotation: 200
nozzle_diameter: 0.400
filament_diameter: 1.750
heater_pin: PB9
sensor_type: ATC Semitec 104GT-2
sensor_pin: PK5
control: pid
pid_kp: 24.297
pid_ki: 1.726
pid_kd: 85.452
min_temp: 0
max_temp: 290

The rotation_distance depends on your extruder gear ratios. For a Clockwork 2 with a 20T gear driving an MGN12 rail, the value is approximately 22.678. Calculate yours with: rotation_distance = gear_ratio * pulley_teeth * belt_pitch. The sensor_type must match your thermistor — ATC Semitec 104GT-2 is common for Voron builds, but NTC 100K B3950 is also popular. PID values shown are starting points; run PID_CALIBRATE to tune for your specific hotend.

Heater Bed


[heater_bed]
heater_pin: PB8
sensor_type: NTC 100K B3950
sensor_pin: PK4
control: pid
pid_kp: 69.254
pid_ki: 2.381
pid_kd: 503.682
min_temp: 0
max_temp: 120

The BTT Octopus v1.1 uses pin PB8 for the bed MOSFET output. The max_temp of 120°C is safe for ABS printing (typical bed temp: 100-110°C). Never exceed 120°C on a stock Voron bed — the adhesive on the silicone heater pad degrades above 130°C. Run PID_CALIBRATION BED=100 to tune the PID values for your specific bed.

Quad Gantry Level


[quad_gantry_level]
gantry_corners:
    -155, -155
    155, -155
    155, 155
    -155, 155
points:
    -155, -155
    155, -155
    155, 155
    -155, 155
speed: 200
horizontal_move_z: 10
retries: 5
retry_tolerance: 0.01
max_adjust: 5

The gantry_corners define where each Z lead screw is located, relative to the bed center. The points are where the probe measures. For a 350mm V2.4, ±155mm puts the probe near each corner screw. The retry_tolerance of 0.01mm means the leveling repeats until all corners are within 0.01mm of each other.

Z Tilt (for Trident)

If you're building a Trident instead of a V2.4, replace quad_gantry_level with z_tilt:


[z_tilt]
z_positions:
    -175, 150
    175, 150
    0, -160
points:
    0, 0
    175, 150
    -175, 150
speed: 200
horizontal_move_z: 5
retries: 5
retry_tolerance: 0.01

Bed Screws


[bed_screws]
screw1: 15, 20
screw2: 170, 20
screw3: 320, 20
screw4: 320, 330
screw5: 170, 330
screw6: 15, 330

These coordinates tell Klipper where to probe for manual bed screw adjustment. The six screws on a V2.4 350mm bed align with the standard Voron bed layout. Use the SCREWS_TILT_CALCULATE command after homing to get precise adjustment instructions.

Safe Z Home


[safe_z_home]
home_xy_position: 175, 175
speed: 200
z_hop: 15

This moves the toolhead to the center of the bed before probing Z. This prevents the probe from triggering off the bed edge if the X/Y position is at a corner. The z_hop of 15mm lifts the toolhead before moving to prevent crashing into prints.

Bed Mesh


[bed_mesh]
speed: 120
horizontal_move_z: 5
mesh_min: 35, 35
mesh_max: 315, 315
probe_count: 7, 7
algorithm: bicubic
fade_start: 1.0
fade_end: 10.0
fade_target: 0

mesh_min and mesh_max define the probing boundaries, inset from the bed edges to keep the probe on the build surface. A 7x7 grid (49 points) provides good coverage for a 350mm bed. The bicubic algorithm gives smooth interpolation between probe points. fade parameters gradually reduce compensation over the first 10mm of Z height, preventing sudden Z adjustments from being visible on the print surface.

Probe — Klicky or Voron TAP


[probe]
pin: PB7
x_offset: 0.0  # Adjust for your probe mount
y_offset: 0.0  # Adjust for your probe mount
z_offset: 0.0  # Set via PROBE_CALIBRATE
speed: 10
samples: 3
samples_result: median
sample_retract_dist: 3
samples_tolerance: 0.015
samples_tolerance_retries: 3

For Voron TAP, the x_offset and y_offset are typically 0 because the probe is nozzle-mounted. For Klicky or Euclid, adjust offsets based on your probe mount geometry. Three samples with a median result filters out noise. Samples tolerance of 0.015mm rejects outliers — if three samples vary by more than this, Klipper retries.

Input Shaper


[input_shaper]
shaper_type_x: zv
shaper_freq_x: 45.0
shaper_type_y: zv
shaper_freq_y: 48.0

[adxl345]
cs_pin: PC4
spi_bus: spi1a

[resonance_tester]
accel_chip: adxl345
probe_points:
    175, 175, 20

These are starting values. You MUST run SHAPER_CALIBRATE to measure your printer's actual resonance frequencies. Mount an ADXL345 accelerometer to the toolhead (for X/Y) or the bed (for Z), then run the calibration. The shaper_type determines the vibration filtering algorithm — zv (ZV) is the simplest, while mzv or ei provide better filtering with slightly more smoothing.

Pressure Advance


[pressure_advance]
pressure_advance: 0.045  # Starting value for filament

Pressure advance compensates for filament compressibility and nozzle pressure. The optimal value depends on your filament type, extruder, and hotend. Run the pressure advance tuning pattern in OrcaSlicer or SuperSlicer to find your specific value. Typical ranges: PLA 0.02-0.05, ABS 0.04-0.08, PETG 0.03-0.06.

Pause/Resume and Virtual SD Card


[pause_resume]

[virtual_sdcard]
path: /home/pi/gcode_files

[pause_resume] enables the PAUSE and RESUME commands used in filament change and error recovery macros. [virtual_sdcard] points to the directory where your G-code files are stored — normally the gcode_files directory shared by Moonraker and Mainsail/Fluidd.

Including Custom Macros


[include macros.cfg]

Keep your PRINT_START, PRINT_END, and other macros in a separate file (macros.cfg) for easier organization. The [include] directive merges the file's contents as if they were part of printer.cfg.

Full Template Structure

Here's the recommended order of sections in your printer.cfg:

[include macros.cfg] — Macro definitions
[mcu] — MCU communication
[stepper_x], [stepper_y], [stepper_z] through [stepper_z3] — Axis configuration
[extruder] — Hotend and extruder
[heater_bed] — Bed heater
[probe] — Probe configuration
[safe_z_home] — Safe homing
[bed_screws] or [z_tilt] — Leveling
[quad_gantry_level] — Gantry leveling
[bed_mesh] — Bed mesh compensation
[input_shaper] and [adxl345] — Resonance compensation
[pressure_advance] — Filament pressure compensation
[pause_resume] and [virtual_sdcard] — Print management
[filament_switch_sensor] — Runout sensor
[exclude_object] — Object exclusion

Verifying Your Configuration

Before attempting to move any axis, run through this checklist:

Verify every pin number against your board's schematic — one wrong pin can short a driver
Check that stepper driver currents are set in hardware (via driver potentiometers) or software (via [tmc2209] sections)
Run FIRMWARE_RESTART after editing printer.cfg
Test each axis individually with small movements (G91 then G1 X10 F1000)
Verify endstop triggering with QUERY_ENDSTOPS
Test the probe with PROBE_ACCURACY before homing Z
Run PID_CALIBRATE for both extruder and bed
Run SHAPER_CALIBRATE with an accelerometer
Run PRESSURE_ADVANCE_CALIBRATE for each filament type

Take it slow. A rushed Klipper config is the #1 cause of fried boards and crashed print heads. Verify every section, test every axis, and only move to the next section when the current one works flawlessly.