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 working correctly. The testing approach is consistent with the basic I/O test, using a minimal Klipper configuration to isolate individual hardware.

If you need to test MCU connection, temperature sensors, fan output, or input ports, please refer to Hardware Testing Method first.

Driver Testing​

Test Purpose​

Use the simplest Klipper configuration to verify whether a single TMC driver (in UART or SPI mode) can communicate properly 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 proceeding with the following operations. Do not hot-plug driver modules or stepper motor cables.

  1. The printer is completely powered off.
  2. The TMC driver to be tested is correctly inserted into the corresponding slot on the mainboard, with the 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. Prepare a minimal printer.cfg file containing only the driver to be tested. It is recommended to back up the original complete configuration file first.

Single Driver Minimal Configuration​

Use the following minimal configuration to replace printer.cfg, retaining only the [printer], [mcu], the [manual_stepper Drive0] for the driver under test, and the corresponding [tmcXXXX manual_stepper Drive0] sections. The [manual_stepper] still requires a minimal [printer] section (kinematics: none), which is simpler than motion axis configurations and suitable for pure hardware verification.

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

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

[manual_stepper Drive0]
# 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]
# Modify uart_pin according to the actual mainboard pins
# 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 checked via ls /dev/serial/by-id/).
  • 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 solely on the chip model. Different TMC5160 driver boards may have values like 0.075, 0.033, 0.022, or others; sampling parameters for drivers like TMC2240 may also differ. If the manufacturer's documentation does not specify, please consult the manufacturer or use their official configuration example first.
  • The configuration does not contain 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 mainboard one by one, you can name each driver port independently, such as Drive0, Drive1, Drive2, referencing the test configuration naming convention:

[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 and switch to the next port.

Test Steps​

  1. Save the above minimal configuration as printer.cfg.

  2. Confirm the motor and driver are correctly plugged in, 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 being enabled, it indicates enable_pin is basically effective.
    • If the motor can still be turned freely, power off and check the enable_pin, driver orientation, jumper caps, and power supply.

  4. Perform 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 a relative movement. Executing MOVE=100 followed by MOVE=0 will make the motor reverse back to the start point.
    • If the motor is still connected to the machine's motion mechanism, it is recommended to first modify to MOVE=10 SPEED=5 for the initial test to confirm direction and travel distance 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 has abnormal direction, power off and check pin configuration, motor wiring sequence, driver direction, and jumper caps.

  5. Verify TMC communication status:

    DUMP_TMC STEPPER=Drive0

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

  6. After testing, disable the motor enable:

    MANUAL_STEPPER STEPPER=Drive0 ENABLE=0

Expected Results​

Test ItemNormal ResultAbnormal Performance
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 easily turned (not enabled)

If all three items above are normal, the driver-mainboard communication and motor wiring are confirmed to be without issues. 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​

[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. Follow the CAN Network Configuration and ID Search steps to search for and fill in the canbus_uuid.
  2. After restarting Klipper, check if the ToolBoard temperature is displayed correctly.
  3. Use SET_PIN PIN=tool_FAN0 VALUE=1 to test the low-voltage fan output on the tool board. After testing, execute SET_PIN PIN=tool_FAN0 VALUE=0.
  4. If you need to test the accelerometer or input ports on the tool board, add the corresponding configuration according to the relevant section above.
CAN Troubleshooting Reminder

Operations on CANH/CANL wiring sequence, termination resistors, jumper caps, and cable management must be done with the power off. Do not plug/unplug CAN cables or adjust termination resistors while the system is powered on.

Common Anomalies and Next Steps​

AnomalyCommon Keywords in klippy.logPriority CheckNext Steps
Klipper cannot connect to MCUUnable to connect, Connect error, Serial connection closedserial / canbus_uuid, firmware, USB/CAN connectionCommon Error Overview
Abnormal temperature displayADC out of range, temperature, not heatingsensor_type, sensor_pin, thermistor connectorTemperature, Heating, and Extrusion Errors
Heater or heated 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 compatibilityReplace fan or cross-test with another port
Input state unchangedNo error (input ports do not generate logs)Pull-up ^, wiring sequence, switch typePower off and check connector and port
No data from accelerometerInvalid adxl345 id, Invalid lis2dw id, timeoutcs_pin, spi_bus, wiring, module modelAccelerometer Testing and Calibration
Resonance test failureNo data, Insufficient axis data, Frequency rangeSensor fixation, 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 unable to read registerDRV_STATUS, read register, GSTATUART/SPI pins, jumper caps, driver power, driver modelTMC Error Troubleshooting
CAN tool board offlinebytes_invalid, Network is down, No buffer space, Timer too closeCAN wiring sequence, termination resistor, power supply, UUIDCAN Network Configuration and ID Search
Random stuttering/loss during printingStepper too far in past, Rescheduled timer, Lost communicationHost computer load, communication line interference, velocity/accelerationSystem, Performance, and Service Errors
Configuration cannot be savedUnable to write, Option conflict, CRC does not matchFile permissions, auto-save section conflict, FIRMWARE_RESTARTConfiguration Errors

Reference Configuration Snippets​

When maintaining test configurations, you can extract snippets 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 test commands must match the configuration section names.
  • Low-voltage output testing: Prioritize low-voltage loads such as fans, RGB, buzzers. Do not use heater cartridges or heated beds as general output_pin test loads.

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

Loading...