MCU ID Configuration

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

Need to troubleshoot thoroughly starting from a backup or minimal configuration: Main MCU Connection Guide

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

Distinguish between firmware ID and flashing ID

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

The configuration file must use the ID from Klipper firmware mode. If only the flashing mode ID is visible, it means the toolboard 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 hosts can directly use python3 to perform the search:

python3 ~/klipper/scripts/canbus_query.py can0

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

Multiple CAN UUIDs

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

Host MCU

If you are using a Linux host process to emulate 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

In Klipper, the MCU ID refers to the identification information used to connect to the control board within the [mcu] or [mcu xxx] configuration sections. Different communication methods require different syntax:

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

Filling Rules:

1. The mainboard uses [mcu] by default, while tool boards or expansion boards use custom names such as [mcu tool] or [mcu toolboard].
2. For USB firmware, only fill in serial:; for CAN firmware, only fill in canbus_uuid:; do not include both items in the same [mcu] section.
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, pins for [mcu tool] should be written as tool:gpio13; the case of the name must remain consistent.
5. The xxxxxxxx in the documentation examples cannot be used directly and must be replaced with the actual ID found.
6. For RS232 devices, in addition to serial:, baud: 250000 and restart_method: command are usually also required; refer to the corresponding product documentation.

Common Mistakes:

• Using a flashing mode ID (such as an ID containing katapult or canboot) as the Klipper firmware ID.
• Configuring canbus_uuid: for USB firmware, or retaining the old serial: for CAN firmware.
• For RS232 devices, only filling in the path and omitting the required baud: or restart_method:.
• Configuring the tool board as [mcu], thereby overriding the mainboard MCU configuration.
• The pin prefix does not match the MCU name, for example, the configuration is [mcu toolboard] but the pin is written as tool:gpio13.

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

CAN ID Query: CAN Network and ID Search

RS232 Path Query: Execute ls -l /dev/serial/by-path/ to obtain a stable device path.

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

Multi-MCU Configuration Examples

USB Mainboard + CAN Toolboard

The USB mainboard is connected via serial:, and the CAN toolboard is connected 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 use serial: connection, 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 use canbus_uuid:, each UUID must be different:

[mcu]
canbus_uuid: aabbccddeeff

[mcu toolboard]
canbus_uuid: 112233445566

Host MCU + USB Mainboard

The host runs the Linux process MCU, and the mainboard is connected 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 the flashing mode ID as the Klipper ID	Ensure the device enters Klipper firmware mode before querying the ID
Filling in both serial: and canbus_uuid: for USB firmware	USB firmware only fills in serial:, CAN firmware only fills in canbus_uuid:
Writing the toolboard as [mcu] and overriding the mainboard configuration	Use custom names like [mcu toolboard] for toolboards
Multiple MCUs sharing the same ID	Each MCU must use its own unique ID
Pin prefix inconsistent with MCU name	Pins for [mcu toolboard] are written as toolboard:PA0, with consistent capitalization
Directly copying xxxxxxxx from documentation	Must be replaced with the actual ID found by searching

Troubleshooting Entry Points

Issue Symptom	Troubleshooting Entry Point
USB ID not found or [Errno 2]	Common Error Overview
CAN UUID invalid or device offline	CAN Network and ID Search
Multi-MCU disconnections, configuration update failures	System, Performance, and Service Errors
Toolboard addition, cross-board pin configuration	Toolboard MCU Addition and Cross-Board Configuration
Pin prefix, duplicate pins, or MCU name errors	Configuration Errors