📚 课程目录第3章 Klipper配置入门

3. Klipper配置入门：printer.cfg文件结构、主要配置段与宏指令的关系

Klipper固件与传统Marline固件的最大差异在于，它将实时运动控制任务交由上位机（通常是树莓派或PC）处理，而打印机主板上的MCU仅负责执行高频率的脉冲输出与传感器采样。这一架构决定了Klipper的几乎所有行为都由一个纯文本配置文件——printer.cfg——驱动。理解printer.cfg的结构、各配置段的作用，以及它们与宏指令（Macro）之间的调用关系，是开发自定义G代码宏、实现复杂打印流程控制的前提。本章将从文件结构、核心配置段、宏指令挂载机制三个层面展开，并结合一个实际调机案例说明配置与宏的协同工作方式。

3.1 printer.cfg 文件结构与解析机制

printer.cfg 采用 INI 风格的分段式文本格式，每一段以方括号中的段名开头，段内以“键 = 值”的形式定义参数。Klipper 启动时，主程序 klippy.py 会逐行解析该文件，将每个配置段映射为对应的对象实例。解析过程严格区分大小写，且不支持行内注释（注释必须独占一行，以 # 开头）。

一个典型的 printer.cfg 文件通常包含以下层次：基础系统段（如 [mcu]、[printer]）、运动学段（[stepper_x]、[stepper_y]、[stepper_z]、[extruder]）、热管理段（[extruder] 中的加热部分、[heater_bed]、[heater_fan]）、辅助功能段（[fan]、[probe]、[bed_mesh]、[gcode_macro]）以及显示与交互段（[display_status]、[output_pin]）。

解析顺序遵循“先定义后引用”的原则。例如，[gcode_macro] 中如果调用了 [bed_mesh] 提供的 BED_MESH_CALIBRATE 命令，则 [bed_mesh] 段必须在文件中先于该宏出现，否则 Klipper 会报“未知命令”错误。这一机制要求配置编写者具备全局视野，合理规划段落的排列顺序。

配置段	核心参数	对应硬件/功能	宏指令关联
[mcu]	serial、baud、restart_method	主板MCU串口连接	FIRMWARE_RESTART
[stepper_x/y/z]	step_pin、dir_pin、enable_pin、rotation_distance	步进电机驱动	G28、G1、SET_KINEMATIC_POSITION
[extruder]	heater_pin、sensor_type、pid_Kp/Ki/Kd、pressure_advance	挤出机加热与送料	M104、M109、SET_PRESSURE_ADVANCE
[heater_bed]	heater_pin、sensor_type、max_power、control	热床加热与温度传感	M140、M190、SET_HEATER_TEMPERATURE
[gcode_macro]	gcode、description、rename_existing	自定义G代码命令	直接调用其他宏或G代码

3.2 核心配置段深度解析

3.2.1 [stepper] 运动轴配置段

[stepper_x]、[stepper_y]、[stepper_z] 三个段定义了打印机三个线性轴的运动学参数。最关键的是 rotation_distance，它表示电机转动一圈所对应的移动距离（单位：mm）。该值由丝杆导程、皮带轮齿数、电机步距角共同决定。例如，对于 1.8° 步距角电机（即 200 步/圈）、16 细分驱动、2mm 导程丝杆，rotation_distance 计算为：

rotation_distance = 导程 / (电机步数 × 细分倍数 / 电机步数)
= 2mm / (200 × 16 / 200) = 2mm / 16 = 0.125mm

实际配置中更推荐使用 gear_ratio 参数来处理减速机构。例如，若挤出机使用 50:10 的齿轮减速比，则配置为 gear_ratio: 50:10，Klipper 会自动计算等效的旋转距离。这一设计避免了手动换算带来的误差，也便于后期更换不同减速比的挤出机。

运动轴配置段与宏指令的关系体现在：宏中使用的 G28（归零）、G1（直线插补）等命令，最终都会映射到这些轴的步进脉冲输出。例如，自定义的 _HOME_X 宏可以调用 G28 X 来单独归零 X 轴，而无需执行完整的 G28。

3.2.2 [extruder] 挤出机配置段

[extruder] 段同时承担运动学与热管理双重职责。运动学部分包括 rotation_distance、max_extrude_only_velocity、max_extrude_only_accel；热管理部分包括 heater_pin、sensor_type、pid_Kp、pid_Ki、pid_Kd。Klipper 对挤出机采用独立的 PID 控制环，与热床控制相互独立。

挤出机的 pressure_advance 参数是 Klipper 的一大特色，它通过提前补偿挤出机内部压力来减少回抽时的拉丝现象。该参数通常通过 TUNING_TOWER 命令进行动态校准，校准结果可以写入宏中，例如：

[gcode_macro SET_PA]
gcode:
  SET_PRESSURE_ADVANCE EXTRUDER=extruder PRESSURE_ADVANCE={params.VALUE}

这样，切片软件中只需调用 SET_PA VALUE=0.05 即可动态调整压力提前量，而无需修改配置文件。

3.2.3 [heater_bed] 热床配置段

热床配置相对简单，核心参数为 heater_pin（加热管控制引脚）、sensor_type（温度传感器类型，如 NTC 100K）、max_power（最大加热功率，0~1 之间的小数）。Klipper 默认使用 PID 控制，但也可以通过 control = watermark 切换为开关控制模式。

热床温度控制与宏的典型交互场景是打印开始前的预热流程。一个完善的 START_PRINT 宏会先设置热床目标温度，等待温度稳定后再进行调平，最后才加热喷头，以避免热床热膨胀影响调平结果。这种顺序控制完全依赖宏中 M140/M190 命令的排列。

经验提示：在 [heater_bed] 中设置 min_temp: 0 和 max_temp: 120 时，务必留出安全余量。若传感器短路或断路，Klipper 会立即触发紧急停止，防止加热失控。宏中调用 M190 时，建议使用 M190 S60 而非 M190 R60，前者会等待温度达到目标值，后者则立即返回。

3.3 [gcode_macro] 宏指令段与配置段的协同机制

[gcode_macro] 是 Klipper 最具扩展性的配置段，它允许用户将一系列 G 代码、Klipper 原生命令、条件判断和变量操作封装为一个自定义命令。宏定义的基本格式如下：

[gcode_macro START_PRINT]
description: 打印开始前的初始化流程
gcode:
  # 获取切片参数
  {% set BED_TEMP = params.BED_TEMP|default(60)|float %}
  {% set EXTRUDER_TEMP = params.EXTRUDER_TEMP|default(200)|float %}
  
  # 热床预热
  M140 S{BED_TEMP}
  M190 S{BED_TEMP}
  
  # 归零与调平
  G28
  BED_MESH_CALIBRATE
  
  # 喷头加热
  M104 S{EXTRUDER_TEMP}
  M109 S{EXTRUDER_TEMP}
  
  # 移动到打印起点
  G1 Z5 F300
  G1 X10 Y10 F6000

宏与配置段的协同体现在三个层面：参数传递（通过 params 对象获取切片软件传入的参数）、命令调用（直接调用其他配置段生成的原生命令）、状态读取（通过 printer 对象查询当前温度、位置等实时数据）。例如，以下宏实现了打印完成后自动关闭加热并报告用时：

[gcode_macro END_PRINT]
gcode:
  # 关闭挤出机和热床
  M104 S0
  M140 S0
  # 关闭风扇
  M106 S0
  # 移动喷头到安全位置
  G91
  G1 Z10 F300
  G90
  G1 X0 Y0 F6000
  # 报告打印时长
  RESPOND TYPE=command MSG="打印完成，总耗时 {printer.print_stats.print_duration|int} 秒"

3.4 实战案例：从配置段到宏的完整调机流程

下面通过一个实际案例，展示如何从零开始配置一台 Cartesian 结构打印机，并编写一个包含调平逻辑的 START_PRINT 宏。

背景与约束：打印机为 i3 结构，使用 8mm 导程丝杆（Z 轴）、GT2 20 齿皮带轮（X/Y 轴）、200 步/圈电机、16 细分驱动。热床为铝基板 + 220V 交流加热管，使用 NTC 100K 热敏电阻。初始现象：打印首层附着不良，且每次打印前需要手动执行繁琐的调平流程。

关键输入数据：

X/Y 轴 rotation_distance = 皮带轮周长 = 20 齿 × 2mm 齿距 = 40mm
Z 轴 rotation_distance = 丝杆导程 = 8mm
挤出机使用 BMG 双驱齿轮，齿轮比 50:10，驱动轮直径 7mm，则 rotation_distance = π × 7 / 5 ≈ 4.398mm

分析判断过程：首先在 [stepper_x] 中填入 step_pin、dir_pin 等硬件引脚，然后通过 STEPPER_BUZZ 命令测试电机方向是否正确。若方向反了，只需交换 dir_pin 的逻辑值（如将 !PB5 改为 PB5）。对于 Z 轴，需要验证 rotation_distance 是否准确，可通过 G91 + G1 Z10 F300 移动 10mm，用卡尺测量实际位移。

实际操作步骤：

在 printer.cfg 中依次添加 [stepper_x]、[stepper_y]、[stepper_z]、[extruder]、[heater_bed] 段，填入上述计算值。
使用 PID_CALIBRATE HEATER=extruder TARGET=200 命令校准挤出机 PID，将输出参数回填到配置段。
使用 BED_MESH_CALIBRATE 手动调平，保存网格到 [bed_mesh] 段。
编写 START_PRINT 宏，将预热、归零、调平、二次预热整合为一个命令。
在切片软件的开始 G 代码中，仅保留 START_PRINT BED_TEMP=60 EXTRUDER_TEMP=210 一行。

结果对比：改造前，每次打印需要手动执行 5 个步骤，耗时约 3 分钟，且首层失败率约 20%。改造后，一键启动，预热与调平自动完成，首层失败率降至 2% 以下。打印时间因减少了人工干预而缩短约 15%。

风险与代价：宏中若未正确处理温度等待逻辑，可能导致喷头在热床未达到目标温度时就开始调平，造成热床膨胀误差。此外，若 BED_MESH_CALIBRATE 失败（如探针未触发），宏会中断执行，需要增加错误处理逻辑。

风险提示：在宏中使用 M109 或 M190 时，务必设置合理的超时时间。Klipper 默认等待 120 秒，若温度长时间无法达到目标值，会触发加热超时错误。建议在宏开头添加 SET_HEATER_TEMPERATURE HEATER=heater_bed TARGET=60 配合 TEMPERATURE_WAIT SENSOR=heater_bed MINIMUM=60 MAXIMUM=65 实现更精细的控制。

3.5 常见误区与配置复盘

误区一：将所有配置堆砌在一个 [gcode_macro] 段中。正确做法是每个宏独立成段，便于维护和调试。Klipper 支持通过 [gcode_macro _START_PRINT] 以下划线开头的宏名来定义“私有宏”，这些宏不会暴露给切片软件，只能被其他宏调用。

误区二：忽略配置段的加载顺序。Klipper 在解析时，如果 [gcode_macro] 中引用了尚未定义的命令，会直接报错。建议将 [gcode_macro] 段放在文件末尾，确保所有硬件配置段已加载完毕。

误区三：在宏中硬编码温度值。切片软件传入的 BED_TEMP 和 EXTRUDER_TEMP 参数应通过 params 对象动态获取，并设置合理的默认值。这样同一份配置可以适配不同材料的打印需求。

误区四：忽视 rename_existing 参数。当宏名与 Klipper 内置命令冲突时（如自定义 G28），需要使用 rename_existing: _G28 将原命令重命名，否则宏会覆盖内置命令，导致归零逻辑失效。