跳到主要内容

TMC 报错排查

技术背景​

TMC（Trinamic）驱动器通过专用寄存器报告状态和错误信息。了解这些寄存器有助于快速诊断问题：

  • IFCNT 寄存器：通信帧计数器，用于验证主控制器与驱动器之间的通信是否正常。
  • GSTAT 寄存器：全局状态寄存器，包含复位、驱动错误等全局状态信息。
  • DRV_STATUS 寄存器：驱动状态寄存器，提供详细的驱动器工作状态，包括温度警告、短路、开路等故障信息。

当 Klipper 报告 TMC 错误时，通常会显示具体的寄存器值和故障标志。TMC 驱动错误表示驱动芯片检测到问题并自我保护禁用，Klipper 检测到驱动禁用后会进入 shutdown 状态。

断电操作

检查跳线帽、驱动模块、电机线、SPI/UART 线序或接线端子前，请完全关闭打印机并断开电源供应。禁止带电插拔驱动模块或步进电机线。万用表电阻档只能在断电状态使用。

链接不上驱动（IFCNT 通信失败）​

报错信息：Unable to read tmc uart 'stepper_x' register IFCNT 或 Unable to read tmc spi 'stepper_x' register IFCNT。

Loading...

报错原因：TMC 驱动器（UART/SPI 模式）与主控制器之间的通信失败，导致无法读取 IFCNT 寄存器值。常见于 UART 跳线帽未安装、驱动板供电异常或 UART/SPI 引脚配置错误。

解决方法：

  1. 断电后检查对应驱动的 UART 跳线帽是否正确安装。
  2. 确认 printer.cfg 中 TMC 配置的 uart_pin（或 spi_bus / spi_software_*_pin）与实际接线一致。
  3. 先通过电源指示灯与驱动模块安装方向初步判断供电状态。如指示灯正常、模块安装方向正确但问题依旧，可使用成品线束替换或交叉测试（将驱动换到其他端口验证）。裸露 24V 端子的电气检测请联系售后或专业人员。
  4. 如果是首次刷写 Klipper 后立刻报错，整机断电数秒（同时拔掉 USB 和主电源）后再上电，清除驱动残留状态。
  5. 断电后尝试更换驱动板或切换驱动端口测试。
  6. 如果使用非 FLY 品牌驱动，确认其 UART 引脚定义（FLY 驱动 UART 脚通常是左边从上往下数第四个引脚）。
Loading...

对于特殊情况，如果购买的驱动 UART 脚在第五个引脚，可按下方跳线方法解决：

Loading...
  1. 检查 uart_address 与驱动板硬件跳线是否匹配。
  2. 检查数据线是否完好，无断裂或接触不良。

驱动过热（OvertempError / OvertempWarning）​

报错信息：TMC 'stepper_x' reports error: DRV_STATUS: ... ot=1(OvertempError!) 或 otpw=1(OvertempWarning!)。

Loading...

报错原因：TMC 驱动芯片温度超过安全阈值触发保护。注意：这是驱动器过热，不是电机过热！

  • OvertempWarning（otpw）：温度超过约 120°C 预警阈值，驱动仍可工作但建议排查。
  • OvertempError（ot）：温度超过约 150°C 关断阈值，驱动自动禁用。

解决方法：

  1. 降低电机运行电流（run_current），建议先降低 20-30%。
  2. 如有设置保持电流（hold_current），可适当降低或完全禁用。
  3. 检查驱动散热片是否贴合良好，导热硅脂是否充足。
  4. 增加驱动散热风扇，确保空气流通。
  5. 确认驱动板采样电阻（sense resistor）值配置正确。
  6. 降低 stealthchop_threshold 或切换到 spreadCycle 模式。
  7. 检查驱动安装环境是否密闭导致热量积聚，避免高温环境中长时间运行。

短路故障（ShortToGND / ShortToSupply）​

报错信息：TMC 'stepper_x' reports error: DRV_STATUS: ... s2vsa=1(ShortToSupply_A!) 或 s2ga=1(ShortToGND_A!)。

报错原因：驱动检测到极高电流。可能是电机线松动短路、电机绕组绝缘破损，或者是 stealthChop 模式下预测负载不准导致过流。

解决方法：

  1. 请先断电再操作。检查对应电机线是否松动或破损，使用万用表电阻档测量电机线圈电阻（正常约 1.5~3Ω）。
  2. 断电后检查电机接头是否牢固。
  3. 如需处理电机外壳接地，请使用厂家提供的接地点或联系售后，不要自行改动电源地线或裸露端子。
  4. 尝试禁用 stealthChop 测试：SET_TMC_FIELD STEPPER=stepper_x FIELD=en_spreadCycle VALUE=1
  5. 如果切换后报错消失，说明是 stealthChop 预测问题；否则可能是真实硬件短路。

开路故障（OpenLoad）​

报错信息：TMC 'stepper_x' reports error: DRV_STATUS: ... ola=1(OpenLoad_A!) 或 olb=1(OpenLoad_B!)。

报错原因：驱动检测到某一相电机绕组没有形成有效负载，通常表示电机线断开、插头松动、线圈接错，或低电流/stealthChop 状态下误判。

解决方法：

  1. 断电后重新插拔电机线，确认端子压接牢固。
  2. 请先断电再操作。使用万用表测量 A/B 两组线圈阻值，两组应接近且不应开路。
  3. 断电后检查电机线序，确认 A 相两根线在同一组，B 相两根线在另一组。
  4. 临时关闭 stealthChop：在配置中设置 stealthchop_threshold: 0 后测试。
  5. 适当提高 run_current 测试，若只在极低电流下出现，可能是误判。
  6. 断电后更换电机线或电机交叉测试，定位是线束、电机还是驱动端口问题。

短路+开路组合故障（A相短路B相开路）​

报错信息：TMC 'extruder' reports error: DRV_STATUS: ... s2vsa=1(ShortToSupply_A!) csactual=31 ola=1(OpenLoad_A!) olb=1(OpenLoad_B!)。

报错原因：TMC 驱动器故障诊断位指示硬件问题：s2vsa=1 表示 A 相短路到电源，ola=1 表示 A 相开路，olb=1 表示 B 相开路，csactual=31 表示当前电流设置值可能过高。这些故障通常同时出现，表明电机或驱动器存在严重的硬件问题。

解决方法：

  1. 请先断电再操作。使用万用表测量步进电机 AB 两组线圈的阻值是否一致（通常应为 1-2Ω 且两组值相近）。
  2. 断电后仔细检查步进电机线束和接插件是否有松动、短路或接触不良。
  3. 确认 TMC 驱动器的电流设置是否合适，过高电流可能导致这些问题。
  4. 尝试禁用 stealthChop 模式测试：在配置中设置 stealthchop_threshold: 0。

短路+开路组合故障（B相短路A相开路）​

报错信息：TMC 'extruder' reports error: DRV_STATUS: ... s2vsb=1(ShortToSupply_B!) ola=1(OpenLoad_A!) cs_actual=25。

Loading...

报错原因：TMC 驱动器故障诊断位指示：s2vsb=1 表示 B 相短路到电源，ola=1 表示 A 相开路，cs_actual=25 表示当前电流设置值。通常由以下原因导致：电机接线错误（A/B 相接反或短路）、电机本身故障（绕组开路）或驱动板硬件问题。

解决方法：

  1. 请先断电再操作。使用万用表测量步进电机 A、B 两组线圈的阻值是否一致（正常应相近）。
  2. 断电后确认电机线序正确，通常应为左边一组（A 相）、右边一组（B 相）。
  3. 断电后检查所有接线端子是否牢固，无松动或接触不良。
  4. 如有条件，可在断电后将电机连接到其他已知正常的驱动端口进行测试。

TMC 驱动 GSTAT 报错（欠压/复位）​

报错信息：TMC 'xxx' reports GSTAT: 00000005 reset=1(Reset) uv_cp=1(Undervoltage!)，以及随后出现的 TMC 'xxx' reports error: GSTAT: 80000000（也可能为 40000000 等只有最高位置 1 的读数）。

含义：GSTAT 是 TMC 驱动的全局状态寄存器，只有低 3 位有定义：

  • reset=1（bit0）：驱动发生过复位（如上电、欠压掉电后自动复位）。
  • drv_err=1（bit1）：驱动内部错误，通常伴随 DRV_STATUS 中的具体故障标志。
  • uv_cp=1（bit2）：电荷泵欠压，说明驱动端的电机电源（VM，通常为 24V）出现欠压或瞬时中断，驱动已无法正常工作。

80000000、40000000 这类高位读数不是新的故障码，而是驱动掉电复位后 SPI 读回的无效数据。能解码出 reset、uv_cp 等具体标志，恰好说明 SPI 通信本身正常，问题在驱动供电链路而非通信；只有当各驱动的读数长期为无意义乱码（如随机变化的 ffffffff）时，才需要排查 SPI 接线（见 SPI 通信错误）。

常见原因：

  • 24V 电源链路接触不良：电源端子压接不牢、线径偏细、保险丝座接触不良、主板内部 VM 分配端子松动。
  • 电源带载能力不足或带载瞬间跌落：多电机同时使能（如执行 G28 归位时 Z 轴多个电机同时通电）的瞬间电流最大，是最容易触发欠压的时刻；即使电源功率看起来充足（例如 600W/24V），也应优先排查端子与线束链路。
  • 电机相线短路或电机线破损：短路会瞬间拉低 VM，导致同一电源链路下的多个驱动同时报欠压。
  • 同一 VM 链路下的多个驱动（如 z/z1/z2/z3）几乎同时报 GSTAT 异常时，基本可以排除单个驱动损坏，应集中排查共用供电链路。

解决方法：

断电操作

检查电源端子、线束、保险丝或电机线前，请完全关闭打印机并断开电源供应。不要在通电状态下插拔线束或触碰端子。

  1. 断电后检查 PSU 到主板的 24V 输入端子：确认压接牢固、无松动、无发黑或烧蚀痕迹；多路输入的主板确认每一路都已接好。
  2. 断电后检查 24V 线束线径是否满足电流需求，检查保险丝座（如有）接触是否良好、保险丝规格是否正确。
  3. 断电后用万用表电阻/通断档检查电机线与电机：确认电机线无破皮、无相间短路，A/B 两组线圈阻值正常且相近（参考值约 1~3Ω，实际测量存在误差，以两组读数一致为判断重点）。
  4. 核算电源带载能力：统计电机、加热器、热床同时工作的总功率并保留余量；功率充足但仍复现时，按第 1、2 步重点排查端子与线束。
  5. 如具备低压测量条件，可重新上电后测量主板 24V 输入端子电压，并在多电机同时使能（如执行 G28）时观察电压是否明显跌落（参考值：应稳定在 24V 附近，实际测量存在误差，以变化趋势为判断重点）。测量时表笔不要短接相邻引脚，避免造成二次短路。
  6. 交叉验证：断电后将报错轴电机换到其他驱动端口、或更换成品电机线束测试，区分是线束/电机问题还是供电链路问题。
  7. 裸露端子的进一步电气检测与电源本体问题请联系售后或专业人员处理，不要自行拆解电源。

相关配置参考：

多 Z 电机机器应为每个 Z 轴驱动分别设置 run_current，适当降低电流可减小同时使能时的瞬时压降（数值需按机器实际情况调整，不能替代供电链路排查）：

[tmc5160 stepper_z]
run_current: 1.2

[tmc5160 stepper_z1]
run_current: 1.2

排查期间可用 DUMP_TMC STEPPER=xxx 读取驱动完整寄存器，确认 GSTAT 与 DRV_STATUS 的实时状态。

相关小节：只有复位标志时的排查见 驱动复位（Reset），DRV_STATUS 中的欠压保护见 欠压保护（Undervoltage）。

驱动复位（Reset）​

报错信息：TMC 'stepper_x' reports error: GSTAT: 00000001 reset=1(Reset)。

Loading...

报错原因：电源不稳定或外部干扰导致驱动器自动复位。常见于电源电压波动、接线接触不良或电磁干扰。

解决方法：

  1. 完全断电后检查 24V 电源线、驱动模块和主板插座是否松动、发黑或烧蚀。
  2. 更换已知正常的电源、驱动模块或线束进行交叉测试。
  3. 检查驱动散热和风扇是否正常。
  4. 检查电机线是否与加热器、热床线长距离并行，必要时断电后重新整理走线。
  5. 请先断电再操作。检查电机线是否存在断裂、内部断股或端子接触不良导致的间歇性连接。拖链长期运动可能导致线缆疲劳断裂，可重点检查拖链弯折处及端子压接处。
  6. 不建议客户自行改动驱动电源输入端、增加电子元件或改动接地；此类操作应交由专业人员或售后处理。

欠压保护（Undervoltage）​

报错信息：TMC 'stepper_x' reports error: DRV_STATUS: ... uv_cp=1(Undervoltage!)。

报错原因：驱动检测到供电电压过低事件。通常由电源故障、接线松动或供电功率不足引起。

解决方法：

  1. 完全断电后检查电源线、主板电源插头和端子外观是否松动、发黑或烧蚀。
  2. 确认电源规格满足驱动和加热器总功率需求。
  3. 使用已知正常的电源或线束进行替换测试。
  4. 裸露 24V 端子的电气检测请联系售后或专业人员，不要自行处理。

SPI 通信错误（DRV_STATUS: ffffffff）​

报错信息：Unable to write tmc spi 'stepper_x' register ...、TMC reports error: DRV_STATUS: ffffffff ... 或 READRSP@RDSEL2: 00000000 ...。

报错原因：SPI 模式下无法与 TMC 驱动通信（tmc2130/tmc5160/tmc2660）。通常是 SPI 接线错误、SPI 总线上有未配置设备、或者 TMC 驱动自复位/故障。

解决方法：

  1. 断电后检查 SPI 接线（MOSI、MISO、SCK、CS）顺序是否正确。
  2. 如果 SPI 总线共享多个设备，确保每个设备都在 Klipper 中完整配置。
  3. 断电后让主板只接一个驱动单独测试，排除共享总线互相干扰。
  4. 确认驱动供电正常，必要时断电数秒后重新上电。
  5. 如果报错伴随 reset=1、uv_cp=1 或随机 ffffffff，优先检查供电和驱动接触。

单独驱动测试：如需隔离验证驱动是否正常，请参考 外设与驱动测试 中的 SPI 驱动单独测试方法。

TMC SPI chain 配置错误​

报错信息：TMC SPI chain must have same length、TMC SPI chain can not have duplicate position。

报错原因：使用 SPI 串联链路的 TMC 驱动时，多个驱动的 chain_position、chain_length 或片选配置不一致，导致 Klipper 无法判断每个驱动在 SPI 链中的位置。

解决方法：

  1. 如果主板不是 SPI 串联链路设计，不要随意添加 chain_position 和 chain_length。
  2. 对照主板或驱动板厂家配置模板，确认每个 TMC 驱动的 chain_length 完全一致。
  3. 确认每个驱动的 chain_position 唯一，不能重复。
  4. 如果只是普通 SPI 总线多 CS 片选结构，应分别配置每个驱动的 cs_pin，不要按 SPI chain 写法配置。
  5. 保存后执行 RESTART，再用 DUMP_TMC STEPPER=<stepper> 逐个确认通信。

Timeout on wait for 'tmcuart_response'​

报错信息：Timeout on wait for 'tmcuart_response' response，日志中可能伴随 Unable to read tmc uart 'stepper_x' register DRV_STATUS。

常见原因：

  • TMC UART 接线虚焊、断裂或接触不良，尤其是拖链内线材反复弯折后内部断裂。
  • uart_pin 配置错误，或主板上 UART 跳线帽未正确安装。
  • 驱动供电不足或电源波动，导致 TMC 芯片在通信瞬间复位。
  • 多个驱动共用同一 UART 总线时地址冲突或总线负载过重。
  • 主板 UART 引脚被其他功能占用（如蓝牙、串口调试）。

解决方法：

断电操作

检查驱动板、UART 接线或跳线帽前，请完全关闭打印机并断开电源供应。

  1. 断电后检查报错驱动的 UART 接线是否牢固，线材是否有明显弯折、破损或虚焊。
  2. 确认 uart_pin 与主板实际接线一致，并检查主板上的 UART 跳线帽是否安装到位。
  3. 如果多个驱动共用一条 UART 总线，确认每个驱动的 uart_address 不重复。
  4. 检查驱动供电是否正常，尤其是 12V/24V 转换模块和保险丝。
  5. 尝试将报错驱动与相邻轴驱动互换位置，确认是驱动问题还是主板插槽/线束问题。
  6. 如果只在打印过程中出现而空闲时正常，检查线束是否在运动时被拉扯。

与 IFCNT 报错的关系：Timeout on wait for 'tmcuart_response' 和 Unable to read tmc uart register IFCNT 本质相同，均为 UART 通信超时。前者多出现在打印过程中，后者多出现在启动初始化阶段。排查方法一致，详见 IFCNT 通信失败。

Loading...