Skip to main content

MCU Connection Guide

Applicability Note

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

Preparation and Notes​

  • Non-recommended host devices: Avoid using devices such as Redmi phones, WiFi dongles, or TV boxes. These devices often use customized or modified systems, which may prevent proper MCU identification.
  • Confirm the number of secondary MCUs: Confirm in advance the number of secondary MCUs (e.g., toolhead boards) you are using; 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 connection to eliminate interference.
  • Recommended interface: It is recommended to use the Fluidd interface, as it displays MCU connection status more intuitively.

Step 1: Backup and Reset Configuration​

1. Access the Host Interface​

Enter the host's IP address in the browser (e.g., 192.168.101.179) to access it.

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 occurs, please ignore it for now.
  • Then, completely power off all devices (including the host and all secondary MCUs).
  • Important: Ensure a complete power-off is performed; otherwise, the subsequent steps cannot proceed.

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-to-CAN bridge firmware. This guide does not apply to other types.
  • Connection method: First connect via SSH, this operation requires a network connection.

Steps​

  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 Errors

    • 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 diagram below:

    Loading...
    Loading...

  4. Verify Firmware Type

    • Based on the firmware you flashed, verify the following key information in the lsusb result:
      • USB firmware: Should show 1d50:614e
      • USB-to-CAN bridge firmware: Should show 1d50:606f
      • USB Katapult firmware: Should show 1d50:6177
      • RS232 Adapter (used with UTOR or with D8 and D8PRO mainboards): Should show 1a86:7523 (This step is unnecessary if using G2T)

Step 3: Search for Device ID​

Important Notes​

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

Method Selection Based on Firmware Type​

USB Firmware Device Execute the following command to search for the USB device ID:

ls /dev/serial/by-id/*

USB-to-CAN Bridge Device Select the appropriate command based on your system type to search for the CAN ID:

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

RS232 Firmware Device Execute the following command to search for the RS232 device path:

ls /dev/serial/by-path/*

Result Interpretation and Handling​

USB ID Search Result​

After executing the command, the terminal will display a device ID similar to the following (example):

  • ✅ Ready to use: If the ID is marked as Klipper after the usb- field

  • ⚠️ Firmware needs flashing: If the ID is marked as katapult after the usb- field

    Loading...

CAN ID Search Result​

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

  • ✅ Ready to use: If the displayed ID is marked as Klipper in the Application: field at the end.
  • ⚠️ Firmware needs flashing: If the displayed ID is marked 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 speed mismatch (ensure the host, mainboard, and toolboard have the same speed)
    • The ID is already occupied (needs to be filtered in the configuration, then shut down, power off, and restart)
Loading...

RS232 ID Search Result​

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 Specific Requirements

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

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

Step 4: Configure the Main MCU ID​

Preparation

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

Reopen the printer.cfg file and find 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:

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

# Modified configuration:
[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 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. Check the main control model: Confirm that the displayed model matches the actual main control model of your mainboard
Verification Points
  • If your main control chip is STM32H723, then Micro-Controller must display an H723-related model
  • If the display is incorrect or unrecognizable, please check the previous configuration steps
Loading...

Step 6: Add Toolboard MCU​

After the main MCU is verified successfully, you can add the toolboard:

  1. Reconnect the toolboard: Reconnect the toolboard's data cable to the host or mainboard
  2. Edit the configuration file: Add the toolboard configuration at the 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 for temporary differentiation. You can fully customize these names, just ensure they are unique in the configuration file.

Configuration Format:

[mcu mcu1]
# Add toolboard ID configuration here

Configuration Examples:

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

Notes:

  • Each MCU must use a unique ID. Ensure the toolboard ID is different from the main MCU and other devices.
  • MCU names are fully customizable (e.g., toolboard, extruder_mcu), just ensure uniqueness in the configuration.
  • Be sure to use a valid toolboard ID verified through the previous steps.
  • RS232 devices must include the baud: 250000 and restart_method: command parameters.
  • When configuring multiple toolboards, set a different name for each device for easy differentiation.

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: Confirm all MCUs are correctly recognized under Mcu Information
  3. Check each MCU status: Ensure the main MCU and toolboards show as connected
Verification Points
  • The main MCU and all toolboards should appear in the list
  • The connection status of each MCU should be "Connected"
  • If a specific MCU is not displayed or connection fails, check its configuration and physical connection
Loading...

Step 8: Check Firmware Version​

After all MCU connections are established, 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. Check version consistency: Ensure the firmware versions of all MCUs match the Klipper version on the host
Version Compatibility Note
  • Custom compiled firmware: Except for pre-configured custom devices, all self-compiled firmware must match the Klipper version on the host.
  • Fly-FAST System: The firmware version for the FAST system is consistent with the system version. The compiled Klipper firmware matches the system version.
  • Consequences of version mismatch: Different firmware versions can lead to 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 reflashed.

Step 9: Restore and Update Configuration File​

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

  1. Delete the current configuration file

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

  2. Restore the 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 ID obtained from 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)

    • Find the [mcu] section corresponding to the toolboard in the configuration file.
    • 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 completing all MCU configuration updates, click SAVE & RESTART to save and restart Klipper.
    • Re-enter the System page to confirm all MCU connection statuses are normal.
Important Reminder
  • Ensure you use the correct ID actually searched during this connection test.
  • If configuring multiple toolboards, update the ID for 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 and endstop settings) will remain unchanged.

The MCU connection troubleshooting and configuration restoration are now complete.

Loading...