Klipper 故障诊断手册：从报错原文到根因

现场手册。五类高频 shutdown —— TMC 驱动错误、限位不触发、Timer too close、链路抖动、热电偶读数越界 —— 每类按「报错原文 → 分层判据表 → 定位步骤」编排，拿到报错就能对上号。全篇的核心纪律：先只读取证（不发运动、不加热），再分层归因，最后才动手。症状常常指向 MCU，根因却在上位机。

0. 通用分层法

Klipper 的一次 shutdown，先回答一个问题：这条报错是谁产生的？ 答案决定你该读哪个寄存器、看哪个日志。

报错原文（关键片段）	归属层	第一动作
`TMC 'extruder' reports error: GSTAT: 00000002 drv_err=1(ErrorShutdown!)`	步进驱动芯片	`DUMP_TMC` 读 `GSTAT` / `DRV_STATUS`
`No trigger on stepper_x after full movement`	电气 / 接线	`QUERY_ENDSTOPS` 静止电平
`MCU 'mcu' shutdown: Timer too close`	上位机调度 + 传输	量 `mcu_task_avg` 与 `sysload`
`MCU 'mcu' shutdown: clocksync state: ... pred_variance=1.19e9`	主机↔MCU 时钟同步	同上，先看 USB 是否重枚举
`MCU 'mcu' shutdown: Thermocouple reader fault`	模拟前端 / 共模干扰	统计 `thermocouple_result` 的 value/fault

三条铁律，违反任何一条都会把排查变成猜：

只读优先：QUERY_ENDSTOPS 只读电平，DUMP_TMC 只读寄存器，两者都不发运动、不加热，可以远程做。
一次只改一个变量：同时改 run_current 又换 USB 线，等于什么都没验证。
记录带机器身份（hostname 或设备名），不要只写 IP —— 同批设备 IP 会漂，事后对不上账。

一、TMC 驱动错误：`drv_err=1(ErrorShutdown!)`

报错原文

TMC 'extruder' reports error: GSTAT: 00000002 drv_err=1(ErrorShutdown!)

Klipper 读到这一位之后会要求 FIRMWARE_RESTART，打印直接中断。

分层判据

GSTAT 是步进驱动芯片的全局状态寄存器，0x00000002 的 bit1 = drv_err：芯片检测到错误并自动关断输出（不再给电机力矩）。

⚠️ 这是 TMC 芯片内部错误（过流 / 过热 / 电源异常 / 电机短路 / 相序错），不是 diag 引脚报的 stall 检测。 diag1_pin 被注释只影响 Klipper 是否用它做 stall 判断，不影响这个软错误上报 —— 所以「把 diag 注释掉」关不掉它，也不该关。

真正的判据在 DRV_STATUS 的逐位解码。实测一台 F407 设备（TMC2240 挤出驱动，run_current: 2、diag1_pin: PD15， rref: 12300、interpolate: False）报错瞬间读到 DRV_STATUS = 0x811f011b：

位	字段	实测	结论
16–20	`cs_actual`	31	实际电流 = 满量程
24	`stallguard`	1	触发
25	`ot`（过温关断）	0	未关断
26	`otpw`（过温预警）	0	未预警
27/28	`s2ga/s2gb`（对地短路）	0	排除
29/30	`ola/olb`（开路）	0	排除
31	`stst`	1	电机静止

这张表的意义：报错瞬间 drv_err 置起，但驱动内部没有任何具体故障标志 —— 这是「边缘状态」故障，满电流 + 芯片温度 111.6–118.44℃（逼近 otpw 的 120℃ 门限），不是短路/开路这类硬故障。反向推理：ADC_TEMP = 118.44℃ 本身证明有电流在流（开路负载不会把芯片烧到 118℃）⇒ 电机确实接着，方向是过热 + 电流贴顶。

另一个判据是可复现性：空闲复测 GSTAT 一直是 0，只有打印时才报 —— 间歇性故障，且该机此前已报过 4 次，属于同一条病线（同一台设备更早的一次记录是 run_current: 2、diag1_pin 被注释、挤出头 250℃）。

配套的电流上限必须心里有数：

口径	值
TMC2240 手册 IRMS 最大	2.1 A RMS（前提：25℃ + 4 层板）；正弦峰值 3.0 A、桥臂 IMAX 5.0 A、供电 4.5–36 V
Klipper 允许填的最大值	2.1213 A RMS（`tmc2240.py`：`KIFS=[11750,24000,36000,36000]`、`max_cur = _get_ifs_rms(3)`；超过直接报配置错）
四档满量程	0.692 / 1.414 / 2.121 / 2.121 A
实际能开多少	散热说了算：小块驱动无散热片/无风冷时开不到 2 A 就触发过热保护，保守起点 1.4 A

⚠️ 还有一个「配置事实」要先核对：若 printer.cfg 头部注释写着「全部外置步进驱动器（200 kHz 脉冲），不走板上 TMC」， Klipper 理论上不会报 TMC 'extruder'。看到这条报错，说明配置里实际启用了 [tmc2240 extruder] 段（实测是被当天取消注释启用的）， 先核对配置事实，再动硬件。

定位步骤

DUMP_TMC STEPPER=extruder REGISTER=GSTAT → 确认 drv_err 是否锁存；
DUMP_TMC STEPPER=extruder REGISTER=DRV_STATUS → 按上表逐位解码，先排除 ot / s2g / ol；
DUMP_TMC STEPPER=extruder REGISTER=ADC_TEMP → 读芯片内部温度，> 110℃ 就走散热方向；
对照 run_current 与实际满量程档位（cs_actual=31 = 贴顶），确认没有超芯片规格；
空闲状态再读一次 GSTAT：为 0 ⇒ 间歇性边缘故障；非 0 ⇒ 硬故障，查相线与电机。

⚠️ 不要在打印中动手：改动前必须确认设备空闲（print_stats.state 非 printing 且 virtual_sdcard.is_active=false），人在现场时不要擅自重启。

处置方向：run_current: 2 → 1.4 + 加散热片/风冷；若该 TMC 段实际没接电机，就把整段重新注释、退回外置驱动器方案。 真堵转/过流（料堵、齿轮咬死、电机卡住）导致的 ErrorShutdown 是硬件保护，不能关 —— 只查误报那一侧。

二、限位不触发：`No trigger after full movement`

报错原文

No trigger on stepper_x after full movement

含义：Klipper 走完整个行程都没收到（新的）限位触发。第一件事不是调 homing_speed，而是分清「配置/方向」还是「电气/接线」。

分层判据：静止电平对照

拿一台同型号正常机做静止电平对照，一次就能定性。只读，不发任何运动指令：

curl -s -X POST "http://127.0.0.1:7125/printer/gcode/script?script=QUERY_ENDSTOPS"
curl -s "http://127.0.0.1:7125/printer/objects/query?query_endstops"
# → status.query_endstops.last_query = {stepper_x:0/1, stepper_y:…, stepper_z:…}

静止态读数	含义	典型物理原因
恒 1（一直「触发」），而正常机为 0	静止态即触发 ⇒ 归零全程不出现「翻转到触发」的新事件 ⇒ 报 No trigger	接到常闭触点 / 线间短接 / 插错口
恒 0，走向限位全程不翻转	信号根本没进来	断线 / 端子没插实 / 开关坏
与正常机一致	电气正常 ⇒ 转去查配置、方向、行程	—

三层的排查次序：① 配置/方向（endstop_pin、position_endstop、dir_pin、homing_speed）→ ② 电气/接线（电平、端子、线序）→ ③ 机械（挡块位置、行程够不够、限位是否被压住）。

定位步骤

两机配置逐行对比 [stepper_x/y/z] 段的 endstop_pin、position_endstop、homing_speed、dir_pin —— 一致 ⇒ 排除配置，锁定这台机的电气/接线状态；
历史日志按天计数：grep -c "No trigger" klippy.log* —— 若今天突然出现、历史 0 次，指向现场动过线/插头，而不是软件回归；
现场一步到位：人手压住限位，同时刷 query_endstops 看电平翻不翻 —— 翻转 = 开关好（查别处）；不翻 = 开关/线/接插件。这一步可以远程配合（现场压、远程读）。

实测案例：一台 F407 设备 X/Z 恒 1、Y 恒 0，姊妹机三轴全 0；两台 stepper 段逐行一致，当日日志 12 次 No trigger（历史 0 次） ⇒ 判为故障机限位接线/接插件问题，而不是配置问题。

四个坑

QUERY_ENDSTOPS 只读电平，不发运动、不加热 ⇒ 远程可用，符合「不在真机做动作」的红线；
query_endstops 对象的 last_query 在没发过 QUERY_ENDSTOPS 时是空 dict ⇒ 必须先发一次再取；
别用 G28 去试：那是真运动，失败后还会多一条 Move out of range 噪声，把证据搅浑；
⚠️ 同时看 ADC out of range：热敏接触不良会先把机器打到 shutdown，掩盖限位问题 —— 先修温度通道再看限位。

三、`Timer too close` / clocksync 失步：主机侧归因

报错原文

同一病根的两种表现：

报错	含义
`MCU 'mcu' shutdown: Timer too close`	主机下发指令的时戳到达 MCU 时已过期（主机侧调度延迟 + 传输重传）
`MCU 'mcu' shutdown: clocksync state: ... pred_variance=1.19e9`	MCU 时基预测方差爆表 = 主机↔MCU 时钟同步彻底失步

分层判据

一句话：Timer too close 几乎从不是 MCU 的问题 —— 先量 MCU 是否闲着，再查主机负载与 USB 链路。 实测（RK3562 上位机 + FLY-D8 主板，STM32H723）关机瞬间的三条证据：

层	指标	实测值	判读
MCU	`mcu_task_avg` / `mcu_awake`	`0.000000` / `0.000`	MCU 闲着 ⇒ 不是它算不过来
上位机	`sysload`	7.2 – 8.28	严重过载
上位机	核心板温度	65 – 68℃	长期高负载
USB	`dmesg` 重枚举	39 分钟掉 3 次（`usb 3-1.2` = 主控 `1d50:614e`）	链路在反复掉线
传输	`bytes_retransmit`	193（平时 9，暴增 20 倍）+ `print_stall = 4`	大量丢包重传

USB 拓扑的细节值得记：该口挂在内置 HUB（1a86:8091，同口还有 CH340）后面。这种拓扑叠加外置步进驱动的 200 kHz 脉冲 EMI，是典型诱因 —— 与「换线/换口」的处置直接对应。

一眼分清 MCU 侧还是主机侧

这一步只需要两个数，30 秒出结论：

`mcu_task_avg` / `mcu_awake`	`sysload`	结论
接近 0	正常（< 2）	两者都闲 ⇒ 查物理链路（USB 重枚举、EMI、接地）
接近 0	高（> 5）	主机侧：调度延迟，MCU 是被迫等指令的受害者
高（> 0.5）	正常	真·MCU 算不过来：查 `step_pulse_duration`、微步细分、SPI 频率与 TMC 读取开销

「MCU 闲着 + 主机过载」是其中最常见也最容易被误判的一格 —— 屏幕上的报错写着 MCU 'mcu' shutdown，人就会先去刷 MCU 固件，而真正要动的是上位机。

定位步骤

# 1) MCU 闲不闲 / 主机负载
curl -s --noproxy '*' http://<host>:7125/printer/objects/query?mcu,system_stats
# 2) 中断速率（5 秒采样，不碰触摸应为 0/秒）
sudo awk '/gt9xx/{print $2}' /proc/interrupts      # 采两次求差
# 3) D 状态进程（不可中断）—— 负载高但可运行进程少 = 驱动挂死
ps -eo pid,stat,wchan:18,comm | awk '$2 ~ /D/'
# 4) USB 重枚举 + 重传统计
dmesg | grep -E "usb .*disconnect"
grep -E "bytes_retransmit|print_stall|sysload" printer_data/logs/klippy.log | tail

判据链读法：mcu_task_avg ≈ 0 一秒排除一半方向；sysload 高 → 看 ps 里谁在 D 状态； D 状态里若出现网卡驱动线程（实测 Realtek SDIO WiFi 有 5 个线程卡在 RTW_XMIT/RECV/CMD_THREAD、RTWHALXT×2），那么 load 5.6 几乎全来自这里，而不是 CPU 在算。这就是「负载高」和「CPU 忙」的区别，也是当天修错一次东西的原因。

处置（按优先级）

修上位机负载：触摸屏中断风暴解绑驱动（irq 108 gt9xx 累计 158 万次、trigger type:8 = 低电平触发、中断线被一直拉低不清除 ⇒ 内核无限重入，irq/108-gt9xx 线程卡 D 状态）→ Xorg 从 76.5% 降到 20% （KlipperScreen 走 llvmpipe 软件渲染，本来就吃 CPU）；WiFi 驱动挂死直接插网线，一插同时解决网络抖动 + 5 个 D 状态线程。
修 USB 物理层：主控换带磁环的屏蔽 USB 线或插主板独立 USB 口，别走内置 HUB；检查电机/驱动线是否与 USB 线捆在一起（EMI）。

给 klipper 进程低延迟优先级（实测落地的 drop-in）：

# /etc/systemd/system/klipper.service.d/priority.conf
[Service]
Nice=-10
IOSchedulingClass=best-effort
IOSchedulingPriority=2

以上都做完再看 Timer too close 是否复发；不要先动 MCU 固件或改运动参数。

算账：别把账记错

700 次/秒的触摸中断只占约 6% 单核（≈ 1.5% 四核）—— 把 load 高归因给触摸屏会修错东西。真正的 load 来自卡在 D 状态的驱动线程。同理，判断「重启还是掉电」要看 pstore：pstore 空 + 日志无关机序列 + 看门狗未被持有（/dev/watchdog 无进程）+ SoC 50℃ ⇒ 指向掉电/硬挂，不是软件崩溃。

四、MCU 链路抖动与自适应缓冲

报错原文

链路层抖动的早期形态不是报错，而是这几个计数器：bytes_retransmit、print_stall、srtt、rttvar、rto。实测一行日志：

bytes_retransmit=9 retransmit_seq=2 srtt=0.000 rttvar=0.000 rto=0.025

分层判据

层	已有机制	判据
传输可靠性	ack/nak + 滑动窗口 + 超时重传（协议文档自述 inspired by TCP）	`bytes_retransmit` 增长速率
超时自适应性	已有：`rto` 由 `srtt` / `rttvar` 估算（即 TCP 的 RTO 算法）⇒ 抖动大时 `rttvar` 上升、`rto` 自动放大	`rttvar` 与 `rto` 是否同步抬升
前瞻缓冲	写死常量：`BUFFER_TIME_HIGH = 1.0`、`BUFFER_TIME_START = 0.250`（`toolhead.py`，不是配置项）	抖动是否超过 1.0 s

所以「用抖动间隔自动调整发送序列」这件事，只对一半，而且那一半 Klipper 已经做了。真正的机会在自适应前瞻缓冲 + 降速保件 + 链路质量画像，顺序不能反。

定位步骤

先量抖动分布：机队现成就有 srtt / rttvar / rto / 重传计数，采集一周就能出画像 —— 没有分布数据，调参就是瞎调；
用真实分布定阈值（比如 rttvar 的 P99 对应多少次重传算劣化）；
再做自适应缓冲：lookahead.set_flush_time() 可运行时调用（toolhead.py），抖动升高时把前瞻从 1.0 s 抬到 1.5–2 s，吸收抖动不掉线；
并行做降速保件：速度减半 ⇒ 报文率减半 ⇒ 链路压力减半，大件宁可表面有痕，也不要报废；
最后才考虑双链路冗余（USB ↔ CAN），需要 CAN 硬件支持。

⚠️ 自适应缓冲的代价：前瞻越大 ⇒ 暂停/急停的响应延迟越长。这是安全权衡，必须有上限并写进文档。

别做的四件事：① 想靠发送策略「消除」物理层抖动 —— 抖动来自线材、接地、电源、EMI、HUB，软件只能「吸收 + 降载 + 报根因」； ② 无限延长超时 / 无限重传 —— 把「该报的故障」变成「长时间卡顿后仍然出错」；③ 改波特率 —— USB CDC 没有波特率概念，CAN 波特率运行中不能改； ④ 大改帧结构与窗口策略 —— 已是 TCP-like 滑动窗口，边际收益低、回归风险高。

⚠️ 与第三节别混为一谈：Timer too close 是主机调度问题（CPU/D 状态/USB 重枚举），链路抖动是物理层问题，两者可以同时存在，但处置手段不同。同日同一台机上两类 shutdown 都出现过，不要归为一个根因。

五、MAX31856 热电偶 OV/UV 与读数越界

报错原文

MCU 'mcu' shutdown: Thermocouple reader fault

界面表现是时而显示温度、时而 0℃，日志反复这条 shutdown，机器陷在「关机 → 自动重启」循环（实测当日累计 87 次关机）。实测条件：一台 F407 设备（主板 FLY-D8），[heater_bed] 用 MAX31856 热偶；该固件分支把热偶读取放在 MCU 侧 （src/thermocouple.c + klippy/extras/spi_temperature.py）。

结论一句话：芯片没错、Klipper 没错，是热偶输入回路被共模干扰顶出共模窗口；把热电偶铁壳接地就好了。

先纠一个换算系数

排查这类问题第一件事是确认换算系数，系数错会把 28℃ 读成 901℃：

❌ 按数据手册 2⁻⁷ LSB 用 ℃ = raw/128，28℃ → 901℃、33.7℃ → 1077℃，据此得出「输入被顶到轨上」的结论 —— 该结论作废；
✅ 以固件代码常数为准：MAX31856_SCALE=5 + MAX31856_MULT=0.0078125 ⇒ ℃ = raw/4096。室温 K 型 raw ≈ 115,904 → 28.3℃，与挤出头 NTC 的 28.2℃ 一致 —— 这条自校验必须做，它同时验证了总线与系数。

分层判据：value / fault 组合

观测	判读
`value=16777215 (0xFFFFFF)` + `fault=255`	SDO/MISO 悬空或芯片从未被选中（16 进制全高，真实 SR 不会 8 位全 1）—— 焊点/供电问题
`value=0, fault=0` 占大比例（70–81%）	SPI 回读拿不到数据（MCU 侧缓冲区初值掩掉首字节 = 0）；时好时坏 ⇒ 接触不良/虚焊/走线
`value=0` + `fault=2`（OV/UV）	OV/UV 期间转换被挂起，LTC 保留旧值
读数恒定一个值（如 28.65 / 29.81 不动）	热偶根本没在测（≈ 芯片冷端值）；接地后变为 28.95–35.65℃ 连续变化 ⇒ 才是真测量
`fault != 0` 且值与前一条完全相同	真 OV/UV（转换挂起）；假 fault 时读数会照常刷新
上千次采样只出现 0x02 一种非零位	排除「随机位错」；位很「专一」⇒ 芯片按真实条件置位

grep -o "thermocouple_result.*" ~/printer_data/logs/klippy.log | grep -o "value=[0-9]* fault=[0-9]*" | sort | uniq -c
grep -o "Max31856: [A-Za-z /]*" ~/printer_data/logs/klippy.log | sort | uniq -c   # MCU 按位展开的告警
grep -c "Printer is shut" ~/printer_data/logs/klippy.log                          # 关机累计

电气门限：为什么小噪声触发不了

手册定义：OVUV=1 ⇔ 输入电压为负（< 0 V）或大于 VDD（> 3.3 V）；
推荐共模窗口 0.5 V ≤ VCM ≤ 1.4 V，BIAS 输出的 0.735 V 正落在中间；
Note 8：OV/UV 限值同时适用于 T+、T− 和 BIAS 三个脚；
「OV/UV 存在期间转换被挂起」⇒ 外观就是「一会儿有读数、一会儿没有」。

⇒ 0.735 V 附近的小噪声触发不了，要报 OV/UV，输入必须被生生打到 0 V 以下或 3.3 V 以上。实测每次只持续 0.3–1.2 秒、间隔无规律（段起点间隔 0.9 / 43.5 / 5.7 / 1.8 / 48.7 s），凑够 3 连击即关机。

定位步骤与修复链

先查供电：实测有一次 4.7 V 供电打伤芯片（真事故）→ 改回 3.3 V，AVDD 与 DVDD 两路都要；
查虚焊：重焊 SDO / CS / SCK（TSSOP-14 手焊易虚），0xFFFFFF 全 1 丢帧从 13–23 条/200 条降到 0；
查 BIAS 连线：BIAS(pin2) → T−(pin3) 接通（手册硬要求，用蜂鸣档实测导通）；
热偶铁壳接地 ← 决定性一步。

指标（同为最近 200 条采样）	接地前	接地后
有效读数（非零且无故障）	0 – 20%	88.5%
`value=0`（读不到数据）	0 – 81%	0 条
读数形态	恒定单值	28.95–35.65℃ / 77 种不同值、连续变化
OV/UV 占比	17 – 20%	11.5%（残留待治）

机理：铁壳悬空 = 浮动导体 = 天线。电机/显示屏排线/开关电源的高 dV/dt 经分布电容耦合到壳上，壳把电位带到高阻浮空的热偶输入；输入只靠 BIAS 那 0.735 V 弱偏置钉着，一出 [0 V, VDD] 窗口就置 OVUV。壳一接地，电位被钉在 0 V，耦合电流入地。

「是芯片的问题还是 Klipper 的问题」一句话分清：

干扰把输入顶出 [0V, VDD]
   ↓  芯片（MAX31856）按手册置 SR 的 OVUV 位并自动暂停转换
Klipper 连续 3 次读到 fault → 主动 shutdown 整机（这是保护，不是 bug）
   ↓
屏幕：MCU 'mcu' shutdown: Thermocouple reader fault

日志里看什么	属于谁
`thermocouple_result … fault=2`	芯片报的（按手册置位）
`shutdown … static_string_id=Thermocouple reader fault` / `Printer is shutdown`	Klipper 决定并执行的

芯片没「断」：SPI 一直通（value=0 已经 0 条）；若芯片掉线/复位，AUTOCONVERT 配置会丢、value 会恒 0。 决定性证据：只做了「铁壳接地」一个动作、代码一行没动，有效读数 0–20% → 88.5% —— 软件问题不可能因接地消失。

关机阈值在哪、为什么 0.9 秒就关机

MAX_INVALID_COUNT = 3 在 klippy/extras/spi_temperature.py 文件头部，是 host 端 Python 的模块级常量 （grep config.get 无命中 ⇒ 不是配置项，上游原版值）；
由 _build_config() 塞进 query_thermocouple … max_invalid_count=%u 下发 MCU（C 侧 spi->max_invalid，uint8 上限 255），计数与关机判定都在 MCU 里；
REPORT_TIME = 0.300 s ⇒ 3 次 ≈ 0.9 s 就关机；改成 30 就是 ≈ 9 s。

⚠️ 放宽阈值只是治标：先按硬件查。改这个 py 需要重启 Klipper host（FIRMWARE_RESTART 不够）。

治残留 11.5%

手册建议	现状	差距
T+ ~ T− 100 nF（差模，强烈建议）	10 nF	小 10 倍
T+ → GND 10 nF（共模）	无	高噪声环境手册明确要求
T− → GND 10 nF（共模）	无	同上
VDD/AVDD/DVDD 各 0.1 µF 就近去耦	待确认	必须贴引脚

补 T+/T− → GND 各 10 nF（治共模尖峰最对症的一步）；2. 差模 10 nF 升 100 nF；
热偶线双绞 + 屏蔽、屏蔽层单端接板侧 GND，远离加热棒/风扇/屏排线；4. 壳地线短而粗、与板 GND 同点；
还不行再 T+/T− 各串 100 Ω（组成 RC）；6. 三个电容都要贴引脚焊。另外 [heater_bed] max_temp: 120 对 K 型偏窄，按用途调宽。

动手时的四个坑

万用表在 4 MHz SPI 上没有判断力：SCK 空闲低（SPI mode 1）、CS 空闲必须 3.3 V（低有效）、MISO 空闲高阻（量到什么都不说明）； CS 每 0.3 s 才拉低约 24 µs（占空比 ≈ 0.008%），万用表看到的是平均值。要看波形得用逻辑分析仪（8 通道 USB + PulseView）。
「用手一碰外壳就报错」= 输入回路强耦合的指纹：断电用电阻档量 外壳 ↔ T−（Ω 级 = 接地型热偶、MΩ 级 = 绝缘型、几百 kΩ = 受潮/绝缘不良/屏蔽层被当信号线接）；带电用 MAX/MIN 峰值档量 T− 对 GND 放几分钟，抓那 0.3 s 瞬变（正常稳在 0.735 V ± 0.05 V）。
别急着降 spi_speed：value=0 占比与 4 MHz 无关。降到 1 MHz 之前先看「全 1 丢帧」是否已为 0；全 1 已清零、采样间隔精确 0.300 s 无丢帧 ⇒ 病根在模拟侧，不在总线。
可临时退回 NTC 止血（Generic 3950 + 对应 pin），机器就不再循环关机，MAX31856 单独调通再切回 —— 但改配置要现场确认。

附：一页速查

报错	关键判据（一句话）	先动什么
`GSTAT drv_err=1`	`DRV_STATUS` 有没有具体故障位；`cs_actual` 是否贴顶；芯片温度是否 > 110℃	降 `run_current` 到 1.4 A + 散热
`No trigger after full movement`	静止电平 vs 正常机（恒 1 / 恒 0 / 一致）	接线与接插件，不是参数
`Timer too close`	`mcu_task_avg ≈ 0` 且 `sysload` 高 ⇒ 主机侧	D 状态线程、中断风暴、USB 重枚举
`pred_variance` 爆表	同上 + `bytes_retransmit` 暴增	USB 线/口，别走内置 HUB
`Thermocouple reader fault`	`value/fault` 组合 + 铁壳对 T− 的电阻	壳接地，再补共模电容

报错	产生层	与限位故障的关系
`No trigger on stepper_x after full movement`	归零逻辑（Klipper）	本条主题：电平没翻转
`Move out of range: …`	运动规划（Klipper）	多半是坐标模式或行程限位问题，不是限位坏
`ADC out of range`	温度采集	热敏接触不良会先把机器打到 shutdown，掩盖限位问题

Klipper 故障诊断手册：从报错原文到根因

0. 通用分层法

一、TMC 驱动错误：`drv_err=1(ErrorShutdown!)`

报错原文

分层判据

定位步骤

二、限位不触发：`No trigger after full movement`

报错原文

分层判据：静止电平对照

定位步骤

同类报错别混

四个坑

三、`Timer too close` / clocksync 失步：主机侧归因

报错原文

分层判据

一眼分清 MCU 侧还是主机侧

定位步骤

处置（按优先级）

算账：别把账记错

四、MCU 链路抖动与自适应缓冲

报错原文

分层判据

定位步骤

五、MAX31856 热电偶 OV/UV 与读数越界

报错原文

先纠一个换算系数

分层判据：value / fault 组合

电气门限：为什么小噪声触发不了

定位步骤与修复链

关机阈值在哪、为什么 0.9 秒就关机

治残留 11.5%

动手时的四个坑

附：一页速查

相关阅读

Klipper 故障诊断手册：从报错原文到根因

0. 通用分层法

一、TMC 驱动错误：drv_err=1(ErrorShutdown!)

报错原文

分层判据

定位步骤

二、限位不触发：No trigger after full movement

报错原文

分层判据：静止电平对照

定位步骤

同类报错别混

四个坑

三、Timer too close / clocksync 失步：主机侧归因

报错原文

分层判据

一眼分清 MCU 侧还是主机侧

定位步骤

处置（按优先级）

算账：别把账记错

四、MCU 链路抖动与自适应缓冲

报错原文

分层判据

定位步骤

五、MAX31856 热电偶 OV/UV 与读数越界

报错原文

先纠一个换算系数

分层判据：value / fault 组合

电气门限：为什么小噪声触发不了

定位步骤与修复链

关机阈值在哪、为什么 0.9 秒就关机

治残留 11.5%

动手时的四个坑

附：一页速查

相关阅读

一、TMC 驱动错误：`drv_err=1(ErrorShutdown!)`

二、限位不触发：`No trigger after full movement`

三、`Timer too close` / clocksync 失步：主机侧归因