Klipper 使用 PWM 工具控制激光器与主轴pwm_tool 配置、M3/M4/M5 宏与 LaserWeb 集成实战【免费下载链接】klipperKlipper is a 3d-printer firmware项目地址: https://gitcode.com/GitHub_Trending/kl/klipper导读本文基于 Klipper 官方文档 docs/Using_PWM_Tools.md 与仓库中的示例配置 config/sample-pwm-tool.cfg系统讲解如何复用打印头风扇的 PWM 输出来驱动激光器laser或主轴spindle。你将掌握[pwm_tool]配置段的全部参数含义、M3/M4/M5 宏的实现原理、安全超时的正确设置方法以及如何在 LaserWeb 等 CAM 工具中无缝集成——最终获得一套可直接复制运行、可安全切换工具头的 PWM 工具控制方案。工作原理把风扇 PWM 输出改造成工具控制口Klipper 打印头风扇原本由 PWM 信号驱动其输出本质是一路可高速更新的脉宽调制信号。借助这一特性可以将打印头的风扇 PWM 输出挪用为激光器或主轴的控制信号——这在更换式打印头switchable print heads场景下尤为实用例如 E3D toolchanger 或各类 DIY 换头方案。CNC/CAM 领域通常约定用M3~M5三个 G-code 命令控制主轴与激光器命令含义参数M3 Svalue主轴顺时针旋转Spindle speed CWS取值 0~255M4 Svalue主轴逆时针旋转Spindle speed CCWS取值 0~255M5停止主轴Spindle stop无参数输出回到 shutdown valueS参数的 0~255 是经典 CNC 的 8 位占空比标度Klipper 侧通过宏把它归一化映射到 0.0~1.0 的 PWM 占空比详见下文M3/M4/M5 宏一节。LaserWeb 等工具默认就能以M3 $INTENSITY的形式发送这些命令因此无需改造切片或 CAM 软件即可接入 Klipper。安全警告驱动激光器必须遵守的底线使用 PWM 工具驱动激光器时请务必把能想到的安全措施全部落实到位这一点在原文档中被着重强调二极管激光器通常是反相的inverted。这意味着当 MCU 重启、固件尚未完成初始化时PWM 引脚处于未定义/默认状态激光器可能会在 MCU 重新启动的短暂时间内以满功率开启。这是硬件级风险必须通过外围电路如常闭联锁继电器加以兜底。激光通电期间应始终佩戴与激光波长匹配的专用护目镜。不需要使用激光时请直接断开激光器电源。必须配置安全超时safety timeout当主机或 MCU 发生错误时工具要能自动停止避免长时间空烧。安全超时正是[pwm_tool]中maximum_mcu_duration参数的职责下文会详细展开。一个隐含但重要的细节原文档与示例配置反复强调homing 时工具需要处于默认速度。因为在归零过程中 Klipper 会执行运动同步若此时工具占空比非默认值超时机制可能被误触发或导致意外的 PWM 输出配置时务必结合下面的超时参数一起考虑。配置[pwm_tool]从风扇引脚到可控工具完整的可运行配置见仓库 config/sample-pwm-tool.cfg其核心是[pwm_tool]配置段[pwm_tool TOOL] pin: !ar9 # 使用你风扇的引脚编号此处为示例 hardware_pwm: True cycle_time: 0.001 shutdown_value: 0 maximum_mcu_duration: 5 # Default: 0 (disabled) # Amount of time in which the host has to acknowledge # a non-shutdown output value. # Suggested value is around 5 seconds. # Use a value that does not burn up your stock. # Please note that during homing, your tool # needs to be in default speed.[pwm_tool]配置段在 docs/Config_Reference.md第 3716 行起中有官方说明各参数含义与默认值整理如下参数默认值说明pin必填要配置为输出的引脚使用你风扇原来的引脚编号!前缀表示反相。示例中!ar9是 BigTreeTech 类主板上的 AR9 引脚反相maximum_mcu_duration0禁用MCU 在没有收到主机确认的情况下最多允许持续输出非 shutdown 值多长时间。若主机无法跟上更新节奏MCU 将进入 shutdown 并把所有引脚置为各自的 shutdown 值。建议值约 5 秒具体以不会烧毁你的工件stock为准value0MCU 配置期间引脚初始值0~1 或 0~scaleshutdown_value0MCU shutdown 事件发生时引脚应置为的值0~1 或 0~scale。激光器场景建议设为 0关闭cycle_time0.100 秒每个 PWM 周期的时间秒。软件 PWM 建议 10 毫秒或更长使用硬件 PWM 时实际周期受硬件实现约束可能与请求值明显不同hardware_pwmFalse是否使用硬件 PWM 而非软件 PWMscale1用于改变value/shutdown_value的解析标度配置为 PWM 引脚控制步进电压参考等场景时可设为等效电流值其中cycle_time: 0.001表示 1 kHz 的 PWM 频率适合激光器等需要较高调制频率的工具。版本注意3 秒上限变更根据 docs/Config_Changes.md 中20250428条目的记录[pwm_tool]及类似 PWM 配置段的cycle_time最大值从 5 秒缩减为3 秒maximum_mcu_duration的上限同样被限制为3 秒。因此在新版本上配置时maximum_mcu_duration: 5这类取值需要改为不超过 3 秒的值。为什么需要maximum_mcu_duration其底层逻辑是看门狗式的正常情况下主机周期性下发新的 PWM 值例如通过运动队列的刷新回调MCU 收到后即视为确认。若主机卡死、串口中断或发生错误导致长时间没有新指令MCU 会在超时后将引脚强制置为shutdown_value——对激光器而言就是立刻关断避免持续高功率输出引发事故。这一点在 pwm_tool.py 中通过_gen_intermediate_updates与_flush_notification机制实现详见源码级原理一节。M3/M4/M5 宏把 0~255 映射成 PWM 占空比[pwm_tool]本身只提供一个SET_PIN运行时命令真正的 M3/M4/M5 是通过[gcode_macro]实现的。示例配置中的宏如下[gcode_macro M3] gcode: {% set S params.S|default(0.0)|float %} SET_PIN PINTOOL VALUE{S / 255.0} [gcode_macro M4] gcode: {% set S params.S|default(0.0)|float %} SET_PIN PINTOOL VALUE{S / 255.0} [gcode_macro M5] gcode: SET_PIN PINTOOL VALUE0要点解析S参数通过 Jinja2 模板读取params.S|default(0.0)|float保证了未传S时安全回退为 0关键映射是VALUE{S / 255.0}把 CNC 惯用的 0~255 标度换算为 Klipper PWM 的 0.0~1.0 占空比。例如M3 S128会执行SET_PIN PINTOOL VALUE0.502M5直接SET_PIN PINTOOL VALUE0把输出置回关闭状态。SET_PIN的语义在 docs/G-Codes.md第 1071 行起中有明确定义PWM 引脚时VALUE应取值 0.0~1.0若配置了scale则取 0~scale。SET_PIN是面向运动队列的异步命令——它会注册一个 lookahead 回调在对应的打印时间点才真正改变引脚电平从而与运动轨迹精确同步这一点在源码cmd_SET_PIN中可以看到toolhead.register_lookahead_callback(...)。LaserWeb 集成配置LaserWeb 是常见的激光雕刻 CAM 前端。原文档给出了一套经过验证的配置完整照录如下GCODE START: M5 ; Disable Laser G21 ; Set units to mm G90 ; Absolute positioning G0 Z0 F7000 ; Set Non-Cutting speed GCODE END: M5 ; Disable Laser G91 ; relative G0 Z20 F4000 ; G90 ; absolute GCODE HOMING: M5 ; Disable Laser G28 ; Home all axis TOOL ON: M3 $INTENSITY TOOL OFF: M5 ; Disable Laser LASER INTENSITY: S要点解读开始/结束/归零时一律先M5确保激光在作业前后始终处于关闭状态属于安全惯例TOOL ON 使用M3 $INTENSITYLaserWeb 会把当前强度值以S参数形式填充进命令正好落入上面宏的S/255.0映射LASER INTENSITY 填S告诉 LaserWeb 强度参数名是S与 M3/M4 宏的解析方式对应。可选增强LCD 菜单控制示例配置还附带了一段可选的 LCD 菜单控制便于在打印机屏幕上直接开关工具和调节速度[menu __main __control __toolonoff] type: input enable: {pwm_tool TOOL in printer} name: Fan: {ON if menu.input else OFF} input: {printer[pwm_tool TOOL].value} input_min: 0 input_max: 1 input_step: 1 gcode: M3 S{255 if menu.input else 0} [menu __main __control __toolspeed] type: input enable: {pwm_tool TOOL in printer} name: Tool speed: {%3d % (menu.input*100)}% input: {printer[pwm_tool TOOL].value} input_min: 0 input_max: 1 input_step: 0.01 gcode: M3 S{%d % (menu.input*255)}这里通过printer[pwm_tool TOOL].value实时读取当前占空比——value状态字段在 docs/Status_Reference.md第 390 行起中有定义表示引脚当前被SET_PIN设置的值。菜单项最终仍复用 M3 宏S{255 if menu.input else 0}、S{%d % (menu.input*255)}保证 0~255 标度的一致性。源码级原理pwm_tool在 Klipper 中如何工作核心实现在 klippy/extras/pwm_tool.py 中模块类MCU_queued_pwm承担了全部底层逻辑。PrinterOutputPin.load_config_prefix是配置入口通过ppins.lookup_pin()解析引脚然后根据hardware_pwm分支走两套完全不同的 MCU 命令序列硬件 PWM 分支向 MCU 下发config_pwm_out含cycle_ticks、起始值、default_value、max_duration随后用queue_pwm_out排入队列PWM_MAX常量由 MCU 固件提供如 Atmel 系列的定时器计数上限占空比换算为value * PWM_MAX的计数值。软件 PWM 分支向 MCU 下发config_digital_out与set_digital_out_pwm_cycle以 GPIO 翻转加周期计数实现软件 PWM。这里有一个硬性约束软件 PWM 模式下shutdown_value只能是 0.0 或 1.0否则_build_config会直接抛出配置错误shutdown value must be 0.0 or 1.0 on soft pwm。其他值得注意的实现细节同步队列syncemitterMCU_queued_pwm从motion_queuing分配一个 syncemitteralloc_stepcompressFalsePWM 更新通过syncemitter_queue_msg注入运动队列与步进指令共享时间基准从而保证占空比切换与打印头运动在时序上严格对齐超时续命机制_gen_intermediate_updates会在当前值非默认值时以duration_ticks为间隔周期性地重发当前值相当于持续喂狗一旦主机停止确认MCU 侧max_duration即触发 shutdown。这与配置中的maximum_mcu_duration一一对应启动值约束_build_config中若设置了max_duration且起始值与 shutdown 值不同会报错Pin with max duration must have start value equal to shutdown value——这正是示例配置中value与shutdown_value都为 0 的原因。测试用例佐证仓库测试 test/klippy/pwm.cfg 与 test/klippy/pwm.test 覆盖了pwm_tool的基本行为测试配置声明了[pwm_tool test_pwm_tool]引脚 PH4测试脚本依次执行SET_PIN PINtest_pwm_tool VALUE0/0.5/0.5/0.25/1验证重复设置、半占空比与满占空比切换均能正确通过运动队列下发。这套测试同时覆盖硬件 PWM 与软件 PWM 两种分支可作为修改配置后回归验证的参考。排查与使用建议激光失控常亮优先检查shutdown_value是否配置为 0以及maximum_mcu_duration是否按版本上限正确设置同时确认二极管激光器的反相特性是否已用!引脚前缀或外围电路处理软 PWM 配置报错报错shutdown value must be 0.0 or 1.0 on soft pwm时要么把shutdown_value改为 0 或 1要么开启hardware_pwm: True超时误触发若打印过程中工具提前关闭可适当增大maximum_mcu_duration不超过 3 秒上限并确保归零/换刀等操作期间工具处于默认占空比更换主板pin需按新主板风扇引脚改写可参考 config/example-extras.cfg 中其它输出引脚配置段的写法保持一致风格。总结通过[pwm_tool] 三个[gcode_macro]宏Klipper 可以把一路风扇 PWM 输出变成完全可控、带安全超时的激光器/主轴驱动口M3/M4 S0-255控制占空比、M5安全关断LaserWeb 开箱即用maximum_mcu_duration提供主机失联时的硬件级兜底源码中的 syncemitter 机制保证 PWM 切换与运动时序精确同步。从 config/sample-pwm-tool.cfg 出发结合本文的参数说明与安全注意点即可在自己的打印机上安全、可靠地启用 PWM 工具控制。【免费下载链接】klipperKlipper is a 3d-printer firmware项目地址: https://gitcode.com/GitHub_Trending/kl/klipper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考