External Driver Troubleshooting

This page is used for troubleshooting issues after configuring an external driver, such as motor not rotating, rotating in only one direction, vibration, skipped steps, model tilting, and 5V boost module anomalies.

Wiring & Configuration: External Driver Usage Tutorial

Quick Diagnosis

If the following phenomena occur, they are typically related to module type, signal level, enable_pin, step_pulse_duration, pulse polarity, or wiring order:

• Motor not rotating at all
• Motor only rotates in one direction, reverse command invalid
• Motor vibration, abnormal noise, or incorrect direction
• Print layer shift or misalignment
• Model tilting, especially unstable position after direction change
• Console command errors or abnormal module appearance when using a 5V boost module
• TMC driver configuration section for the corresponding axis still retained in the configuration

Power Off Operation

Before inspecting the external driver, 5V boost module, connectors, wiring order, or replacing cables, completely turn off the printer and disconnect the power supply. Do not plug or unplug the boost module, external driver signal cables, or touch exposed terminals while powered on.

TMC Configuration Residue Check

After using an external driver, only the [stepper_*] configuration needs to be retained for the corresponding axis. Please delete or comment out the entire TMC configuration section for the same axis:

[stepper_x]
step_pin: PA2
dir_pin: PA3
enable_pin: !PA8
microsteps: 16
step_pulse_duration: 0.000005

# The following TMC configuration is no longer used; delete or comment out the entire section
#[tmc2209 stepper_x]
#uart_pin: PA10
#run_current: 0.8

Common configuration sections to check include:

• [tmc2209 stepper_x]
• [tmc5160 stepper_x]
• [tmc2209 stepper_y]
• [tmc5160 stepper_y]
• [tmc2209 extruder]
• [tmc5160 extruder]

If the TMC configuration for the corresponding axis is retained, Klipper will continue to attempt initializing that TMC driver, which may cause communication errors, configuration errors, or prevent the motor from working properly.

Module Type and Signal Level Check

There are two common types of external driver adapter modules. First, confirm which type is actually being used:

Module Type	Output Level	Applicable Scenario
Standard passthrough module	Board originally outputs 3.3V, module still outputs 3.3V; board originally outputs 5V, module still outputs 5V	Suitable when the board's signal level already meets the external driver's input requirements
5V boost module	Board originally outputs 3.3V, boosted to 5V; board originally outputs 5V, still outputs 5V	Suitable when the external driver requires 5V input, but the board's drive signal is 3.3V

If the external driver cannot reliably recognize the 3.3V STEP, DIR, or EN signals, issues such as motor not rotating, rotating in only one direction, uncontrolled direction, or intermittent skipped steps may occur. When using an external driver with D-series and C-series motherboards, if the driver requires 5V input, a 5V boost module should be used; a standard passthrough module will not boost the 3.3V signal to 5V.

Low Voltage Measurement

When measuring low-voltage signals like STEP, DIR, or EN, avoid shorting adjacent pins with probes. If you are not familiar with measurement methods, first confirm via the module model, board documentation, and replacement of the finished module; do not touch exposed terminals.

5V Module Test Instructions

Safety Boundary

This check is only for users using a 5V boost module (D-series, C-series motherboards). Users with standard modules should skip this section.

Ordinary users should not touch the exposed pins of the module or motherboard with probes while powered on. Electrical inspection of exposed pins should be handled by after-sales support or personnel with electrical experience.

After installing the 5V boost module onto the motherboard, do not immediately connect the external driver. First, follow the steps below to confirm the module, configuration, and wiring show no obvious anomalies.

Add Test Configuration

Add the following configuration to the printer.cfg file. Be sure to modify the pins to the corresponding driver port pins:

[output_pin STEP]
pin: PC14

[output_pin DIR]
pin: PC13

[output_pin EN]
pin: PC15

Pin Description

• Replace the example PC14, PC13, PC15 with the actual driver port pins used.
• For example, when using the X-axis driver port, refer to the motherboard schematic to find the corresponding STEP, DIR, and EN pin numbers.

Power Off and Inspect Module and Wiring

1. Confirm the installation orientation of the 5V boost module matches the motherboard silk screen and manual.
2. Confirm the wiring order for EN, PUL, DIR, GND, etc., matches the selected wiring method.
3. Prioritize using the manufacturer-provided finished module and finished wiring harness; do not modify the wiring yourself.
4. Temporarily do not connect the external driver to avoid damaging the driver if the configuration or wiring order is incorrect.

Software Output Check

1. Enter the console interface in Mainsail or Fluidd.
2. Ensure no external driver or other actuating device is connected, then execute the following commands sequentially. Confirm the console reports no errors:

SET_PIN PIN=EN VALUE=1
SET_PIN PIN=EN VALUE=0
SET_PIN PIN=STEP VALUE=1
SET_PIN PIN=STEP VALUE=0
SET_PIN PIN=DIR VALUE=1
SET_PIN PIN=DIR VALUE=0

3. If a command reports an error, first verify that the pin names in printer.cfg match the actual driver port.

Test Result Evaluation

Check Item	Normal Result	Abnormal Result	Recommended Action
Module orientation and wiring order	Matches motherboard silk screen and manual	Inserted backwards, misaligned, or incorrect wiring order	Fully power off, then reinstall or replace with a finished wiring harness
Console commands	SET_PIN commands execute without error	Pin not found or command fails	Verify pin configuration in printer.cfg
Module/Wiring appearance	No heat, odor, damage, or looseness	Heat, odor, damage, looseness	Power off immediately, replace module or wiring harness

After Passing Check

After confirming the appearance, wiring order, and configuration are all normal, fully power off before proceeding with the formal driver wiring.

Enable Pin Determination Method

The active level of the external driver's EN (Enable) pin varies. Confirm before configuration:

Wiring Scenario	enable_pin Syntax	Description
EN- connected to board signal wire; driver is low-level enable	Loading...	Most external drivers are low-level enable; add !
EN- connected to board signal wire; driver is high-level enable	Loading...	Few drivers are high-level enable; do not add !
EN+ already connected to common anode/VCC; enabled upon power on	Delete the entire enable_pin line	Driver is always enabled; no software control needed

enable_pin defaults to high-level enable. The preceding ! indicates low-level enable. Many external drivers have a low-level active EN (Active Low); these typically require the syntax enable_pin: !PA8. If the driver is high-level active (Active High), use enable_pin: PA8.

step_pulse_duration and Direction Timing

Klipper defaults to step_pulse_duration: 0.000002 (2µs) for non-TMC drivers. This parameter simultaneously constrains the step pulse width and the direction switching delay; the direction timing is always referenced to the rising edge of the step pulse.

If the driver requires a minimum interval of 10µs between the step rising edge and the direction change, set:

step_pulse_duration: 0.000010

Value recommendations:

1. Refer to the Minimum Step Pulse Width or Direction Setup Time parameters in the external driver's manual.
2. If both parameters exist, prioritize the larger value and leave some margin.
3. If the manual does not specify, start from 0.000005 and gradually increase for testing.

Common Issue Handling

Layer Shift / Skipped Steps

Possible Cause: step_pulse_duration is too short, causing the external driver to fail to reliably recognize the step pulse.

Troubleshooting:

1. First try
   Loading...
2. If issues persist, increase to
   Loading...
3. If still ineffective, continue increasing to
   Loading...
   or
   Loading...

After each adjustment, save the configuration and restart Klipper (FIRMWARE_RESTART), then test the print quality.

Model Tilting (Direction Change Anomaly)

Possible Cause: The DIR direction signal is not reliably recognized by the external driver, or step_pulse_duration is too short, causing unstable direction change timing.

Troubleshooting:

1. Confirm the module type is correct; refer to Module Type and Signal Level Check above.
2. If the board outputs 3.3V and the driver requires 5V input, replace it with a 5V boost module.
3. Power off and check if the DIR wiring order is connected to the correct DIR terminal on the driver.
4. Verify the dir_pin matches the actual direction pin of the driver port being used.
5. Appropriately increase step_pulse_duration, then save the configuration and restart Klipper for testing.

One-Way Only / Uncontrolled Direction

Possible Cause: The DIR signal is not stably recognized by the external driver. This is commonly caused by mismatched module types, 3.3V signals not being stepped up, incorrect DIR wiring, or incorrect dir_pin configuration.

Troubleshooting Sequence:

1. Confirm the module type is correct. Refer to the Module Type and Signal Level Check above.
2. If the motherboard outputs 3.3V and the driver requires a 5V input, replace it with a 5V step-up module.
3. With power off, check if the DIR wiring is connected to the corresponding DIR/PUL terminal on the driver.
4. Verify that the dir_pin corresponds to the actual direction pin of the drive port in use.
5. Then, depending on the actual direction, add or remove the ! before dir_pin.

Motor Not Rotating / Vibration

Troubleshooting Sequence:

1. Confirm the module type is correct. Refer to the Module Type and Signal Level Check above.
2. Confirm the polarity of enable_pin is correct. Refer to the Enable Pin Determination Method above.
3. Confirm that the TMC configuration for the corresponding axis has been deleted or fully commented out. Refer to the TMC Configuration Residual Check above.
4. Confirm that step_pulse_duration has been increased.
5. Confirm that the driver DIP switch microstepping matches the Klipper microsteps setting.
6. With power off, check if the PUL/DIR/EN wiring matches the selected wiring method.