Skip to main content

Peripheral and Driver Testing

This document is used to verify whether peripheral modules such as stepper drivers and CAN tool boards are functioning correctly. The testing approach is consistent with basic I/O testing, using a minimal Klipper configuration to isolate individual hardware.

If you need to test MCU connections, temperature sensors, fan outputs, or input ports, please first refer to Hardware Testing Methods.

Driver Testing​

Test Purpose​

Use the simplest Klipper configuration to verify whether a single TMC driver (UART or SPI mode) can communicate normally with the mainboard and confirm that the motor can be controlled.

Prerequisites​

Power Off Operation

Please completely shut down the printer and disconnect the power supply before performing the following operations. Do not plug or unplug driver modules or stepper motor cables while powered on.

  1. The printer is completely powered off.
  2. The TMC driver under test is correctly inserted into the corresponding socket on the mainboard, with correct orientation confirmed.
  3. For UART mode drivers (e.g., TMC2209), confirm that the UART jumper cap for the corresponding driver port is installed.
  4. Connect only one stepper motor to the driver port under test; leave other driver ports empty for now.
  5. Back up the original complete configuration file and prepare a temporary printer.cfg containing only the basic minimal configuration and the test fragment for the driver under test.

Minimal Single Driver Configuration​

First, write the basic minimal configuration, then append the test fragment corresponding to the current driver mode after the basic configuration. [manual_stepper] still requires a minimal [printer] section (kinematics: none), which is simpler than a motion axis configuration and suitable for pure hardware verification.

Basic Minimal Configuration​

[printer]
kinematics: none
max_velocity: 200.00
max_accel: 40000.00

[mcu]
serial: /dev/serial/by-id/usb-Klipper_xxxxxxxxxxx

Driver Test Configuration Fragment​

Below is only the driver test fragment that needs to be appended. Do not add a second [printer] or [mcu] section.

[manual_stepper Drive0]
# Please modify the following three items according to the actual mainboard pins
step_pin: PE2
dir_pin: PC5
enable_pin: !PF11
# The following parameters do not need modification
microsteps: 16
rotation_distance: 40
velocity: 500
accel: 10000
position_min: 0
position_max: 1000

[tmc2209 manual_stepper Drive0]
# Please modify uart_pin according to the actual mainboard pin
# Please modify sense_resistor according to the driver manufacturer's documentation
uart_pin: PC4
interpolate: False
run_current: 0.8
sense_resistor: <driver_sense_resistor>
stealthchop_threshold: 0
Configuration Notes
  • serial: Replace with the actual serial port ID of the mainboard (can be viewed via ls /dev/serial/by-id/). Only keep one instance in the basic minimal configuration.
  • step_pin / dir_pin / enable_pin: Replace with the mainboard pins corresponding to the driver port under test.
  • uart_pin (UART mode) / cs_pin + spi_bus (SPI mode): Replace with the actual pins and SPI bus number.
  • sense_resistor: Must be filled in according to the parameters provided by the driver manufacturer; do not guess based on the chip model alone. Different TMC5160 driver boards may use 0.075, 0.033, 0.022, or other values; sampling parameters for TMC2240 and other drivers may also differ. If the manufacturer's documentation does not specify, please consult the manufacturer or use their official configuration examples first.
  • The configuration does not include any heaters or fans; it is only for driver communication verification.

Multi-Driver Testing Method​

If you need to verify multiple driver ports on a single mainboard one by one, you can follow the naming convention in the test configuration, writing each driver port as a separate Drive0, Drive1, Drive2:

[manual_stepper Drive1]
step_pin: PE3
dir_pin: PF13
enable_pin: !PF14
microsteps: 16
rotation_distance: 40
velocity: 500
accel: 10000
position_min: 0
position_max: 1000

[tmc2209 manual_stepper Drive1]
uart_pin: PF12
interpolate: False
run_current: 0.8
sense_resistor: <driver_sense_resistor>
stealthchop_threshold: 0

During testing, only connect the motor to the driver port currently under test. After confirming one port, power off, then switch to the next port.

Test Steps​

  1. Save the basic minimal configuration and the current driver test fragment as printer.cfg.

  2. Confirm the motor and driver are properly inserted, then power on and start Klipper.

  3. In the Mainsail / Fluidd console, enter the following commands to enable the motor and set the current position to 0:

    MANUAL_STEPPER STEPPER=Drive0 ENABLE=1
    MANUAL_STEPPER STEPPER=Drive0 SET_POSITION=0
    • If the motor has holding torque after enabling, it indicates enable_pin is basically effective.
    • If the motor can still be turned freely, power off and check enable_pin, driver orientation, jumper caps, and power supply.

  4. Perform a manual movement test:

    MANUAL_STEPPER STEPPER=Drive0 MOVE=100 SPEED=100
    MANUAL_STEPPER STEPPER=Drive0 MOVE=0 SPEED=100
    • MOVE= is the target position, not relative displacement. After executing MOVE=100, executing MOVE=0 will cause the motor to reverse back to the starting point.
    • If the motor is still connected to the machine's motion mechanism, it is recommended to first change to MOVE=10 SPEED=5 for the initial test to confirm direction and travel range safety before increasing speed.
    • If the motor rotates smoothly without stuttering, it indicates the driver, motor, and step/direction pins are basically normal.
    • If the motor does not respond, only vibrates, or the direction is abnormal, power off and check pin configuration, motor wiring sequence, driver orientation, and jumper caps.

  5. Verify TMC communication status:

    DUMP_TMC STEPPER=Drive0

    If register information is returned normally, it indicates UART/SPI communication is basically normal. If it prompts that registers cannot be read, please refer to TMC Error Troubleshooting.

  6. After testing, disable the motor:

    MANUAL_STEPPER STEPPER=Drive0 ENABLE=0

Expected Results​

Test ItemNormal ResultAbnormal Behavior
Manual movementMotor moves forward and backward as commandedNo movement, vibration, stuttering, or abnormal direction
TMC communicationDUMP_TMC returns register informationUnable to read UART/SPI registers
Holding torqueMotor shaft cannot be turned freely after ENABLE=1Shaft can be turned easily (not enabled)

If all three items above are normal, it indicates that the driver-to-mainboard communication and motor wiring are fine. You can restore the original printer.cfg and continue troubleshooting other hardware.

CAN Tool Board Minimal Test​

Test Purpose​

Confirm that the CAN tool board is recognized by Klipper and verify the temperature sensor, fan, accelerometer, or input ports on the tool board.

Minimal Configuration​

First, keep the basic minimal configuration, then append the following CAN tool board test fragment after the configuration. If only testing the CAN tool board, keep the mainboard [mcu] as well to allow Klipper to start normally and display the mainboard connection status.

[mcu tool]
canbus_uuid: xxxxxxxxxxxx

[temperature_sensor ToolBoard]
sensor_type: temperature_mcu
sensor_mcu: tool

[output_pin tool_FAN0]
pin: tool:gpio13
pwm: True
cycle_time: 0.010
value: 0
shutdown_value: 0

Test Steps​

  1. Search for and fill in the canbus_uuid according to CAN Network Configuration and ID Search.
  2. After restarting Klipper, check if the ToolBoard temperature is displayed normally.
  3. Use SET_PIN PIN=tool_FAN0 VALUE=1 to test the tool board's low-voltage fan output. After testing, execute SET_PIN PIN=tool_FAN0 VALUE=0.
  4. If you need to test the tool board's accelerometer or input ports, add the corresponding configuration according to the relevant sections above.
CAN Troubleshooting Tip

CANH/CANL wiring order, termination resistors, jumper caps, and harness management must all be performed with the power off. Do not plug or unplug CAN cables or adjust termination resistors while powered on.

Common Anomalies and Next Steps​

AnomalyCommon Keywords in klippy.logPriority CheckNext Step
Klipper cannot connect to MCUUnable to connect, Connect error, Serial connection closedserial / canbus_uuid, firmware, USB/CAN connectionCommon Error Overview
Temperature display anomalyADC out of range, temperature, not heatingsensor_type, sensor_pin, thermistor connectorTemperature, Heating, and Extrusion Errors
Heater or bed shutdownVerify heater, not heating at expected rateThermistor contact, PID, heater power, SSRTemperature, Heating, and Extrusion Errors
Fan not spinningNo error (output ports do not generate logs)pin, fan voltage specification, PWM compatibilitySwap fan or port for cross-testing
Input status unchangedNo error (input ports do not generate logs)Pull-up ^, wiring order, switch typePower off and check connector and port
Accelerometer no dataInvalid adxl345 id, Invalid lis2dw id, timeoutcs_pin, spi_bus, wiring, module modelAccelerometer Testing and Calibration
Resonance test failedNo data, Insufficient axis data, Frequency rangeSensor mounting, belt tension, fan vibrationAccelerometer Testing and Calibration
Motor not movingUnable to read tmc uart, Unable to write tmc spistep_pin, dir_pin, enable_pin, TMC configurationTMC Error Troubleshooting
TMC cannot read registersDRV_STATUS, read register, GSTATUART/SPI pins, jumper cap, driver power, driver modelTMC Error Troubleshooting
CAN tool board offlinebytes_invalid, Network is down, No buffer space, Timer too closeCAN wiring order, termination resistor, power supply, UUIDCAN Network Configuration and ID Search
Random stuttering/loss during printingStepper too far in past, Rescheduled timer, Lost communicationHost load, communication line interference, speed/accelerationSystem, Performance, and Service Errors
Configuration cannot be savedUnable to write, Option conflict, CRC does not matchFile permissions, save config section conflict, FIRMWARE_RESTARTConfiguration Errors

Reference Configuration Fragments​

When maintaining test configurations, you can extract fragments from the corresponding mainboard/tool board templates based on the hardware type:

  • Mainboard testing: temperature_sensor, manual_stepper DriveN, tmcXXXX manual_stepper DriveN, output_pin FANx, gcode_button IOx.
  • Tool board testing: temperature_sensor, adxl345 / lis2dw, manual_stepper Drive0, output_pin FANx, gcode_button.
  • Multi-driver testing: Maintain naming like Drive0, Drive1, Drive2. The STEPPER= in the test command should match the configuration section name.
  • Low-voltage output testing: Prioritize choosing low-voltage loads like fans, RGB, buzzers. Do not use heater cartridges or heated beds as regular output_pin test subjects.

If a module cannot pass the above minimal test, first restore the original configuration, then proceed to the corresponding FAQ page for further troubleshooting based on the specific error.

Loading...