跳到主要内容

CAN 报错排查

本文用于处理 CAN 网络常见报错、通信异常排查以及搜索不到 CAN ID 时的排查流程。

适用场景：

  • Klipper 出现 CAN0、CAN UUID 或 CAN 网络相关报错。
  • CAN 设备间歇性离线或搜索不到。
  • 需要排查 CAN bytes_invalid、USB CANBUS bridge、BUS-OFF、Timer too close 等问题。

若需配置 CAN0、搜索 CAN ID 或了解接线与终端电阻规则，请先参考 CAN 网络配置与 ID 搜索。

常见报错判断​

报错常见原因处理方式
OSError: [Errno 19] No such device上位机找不到 CAN 设备检查 UTOC、USB 线、CAN 桥接固件和供电
can.CanError: Failed to transmit: [Errno 100] Network is downCAN0 未启动或配置错误重新配置 CAN0 并重启
can.CanError: Failed to transmit: [Errno 105] No buffer space availableCAN 缓存不足或系统网络队列异常确认缓存为 1024，必要时重新配置 CAN0
mcu 'xxx': Invalid CAN uuidCAN UUID 填写错误或设备未在线重新搜索 UUID，检查线序、供电和终端电阻
Serial connection closedKlipper 已找到配置但连接中断检查 CAN 网络质量、线序、终端电阻和固件速率
Duplicate canbus_uuid多个 MCU 配置使用了同一个 CAN UUID重新搜索 UUID，确认每个 [mcu xxx] 唯一
Unknown canbus_uuid xxx配置中的 CAN UUID 不在当前网络搜索结果中注释对应 MCU 配置后重新搜索并填写
Can not update MCU 'xxx' config as it is shutdownCAN MCU 已先进入 shutdown，后续配置更新失败向上翻 klippy.log 找第一条掉线或 shutdown 根因
USB CANBUS bridge 'mcu' is discarding!USB-CAN 桥接 MCU 的 CAN 硬件已丢弃消息查看 canstat_mcu、bus_state、供电、收发器和线束
can state BUS-OFF / ERROR-PASSIVECAN 控制器进入错误状态断电检查物理总线、终端电阻、线序和节点数量

更多 Klipper 报错可参考 常见报错提示。

CAN 通信报错排查​

电磁干扰是常见根源

CAN 总线通信异常的很大一部分原因是电磁干扰（EMI）。3D 打印机内部的步进电机线、加热线、热床线在大电流工作时会产生强电磁场，如果 CAN 通信线（CANH/CANL）与这些强电线近距离平行走线，干扰信号会耦合到 CAN 总线上，导致：

  • 通信超时、MCU 间歇性掉线
  • CAN 设备随机离线、canbus_query.py 扫描不到
  • 归位过程中触发 Timer too close 或 Communication timeout
  • 打印过程中突然 shutdown，日志无明显硬件错误

排查干扰时，优先检查 CAN 线与强电线的走线布局、屏蔽层接地、终端电阻完整性。

CAN bytes_invalid 计数器持续增长​

报错信息：klippy.log 中每秒统计行 Stats 出现 bytes_invalid 非零且持续增长。

报错原因：CAN 总线消息被重新排序（reordered messages），这是严重问题，会导致打印过程中任何阶段出现不稳定和随机错误。

已知原因：

  • Linux 内核版本低于 v6.6.0，存在 gs_usb CAN 驱动重排序 Bug。
  • 使用 candlelight 固件的 USB-CAN 适配器，固件版本低于 v2.0。
  • Klipper USB-to-CAN 桥接模式节点固件低于 v0.12.0。

解决方法：

  1. 如果使用 candlelight USB-CAN 适配器，升级固件至 v2.0 或更高。
  2. 如果使用 Klipper USB-to-CAN 桥接模式，确保桥接节点刷写 Klipper v0.12.0+ 固件。
  3. 如果 bytes_invalid 仍在增长，说明根本原因未解决，需继续排查内核版本和固件版本。
  4. 注意：bytes_invalid 递增不是由接线或终端电阻等硬件问题引起的，只能通过更新软件/固件修复。

CAN 总线队列不足导致 Timer too close​

报错信息：CAN 总线通信时出现 MCU 'xxx' shutdown: Timer too close。

报错原因：Linux 内核为 CAN 网络接口设置的默认队列长度（qlen）通常为 10，对 Klipper 高频低延迟通信需求来说偏小。Klipper 官方示例常用 txqueuelen 128；FlyOS-FAST 预设为 1024，在节点较多或高负载场景下余量更大。

解决方法：

  1. 检查当前 CAN 接口队列长度：
ip link show can0 | grep qlen
  1. 临时增大队列长度。普通系统可先测试 128，FLY 系统或多节点机器可使用 1024：
sudo ip link set dev can0 qlen 128
# 或
sudo ip link set dev can0 qlen 1024
  1. 永久设置：在 /etc/network/interfaces.d/can0 中添加 txqueuelen 128 或 txqueuelen 1024 参数；如果使用 systemd-networkd，则在 .link 文件中设置 TxQueueLength=。

USB CANBUS bridge is discarding / bus_state=off​

报错信息：USB CANBUS bridge 'mcu' is discarding!、canstat_mcu: bus_state=off、can state BUS-OFF、ERROR-PASSIVE、随后出现 Timeout with MCU 'xxx' 或 Serial connection closed。

报错原因：USB-CAN 桥接 MCU 的 CAN 硬件已经停止正常发送或接收消息。它通常不是简单的 txqueuelen 不足；更常见的是 CAN 线束接触不良、终端电阻位置错误、收发器或某个节点异常、工具板供电波动、总线过长或节点过多导致信号余量不足。

排查方法：

断电操作

检查 CANH/CANL、重新插拔工具板、调整终端电阻或测量 CANH-CANL 电阻前，请完全关闭打印机并断开电源供应。不要在通电状态下增减 CAN 节点或插拔工具板线束。

  1. 在 klippy.log 中找到 USB CANBUS bridge 'mcu' is discarding! 前后的 Stats 行，记录 canstat_mcu 的 bus_state、rx_error、tx_error、tx_retries。
  2. 如果 bus_state 从 active 变为 off 或 passive，优先按硬件总线问题排查，不要只调整 Linux 队列长度。
  3. 断电后确认 CAN 总线上有且仅有两个终端电阻，且位于物理总线两端；测得 CANH-CANL 阻值通常应接近 60Ω。
  4. 逐个减少 CAN 节点测试：先只保留主板和一个工具板，再逐步增加节点，确认是否某块工具板、某条线束或某个分支一接入就触发异常。
  5. 检查工具板供电和接插件压接状态；若某个工具板复位，桥接端可能先出现 discarding，随后其他 MCU 才被报告超时。
  6. 多工具头或长线束机器可临时降低 CAN 速率测试，或将多个工具头分到两个 USB-CAN 适配器上交叉验证。
  7. 更新 Klipper 与全部 CAN 节点固件后仍复现时，优先替换成品 CAN 线、USB-CAN 适配器或工具板收发器模块交叉测试。

多 CAN 节点只部分搜索到 UUID​

报错信息：canbus_query.py 只能搜索到部分工具板 UUID，或同一条 CAN 总线上任意一两个节点正常，增加到第三个或更多节点后全部搜索不到、连接超时、BUS-OFF。

常见原因：

  • 新增工具板没有进入 Katapult / Klipper CAN 模式，或固件 CAN 速率与上位机 can0 不一致。
  • 某个节点 CANH/CANL 接反、压接不良、收发器损坏，接入后拖垮整条总线。
  • 终端电阻不在物理总线两端，或工具板、集线板、转接板上误启用了多余终端电阻。
  • 多工具头线束形成过长回路、星形分支或阻抗不连续，节点数量增加后信号余量不足。
  • 不同批次工具板使用不同 bootloader、Katapult 或 Klipper 固件，搜索状态不一致。

排查方法：

断电操作

增减 CAN 节点、调整终端电阻、重新压接线束或测量 CANH-CANL 电阻前，请完全关闭打印机并断开电源供应。

  1. 只保留上位机 CAN 接口和一个目标工具板，确认单节点可搜索到 UUID。
  2. 逐个更换短线、端口和工具板，确认是某个节点问题，还是节点数量增加后才触发问题。
  3. 核对每块工具板的 bootloader、Klipper 固件通信方式和 CAN 速率，确保所有节点与 can0 一致。
  4. 确认每个 [mcu xxx] 的 canbus_uuid 唯一；如果设备已写入配置，搜索前可临时注释对应 MCU 配置并重启 Klipper。
  5. 断电测量 CANH-CANL 电阻，约 60Ω 通常表示两端各有一个 120Ω 终端电阻；明显偏离时先处理终端电阻。
  6. 如果任意两个节点稳定、三个以上不稳定，优先检查总线拓扑、线长、终端位置和集线板说明；必要时拆分为两条 CAN 总线。

CAN 总线节点不响应​

报错信息：CAN 设备突然离线，canbus_query.py 扫描不到设备。

常见原因：

  • CAN 终端电阻缺失或不正确（CANH-CANL 之间必须有且仅有两个 120Ω 电阻）。
  • CANH/CANL 接线松动、压接不良或插头松动。
  • CAN 线未使用双绞屏蔽线，或与强电线平行走线导致电磁干扰（最常见也最隐蔽的原因）。
  • USB-CAN 适配器供电异常。

干扰排查重点：

电磁干扰导致的 CAN 通信异常往往表现为"间歇性"和"随机性"——有时一切正常，有时突然掉线，断电重启后又恢复。排查时应重点关注：

  • 走线布局：CAN 通信线是否与电机线、加热线、热床线在拖链中并排走线？高速 PWM 调制的电机驱动信号和加热器开关噪声是最强的干扰源。
  • 屏蔽层接地：使用屏蔽线时，屏蔽层是否单端接地（仅在上位机侧接地）？双端接地会形成地环路，反而引入干扰。
  • 终端电阻位置：终端电阻是否安装在 CAN 总线物理末端，并通过板载跳线帽、拨码开关或成品终端接口启用？
  • CAN 线材规格：是否使用双绞线（绞距不超过几厘米）？平行线（非双绞）对共模干扰几乎没有抑制能力。
  • 接地完整性：机器电源、外壳是否可靠接地？未接地的机器金属框架相当于一个大型天线，容易拾取环境噪声。

排查方法：

断电操作

以下硬件排查必须在打印机完全断电并断开电源供应后进行：检查 CANH/CANL、重新走线、调整屏蔽层、启用/关闭终端电阻、测量 CANH-CANL 电阻。

  1. 确认 CAN 总线上有且仅有两个 120Ω 终端电阻，优先使用板载跳线帽、拨码开关或成品终端接口。
  2. 检查 CANH/CANL 接线是否牢固，插头是否完全插入。
  3. 请先断电再操作。使用万用表测量 CANH-CANL 之间电阻（正常约 60Ω）。
  4. 重新走线：将 CAN 通信线与强电线分开走线，保持至少 2-3cm 距离，避免平行。
  5. 确认屏蔽接地：屏蔽线仅在上位机侧接地，工具板侧悬空不接；不要自行拆卸电源或改动市电地线。
  6. 使用 candump 监控 CAN 总线流量，观察是否有大量错误帧（error frames）出现。
  7. 临时降低打印速度/加速度测试，如果问题消失，说明干扰与电机驱动强度正相关。

搜索不到 ID 的排查顺序​

  1. 执行 ip -details link show can0，确认 CAN0 存在并处于可用状态。
  2. 确认工具板、主板固件 CAN 速率与上位机 CAN0 速率一致。
  3. 如果设备 ID 已写入 printer.cfg，先临时注释对应配置，再关机断电约 10 秒后重新上电搜索。
  4. 检查 CAN-H 与 CAN-L 是否接反、断线或接触不良。
  5. 确认 CAN 网络两端各有一个 120Ω 终端电阻，整机断电后测量 CAN-H 与 CAN-L 之间的阻值应约为 60Ω。
  6. 确认工具板或主板已正常供电。
  7. 确认固件编译时选择了正确的通信方式。
  8. 若搜索结果显示 Application: CANBOOT 或 Application: Katapult，请先刷写 Klipper 固件后再搜索。

终端电阻规则​

断电操作

调整终端电阻跳线帽、拨码开关或重新插拔 CAN 线前，请完全关闭打印机并断开电源供应。

设备类型终端电阻要求操作说明
CAN 工具板需要 120Ω 终端电阻通过板载跳线帽或拨码开关启用
主板 CAN 接口需要 120Ω 终端电阻通过板载跳线帽或拨码开关启用
UTOC 类转换模块通常已内置 120Ω 电阻无需再额外启用终端电阻

快速排查顺序​

  1. 先看设备：执行 lsusb，确认能看到 1d50:606f。
  2. 再看配置：执行 ip -details link show can0，确认 CAN0 存在、速率正确、缓存为 1024。
  3. 最后看硬件：完全断电后测量 CAN-H 与 CAN-L，确认阻值约为 60Ω。

全部检查后仍然异常时，可尝试更换 USB 线、CAN 线、UTOC 或 CAN 桥接设备交叉测试。

CAN 设备固件更新参考​

本节用于已经能连接到 CAN 网络、且需要通过 CAN 更新主板或工具板固件的场景。不同产品的固件名称和编译方式不同，请先按对应产品教程编译好固件。

准备工作​

  1. 按产品教程编译好新的固件。
  2. 确认可搜索到设备 CAN UUID，或已在 printer.cfg 中填写该设备的 canbus_uuid:。
  3. 停止 Klipper 服务：
sudo systemctl stop klipper

执行更新​

将下方命令中的 <CAN_UUID> 替换为实际设备 ID。

版本说明

根据系统版本选择对应指令。

  • FlyOS-FAST 1.3.8 及以上版本 或 2026 年 4 月 9 日后更新过 Klipper 的系统：
python3 ~/klipper/lib/katapult/flashtool.py -u <CAN_UUID>
  • 旧版本系统，即 FlyOS-FAST 1.3.8 之前，或 2026 年 4 月 9 日前未更新 Klipper 的系统：
python3 ~/klipper/lib/canboot/flash_can.py -u <CAN_UUID>
注意

-u 后面必须有一个空格，然后再填写 CAN UUID。

出现 CAN Flash Success 提示，通常表示烧录成功。

Loading...

更新后操作​

更新完成后重新启动 Klipper：

sudo systemctl start klipper

如果更新后无法连接，请重新搜索 CAN ID，并确认 printer.cfg 中的 canbus_uuid: 是否仍然正确。

最终检查清单​

搜索不到 CAN ID 或 Klipper 无法连接 CAN 设备时，可按以下顺序快速核对：

  1. can0 可以被系统识别。
  2. bitrate 与固件编译时设置的 CAN 速率一致。
  3. qlen 或 txqueuelen 为 1024。
  4. CAN-H 与 CAN-L 没有接反。
  5. CAN 总线两端终端电阻正确。
  6. 工具板或主板供电正常。
  7. 固件通信方式选择正确。
  8. printer.cfg 中使用的是实际搜索到的 canbus_uuid:。
  9. 同一个 [mcu] 中没有同时启用 serial: 和 canbus_uuid:。
Loading...