How To Configure a BLTouch Sensor in Klipper?

An automatic bed leveling sensor is perhaps the best upgrade you can add to your 3D printer, as the benefits that it brings to the 3D printing process are endless, both in the front of improving the quality of your prints and your 3D printing experience as the user.

On the other hand, it’s worth mentioning that utilizing an automatic bed leveling sensor is not without hurdles either, as the initial setup, which includes processes such as wiring, mounting, firmware configuration, and offset calibration, can be pretty challenging to perform if you don’t have prior familiarity.

In today’s article, our topic will be configuring the BLTouch automatic bed leveling sensor, specifically in Klipper firmware, which will be slightly different than getting your BLTouch to work in Marlin, the firmware that most 3D printing enthusiasts are accustomed to due to its high popularity.

So, how can you configure your BLTouch auto bed leveling sensor to work in Klipper firmware?

In a nutshell, to configure your BLTouch auto bed leveling sensor to work with Klipper firmware, you will need to add the [bltouch] and the [safe_z_home] sections with the appropriate parameters included, modify the endstop_pin parameter in the [stepper_z] section, and finally, remove the position_endstop parameter from it by editing the config file.

Moving forward, we will dive deeper into the process of configuring a BLTouch sensor in Klipper, find out whether it’s possible to install Klipper on an Ender 3 that has a BLTouch attached, go through fixing the issue of the BLTouch failed to deploy error in Klipper, and finally, take a quick look at the process of configuring the X, Y, and Z offsets for BLTouch in Klipper.

How To Configure a BLTouch Sensor in Klipper?

As each firmware has a distinct process for configuring the BLTouch to work, you will need to perform the necessary configuration in Klipper even if you had BLTouch set up and working with different firmware, such as Marlin, beforehand.

Below, you can find a step-by-step guide that you can follow to configure your BLTouch automatic bed leveling sensor to work with Klipper firmware:

  1. Open the printer.cfg file with your favorite text editor. You can quickly access this file by using the Configuration tab in FluiddPi.
  2. Type [bltouch] in an empty line at the bottom of the file.
  3. Locate the pin the white wire is connected to and note it down as “sensor pin.”
  4. Locate the pin the yellow wire is connected to (according to the original wiring) and note it down as the “control pin.”
  5. Make a new line under the [bltouch] line, and type “sensor_pin: ^”, (without quotes) followed by the pin number you have noted in Step 3. An example would be sensor_pin: ^P1.27.
  6. Make a new line under the sensor_pin line you have created in the step before, and type “control_pin: ” (without quotes) followed by the pin number you have noted in Step 4. An example would be control_pin: P1.25.
  7. If the version of the BLTouch you’re using is v3.0 or v3.1, make a new line under the control_pin line you have created in the step before, and type “probe_with_touch_mode: True “. Else, skip this step.
  8. Leave an empty line after the sensor_pin line, and type [safe_z_home] in the following line.
  9. Make a new line under the [safe_z_home] line, and type “home_xy_position: ” (without quotes), followed by the coordinates of the center of your print bed. An example would be home_xy_position: 100, 100.
  10. Make a new line under the home_xy_position line you have created in the step before, and type “z_hop: ” followed by the Z-hop distance value you would like to use. An example would be z_hop: 10 for 10 millimeters of distance.
  11. Make a new line under the z_hop line you have created in the step before, and type “z_hop_speed: ” followed by the Z-hop speed value you would like to use. An example would be z_hop_speed: 5 for 5mm/s of speed.
  12. Locate the [stepper_z] section and completely delete the “position_endstop” line that belongs to the section.
  13. Locate the “endstop_pin” line in the [stepper_z] section, and change its value to “probe:z_virtual_endstop”. After the modification, the line should read endstop_pin: probe:z_virtual_endstop.
  14. Save the configuration file.

Once you’re through with the process of setting the BLTouch up to work with Klipper, the next step is to perform the necessary tests to ensure that the automatic bed leveling sensor is indeed operating correctly.

Below, you can find the steps that you will need to follow to conduct the required tests that will indicate whether the BLTouch is correctly configured in Klipper:

  1. Turn the 3D printer on for the BLTouch to perform the self-test process. When the self-test process is done, the pin should be stowed, and the red LED on the BLTouch should be lit. In cases where the red LED is blinking, or the pin isn’t stowing, check for errors in wiring or configuration.
  2. Run the command “BLTOUCH_DEBUG COMMAND=pin_down”. This command should prompt the BLTouch to release the pin, and turn the red LED off. If it doesn’t, check for errors in wiring or configuration.
  3. Run the command “BLTOUCH_DEBUG COMMAND=up”. This command should prompt the BLTouch to stow the pin and turn the red LED back on. If it doesn’t, check for errors in wiring or configuration.
  4. Run the command “BLTOUCH_DEBUG COMMAND=pin_down” and wait for the pin to move down.
  5. Run the command “BLTOUCH_DEBUG COMMAND=touch_mode”.
  6. Run the command “QUERY_PROBE’. The output should be “probe:open“.
  7. Push the pin of the BLTouch upwards slightly with the help of a small object, such as a pen (ensure that it’s clean), and run the “QUERY_PROBE” command again in this state. The output should be “probe: TRIGGERED“.
  8. Run the command “BLTOUCH_DEBUG COMMAND=pin_up”.
  9. Move the printhead away from the bed.
  10. Run the G28 G-code command to trigger auto-homing.
  11. As the printhead moves down to approach the print bed, stop the movement by touching the pin with the pen, which should stop the printhead. If it doesn’t, turn the 3D printer off to prevent a scenario where the printhead crashes into the print bed.
  12. Run the G28 G-code command, and let it run without intervention.

Upon completing the testing process, it will be confirmed that Klipper and the BLTouch can communicate without any problems by using the current configuration.

For best results, we also recommend configuring the bed mesh module in Klipper, which will allow the BLTouch to conduct the automatic bed leveling process by utilizing a mesh that maps out the imperfections of the print bed, increasing accuracy.

How to Configure BLTouch X, Y, and Z Offsets on Klipper?

Configuring the X, Y, and Z offsets correctly is a step you will need to take again after switching to Klipper firmware, as your old offset configuration that worked with the firmware you have switched from will be deleted.

First, let’s start with the process of configuring the X and Y offsets in Klipper for the BLTouch, which you should perform first:

  1. Run the “PROBE” command.
  2. Wait for the printhead to position itself, and mark the area on the print bed that corresponds to the current XY position of the probe.
  3. Run the “GET_POSITION” command. Note the X and Y values that are displayed.
  4. Move the printhead in a way that brings the nozzle directly above the mark you have placed in Step 2.
  5. Run the “GET_POSITION” command again. Note the X and Y values that are displayed.
  6. Subtract the Step 3 X value from the Step 5 X value and the Step 3 Y value from the Step 5 Y value. Note these values down.
  7. Open the printer.cfg file in your favorite text editor.
  8. Replace the current x_offset and the y_offset values with the ones you have noted in Step 6. If the x_offset and y_offset labels don’t exist, create them.
  9. Save the configuration file.

For instance, if the X and Y values you have found in Step 6 are -10 and -20, respectively, the additions you would need to make to printer.cfg would be as follows:

x_offset: -10

y_offset: -20

Now, let’s take a look at the procedure that is required to configure the BLTouch Z offset in Klipper:

  1. Run the G28 G-code command to auto-home the printer.
  2. Move the printhead to the center of the print bed.
  3. Run the “PROBE_CALIBRATE” command.
  4. Wait for the automatic probing to be over.
  5. Place a piece of paper on the print bed, right under where the nozzle is positioned.
  6. Use the TESTZ command to move the nozzle up or down to the point where the nozzle slightly limits the movement of the paper, but doesn’t completely restrict it. For instance, you can run TESTZ=-0.1 to bring the nozzle 0.1 mm closer to the bed or TESTZ=0.1 to take the nozzle 0.1 mm away from the bed.
  7. Run the “ACCEPT” command.
  8. Run the “SAVE_CONFIG” command.

Can You Run Klipper on an Ender 3 (Pro/V2) with BLTouch?

Since compatibility can be a bit of a mysterious topic in 3D printing, it’s only natural to wonder whether the new firmware you will be installing to your 3D printer would also work just as well as the firmware you have been using so far.

As Klipper supports both the Ender 3 3D printer and the usage of the BLTouch automatic bed leveling sensor without any issues, it’s indeed possible to run Klipper on an Ender 3 that has a BLTouch probe attached to it and benefit from the features that Klipper brings to the table.

That being said, even though Klipper comes with a default configuration file that is made explicitly for the Ender 3, it will still be necessary to make the required additions for the BLTouch to operate, as it’s not something that is included in configuration files by default.

BLTouch Failed to Deploy Error on Klipper – What Causes It?

The “failed to deploy” error is one that you may face while attempting to use your BLTouch with Klipper firmware, and even though the issue at hand is apparent from the name, the firmware doesn’t give a lot of information about what could be causing it.

Below, you can find the most common culprits behind the BLTouch failed to deploy error in Klipper:

  • The BLTouch pin is stuck in the housing and unable to move down.
  • There is an issue related to the BLTouch configuration in Klipper, such as an incorrect sensor pin number.
  • The wiring of the BLTouch is damaged.
  • The wiring of the BLTouch is incorrect.
  • The wiring of the BLTouch is loose.

Wrapping Up

While switching to a new firmware with a different syntax for configuration can be confusing at first look, especially if you need to configure additional components, such as the BLTouch, Klipper makes it relatively straightforward to get things going.

To quickly recap, the process of configuring the BLTouch to work with Klipper entirely takes place in the configuration file, where you will need to follow the steps listed below:

  • Adding the [bltouch] section and filling it with the information that specifies the sensor and control pin numbers
  • Adding the [safe_z_home] section and filling it with data that specifies the Z-hop parameters and the bed center coordinates
  • Removing the position_endstop parameter from the [stepper_z] section
  • Modifying the endstop_pin parameter in the [stepper_z] section

As the entire process practically involves letting Klipper know which pins the BLTouch is connected to and telling it not to use the physical endstops anymore, there isn’t a whole lot of complexity involved in the procedure other than finding the correct pin numbers when we really think about it.

Happy printing!