Skip to main content

BLTouch Configuration & Troubleshooting

This article introduces the wiring, configuration, testing, calibration, and common troubleshooting of the BLTouch probe in Klipper.

Related Errors: For quick troubleshooting of BLTouch-related errors, see Motion, Endstop & Leveling Errors.

Wiring and Configuration​

Power Off

Before starting, fully shut down the printer and disconnect the power supply. Do not plug or unplug wiring harnesses, arrange interface cables, or touch terminals while the printer is powered on.

The BLTouch has two sets of wires:

  • Three-wire (Servo/Control): The yellow wire is the control_pin signal.
  • Two-wire (Sensor): The white wire is the sensor_pin signal.

Connect the control end to the Servo / BLTouch control pins on the mainboard. Connect the sensor end to the Probe / Z-Max endstop input pins on the mainboard. Refer to the specific FLY mainboard configuration documentation for the correct pins.

Pull-up Resistor

Most BLTouch sensor_pin configurations require a pull-up resistor. Add a ^ prefix to the pin name, for example: sensor_pin: ^PC4.

Basic configuration example:

[bltouch]
sensor_pin: ^PC4
control_pin: PA1
x_offset: 0
y_offset: 0
z_offset: 0
speed: 5

If using BLTouch as the Z-axis homing endstop, you need to:

  1. Set endstop_pin: probe:z_virtual_endstop in the [stepper_z] section and delete position_endstop.
  2. Add the [safe_z_home] configuration:
[safe_z_home]
home_xy_position: 100, 100  # Change to the center coordinates of the heated bed
speed: 50
z_hop: 10                   # Lift 10mm before homing
z_hop_speed: 5
z_hop Height

z_hop must be high enough to ensure that even with the probe extended, it will not collide with the heated bed or fixtures.

Initial Tests​

Self-test​

Upon powering on, the BLTouch should automatically perform a self-test: the probe will retract and extend several times, then retract, with a solid red LED. If the red LED blinks or the probe remains extended, power off the printer and check the wiring and configuration.

Control Pin Test​

BLTOUCH_DEBUG COMMAND=pin_down

Confirm the probe extends and the red LED turns off. Then:

BLTOUCH_DEBUG COMMAND=pin_up

Confirm the probe retracts and the red LED turns back on. If the red LED blinks, there is an anomaly.

Sensor Pin Test​

  1. Execute BLTOUCH_DEBUG COMMAND=pin_down, confirm the probe extends.
  2. Execute BLTOUCH_DEBUG COMMAND=touch_mode.
  3. Execute QUERY_PROBE. It should return probe: open.
  4. Gently push the probe pin upward with your fingernail. Execute QUERY_PROBE again. It should return probe: TRIGGERED.
  5. Execute BLTOUCH_DEBUG COMMAND=pin_up to retract the probe.

If the QUERY_PROBE result is incorrect, it is typically a wiring or configuration error (some clone versions require special handling, see below).

Probe Test​

Move the print head away from the heated bed. Execute G28 (or PROBE). As the print head starts to descend, gently touch the probe pin with your fingernail to trigger it. Be prepared to power off the printer at any time. After success, perform a normal homing operation to allow the probe to contact the heated bed.

Fault Recovery (Blinking Red LED)​

When the BLTouch enters an abnormal state and the red LED continuously blinks, execute:

BLTOUCH_DEBUG COMMAND=reset

Common trigger: The probe is blocked during calibration, causing an interruption.

If the probe still does not work correctly after reset, the internal magnet core may have shifted:

Power Off

Before disassembling or adjusting the BLTouch probe, fully shut down the printer and disconnect the power supply.

  1. After powering off, unscrew the top screw of the probe. Use a ballpoint pen to gently push the magnet core back into its original position.
  2. Reinsert the probe so it naturally falls to the extended position.
  3. Carefully adjust the screw position. After powering on, test extension/retraction and the red LED using BLTOUCH_DEBUG COMMAND=reset, pin_up, and pin_down.

Clone Version Compatibility​

Most clone BLTouch units work correctly with default configurations, but some clones may have the following issues:

Important Note

Do not set pin_up_reports_not_triggered or pin_up_touch_mode_reports_triggered to False without confirming necessity. These two items should not be modified for genuine BLTouch probes. Incorrect settings can increase probe time and potentially damage the printer.

Touch Mode Not Supported​

Some clones do not support touch_mode. The QUERY_PROBE command may not work correctly, but G28 / PROBE can still succeed. Do not enable probe_with_touch_mode for such devices.

BLTouch failed to verify sensor state​

The clone device cannot pass Klipper's internal sensor verification. First, follow the Sensor Pin Test to confirm QUERY_PROBE returns correct results. If manual tests are always normal but the error persists, add:

[bltouch]
pin_up_touch_mode_reports_triggered: False

BLTouch failed to raise probe​

Older clones cannot report the probe retraction state. Testing method:

  1. Move the print head away from the hot bed.
  2. BLTOUCH_DEBUG COMMAND=pin_down → Confirm extension.
  3. QUERY_PROBE → Should return probe: open.
  4. BLTOUCH_DEBUG COMMAND=pin_up → Confirm retraction.
  5. QUERY_PROBE → If it returns probe: TRIGGERED (instead of open), the device cannot report retraction.

After confirmation, add:

[bltouch]
pin_up_reports_not_triggered: False

BLTouch V3 Version Notes​

V3.0 Signal Issues​

If the BLTouch V3.0's sensor_pin is connected to an endstop pin with a filter capacitor, it may fail to send a stable trigger signal. This manifests as QUERY_PROBE tests passing normally, but the print head occasionally not stopping during G28 / PROBE. Solution:

[bltouch]
probe_with_touch_mode: True

V3.1 Intermittent Error State​

The BLTouch V3.1 may occasionally flash the red LED for a few seconds after a successful probe. Klipper will automatically clear this error, and it is usually harmless. Setting probe_with_touch_mode: True can avoid this issue.

Accuracy Impact

Some clone devices and BLTouch V2.0 or earlier versions may experience decreased accuracy when probe_with_touch_mode: True is enabled, and the probe extension time increases. Use the PROBE_ACCURACY command to compare performance before and after making this change.

Multiple Probes Without Retraction​

By default, Klipper retracts and re-extends the probe after each probe, which can be time-consuming for multiple probes. The following option keeps the probe extended between consecutive probes:

[bltouch]
stow_on_each_sample: False
Safety Notice

When set to False, Klipper may move the print head horizontally with the probe extended. Ensure sufficient Z clearance for all probe operations, otherwise the probe may collide with obstacles and damage the printer during horizontal moves.

Recommended Combination

It is recommended to also set probe_with_touch_mode: True when using stow_on_each_sample: False. This simplifies signal logic and improves stability. Some clone devices may fail to detect subsequent triggers without this option.

Offset Calibration​

Use the PROBE_CALIBRATE command to calibrate x_offset, y_offset, and z_offset.

Z Offset Suggestion

The ideal z_offset value is close to 1mm. If the deviation is too large, it is recommended to adjust the probe mounting height: the probe should trigger well before the nozzle contacts the hot bed, and when retracted, should be higher than the nozzle to avoid scraping prints. Re-run PROBE_CALIBRATE after adjusting.

Output Mode (5V / Open-Drain)​

BLTouch V3.0 and V3.1 support both 5V and Open-Drain output modes. The default is Open-Drain.

  • If the mainboard input pin requires a 5V high level and is tolerant of 5V, you can set:
[bltouch]
set_output_mode: 5V
Voltage Compatibility

Only use 5V mode if you have confirmed that the mainboard input signal line is tolerant of 5V. Incorrect settings can damage the mainboard CPU.

  • V3.0: The mode must be set via set_output_mode: 5V at every startup, as the V3.0 cannot retain the setting.
  • V3.1: The mode can be written to the internal EEPROM once using BLTOUCH_STORE MODE=5V. After this, set_output_mode is no longer required. Do not execute the store command repeatedly, as the EEPROM has a lifespan of approximately 100,000 write cycles.
  • Other Probes: Some probes permanently set the output mode via board jumpers or trace cuts. The set_output_mode parameter is not needed in such cases.
Loading...