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 MCUs: Please confirm in advance the number of MCUs (e.g., toolboards) you are using, as multiple 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 connection to eliminate interference.
  • Recommended Interface: It is recommended to use the Fluidd interface, as it can display 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, 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 upper right corner. Klipper will save the configuration and restart the service.
  • If an error appears, please ignore it for now.
  • Subsequently, completely power off all devices (including the host and all MCUs).
  • Important: A complete power-off is mandatory; 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. Perform Device Detection

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

  2. Handle Command Exceptions

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

  3. Identify Device Information Identify your device in the lsusb output based on the images below:

    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 device IDs similar to the example below:

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

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

    Loading...

CAN ID Search Results​

After executing the command, 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 Firmware Flash: 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 blocked in the configuration, then shut down, 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 Requirements

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 ID​

Preparations

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

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

Configure according to your connection method by referring to the corresponding method below:

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

Configuration Example:

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

# Modify 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 completing the main MCU configuration, verify if the connection is successful:

  1. Open the Fluidd interface, click System in the left menu.
  2. View MCU Information: Find the Micro-Controller information under Mcu Information.
  3. Verify Main Controller Model: Confirm 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: Add the corresponding ID in the newly added configuration section based on the toolboard's firmware type.
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 differs 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 in 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, re-verify the connection status of all MCUs:

  1. Open the Fluidd interface, click System in the left menu.
  2. View MCU Information: Under Mcu Information, confirm all MCUs are correctly recognized.
  3. Check Each MCU 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 completing all MCU connections, verify firmware version compatibility:

  1. Open the Fluidd interface, 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 Notes
  • 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 anomalies, 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, 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 with 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 main MCU USB ID you searched for.

    CAN Connection Configuration:

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

  4. Update Toolboard Configuration (if applicable)

    • Find the [mcu] section corresponding to the toolboard in the configuration file.
    • Update it with the actual toolboard ID you searched for, 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 to confirm all MCU connection statuses are normal.
Important Reminders
  • Ensure you use the correct IDs actually searched for 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...