Klipper 断料检测教程：filament_switch_sensor 配置

Klipper 断料检测通常使用 [filament_switch_sensor] 配置。最关键的是写对主板引脚 switch_pin，再根据传感器常开/常闭状态决定是否反相，最后设置断料暂停、插入耗材和事件延迟。

接线前先断电，并核对主板接口电压和引脚定义。不要把 5V 信号直接接到只允许 3.3V 的 MCU 引脚，也不要在通电状态下反复插拔传感器。

Klipper 断料检测最小配置

[filament_switch_sensor Filament_Runout_Sensor]
pause_on_runout: True
switch_pin: PD2

上面的 PD2 只是示例，必须替换成你的主板和接线所对应的真实引脚。不同主板命名不一样，应以 Klipper 官方配置、主板原理图或厂家示例为准。

switch_pin 怎么判断是否需要感叹号

switch_pin 用来告诉 Klipper 断料传感器连接在哪个 MCU 引脚。引脚前的 ! 表示反相逻辑；某些接线还会使用 ^ 启用内部上拉，但是否需要上拉必须按主板和传感器电路判断。

在 Fluidd 或 Mainsail 中打开断料传感器状态。
分别测试“插入耗材”和“拔出耗材”两个状态。
如果状态完全相反，再把 PD2 改为 !PD2 后重启 Klipper 测试。
如果状态始终不变，优先检查接线、接口电压、引脚名称和传感器本身，而不是不断尝试符号。

pause_on_runout 和 runout_gcode 的区别

pause_on_runout: True 会在检测到断料时调用暂停流程。多数情况下已经足够，不必再在 runout_gcode 中重复写一次 PAUSE。

runout_gcode 更适合放提示音、消息通知、移动喷头或自定义宏。例如：

[filament_switch_sensor Filament_Runout_Sensor]
pause_on_runout: True
switch_pin: PD2
runout_gcode:
  RESPOND MSG="Filament runout detected"

如果把 pause_on_runout 设为 False，就需要在 runout_gcode 中明确写出你希望执行的动作，否则检测到断料也可能不会暂停。

insert_gcode 有什么用

insert_gcode 会在重新插入耗材时运行。它可以用于发送提示、执行装料宏或恢复部分状态，但不建议未经确认就自动挤出大量耗材，避免喷头未加热时强行送料。

insert_gcode:
  RESPOND MSG="Filament inserted"

event_delay 和 pause_delay 怎么设置

event_delay：两次传感器事件之间允许的最小间隔，用于过滤开关抖动和重复触发。
pause_delay：发出暂停命令后，到执行 runout_gcode 之间的延迟。部分前端或宏需要留出一点处理时间。

不要直接照抄很大的延迟值。先从默认设置开始，只有确认存在抖动或暂停顺序问题时再逐步调整。

查询、启用和禁用断料传感器

QUERY_FILAMENT_SENSOR SENSOR=Filament_Runout_Sensor
SET_FILAMENT_SENSOR SENSOR=Filament_Runout_Sensor ENABLE=0
SET_FILAMENT_SENSOR SENSOR=Filament_Runout_Sensor ENABLE=1

QUERY_FILAMENT_SENSOR 用于查询当前状态；SET_FILAMENT_SENSOR 可以临时禁用或重新启用传感器。宏里的 SENSOR 名称必须和配置段名称一致。

断料检测不触发的排查顺序

确认 Klipper 启动时没有配置语法或未知引脚错误。
用界面或查询命令观察插入/拔出耗材时状态是否变化。
状态相反时测试 ! 反相；状态不变时检查接线和传感器。
确认传感器没有被 ENABLE=0 禁用。
最后再检查 PAUSE 宏、前端和自定义 runout_gcode。

完整参数仍应参考 Klipper Configuration Reference，并按你的主板配置文件调整。

Klipper 断料检测配置教程：filament_switch_sensor、switch_pin 与 PAUSE