MCU Connection Guide

Applicability Note

This guide is used to troubleshoot issues where the main MCU cannot connect properly to Klipper. If the device connects normally and you only need to replace or fill in the MCU ID, please refer directly to MCU ID Configuration without clearing the existing configuration.

Troubleshooting Workflow

1. Back up the current printer.cfg.
2. Enable the minimal test configuration only when Klipper cannot be accessed.
3. Confirm the firmware type currently running on the mainboard.
4. Query the real MCU ID and write it into a temporary configuration to verify the connection.
5. Restore the full configuration, updating only the MCU connection entries within it.

Verify One Device at a Time

When connecting multiple USB/CAN secondary boards, it is easy to mistakenly fill the toolboard ID into the mainboard [mcu] section. During troubleshooting, it is recommended to verify only the mainboard at a time, and then add toolboards one by one after confirming success.

Step 1: Back Up Current Configuration

1. Access the Configuration File Manager

Enter the host machine's IP address in your browser. Fluidd users click the ... on the left, Mainsail users click Machine, and then locate printer.cfg.

Loading...

Loading...

Loading...

2. Create a Backup

Right-click on printer.cfg, select Duplicate, and rename the copy to:

printer_Backup.cfg

Fluidd operation example:

Loading...

Mainsail operation example:

Loading...

Do Not Skip the Backup

The subsequent minimal configuration is only for connection testing and cannot replace the official printer configuration. Only proceed after confirming that printer_Backup.cfg exists and its contents are complete.

Check for Wildcard Includes

If the official configuration uses [include *.cfg], the printer_Backup.cfg in the same directory may also be loaded. Move the backup to a subdirectory that will not be matched by this rule, or save it with a .txt extension instead, to avoid duplicate configuration sections.

Step 2: Enable Minimal Test Configuration as Needed

When This Can Be Skipped

If Klipper is currently able to start and connect normally, and you only need to change the MCU ID, keep the full configuration and proceed directly to Step 3.

When Klipper fails to start due to an incorrect configuration or multiple secondary boards, you can temporarily replace the contents of printer.cfg with the following minimal configuration:

[mcu]
serial: /tmp/klipper_host_mcu

[printer]
kinematics: none
max_velocity: 200
max_accel: 1000

Click SAVE & RESTART to save. The /tmp/klipper_host_mcu here is the temporary connection address for the host machine's Host MCU, used only to allow the minimal configuration to start. It is not the mainboard's real USB ID.

Power Off Operation

Before starting, completely shut down the printer and disconnect the power supply. Do not plug or unplug wiring, organize connector cabling, or touch terminals while the system is powered on.

After powering off, disconnect the data cables of toolboards that are not participating in the test for now, keeping only the necessary data connections between the host machine and the mainboard. Do not disassemble the power supply, modify mains wiring, or touch exposed terminals. Reapply power only after confirming the connections.

Step 3: Confirm Firmware and Communication Method

First, access the host machine following the SSH Connection Tutorial, then execute:

lsusb

Determine the device's current mode based on the output:

VID:PID	Device Status	Next Step
1d50:614e	Klipper USB firmware	Query USB ID
1d50:606f	USB to CAN bridge firmware	Query CAN UUID
1d50:6177	Katapult flashing mode	Flash or start Klipper firmware first
1a86:7523	USB serial adapter	Query RS232 path

Loading...

Loading...

If prompted with lsusb: command not found, install usbutils:

sudo apt-get update
sudo apt-get install usbutils

lsusb Shows No Target Device

First confirm that the mainboard is properly powered, the data cable supports communication, and the firmware mode is correct. Do not guess the ID based solely on the device name, and do not write the ID for Katapult/Bootloader mode into printer.cfg.

Step 4: Query and Fill In the MCU ID

USB Mainboard

ls /dev/serial/by-id/*

The output should contain usb-Klipper_.... Devices containing katapult or Bootloader are still in flashing mode and cannot be used as the Klipper runtime ID.

CAN Mainboard

• Standard Linux Host
• FlyOS-FAST / FLY Host

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

python3 ~/klipper/scripts/canbus_query.py can0

Only the UUID corresponding to Application: Klipper can be written into the configuration. If Total 0 uuids found is displayed, go to CAN Network and ID Search for further troubleshooting.

RS232 Device

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

The following rule shares the same content as the FAQ:

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

Full query instructions and multi-MCU examples: MCU ID Configuration

Step 5: Verify the Main MCU

Update the connection address in [mcu] to the real ID just queried. If the minimal configuration was enabled in Step 2, replace the /tmp/klipper_host_mcu within it; if the official configuration was kept, only modify the existing serial: or canbus_uuid: in [mcu], and do not change any other parameters.

• USB Mainboard
• CAN Mainboard

[mcu]
serial: /dev/serial/by-id/usb-Klipper_stm32h723xx_12345-if00

[mcu]
canbus_uuid: 688e89f0e401

Click SAVE & RESTART. After a successful connection:

1. Open the System page in Fluidd.
2. Locate the main MCU in Mcu Information.
3. Verify that the Micro-Controller matches the actual main controller model of the mainboard.

Verification Points

• [mcu] should correspond to the mainboard and should not display as a toolboard model.
• All MCU firmware versions should be compatible with the current Klipper system.
• If the connection still fails, refer to Connection Issue Troubleshooting based on the original error message.

Loading...

Step 6: Restore the Full Printer Configuration

The Official Configuration Must Be Restored

If the minimal configuration was enabled in Step 2, you must restore the official configuration after completing the connection verification. Do not keep a test configuration containing only [mcu] and kinematics: none in use long-term.

Using the Minimal Configuration

After confirming the main MCU is connected:

1. Rename the current temporary printer.cfg to printer_MCU_Test.txt to keep it for review and prevent it from being loaded by the *.cfg wildcard.
2. Copy the previous printer_Backup.cfg and name the copy printer.cfg.
3. Open the restored printer.cfg and locate the original [mcu] configuration section.
4. Update only the serial: or canbus_uuid: values. Do not overwrite stepper motors, heaters, endstops, or other printer parameters.
5. Click SAVE & RESTART, then check Mcu Information again to confirm the connection.

If the backup does not exist or is incomplete, first restore the full configuration from the configuration history. Do not continue overwriting the current file.

Skipping the Minimal Configuration

The current printer.cfg is already the official configuration, so there is no need to rename or restore files. Confirm the MCU connection is successful and keep the backup created in the first step.

Step 7: Adding the Toolboard

After the main MCU is verified successfully, connect and add toolboards one by one:

Toolboard and Multi-MCU Configuration: Toolboard MCU Addition and Cross-Board Configuration