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

  • Unrecommended Host Devices: Avoid using devices such as Redmi phones, WiFi sticks, or set-top boxes. These often use customized or modified systems that may prevent correct MCU identification.
  • Confirm Number of Secondary Devices: Verify the number of secondary devices (e.g., tool boards) you are using in advance; multiple secondary devices may affect the connection.
  • Simplify Wiring: It is recommended to temporarily remove all wiring except data cables from the mainboard and tool board, keeping only necessary data connections to eliminate interference.
  • Recommended Interface: It is recommended to use the Fluidd interface, which displays MCU connection status more intuitively.

Step 1: Backup and Reset Configuration​

1. Access the Host Interface​

Enter the IP address of the host device in a browser 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.
  • Ignore any error messages that appear for now.
  • Then, completely power off all devices (including the host and all secondary devices).
  • Important: Ensure a complete power-off is achieved; otherwise, 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 tool board.
  • Firmware Type: Confirm your FLY mainboard firmware is USB firmware or USB to CAN bridge firmware. This guide is not applicable to other types.
  • Connection Method: Please first connect via SSH. This operation requires a network connection.

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 Errors

    • If the lsusb command is not found, install it first: 
      sudo apt-get install usbutils
    • If no devices are displayed after execution, consider replacing the host device.

  3. Identify Device Information Identify your device in the lsusb output according to the diagram below:

    Loading...
    Loading...

  4. Verify Firmware Type

    • Check the following key information in the lsusb result based on the firmware you flashed:
      • 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 on D8 and D8PRO mainboards): Should show 1a86:7523 (not needed with 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 tool boards, not for the main MCU.

Choose Method Based on Firmware Type​

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

ls /dev/serial/by-id/*

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

~/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 Results​

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

  • Directly usable: The field after usb- shows Klipper (e.g., usb-Klipper_stm32f407xx_...), indicating Klipper firmware has been flashed.
  • Firmware required: The field after usb- shows katapult (e.g., usb-katapult_stm32f407xx_...), indicating it is currently in Bootloader mode and Klipper firmware needs to be flashed.
  • Unrecognized: In the example ID below, the field after usb- shows 1a86_USB_Serial, indicating the device is a CH340 serial adapter chip, not an MCU running Klipper/katapult firmware. The corresponding firmware must be flashed first.
/dev/serial/by-id/usb-1a86_USB_Serial-if00-port0
  • Normal situation:
Loading...

CAN ID Search Results​

After executing the command, judge based on the terminal output:

  • Directly usable: The Application: field at the end of the displayed ID is marked as Klipper.
  • Firmware required: The Application: field at the end of the displayed ID is marked as CANBOOT or Katapult.
  • No device found: If Total 0 uuids found is displayed, possible reasons include:
    • Incorrect CAN network configuration
    • CAN bus speed mismatch (ensure host, mainboard, and tool board speeds are consistent)
    • The ID is already in use (need to mask it in the configuration, then power off and restart)
Loading...

RS232 ID Search Results​

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

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

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

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

Step 4: Configure the Main MCU ID​

Preparation

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

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

Refer to the corresponding method below based on your connection type:

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 configuring the main MCU, verify if the connection is successful:

  1. Open the Fluidd interface and click System in the left menu.
  2. Check 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 an STM32H723, Micro-Controller must display an H723-related model.
  • If the display is incorrect or unrecognizable, check the previous configuration steps.
Loading...

Step 6: Add Tool Board MCU​

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

  1. Reconnect the Tool Board: Reconnect the tool board's data cable to the host or mainboard.
  2. Edit Configuration File: Add the tool board configuration at the bottom of the printer.cfg file.
  3. Configure Tool Board ID: Add the corresponding ID in the new configuration section based on the tool board's firmware type.
MCU Naming Note

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

Configuration Format:

[mcu mcu1]
# Add the tool board 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 tool board ID is different from the main MCU and other devices.
  • MCU names are fully customizable (e.g., toolboard, extruder_mcu, etc.), just maintain uniqueness in the configuration.
  • Only use tool board IDs verified as valid through the previous steps.
  • RS232 devices must include the baud: 250000 and restart_method: command parameters.
  • When configuring multiple tool boards, assign different names to each device for easy distinction.

Multi-Tool Board Cross-Board Pin Configuration​

When using multiple tool boards, you may encounter the need for cross-board pin assignment. For example, using the heating port of the first tool board for the heater, but connecting the temperature sensor to the mainboard or a second tool board.

Core Principle

In Klipper's multi-MCU configuration, pins in any configuration section can directly reference pins on any defined MCU using the format <mcu_name>:<pin_number>, without additional configuration. Klipper will automatically send instructions to the corresponding MCU via the communication bus (CAN/USB/Serial).

Typical Scenario: Heater on Tool Board, Temperature Sensor on Mainboard

Assume the system configuration is as follows:

  • Main MCU: Runs the Klipper host firmware on the host, temperature sensor connected to the mainboard.
  • toolboard1: Tool board, heater and extruder stepper connected to the tool board.

Step One: Define All MCUs

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

[mcu toolboard1]
canbus_uuid: e51d5c71a901

Step Two: Reference Pins Across Boards Directly in Configuration

[extruder]
# Stepper and heater use tool board pins
step_pin: toolboard1:<step_pin>
dir_pin: toolboard1:<dir_pin>
enable_pin: !toolboard1:<enable_pin>
heater_pin: toolboard1:<heater_pin>          # Heater on toolboard1
# Temperature sensor uses mainboard pins (write gpio or mcu:gpio directly)
sensor_type: ATC Semitec 104GT-2
sensor_pin: <sensor_pin>                        # Temperature sensor on mainboard
# Other parameters
rotation_distance: 22.44
gear_ratio: 50:17
microsteps: 16
full_steps_per_rotation: 200
nozzle_diameter: 0.400
filament_diameter: 1.75
min_temp: -235
max_temp: 350
max_power: 1.0
min_extrude_temp: 170
control: watermark
Pin Naming Rules
  • Tool Board Pins: Format is <mcu_name>:<pin_number>, e.g., toolboard1:<heater_pin>
  • Main MCU Pins: Can be written directly as the actual pin name.
  • Pins in the same configuration section can come from different MCUs; Klipper handles cross-board communication automatically.

More Cross-Board Configuration Examples

Heater on the first tool board, temperature sensor on the second tool board:

[extruder]
step_pin: toolboard1:<step_pin>
heater_pin: toolboard1:<heater_pin>      # Heater on first tool board
sensor_type: ATC Semitec 104GT-2
sensor_pin: toolboard2:<sensor_pin>     # Temperature sensor on second tool board
# ... other extruder parameters
Notes
  • When referencing pins across boards, ensure the corresponding MCU has been correctly defined in the configuration file using [mcu <name>].
  • It is recommended to connect functionally closely related devices (like heater and temperature sensor) on the same tool board for optimal response speed and reliability.

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

Step 7: Verify All MCU Connections​

After adding the tool board and restarting Klipper, re-verify the connection status of all MCUs:

  1. Open the Fluidd interface and click System in the left menu.
  2. Check MCU Information: Confirm all MCUs are correctly recognized under Mcu Information.
  3. Verify Each MCU Status: Ensure the main MCU and tool boards all show a connected status.
Verification Points
  • The main MCU and all tool boards 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, verify firmware version compatibility:

  1. Open the Fluidd interface and click System in the left menu.
  2. Check Version Information: Find the Version field under Mcu Information.
  3. Verify Version Consistency: Confirm the firmware version of all MCUs matches the host Klipper version.
Version Compatibility Notes
  • Custom Compiled Firmware: Except for pre-configured custom devices, all self-compiled firmware must match the host Klipper version.
  • Fly-FAST System: The firmware version for FAST systems matches the system version; the compiled Klipper firmware corresponds to the system version.
  • Consequences of Version Mismatch: Mismatched firmware versions can cause functional abnormalities, communication failures, or system instability.

Verification Points:

  • The Version information for the main MCU and all tool boards 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 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 based on the ID 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 obtained

    CAN Connection Configuration:

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

  4. Update Tool Board Configuration (if applicable)

    • Find the [mcu] section corresponding to the tool board in the configuration file.
    • Update to the actual tool board ID based on the connection method:

    USB Tool Board:

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

    CAN Tool Board:

    [mcu toolboard]
    canbus_uuid: 688e89f0e402

    RS232 Tool Board:

    [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 and confirm all MCU connection statuses are normal.
Important Reminder
  • Ensure you use the correct IDs obtained during this connection test.
  • If configuring multiple tool boards, update the ID in each [mcu] section one by one.
  • RS232 tool boards must include the baud: 250000 and restart_method: command parameters.
  • After restoring the configuration, the original printer parameters (such as stepper motor, endstop settings, etc.) will remain unchanged.

This completes the MCU connection troubleshooting and configuration restoration.

Loading...