MCU 连接指南
本指南用于排查主 MCU 无法与 Klipper 正常连接的问题。如果设备能够正常连接，只需要更换或补填 MCU ID，请直接查看 MCU ID 配置，无需清空现有配置。
排查流程
- 备份当前
printer.cfg。 - 仅在无法进入 Klipper 时启用最小测试配置。
- 确认主板当前运行的固件类型。
- 查询真实 MCU ID，并写入临时配置验证连接。
- 恢复完整配置，只更新其中的 MCU 连接项。
连接多个 USB/CAN 下位机时，容易把工具板 ID 误填到主板 [mcu]。排查阶段建议一次只验证主板，确认成功后再逐个添加工具板。
第一步：备份当前配置
1. 进入配置文件管理
在浏览器中输入上位机 IP 地址。Fluidd 用户点击左侧的 ...，Mainsail 用户点击 机器，然后找到 printer.cfg。
2. 创建备份
右键点击 printer.cfg，选择 Duplicate，将副本重命名为：
printer_Backup.cfg
Fluidd 操作示例：
Mainsail 操作示例：
后续最小配置只用于连接测试，不能代替正式打印机配置。确认 printer_Backup.cfg 已存在且内容完整后，才能继续。
如果正式配置使用了 [include *.cfg]，同目录中的 printer_Backup.cfg 也可能被加载。请将备份移到不会被该规则匹配的子目录，或改用 .txt 后缀保存，避免产生重复配置段。
第二步：按需启用最小测试配置
如果 Klipper 当前能够正常启动和连接，只是需要修改 MCU ID，请保留完整配置并直接前往第三步。
当错误配置或多个下位机导致 Klipper 无法启动时，可以暂时将 printer.cfg 内容替换为以下最小配置：
[mcu]
serial: /tmp/klipper_host_mcu
[printer]
kinematics: none
max_velocity: 200
max_accel: 1000
点击 SAVE & RESTART 保存。此处的 /tmp/klipper_host_mcu 是上位机 Host MCU 的临时连接地址，仅用于让最小配置启动，不是主板的真实 USB ID。
开始前请完全关闭打印机并断开电源供应。不要在通电状态下插拔线束、整理接口线序或触碰端子。
断电后断开暂不参与测试的工具板数据线，只保留上位机与主板之间必要的数据连接。不要拆解电源、改动市电接线或触碰裸露端子。确认连接后再重新上电。
第三步：确认固件与通信方式
先按SSH 连接教程进入上位机，然后执行：
lsusb
根据输出判断设备当前模式：
VID:PID | 设备状态 | 下一步 |
|---|---|---|
1d50:614e | Klipper USB 固件 | 查询 USB ID |
1d50:606f | USB 转 CAN 桥接固件 | 查询 CAN UUID |
1d50:6177 | Katapult 烧录模式 | 先刷写或启动 Klipper 固件 |
1a86:7523 | USB 串口适配器 | 查询 RS232 路径 |
若提示 lsusb: command not found，可安装 usbutils：
sudo apt-get update
sudo apt-get install usbutils
lsusb 没有目标设备先确认主板已经正常供电、数据线支持通信且固件模式正确。不要仅凭设备名称猜测 ID，也不要将 Katapult/Bootloader 模式的 ID 写入 printer.cfg。
第四步：查询并填写 MCU ID
USB 主板
ls /dev/serial/by-id/*
输出中应包含 usb-Klipper_...。包含 katapult 或 Bootloader 的设备仍处于烧录模式，不能作为 Klipper 运行 ID。
CAN 主板
- 普通 Linux 上位机
- FlyOS-FAST / FLY 上位机
~/klippy-env/bin/python ~/klipper/scripts/canbus_query.py can0
python3 ~/klipper/scripts/canbus_query.py can0
只有 Application: Klipper 对应的 UUID 才能写入配置。若显示 Total 0 uuids found，请转到 CAN 网络与 ID 搜索继续排查。
RS232 设备
ls -l /dev/serial/by-path/
以下规则与 FAQ 共用同一份内容：
MCU ID 配置说明
Klipper 中的 MCU ID 指的是 [mcu] 或 [mcu xxx] 配置段里用于连接控制板的识别信息。不同通信方式写法不同：
| 连接方式 | 配置项 | 示例 |
|---|---|---|
| USB 固件 | serial: | serial: /dev/serial/by-id/usb-Klipper_xxxxxxxxxxxx |
| CAN 固件 | canbus_uuid: | canbus_uuid: xxxxxxxxxxxx |
| RS232 设备 | serial: | serial: /dev/serial/by-path/xxxxxxxxxxxx |
| 上位机 MCU | serial: | serial: /tmp/klipper_host_mcu |
填写规则：
- 主板默认使用
[mcu]，工具板或扩展板使用[mcu tool]、[mcu toolboard]等自定义名称。 - USB 固件只填写
serial:，CAN 固件只填写canbus_uuid:，不要在同一个[mcu]中同时保留两项。 - 多 MCU 机器中，每个
[mcu xxx]都必须使用自己的真实 ID，不要复制同一个 USB ID 或 CAN UUID。 [mcu xxx]的名称会影响引脚前缀，例如[mcu tool]的引脚应写成tool:gpio13；名称大小写要保持一致。- 文档示例里的
xxxxxxxx不能直接使用，必须替换为实际搜索到的 ID。 - RS232 设备除
serial:外，通常还需要填写baud: 250000和restart_method: command；以对应产品文档为准。
常见错误：
- 把烧录模式 ID（如包含
katapult、canboot的 ID）当作 Klipper 固件 ID 使用。 - USB 固件配置了
canbus_uuid:，或 CAN 固件仍保留旧的serial:。 - RS232 设备只填写路径，遗漏所需的
baud:或restart_method:。 - 工具板配置成
[mcu]，覆盖了主板 MCU 配置。 - 引脚前缀和 MCU 名称不一致，例如配置是
[mcu toolboard]，引脚却写tool:gpio13。
USB ID 查询：USB 固件可执行
ls /dev/serial/by-id/*获取 ID。
CAN ID 查询：CAN 网络与 ID 搜索
RS232 路径查询：执行
ls -l /dev/serial/by-path/获取稳定设备路径。
工具板配置：工具板 MCU 添加与跨板配置
完整查询说明和多 MCU 示例：MCU ID 配置
第五步：验证主 MCU
将 [mcu] 中的连接地址更新为刚查询到的真实 ID。如果第二步启用了最小配置，请替换其中的 /tmp/klipper_host_mcu；如果保留了正式配置，则只修改原有 [mcu] 的 serial: 或 canbus_uuid:，不要改动其他参数。
- USB 主板
- CAN 主板
[mcu]
serial: /dev/serial/by-id/usb-Klipper_stm32h723xx_12345-if00
[mcu]
canbus_uuid: 688e89f0e401
点击 SAVE & RESTART。连接成功后：
- 打开 Fluidd 的
System页面。 - 在
Mcu Information中找到主 MCU。 - 核对
Micro-Controller与主板实际主控型号是否一致。
[mcu]应对应主板，不应显示成工具板型号。- 所有 MCU 固件版本应与当前 Klipper 系统兼容。
- 如果仍然无法连接，请按报错原文进入连接问题排查。
第六步：恢复完整打印机配置
如果第二步启用了最小配置，完成连接验证后必须恢复正式配置。不要把仅含 [mcu] 和 kinematics: none 的测试配置长期使用。
使用过最小配置
确认主 MCU 能够连接后：
- 将当前临时的
printer.cfg重命名为printer_MCU_Test.txt，保留它用于复查，同时避免被*.cfg通配符加载。 - 复制此前的
printer_Backup.cfg，将副本命名为printer.cfg。 - 打开恢复后的
printer.cfg，找到原有[mcu]配置段。 - 只更新
serial:或canbus_uuid:，不要覆盖步进电机、加热器、限位和其他打印机参数。 - 点击 SAVE & RESTART，再次进入
Mcu Information确认连接。
如果备份不存在或内容不完整，请先从配置历史记录恢复完整配置，不要继续覆盖当前文件。
跳过了最小配置
当前 printer.cfg 已经是正式配置，无需重命名或恢复文件。确认 MCU 连接成功并保留第一步创建的备份即可。
第七步：添加工具板
主 MCU 验证成功后，再逐个连接并添加工具板：
工具板与多 MCU 配置：工具板 MCU 添加与跨板配置