MCU ID Configuration

This page is used to centralizedly explain the ID filling rules for mainboards, toolboards, CAN devices, and host MCUs in Klipper. When configuring connection-related issues, first confirm the communication method, then fill in the corresponding serial: or canbus_uuid:.

Querying MCU ID

Before filling in the ID, you need to log in to the host via SSH and execute the corresponding command to obtain the actual device identifier.

USB Devices

ls /dev/serial/by-id/*

Example output (usb-Klipper_... is the ID in Klipper firmware mode):

/dev/serial/by-id/usb-Klipper_stm32h723xx_12345-if00

Distinguishing Firmware ID from Flash ID

• Klipper firmware ID example: usb-Klipper_stm32h723xx_12345-if00
• Flash mode ID example: usb-katapult_stm32h723xx_12345-if00 (contains katapult)
• Flash mode ID example: usb-STM32_Bootloader_xxxxxxxxxxxx (contains Bootloader)

The configuration file MUST use the Klipper firmware mode ID. If only the flash mode ID can be seen, it indicates the tool board has not entered the Klipper firmware running state.

CAN Devices

• SSH Command Line
• FlyOS-FAST / FLY Host

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

Example output:

Found canbus_uuid=688e89f0e402, Application: Klipper

FAST or FLY host directly uses python3 to execute the search:

python3 ~/klipper/scripts/canbus_query.py can0

The CAN0 interface on the FAST system is preset to 1M baud rate and 1024 buffer, generally requiring no manual configuration.

Multiple CAN UUIDs

UUIDs whose Application shows CANBOOT or Katapult are IDs in flash mode and cannot be used directly in printer.cfg. For detailed troubleshooting, please refer to CAN Network and ID Search.

Host MCU

If using a host Linux process to simulate an MCU ([mcu host]), its serial port is fixed as:

[mcu host]
serial: /tmp/klipper_host_mcu

RS232 Devices

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

Example output:

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

Toolboard Configuration: Toolboard MCU Addition and Cross-Board Configuration

MCU ID Configuration Description

The MCU ID in Klipper refers to the identification information used in the [mcu] or [mcu xxx] configuration section for connecting to the control board. Different communication methods have different formats:

Connection Method	Configuration Item	Example
USB Firmware	serial:	serial: /dev/serial/by-id/usb-Klipper_xxxxxxxxxxxx
CAN Firmware	canbus_uuid:	canbus_uuid: xxxxxxxxxxxx
Host MCU	serial:	serial: /tmp/klipper_host_mcu

Filling Rules:

1. The mainboard defaults to using [mcu], while tool boards or expansion boards use custom names like [mcu tool], [mcu toolboard], etc.
2. USB firmware only fills in serial:, and CAN firmware only fills in canbus_uuid:; do not retain both items in the same [mcu].
3. In multi-MCU machines, each [mcu xxx] must use its own real ID; do not copy the same USB ID or CAN UUID.
4. The name of [mcu xxx] affects the pin prefix; for example, a pin for [mcu tool] should be written as tool:gpio13; keep the name case consistent.
5. The xxxxxxxx in documentation examples cannot be used directly; it must be replaced with the actual searched ID.

Common Errors:

• Using a flashing mode ID (such as an ID containing katapult or canboot) as a Klipper firmware ID.
• Configuring canbus_uuid: in USB firmware, or retaining the old serial: in CAN firmware.
• Configuring a tool board as [mcu], overwriting the mainboard MCU configuration.
• Pin prefix inconsistency with the MCU name, for example, configuring [mcu toolboard] but writing the pin as tool:gpio13.

USB ID Query: For USB firmware, run ls /dev/serial/by-id/* to obtain the ID.

CAN ID Query: CAN Network and ID Search

Tool Board Configuration: Tool Board MCU Addition and Cross-Board Configuration

Multi-MCU Configuration Examples

USB Mainboard + CAN Toolboard

The USB mainboard connects via serial:, and the CAN toolboard connects via 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 Mainboard + USB Toolboard

Both connect via serial:, distinguished by different IDs:

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

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

CAN Mainboard + CAN Toolboard

Both connect via canbus_uuid:, each UUID must be unique:

[mcu]
canbus_uuid: aabbccddeeff

[mcu toolboard]
canbus_uuid: 112233445566

Host MCU + USB Mainboard

The host runs a Linux process MCU, and the mainboard connects via USB:

[mcu host]
serial: /tmp/klipper_host_mcu

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

Common Misconceptions

Incorrect Practice	Correct Practice
Using flash mode ID as Klipper ID	Ensure the device is in Klipper firmware state before querying the ID
Filling both serial: and canbus_uuid: for USB firmware	USB firmware only uses serial:, CAN firmware only uses canbus_uuid:
Naming toolboard [mcu] overwriting mainboard config	Use custom names like [mcu toolboard] for toolboards
Multiple MCUs sharing the same ID	Each MCU must use its own unique ID
Mismatched pin prefix and MCU name	Pins for [mcu toolboard] should be written as toolboard:PA0, with consistent case
Directly copying xxxxxxxx from documentation	Must replace with the actual ID found during the search

Troubleshooting Entry Points

Problem Description	Entry Point
USB ID not found or [Errno 2]	Common Error Overview
Invalid CAN UUID or device offline	CAN Network and ID Search
Multi-MCU disconnection, config update failure	System, Performance, and Service Errors
Toolboard addition, cross-board pin configuration	Toolboard MCU Addition and Cross-Board Configuration
Pin prefix errors, duplicate pins, or MCU name errors	Configuration Errors