Skip to main content

MCU Connection Guide

Applicability

This guide is used to troubleshoot and resolve issues where an MCU cannot connect properly to Klipper.

Preparations and Precautions​

  • Not Recommended Host Devices: Avoid using devices like Redmi phones, WiFi dongles, set-top boxes, etc. They often use customized or modified systems which may prevent proper MCU recognition.
  • Confirm Number of Secondary MCUs: Please confirm in advance the number of secondary MCUs (e.g., toolboards) you are using, as multiple secondary MCUs may affect the connection.
  • Simplify Wiring: It is recommended to temporarily remove all wiring from the mainboard and toolboard except for the data cable, keeping only the necessary data connections to eliminate interference.
  • Recommended Interface: It is recommended to use the Fluidd interface, as it can display the MCU connection status more intuitively.

Step 1: Backup and Reset Configuration​

1. Access the Host Interface​

Access the host by entering its IP address (e.g., 192.168.101.179) in your browser.

Loading...

2. Locate the Configuration File​

Enter the WEB interface and find the configuration option in the left sidebar:

Fluidd Users: Click ..., then find printer.cfg.

Loading...

Mainsail Users: Click Machine, then find printer.cfg.

Loading...

3. Backup the Configuration File​

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

printer_Backup.cfg

Fluidd Operation Example:

Loading...

Mainsail Operation Example:

Loading...

4. Reset the Configuration File​

Reopen printer.cfg, clear all content, and paste the following basic configuration:

[mcu]
serial: /tmp/klipper_host_mcu

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

5. Save and Restart​

  • Click SAVE & RESTART in the top right corner. Klipper will save the configuration and restart the service.
  • If an error appears, please ignore it for now.
  • Subsequently, please completely power off all devices (including the host and all secondary MCUs).
  • Important: A complete power cycle is essential; otherwise, subsequent steps cannot be performed.

Step 2: Detect Devices and Confirm Firmware Type​

Prerequisites​

  • Primary Device Order: The first MCU must be the mainboard, not a toolboard.
  • Firmware Type: Confirm that your FLY mainboard firmware is USB firmware or USB Bridge CAN firmware. This guide does not apply to other types.
  • Connection Method: Please first Connect via SSH. This operation needs to be performed over the network.

Procedure​

  1. Execute Device Detection

    • After successfully connecting via SSH, execute the following command: 
      lsusb
    • The system will list all recognized USB devices.

  2. Handle Command Exception

    • If prompted that the lsusb command does not exist, please install it first: 
      sudo apt-get install usbutils
    • If no devices are displayed after execution, consider replacing the host.

  3. Identify Device Information Refer to the images below to identify your device in the output of lsusb:

    Loading...
    Loading...

  4. Verify Firmware Type

    • Based on the firmware you flashed, check for the following key information in the lsusb results:
      • USB Firmware: Should display 1d50:614e
      • USB Bridge CAN Firmware: Should display 1d50:606f
      • USB Katapult Firmware: Should display 1d50:6177
      • RS232 Adapter (used with UTOR or D8/D8PRO mainboards): Should display 1a86:7523 (not required if using G2T)

Step 3: Search for Device ID​

Important Notes​

  • USB ID Search: Only applicable to USB firmware, cannot be used for CAN or RS232.
  • CAN ID Search: Only applicable to CAN bus devices, cannot be used for USB or RS232.
  • RS232 ID Search: Only applicable to RS232 firmware, cannot be used for USB or CAN.
  • RS232 Specificity: RS232 firmware is typically only used for toolboards, not for the main MCU.

Choose Method Based on Firmware Type​

USB Firmware Devices Execute the following command to search for USB device IDs:

ls /dev/serial/by-id/*

USB Bridge CAN Devices Choose the corresponding command to search for CAN IDs based on your system type:

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

RS232 Firmware Devices Execute the following command to search for RS232 device paths:

ls /dev/serial/by-path/*

Result Interpretation and Handling​

USB ID Search Results​

After executing the command, the terminal will display a device ID similar to the example below:

  • ✅ Ready to Use: If the ID is labeled as Klipper after the usb- field.

  • ⚠️ Requires Flashing: If the ID is labeled as katapult after the usb- field.

    Loading...

CAN ID Search Results​

After executing the command, please judge based on the actual situation:

  • ✅ Ready to Use: If the displayed ID is labeled as Klipper in the Application: field at the end.
  • ⚠️ Requires Flashing: If the displayed ID is labeled as CANBOOT or Katapult in the Application: field at the end.
  • ❌ Device Not Found: If Total 0 uuids found is displayed, possible reasons include:
    • Incorrect CAN network configuration
    • CAN rate mismatch (ensure host, mainboard, and toolboard rates are consistent)
    • The ID is already occupied (needs to be masked in the configuration, then shutdown, power off, and restart)
Loading...

RS232 ID Search Results​

After executing the command, the terminal will display the RS232 device path (example):

  • /dev/serial/by-path/platform-3f980000.usb-usb-0:1.2:1.0-port0
RS232 Configuration Special Requirement

RS232 devices must specify baud rate and restart method in the configuration:

[mcu toolboard]
serial: <Replace here with the queried RS232 device path>
baud: 250000
restart_method: command

Step 4: Configure the Main MCU's ID​

Preparation

Before starting configuration, ensure the toolboard's connection to the host or mainboard is disconnected to avoid device identification conflicts.

Reopen the printer.cfg file and locate the serial: /tmp/klipper_host_mcu configuration line in the [mcu] section.

Based on your connection method, refer to the corresponding method below for configuration:

Replace /tmp/klipper_host_mcu after serial: with the searched USB ID.

Configuration Example:

# The searched USB ID is:
# /dev/serial/by-id/usb-Klipper_stm32h723xx_12345-if00

# Modify the configuration to:
[mcu]
serial: /dev/serial/by-id/usb-Klipper_stm32h723xx_12345-if00

Save the configuration and restart the Klipper service.

Step 5: Verify Main MCU Connection​

After configuring the main MCU, you need to verify if the connection is successful:

  1. Open the Fluidd interface and click System in the left menu.
  2. View MCU Information: Find the Micro-Controller information under Mcu Information.
  3. Verify Main Controller Model: Confirm that the displayed model matches the actual main controller model of your mainboard.
Verification Points
  • If your main controller is STM32H723, then Micro-Controller must display an H723-related model.
  • If the display is incorrect or unrecognized, please check the previous configuration steps.
Loading...

Step 6: Add Toolboard MCU​

After successfully verifying the main MCU, you can add the toolboard:

  1. Reconnect the Toolboard: Reconnect the toolboard's data cable to the host or mainboard.
  2. Edit Configuration File: Add the toolboard configuration at the very bottom of the printer.cfg file.
  3. Configure Toolboard ID: Based on the toolboard's firmware type, add the corresponding ID in the newly added configuration section.
MCU Naming Note

Names like mcu1, mcu2 in the configuration are only used to temporarily distinguish different devices. You can completely customize these names, just ensure they remain unique within the configuration file.

Configuration Format:

[mcu mcu1]
# Add the toolboard's ID configuration here

Configuration Examples:

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

Precautions:

  • Each MCU must use a unique ID. Ensure the toolboard ID is different from the main MCU and other devices.
  • MCU names can be completely customized (e.g., toolboard, extruder_mcu, etc.), just maintain uniqueness in the configuration.
  • Be sure to use the toolboard ID verified as effective through the previous steps.
  • RS232 devices must include the baud: 250000 and restart_method: command parameters.
  • When configuring multiple toolboards, set different names for each device for easy distinction.

After completing the configuration, save and restart the Klipper service.

Step 7: Verify All MCU Connections​

After adding the toolboard and restarting Klipper, you need to re-verify the connection status of all MCUs:

  1. Open the Fluidd interface and click System in the left menu.
  2. View MCU Information: Under Mcu Information, confirm that all MCUs are correctly recognized.
  3. Check Each MCU's Status: Ensure both the main MCU and toolboard(s) show as connected.
Verification Points
  • The main MCU and all toolboards should appear in the list.
  • The connection status for each MCU should be "Connected".
  • If an MCU is not displayed or fails to connect, check its configuration and physical connection.
Loading...

Step 8: Check Firmware Version​

After all MCU connections are established, you need to verify firmware version compatibility:

  1. Open the Fluidd interface and click System in the left menu.
  2. View Version Information: Find the Version field under Mcu Information.
  3. Verify Version Consistency: Confirm that the firmware version of all MCUs matches the host's Klipper version.
Version Compatibility Note
  • Custom Compiled Firmware: Except for pre-configured custom devices, all self-compiled firmware must match the host's Klipper version.
  • Fly-FAST System: The FAST system's firmware version is consistent with the system version. The compiled Klipper firmware matches the system version.
  • Consequences of Version Mismatch: Different firmware versions may cause functional abnormalities, communication failures, or system instability.

Verification Points:

  • The Version information for the main MCU and all toolboards should be displayed and consistent.
  • If versions do not match, the corresponding firmware needs to be re-flashed.

Step 9: Restore and Update Configuration File​

After confirming all MCU connections are normal, you need to restore the original configuration file and update the MCU configurations:

  1. Delete Current Configuration File

    • In the configuration file management interface, find and delete the current printer.cfg file.

  2. Restore Backup Configuration

    • Rename the previously backed-up printer_Backup.cfg file to printer.cfg.

  3. Update MCU Configuration

    • Open the restored printer.cfg file.
    • Find the original [mcu] configuration section and update it based on the IDs obtained in the previous steps:

    USB Connection Configuration:

    [mcu]
    serial: /dev/serial/by-id/usb-Klipper_stm32h723xx_12345-if00
    # Replace with the actual searched main MCU USB ID

    CAN Connection Configuration:

    [mcu]
    canbus_uuid: 688e89f0e401
    # Replace with the actual searched main MCU CAN UUID

  4. Update Toolboard Configuration (if applicable)

    • In the configuration file, find the [mcu] section corresponding to the toolboard.
    • Update it with the actual searched toolboard ID based on the connection method:

    USB Toolboard:

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

    CAN Toolboard:

    [mcu toolboard]
    canbus_uuid: 688e89f0e402

    RS232 Toolboard:

    [mcu toolboard]
    serial: /dev/serial/by-path/platform-3f980000.usb-usb-0:1.2:1.0-port0
    baud: 250000
    restart_method: command

  5. Save and Restart

    • After updating all MCU configurations, click SAVE & RESTART to save and restart Klipper.
    • Re-enter the System page and confirm all MCU connection statuses are normal.
Important Reminder
  • Ensure you use the correct IDs actually searched during this connection test.
  • If configuring multiple toolboards, update the ID in each [mcu] section one by one.
  • RS232 toolboards must include the baud: 250000 and restart_method: command parameters.
  • After restoring the configuration, the original printer parameters (such as stepper motor, limit switch settings, etc.) will remain unchanged.

At this point, MCU connection troubleshooting and configuration restoration are complete.

Loading...