Klipper
概述
[wdd <stepper>] 是威动电机（WD DRIVE）驱动器在 Klipper 下的扩展模块，用于配置电机的控制参数：控制环整定、前馈、保护阈值、归位检测、负载模型等。这些参数会在 Klipper 启动时自动写入驱动器，运行过程中也可以随时读取或修改。
- 支持旋转电机（stp42）与直线电机（lin）两种驱动器，参数会自动适配对应型号，无需手动选择寄存器。
- 配置里写了什么就下发什么；没有写的可选项沿用驱动器出厂默认值。
准备工作
使用前请确认：
- 一台可正常运行的 Klipper 主机；
- 一台威动电机；
- 上位机与驱动板之间有可用的 CAN 通讯（USB-CAN 适配器或 CAN 网关）；
printer.cfg中已有目标电机的[stepper_*]配置，且microsteps、rotation_distance、step_pin均已填写。
配置 CAN 通讯（首次使用）
-
连接 CAN 总线：把 USB-CAN 适配器接到驱动板，总线两端各接 120 Ω 终端电阻，各节点波特率保持一致。
-
启用 CAN 接口。wddrive 固件固定使用 1 Mbit/s：
sudo ip link set can0 up type can bitrate 1000000 -
查询总线上的设备，取得驱动板的 CAN UUID：
~/klippy-env/bin/python ~/klipper/scripts/canbus_query.py can0输出形如：
Found canbus_uuid=1d002a00001c, Application: Klipper -
把 UUID 写入
printer.cfg的[mcu]段：[mcu] canbus_uuid: 1d002a00001c
查询不到设备时，依次检查：
can0是否已启用（ip -details link show can0）、波特率是否为 1 Mbit/s、终端电阻与接线是否正确、驱动板是否已运行在 Klipper 模式。
启用 wdd 模块
-
下载扩展模块 wdd.py，放入 Klipper 的
klippy/extras/目录。如果 Klipper 主机是树莓派，可以在电脑上
wdd.py所在目录（通常是「下载」目录）打开终端，直接用scp上传（把pi、raspberrypi.local换成实际的登录用户名与主机地址，也可以直接写 IP）：scp wdd.py pi@raspberrypi.local:~/klipper/klippy/extras/首次连接会提示确认主机指纹，按提示输入树莓派的登录密码即可。
-
在
printer.cfg中新增[wdd <电机名>]配置段，名称与对应步进电机的最后一段一致（如[wdd stepper_x]对应[stepper_x]）。 -
参考下面的说明填写参数。
-
保存后执行
RESTART使配置生效。
如果参数有误（缺少必要的整定方式、数值为负或超出允许范围等），Klipper 会在启动时报错并停止，不会带着错误配置运行。
配置说明
[wdd ...]会读取同名[stepper_*]的细分、行程等设置，两者必须同时存在。- 配置里明确写出的参数才会下发；未填写的可选项保留驱动器出厂默认值。
- 归位检测参数（
homing_*）有内置默认值，会始终下发，请按实际机械在台架上标定。 - 所有数值必须为非负数。
控制环整定
电机有三个控制环：位置环、速度环、电流环。每个环都必须给出整定方式，可以选择下面两种之一：
| 整定方式 | 如何填写 |
|---|---|
| 带宽整定 | 填写该环的 <环名>_bandwidth（单位 Hz）。此时该环的 kp / ki 会被忽略。 |
| 增益整定 | 填写该环的 <环名>_kp；速度环与电流环还必须同时填写 <环名>_ki。位置环没有积分项，只填 position_kp。 |
| 参数 | 说明 |
|---|---|
current_bandwidth |
电流环带宽 |
current_kp / current_ki |
电流环 P / I 增益 |
velocity_bandwidth |
速度环带宽 |
velocity_kp / velocity_ki |
速度环 P / I 增益 |
position_bandwidth |
位置环带宽 |
position_kp |
位置环 P 增益 |
# 电流环：带宽整定
current_bandwidth: 1000
# 速度环：kp/ki 整定（两者必须同时填写）
velocity_kp: 1.2
velocity_ki: 0.05
# 位置环：只有 kp
position_kp: 0.8
带宽与 kp/ki 二选一即可，整定方式由系统自动识别，不需要额外开关。
前馈（可选）
前馈用于改善跟随性能，属于可选项。
| 参数 | 说明 |
|---|---|
velocity_feed_forward |
速度前馈系数，0 表示关闭 |
velocity_accel_feed_forward |
加速度前馈系数 |
position_velocity_feed_forward |
位置模式下的速度前馈比例，1.0 表示直通 |
position_acceleration_feed_forward |
位置模式下的加速度前馈系数 |
位置类控制模式使用
position_*前馈，速度模式（PV）使用velocity_*前馈，两者互不影响，按需配置。
保护参数（可选）
以下保护参数均为可选项，不填写时使用驱动器出厂默认值。
电压保护
| 参数 | 说明 | 单位 |
|---|---|---|
over_voltage_fault |
过压故障阈值 | V |
over_voltage_warning |
过压警告阈值 | V |
under_voltage_fault |
欠压故障阈值 | V |
under_voltage_warning |
欠压警告阈值 | V |
voltage_filter_time |
电压滤波时间 | ms |
电流与过载保护
| 参数 | 说明 | 单位 |
|---|---|---|
short_circuit_threshold |
短路 / 过流保护阈值 | A |
over_current_filter_time |
过流滤波时间 | ms |
i2t_overload_level |
I²t 过载预警水位 | % |
i2t_max_time |
I²t 满载动作时间 | ms |
电机温度保护
| 参数 | 说明 | 单位 |
|---|---|---|
motor_over_temp_fault |
电机过温故障阈值 | °C |
motor_over_temp_warning |
电机过温警告阈值 | °C |
例如 over_voltage_fault: 54 表示过压故障阈值 54 V；motor_over_temp_fault: 85 表示电机过温故障 85 °C。
电机温度读取（可选）
驱动器内部带有电机温度采样（对象字典 0x2000:0C）。开启 motor_temperature 后，模块会周期性读取该温度并注册成 Klipper 温度传感器，可以直接在 Mainsail / Fluidd 的温度曲线里查看。若驱动器的对象字典没有 0x2000:0C，读取会失败并在日志中告警，请不要开启。
| 参数 | 说明 | 默认值 |
|---|---|---|
motor_temperature |
是否启用电机温度传感器，填 True 开启 |
False |
motor_temperature_gcode_id |
可选，温度传感器的 M105 标识（如 T0），填写后 M105 会一并返回该温度 |
不填（不在 M105 中显示） |
[wdd stepper_x]
# ...
motor_temperature: True
motor_temperature_gcode_id: T0 # 可选
启用后：
- 传感器以
temperature_sensor wdd stepper_x注册，可直接在 Mainsail / Fluidd 的温度图表中查看； - 可以用
TEMPERATURE_WAIT SENSOR="wdd stepper_x" MINIMUM=... MAXIMUM=...等待温度进入目标区间； wdd stepper_x对象状态中同时提供temperature与motor_temperature两个字段；- 单次读取超时会沿用上一次的数值，连续多次失败才会在
klipper.log中记录警告。
本开关只负责读取与显示温度，不写入对象字典；电机过温保护由上文
motor_over_temp_fault/motor_over_temp_warning负责，两者互不依赖，可以只开其中一个。
撞块归位检测
归位时驱动器会让电机缓慢顶向机械限位（撞块），当相位电流升高与位置跟随误差增大同时出现时判定已到达限位。相关参数有内置默认值，会始终下发。
| 参数 | 说明 | 默认值 |
|---|---|---|
homing_force_limit |
撞块阶段的最大推力（电流上限） | 1.0 A |
homing_current_threshold |
判定撞块所需的电流阈值 | 0.7 A |
homing_following_error |
判定撞块所需的位置跟随误差 | 2.0 mm |
homing_filter_time |
上述条件需持续保持的时间 | 50 ms |
homing_retract_distance |
撞块后的回退距离 | 3.0 mm |
注意： 上表默认值只是参考起点，不是安全值。请务必根据实际电机与机械结构在台架上标定后再用于生产，也不要把阈值全部设为 0，否则归位可能在开始瞬间就误判到位。
负载模型与其它
| 参数 | 说明 |
|---|---|
load_inertia_ratio |
旋转电机（stp42）的负载惯量比 |
load_mass |
直线电机（lin）的负载质量，单位 kg |
encoder_pll_bandwidth |
编码器 PLL 带宽 |
max_profile_velocity |
最大轮廓速度 |
max_motor_speed |
最大电机转速 |
两个负载参数按电机类型二选一填写。
多电机与多驱动板配置
一台 Klipper 主机可以同时控制多台威动电机。每台驱动器都是 CAN 总线上的一个独立节点，需要为它单独声明一个 [mcu <名称>] 段，并在对应 [stepper_*] 的引脚前加上该名称作为前缀。
定义多个 MCU
不带名称的 [mcu] 是默认 MCU；其余驱动板用 [mcu <名称>] 单独声明。每块板填写自己的 canbus_uuid，挂在同一条 CAN 总线上时 canbus_interface 相同：
[mcu]
canbus_interface: can0
canbus_uuid: f280ac7410f9
[mcu y]
canbus_interface: can0
canbus_uuid: c039d265332e
[mcu y1]
canbus_interface: can0
canbus_uuid: 24c700add124
引脚前缀
[stepper_*] 里的引脚归属哪块 MCU，由引脚前的 <mcu 名称>: 前缀决定；不写前缀就是默认的 [mcu]。注意取反符号 ! 写在最前面，即 !<名称>:<引脚>：
[stepper_x] # 使用默认 [mcu]
step_pin: PA0
dir_pin: PA1
enable_pin: !PA2
endstop_pin: PA3
[stepper_y] # 使用 [mcu y]
step_pin: y:PA0
dir_pin: y:PA1
enable_pin: !y:PA2
endstop_pin: y:PA3
[stepper_y1] # 使用 [mcu y1]，方向取反
step_pin: y1:PA0
dir_pin: !y1:PA1
enable_pin: !y1:PA2
endstop_pin: y1:PA3
wdd 段
每台电机都要有对应的 [wdd <stepper 名称>]，名称与 [stepper_*] 的最后一段一致，与它挂在哪块 MCU 上无关：
[wdd stepper_x]
# ...
[wdd stepper_y]
# ...
[wdd stepper_y1]
# ...
龙门等需要同步的双 Y 轴可以像上面这样用两个电机并联驱动（Klipper 会把
stepper_y1自动并入 Y 轴）；若无需机械同步，各自独立配置即可。所有电机共用同一条 CAN 总线时，请确保总线两端各接一个 120 Ω 终端电阻，各节点波特率统一为 1 Mbit/s。
完整配置示例
以下为旋转电机（stp42）的完整示例；直线电机（lin）把 load_inertia_ratio 换成 load_mass 即可。
[stepper_x]
step_pin: PA0
dir_pin: PA1
enable_pin: !PA2
microsteps: 16
rotation_distance: 20
endstop_pin: PA3
position_endstop: 0
position_max: 400
homing_speed: 50.0
[wdd stepper_x]
# --- 控制环（每环带宽与 kp/ki 二选一，三环都必须给） ---
current_bandwidth: 1000 # 电流环：带宽整定
velocity_kp: 1.2 # 速度环：kp/ki 整定
velocity_ki: 0.05
position_kp: 0.8 # 位置环：只有 kp
# --- 前馈（可选） ---
position_velocity_feed_forward: 0.5 # 位置模式速度前馈
position_acceleration_feed_forward: 0.7 # 位置模式加速度前馈
# --- 负载模型（按电机类型二选一） ---
load_inertia_ratio: 0.32 # 旋转电机（stp42）
# load_mass: 0.5 # 直线电机（lin），单位 kg
# --- 保护（可选，缺省使用出厂默认值） ---
over_voltage_fault: 54 # V
under_voltage_warning: 20 # V
motor_over_temp_fault: 85 # °C
short_circuit_threshold: 5 # A
i2t_overload_level: 100 # %
i2t_max_time: 10000 # ms
# --- 撞块归位检测（有默认值，会始终下发；此处演示覆盖） ---
# homing_force_limit: 1.0 # A，撞块阶段最大推力
# homing_current_threshold: 0.7 # A，撞块电流阈值
# homing_following_error: 2.0 # mm，撞块位置跟随误差
# homing_filter_time: 50 # ms，条件需持续保持的时间
# homing_retract_distance: 3.0 # mm，撞块后回退距离
# --- 电机温度读取（可选） ---
# motor_temperature: True # 启用电机温度传感器
# motor_temperature_gcode_id: T0 # 可选，M105 中显示为 T0
# --- 其它（可选） ---
# encoder_pll_bandwidth: 2000
# max_profile_velocity: 300
# max_motor_speed: 3000
运行时调整
调机时无需重启，可直接在 Klipper 控制台读取或修改参数。
写入参数（VALUE 填物理值，直接带单位对应的数值即可）：
WDD_SET STEPPER=stepper_x PARAM=current_bandwidth VALUE=800
WDD_SET STEPPER=stepper_x PARAM=over_voltage_fault VALUE=52
WDD_SET STEPPER=stepper_x PARAM=homing_force_limit VALUE=1.0
读取参数：
WDD_GET STEPPER=stepper_x PARAM=current_bandwidth
WDD_GET STEPPER=stepper_x PARAM=over_voltage_fault
命令执行后，控制台会回显读取到的当前值。
以下参数名可在
PARAM=后使用，与配置文件中的名称一致：控制环参数、前馈参数、保护参数、归位参数、负载模型参数。