跳到主要内容

MCU ID 配置

本页用于集中说明 Klipper 中主板、工具板、CAN 设备和上位机 MCU 的 ID 填写规则。配置连接类问题时，请先确认通信方式，再填写对应的 serial: 或 canbus_uuid:。

查询 MCU ID​

在填写 ID 之前，需要通过 SSH 登录上位机执行对应命令获取真实的设备标识。

USB 设备​

ls /dev/serial/by-id/*

输出示例（usb-Klipper_... 为 Klipper 固件模式下的 ID）：

/dev/serial/by-id/usb-Klipper_stm32h723xx_12345-if00
区分固件 ID 与烧录 ID
  • Klipper 固件 ID 示例：usb-Klipper_stm32h723xx_12345-if00
  • 烧录模式 ID 示例：usb-katapult_stm32h723xx_12345-if00（含 katapult）
  • 烧录模式 ID 示例：usb-STM32_Bootloader_xxxxxxxxxxxx（含 Bootloader）

配置文件中必须使用 Klipper 固件模式的 ID。如果只能看到烧录模式 ID，说明工具板未进入 Klipper 固件运行状态。

CAN 设备​

~/klippy-env/bin/python ~/klipper/scripts/canbus_query.py can0

输出示例：

Found canbus_uuid=688e89f0e402, Application: Klipper
多个 CAN UUID

Application 显示为 CANBOOT 或 Katapult 的 UUID 为烧录模式下的 ID，不能直接用于 printer.cfg。详细排查请参考 CAN 网络与 ID 搜索。

上位机 MCU​

如果使用上位机 Linux 进程模拟 MCU（[mcu host]），其串口固定为：

[mcu host]
serial: /tmp/klipper_host_mcu

RS232 设备​

ls -l /dev/serial/by-path/

输出示例：

/dev/serial/by-path/platform-3f980000.usb-usb-0:1.2:1.0-port0

工具板配置：工具板 MCU 添加与跨板配置

MCU ID 配置说明​

Klipper 中的 MCU ID 指的是 [mcu] 或 [mcu xxx] 配置段里用于连接控制板的识别信息。不同通信方式写法不同：

连接方式配置项示例
USB 固件serial:serial: /dev/serial/by-id/usb-Klipper_xxxxxxxxxxxx
CAN 固件canbus_uuid:canbus_uuid: xxxxxxxxxxxx
上位机 MCUserial:serial: /tmp/klipper_host_mcu

填写规则：

  1. 主板默认使用 [mcu]，工具板或扩展板使用 [mcu tool]、[mcu toolboard] 等自定义名称。
  2. USB 固件只填写 serial:，CAN 固件只填写 canbus_uuid:，不要在同一个 [mcu] 中同时保留两项。
  3. 多 MCU 机器中，每个 [mcu xxx] 都必须使用自己的真实 ID，不要复制同一个 USB ID 或 CAN UUID。
  4. [mcu xxx] 的名称会影响引脚前缀，例如 [mcu tool] 的引脚应写成 tool:gpio13；名称大小写要保持一致。
  5. 文档示例里的 xxxxxxxx 不能直接使用，必须替换为实际搜索到的 ID。

常见错误：

  • 把烧录模式 ID（如包含 katapult、canboot 的 ID）当作 Klipper 固件 ID 使用。
  • USB 固件配置了 canbus_uuid:，或 CAN 固件仍保留旧的 serial:。
  • 工具板配置成 [mcu]，覆盖了主板 MCU 配置。
  • 引脚前缀和 MCU 名称不一致，例如配置是 [mcu toolboard]，引脚却写 tool:gpio13。

USB ID 查询：USB 固件可执行 ls /dev/serial/by-id/* 获取 ID。

CAN ID 查询：CAN 网络与 ID 搜索

工具板配置：工具板 MCU 添加与跨板配置

多 MCU 配置示例​

USB 主板 + CAN 工具板​

USB 主板通过 serial: 连接，CAN 工具板通过 canbus_uuid: 连接：

[mcu]
serial: /dev/serial/by-id/usb-Klipper_xxxxxxxxxxxx

[mcu tool]
canbus_uuid: xxxxxxxxxxxx

[temperature_sensor ToolBoard]
sensor_type: temperature_mcu
sensor_mcu: tool

USB 主板 + USB 工具板​

两者都使用 serial: 连接，通过不同的 ID 区分：

[mcu]
serial: /dev/serial/by-id/usb-Klipper_mainboard_xxxxxxxxxxxx

[mcu toolboard]
serial: /dev/serial/by-id/usb-Klipper_toolboard_xxxxxxxxxxxx

CAN 主板 + CAN 工具板​

两者都使用 canbus_uuid:，每个 UUID 必须不同：

[mcu]
canbus_uuid: aabbccddeeff

[mcu toolboard]
canbus_uuid: 112233445566

上位机 MCU + USB 主板​

上位机运行 Linux 进程 MCU，主板通过 USB 连接：

[mcu host]
serial: /tmp/klipper_host_mcu

[mcu]
serial: /dev/serial/by-id/usb-Klipper_xxxxxxxxxxxx

常见误区​

错误做法正确做法
把烧录模式 ID 当 Klipper ID 使用确保设备进入 Klipper 固件后再查询 ID
USB 固件同时填写 serial: 和 canbus_uuid:USB 固件只填 serial:，CAN 固件只填 canbus_uuid:
工具板写成 [mcu] 覆盖主板配置工具板使用 [mcu toolboard] 等自定义名称
多个 MCU 共用同一个 ID每个 MCU 必须使用自己的唯一 ID
引脚前缀与 MCU 名称不一致[mcu toolboard] 的引脚写 toolboard:PA0，名称大小写一致
文档中的 xxxxxxxx 直接复制使用必须替换为实际搜索到的真实 ID

排查入口​

问题表现排查入口
USB ID 找不到或 [Errno 2]常见报错总览
CAN UUID 无效或设备不在线CAN 网络与 ID 搜索
多 MCU 掉线、配置无法更新系统、性能与服务报错
工具板添加、跨板引脚配置工具板 MCU 添加与跨板配置
引脚前缀、重复引脚或 MCU 名称错误配置类报错
Loading...