Skip to main content

Toolboard MCU Addition and Cross-Board Configuration

This page covers adding a toolboard, verifying multi-MCU status, and configuring cross-board pins after the main MCU has been successfully connected. If you have not yet completed the main MCU connection verification, please first follow the MCU Connection Guide.

Prerequisites​

Before starting to add a toolboard, ensure:

  • The main MCU has been connected and verified according to the MCU Connection Guide.
  • The toolboard firmware has been flashed.
  • The toolboard's data cable is connected to the corresponding interface (CAN/USB/RS232) on the host computer or mainboard.

Querying the Toolboard ID​

The method to query the toolboard ID depends on its communication interface. For complete rules on filling in the MCU ID, please refer to MCU ID Configuration. The following is a quick operation guide:

USB Toolboard​

SSH into the host computer and run the following command to list all USB serial devices:

ls /dev/serial/by-id/*

Example output:

/dev/serial/by-id/usb-Klipper_stm32f446xx_54321-if00
Distinguishing Klipper Firmware from Flash Mode

IDs in flash mode usually contain katapult or stm32duino (e.g., usb-katapult_stm32f446xx_...). Ensure you use the ID from Klipper firmware mode, not the flash mode ID.

CAN Toolboard​

SSH into the host computer and run the following command to search for CAN device UUIDs:

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

Example output:

Found canbus_uuid=688e89f0e402, Application: Klipper
CAN UUID vs. CANBoot UUID

The Klipper firmware UUID for a CAN toolboard is different from the CANBoot flash UUID. If the Application displays as CANBOOT or Katapult, the device is in flash mode. For detailed troubleshooting, refer to CAN Network and ID Search.

RS232 Toolboard​

SSH into the host computer and run the following command to view the USB-to-serial device path:

ls -l /dev/serial/by-path/

Example output:

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

Toolboards communicating via RS232 must have the baud: 250000 and restart_method: command parameters configured; otherwise, communication will fail.

Adding a Toolboard MCU​

After obtaining the toolboard ID, add the corresponding MCU configuration section at the end of printer.cfg:

[mcu toolboard]
serial: /dev/serial/by-id/usb-Klipper_stm32f446xx_54321-if00
Naming Rules
  • MCU names are fully customizable, e.g., toolboard, tool, extruder_mcu, etc.; they just need to be unique within the configuration.
  • The MCU name will be used as the prefix for cross-board pins. For example, with [mcu toolboard], references use toolboard:PA0. Consistent capitalization is required.
  • Each MCU's name and ID must be unique and cannot duplicate the main MCU or other toolboards.
  • When configuring multiple toolboards, assign a different name to each device for clarity.

After configuration, click SAVE & RESTART to save and restart Klipper.

Verifying All MCU Connections​

After adding the toolboard and restarting Klipper, confirm that all MCUs are online:

  1. Open the Fluidd interface and click System in the left menu.
  2. Under Mcu Information, verify that the main MCU and all toolboards are correctly recognized and show a connected status.
Loading...

Checking Firmware Versions​

After connecting all MCUs, verify firmware version compatibility:

  1. Open the Fluidd interface and click System in the left menu.
  2. Under Mcu Information, find the Version field.
  3. Ensure the firmware version of all MCUs matches the Klipper version on the host computer.
Version Compatibility Notes
  • Except for pre-configured custom devices, all self-compiled firmware must be consistent with the Klipper version on the host computer.
  • The firmware version for FAST systems matches the system version; compiled Klipper firmware will be consistent with the system version.
  • Mismatched firmware versions can cause functional anomalies, communication failures, or system instability.

Updating the Main Configuration File​

Applicable Scenario

If you backed up printer_Backup.cfg as instructed in the MCU Connection Guide, this section is for writing the verified MCU IDs back into the full configuration. If you are already using a finalized configuration file, you can skip this section.

After confirming all MCU connections are normal:

  1. In the configuration file manager, delete the current temporary printer.cfg.
  2. Rename the previously backed up printer_Backup.cfg to printer.cfg.
  3. Open the restored printer.cfg, locate the original [mcu] and [mcu <name>] sections, and update them with the verified real IDs.
  4. Click SAVE & RESTART to save and restart Klipper.
Important Reminders
  • Ensure you use the correct IDs actually found during this connection test.
  • 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.

Multi-Toolboard Cross-Board Pin Configuration​

When using multiple toolboards, you may encounter the need to assign pins across boards. For example, using the heating port on the first toolboard but connecting the temperature sensor to the mainboard or a second toolboard.

Core Principle

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

Typical Scenario: Heater on Toolboard, Temperature Sensor on Mainboard​

Assume the system is configured as follows:

  • Main MCU: Runs the host Klipper firmware, temperature sensor connected to the mainboard.
  • toolboard1: Toolboard, heater cartridge and extruder stepper connected to the toolboard.

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 toolboard pins
step_pin: toolboard1:<step_pin>
dir_pin: toolboard1:<dir_pin>
enable_pin: !toolboard1:<enable_pin>
heater_pin: toolboard1:<heater_pin>

# Temperature sensor uses mainboard pin
sensor_type: ATC Semitec 104GT-2
sensor_pin: <sensor_pin>

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
  • Toolboard pin format is <mcu_name>:<pin_number>, e.g., toolboard1:<heater_pin>.
  • Main MCU pins can be written using the actual pin name directly, without a prefix.
  • Pins within the same configuration section can originate from different MCUs; Klipper handles the cross-board communication automatically.

Further Cross-Board Configuration Examples​

Heater on first toolboard, temperature sensor on second toolboard:

[extruder]
step_pin: toolboard1:<step_pin>
heater_pin: toolboard1:<heater_pin>
sensor_type: ATC Semitec 104GT-2
sensor_pin: toolboard2:<sensor_pin>
Important Notes
  • When referencing pins across boards, ensure the corresponding MCU is properly defined in the configuration file via [mcu <name>].
  • MCU name capitalization must be consistent; [mcu ToolBoard] and referencing toolboard:PA0 will cause an error.
  • It is recommended to connect functionally related devices (e.g., heater cartridge and temperature sensor) to the same toolboard for optimal response speed and reliability.

Frequently Asked Questions​

IssueTroubleshooting Direction
Toolboard offlineCheck the data cable connection, verify the ID is correct, differentiate between Klipper firmware ID and flash mode ID
Multi-toolboard name/ID conflictEach [mcu] name and ID must be unique; refer to MCU ID Configuration
Pin prefix mismatchThe pin prefix for [mcu toolboard] should be toolboard:, ensure case consistency
Firmware version incompatibilityRecompile the firmware to match the Klipper version on the host computer
CAN UUID not foundRefer to CAN Network and ID Search
RS232 communication failureCheck that baud: 250000 and restart_method: command are configured
Loading...