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. They often use customized or modified systems, which may prevent the MCU from being recognized correctly.
  • Confirm the number of secondary MCUs: Please confirm the number of secondary MCUs (e.g., tool boards) you are using in advance, as multiple secondary MCUs may affect the connection.
  • Simplify wiring: It is recommended to temporarily remove all wiring except for the data cable from the mainboard and tool board, keeping only the necessary data connection to eliminate interference.
  • Recommended interface: It is recommended to use the Fluidd interface, as it displays the 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 your 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 on 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.
  • Afterwards, completely power off all devices (including the host and all secondary MCUs).
  • Important: Ensure a complete power off; otherwise, subsequent steps cannot be performed.

Step 2: Detect Device and Confirm Firmware Type​

Prerequisites​

  • Main device order: The first MCU must be the mainboard, not a tool board.
  • Firmware type: Confirm that your FLY mainboard firmware is USB firmware or USB to CAN bridge firmware. This guide is not applicable to other types.
  • Connection method: Please connect via SSH first. This operation must 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 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 device.

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

    Loading...
    Loading...

  4. Verify Firmware Type

    • Based on the firmware you have flashed, check the following key information in the lsusb results:
      • USB firmware: Should display 1d50:614e
      • USB to CAN bridge 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 when used with G2T)

Step 3: Search for Device ID​

Important Notes​

  • USB ID search: Applicable only to USB firmware, cannot be used for CAN or RS232.
  • CAN ID search: Applicable only to CAN bus devices, cannot be used for USB or RS232.
  • RS232 ID search: Applicable only to RS232 firmware, cannot be used for USB or CAN.
  • RS232 Specificity: RS232 firmware is typically only used for tool boards, not main MCUs.

Choose Method 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 Based on your system type, choose the corresponding command 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/*

Results Interpretation and Handling​

USB ID Search Results​

After executing the command, the terminal will display a device ID similar to the one below (this is just an example):

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

  • ⚠️ Firmware flash required: If the ID is labeled katapult after the usb- field

    Loading...

CAN ID Search Results​

After executing the command, determine the situation based on the actual output:

  • ✅ Ready to use: If the displayed ID is labeled Klipper in the Application: field at the end.
  • ⚠️ Firmware flash required: If the displayed ID is labeled 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 bitrate mismatch (please ensure the host, mainboard, and tool board bitrates are consistent)
    • The ID is already occupied (needs to be masked 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 Specific Requirements

When configuring an RS232 device, you must specify the baud rate and restart method:

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

Step 4: Configure Main MCU ID​

Preparation

Before starting the configuration, ensure that the connection between the tool board 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 found USB ID.

Configuration Example:

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

# Change 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 completing the main MCU configuration, you need to verify the connection is successful:

  1. Open the Fluidd interface, click System in the left menu
  2. Check MCU information: Find the Micro-Controller information under Mcu Information
  3. Verify main controller model: Ensure 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 a model related to H723
  • If the display is incorrect or unrecognizable, please 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 the configuration file: Add the tool board configuration at the very bottom of the printer.cfg file
  3. Configure the tool board ID: Add the corresponding ID in the new configuration section based on the tool board's firmware type
MCU Naming Note

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

Configuration Format:

[mcu mcu1]
# Add the tool board's 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 any other devices.
  • MCU names are fully customizable (e.g., toolboard, extruder_mcu, etc.). Just maintain uniqueness in the configuration.
  • Please ensure you use a tool board ID verified as valid through the previous steps.
  • RS232 devices must include the baud: 250000 and restart_method: command parameters.
  • When configuring multiple tool boards, set a different name for each device to distinguish them.

Configuring Pins Across Multiple Tool Boards​

When using multiple tool boards, you may encounter scenarios where pins need to be assigned across boards. For example, using the heater port on the first tool board for heating, but the temperature sensor is connected to the mainboard or the 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 <mcu_name>:<pin_number> format. No additional configuration is needed. Klipper will automatically route commands to the corresponding MCU via the communication bus (CAN/USB/Serial).

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

Assume the system is configured as follows:

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

Step 1: Define All MCUs

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

[mcu toolboard1]
canbus_uuid: e51d5c71a901

Step 2: Reference Pins Across Boards Directly in the Configuration

[extruder]
# Stepper and heater use tool board pins
step_pin: toolboard1:gpio9
dir_pin: toolboard1:gpio10
enable_pin: !toolboard1:gpio7
heater_pin: toolboard1:gpio6          # Heater cartridge on toolboard1
# Temperature sensor uses mainboard pin (write gpio or mcu:gpio directly)
sensor_type: ATC Semitec 104GT-2
sensor_pin: PA0                        # Temperature sensor connected to 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:gpio6
  • Main MCU pins: Can be written directly as the pin name (e.g., PA0)
  • Pins within the same configuration section can originate from different MCUs. Klipper will handle the 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:gpio9
heater_pin: toolboard1:gpio6      # Heater on first tool board
sensor_type: ATC Semitec 104GT-2
sensor_pin: toolboard2:gpio26     # Temperature sensor on second tool board
# ... rest of 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 related devices (e.g., heater cartridge and temperature sensor) to 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, click System in the left menu
  2. Check MCU information: Confirm that all MCUs are correctly recognized under Mcu Information
  3. Verify each MCU status: Ensure both the main MCU and tool board(s) show a connected status
Verification Points
  • The main MCU and all tool boards should appear in the list
  • The connection status of 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, click System in the left menu
  2. Check version information: Find the Version field under Mcu Information
  3. Verify version consistency: Ensure 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 be the same version as the host Klipper version.
  • Fly-FAST System: The firmware version on the FAST system matches 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 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 configurations:

  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 the main MCU configuration

    • Open the restored printer.cfg file
    • Find the original [mcu] configuration section and update it with 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 found main MCU USB ID

    CAN Connection Configuration:

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

  4. Update tool board configuration(s) (if applicable)

    • Find the [mcu] section(s) corresponding to the tool board(s) in the configuration file
    • Update with the actual found tool board ID(s) 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 to confirm all MCU connection statuses are normal
Important Reminder
  • Ensure you use the actual correct IDs found 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 concludes the MCU connection troubleshooting and configuration restoration process.

Loading...