Voron Klipper printer.cfg from Scratch — Complete Configuration Template

Klipper Configuration 固件

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. 最后更新：2025 年 5 月。

此配置可作为模板使用。根据您的主板（BTT Octopus、Fysetc Spider、Manta 等）调整引脚编号，并根据您的构建尺寸（250mm、300mm 或 350mm）调整位置端点。在应用前，务必对照主板原理图验证引脚映射。

MCU 部分

[mcu] 部分告诉 Klipper 如何与您的主板通信。在通过 USB 刷入固件的 BTT Octopus v1.1 上：


[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 轴运动


[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 轴运动


[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 — 龙门 Z 电机

V2.4 使用四个 Z 电机进行四龙门调平。每个电机都有自己的步进电机驱动器：


[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]
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_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]
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 轴倾斜（适用于 Trident）

如果你正在构建 Trident 而不是 V2.4，请将 quad_gantry_level 替换为 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]
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.

安全 Z 轴归零


[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]
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.

探针 — Klicky 或 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]
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: 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.

暂停/恢复和虚拟 SD 卡


[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.

包含自定义宏


[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.

完整模板结构

以下是 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] 和 [adxl345] — 共振补偿
[pressure_advance] — 耗材压力补偿
[pause_resume] 和 [virtual_sdcard] — 打印管理
[filament_switch_sensor] — 缺料传感器
[exclude_object] — 对象排除

验证您的配置

在尝试移动任何轴之前，请完成此检查清单：

对照主板原理图核对每个引脚编号——一个错误的引脚可能导致驱动器短路
检查步进电机驱动电流是否通过硬件（驱动电位器）或软件（通过 [tmc2209] 配置段）设置
编辑 printer.cfg 后运行 FIRMWARE_RESTART
使用小幅移动单独测试每个轴（G91 然后 G1 X10 F1000）
使用 QUERY_ENDSTOPS 验证限位开关触发
在 Z 轴归零前使用 PROBE_ACCURACY 测试探针
对挤出机和热床分别运行 PID_CALIBRATE
使用加速度计运行 SHAPER_CALIBRATE
对每种耗材类型运行 PRESSURE_ADVANCE_CALIBRATE

慢慢来。匆忙配置 Klipper 是烧毁电路板和撞坏打印头的首要原因。验证每个部分，测试每个轴，并且只有在当前部分完美运行后才进入下一部分。