As we assume previous knowledge of Klipper and how to access the configuration, we’ll jump straight into ABL and its options. Be aware, ABL is no replacement for poorly built printers and mechanical problems, but it is a replacement for tedious and imprecise manual “paper tests” to establish level beds.

When talking about ABL, we’re talking about the automatic creation of a bed mesh with the intention of automatically compensating for fluctuations in Z height to create the perfect first layer. A bed mesh is a series of Z height measurement points across the build surface. Hence, we start with exploring the configuration settings in Klipper for a bed mesh.

The following is a brief bullet point overview of Klipper’s basic configuration. The settings are slightly different depending on whether your printer has a rectangular or round print bed.

Rectangular

• “speed” is the movement speed of the tool head. The default setting is 50 mm/s.
• “horizontal_move_z” is the movement of the tool head along the Z-axis prior to moving to the next point of measuring.
• “mesh_min” represents the coordinates of the first point of measurement relative to the probe location.
• “mesh_max” represents the coordinates of the furthest point of probing relative to the probe location.
• “probe_count” is the number of probing points along the X- and Y-axes respectively. The default setting is 3,3.

Round

• “speed” is the same as above.
• “horizontal_move_z” is also the same as above.
• “mesh_radius” represents the probing radius in relation to the mesh origin.
• “mesh_origin” represents the origin for probing. The default setting is 0,0.
• “round_probe_count” is the maximum number of probing points along the X- and Y-axes respectively. The default setting is 5.

The advanced settings are a little more interesting because they allow for fine-tuning. The functions are divided into five functional groups. As it’s beyond the scope of this article to explain every function in detail, we’ll provide an overview so that you can develop a good understanding of what the functions within the functional groups do.

• “Mesh Interpolation” settings provide us with various options to determine how fine a mesh we would like to compute, with additional mathematically derived points between the probing points in our basic configuration. We can determine the number of those additional points along the X- and Y- axes, the mathematical method by which we compute those points (Lagrange and bicubic), as well as a tension factor for the bicubic method that changes the calculated height for the additional mesh points (i.e. it over-exaggerates or under-exaggerates the calculated heights).
• “Move Splitting” allows the user to determine how closely our tool head will follow the calculated mesh by way of setting the distance the nozzle moves before checking against the mesh and correcting the height. We can also set the difference in Z-height, which will trigger a split.
• “Mesh Fade” helps the user to eventually level out the workpiece by reducing the amount of mesh bed correction over a set number of layers.
• “Relative Reference Index” is an interesting setting, as it provides users with probes that tend to drift with a way to automatically adjust the Z-offset based on a reference probing point. This setting is not really needed for the BLTouch, as this probe simply does not suffer from drift or interference.
• “Faulty Regions” allow users to define bed areas where probing results may be faulty, then compensate by probing several times around the edges of such areas.

Mounting the BLTouch is easy. Mounting brackets for most popular 3D printers are available on Thingiverse or can be purchased through online retailers. You could even design your own.

There are a few general things to consider when mounting the BLTouch:

• The BLTouch needs to be mounted perpendicular to the build surface. Otherwise, the probe will not deliver sensible measurements.
• Mount the probe as close as practically possible to the nozzle. It’s always better to keep the offset between the probe and nozzle as small as possible to avoid the introduction of odd artifacts.
• Ensure there’s sufficient space in parking and cleaning positions to avoid damaging the probe.
• Ensure there’s a sensible way to route the cable for connecting the BLTouch to the printer’s controller board.

Mounting Height

The most important setting for a successful setup of the BLTouch is the mounting height!

Make sure to mount the sensor at the correct height in accordance with the BLTouch documentation. The image above shows the latest version 3.1, and it’s backward compatible with version 2. The most important dimensions are the push pin drop of 6.6 mm and the height difference between the push pin in the retracted position and the nozzle tip – which should be between 2.3 and 4.3 mm as shown above.

If the BLTouch isn’t configured as recommended, a number of things could go wrong. It’s possible that the sensor will not trigger, allowing the nozzle to hit the build surface (not great). Alternatively, there could be an insufficient clearance in the sensor’s retracted position, which would prevent the nozzle from reaching the build surface at all.

Next, we’ll need to identify the relevant pinouts on our printer’s controller board. Because of the wide range of boards and some users having had problems in identifying the correct pins, Antlabs has kindly provided links with QR codes in the BLTouch manual that lead to sites explaining where to find the correct pins.

The BLTouch probe V3.1 supports 5-V and 3.3-V logic, meaning it supports controller boards that can deal with a 5-V high signal on the input pins (like the Arduino range) as well as those that use 3.3 V (the Esp32 or the Raspberry Pi range of boards, for example). It comes with a white five-pin connector on one end and, at the other end, a two- and a three-pin female plug with the following color-to-pin allocations:

Two-Pin Female Plug

• White: Z-min
• Black: Ground

Three-Pin Female Plug

• Orange: Signal
• Red: +
• Black or blue: Ground

How to Do It

1. Ensure that the 3D printer is switched off, and it’s safe to work on.
2. Run the connection cable from the BLTouch to the controller board in such a manner that the cable does not interfere with the mechanics and free movement of the printhead.
3. Secure the cable with cable ties where needed. If the supplied cable is too short, extensions are available to buy.
4. Create the connections according to the pin allocation above.

Tips

On some boards, the order of the connector for the three-pin plug may be different from the cable. In this case, we have to release the wire terminations from the plug and reinsert them in the required order.

In the unlikely event that the controller board is not listed, Google is usually our friend. Use it to search for your controller board’s pinouts. You’ll need the exact label for the servo pin for the BLTouch’s orange signal connection and the Z-min pin for the BLTouch’s white wire. Make sure to note the pin name because you’ll need it later for our software configuration!

Some users reported problems due to electrical interference issues, which can be addressed by using shielded wiring and keeping the connection wires away from other wires. Those reports have to be taken with a grain of salt, though, as a lot of the problems reported are often due to the probe in question being a clone.

As mentioned above, some fake probes work well, while others don’t. As the old saying goes, “You get what you pay for.”

Now that we have mounted the BLTouch probe, it’s ready to be configured. Whatever we use to interact with Klipper – be it Mainsail, Repetier, or others – the configuration process is the same. To complete the configuration, we’ll need the following:

• The board-specific names of the Z-min and servo pins used to connect the BLTouch
• The dimensions and shape of our print bed

A Ramps 1.6 controller board was used for this example.

How to Do It

1. Open the Klipper configuration, then add (or uncomment if already present) the heading as shown in the image above.
2. Under the heading, add the following entries. Remember that the pin name may be different on your board.
   • sensor_pin: ^PD3
   • control_pin: PH3

3. Save your configuration.
4. Switch on your printer.
5. Restart Klipper.
6. Observe and check the probe.

During the initial self-test, the probe will retract and drop the pin a few times. It will conclude with the red LED lit and the pin in the up position. Provided the BLTouch passes the initial self-test, all is well.

Regarding the input for the sensor pin, keep in mind that not every BLTouch requires the pull-up resistor to be activated with ‘^‘.

Bed Mesh Setting

Before moving on to testing and calibration, we would recommend to take this opportunity to set up the bed mesh setting as well. While not strictly required to get the BLTouch probe up and running, the entire purpose of this article is to enable our readers to successfully perform ABL, and that requires a mesh.

How to Do It

The following instructions are just to show you how to set up the bed mesh setting. The inputs assume a print bed of 250 x 220 mm with an X offset of 24 mm and a Y offset of 5 mm.

1. Open Klipper configuration
2. Add the heading if not already present
3. Then, add the following under the heading:
   • speed: 120
   • horizontal_move_z: 5
   • mesh_min: 35, 6
   • mesh_max: 240, 198
   • probe_count: 5, 3

Again, the entries above are examples to serve as a guide only. The offset you use will need to be determined via the calibration procedure explained in the next section, and your entries must be edited accordingly.

Advanced Configuration

Ignore the advanced settings for now and keep things simple to start with. Once all is well and working as it should, then feel free to experiment with the advanced settings and fine-tune your printer. When you’re ready to do so, we strongly recommend changing one setting at a time to see the effect.

We need to test the probe function without risk of damage to the printer. To do so, we’ll send a number of commands, one after the other in the order below via our command terminal to the printer.

Test 1

Let’s start by sending several commands.

1. Send BLTOUCH_DEBUG COMMAND=pin_down. The pin should move down, and the red LED should be off.
2. Send BLTOUCH_DEBUG COMMAND=pin_up. The pin should move up, and the red LED should be on.
3. Then, send the following:
   • BLTOUCH_DEBUG COMMAND=pin_down
   • BLTOUCH_DEBUG COMMAND=touch_mode
   • QUERY_PROBE

4. After sending the last command, verify that it reports probe: open

Test 2

Next, gently push the pin up by a few millimeters. Then, send the command QUERY_PROBE and verify it reports probe: triggered.

After that, send the command BLTOUCH_DEBUG COMMAND=pin_up. The pin should move up.

Test 3

For the last test, please be ready to switch off the printer in case of malfunction. Send the command PROBE.

Let the push pin touch something at a safe distance from the print bed. Depending on setup, it might probe twice or more times. The printer should stop as intended.

If all works as intended, we’re done with the basic setup for the BLTouch. If the LED flashes or the pin is down at the end of the test, check out the troubleshooting notes below for guidance.

Tips

Under normal circumstances, the probe should be working now as intended. If the probe doesn’t behave as it should check over the setup again step by step. This includes ensuring all relevant cables and connectors are connected as they should be.

For users with less common controller boards, check the many forums out there for possible solutions. Lastly, if the probe is not an original BLTouch, there’s the possibility that the probe simply doesn’t work. In such cases, we recommend that you get the original.

Now that we’re certain that the probe works as intended, we need to calibrate the X, Y, and Z offsets. Probe calibration is well documented by Klipper, but we provide a brief run-through.

Step 1

Via the terminal, issue the command PROBE, then physically mark the position where the probe touches the bed with a marker.

Next, send the command GET_POSITION. You’ll receive something back like the following:

Recv: // : X:46.500000 Y:27.000000 Z:15.000000 E:0.000000

Note down the X and Y positions as “probe x” and “probe y”. Using the example above, the notes should look similar to the following:

• probe x= 46.5
• probe y= 27

Step 2

For the next step, we need to move the nozzle to the marker by using G1 commands. Several commands may be needed before being perfectly centered on the marker. The X and Y will be different for everyone, but to illustrate the command format, it would look something like the following: G1 F300 X30 Y30 Z10

When the nozzle tip aligns perfectly with the position of the mark we made previously, send the command GET_POSITION. This time, note down the X and Y positions as “nozzle x” and “nozzle y”.

For example, if you received Recv: // : X:60.500000 Y:60.000000 Z:15.000000 E:0.000000, you’ll note down nozzle x= 60.5 and nozzle y= 60.

Now, you can calculate the X and Y offsets. The formula is simply nozzle x – probe x and nozzle y – probe y. In our example, the offset is x=14 and y = 33.

Lastly, in the configuration file under the heading, add offsets as follows:

• x_offset: 14
• y_offset: 33

Step 3

Almost there! The last calibration step is finding the Z offset. Klipper offers a command to do that easily. First, we home our printer, then run PROBE_CALIBRATE. It’ll do one automatic probe, then move the nozzle over the probe point before going into the manual probe tool.

Most Klipper users will be familiar with paper test:

1. Put a sheet of paper or the 0.1-mm blade of a feeler gauge between nozzle and bed.
2. Adjust the Z height up or down with the TESTZ command until there’s a little friction felt when moving the paper or feeler gauge. For example, to move the nozzle up or down by .1 mm, you would enter the following:
   • TESTZ Z=+.1
   • TESTZ Z=-.1

3. When you’re satisfied with the results, type ACCEPT in the terminal.
4. Finish with SAVE_CONFIG, then restart the printer.

Step 4

We’re finally ready for our first mesh. Type BED_MESH_CALIBRATE into the terminal and enjoy!

Once the automatic bed mesh probing has been created, we’re prompted to SAVE_CONFIG. This will save the mesh in our configuration for future use.

Don’t forget to set up the relevant mesh command in your slicer. Otherwise, it won’t be included in the G-code we generate.

We can run into a number of problems with the BLTouch, and there are further tuning steps that may be of interest to the discerning user. Below, we’ll recommend solutions to the most common problems. Remember also to check out Klipper’s documentation for the finer points of ABL that are beyond the scope of this article.

Problems During Testing

The most obvious issues are indicated by the BLTouch’s red LED flashing fast or the pin being down at the start of the printer. If we find the above, it’s most likely a wiring issue. Check all connections, then try again. Note that, there have been instances when a BLT is wired backward.

If the red LED flashes or the pin is down when it shouldn’t be during the initial testing, please check the wiring as well as the configuration again. Are the pin names correct? Has a pull-up resistor been specified?

Error State

Occasionally, the BLTouch can go bad for no obvious reason and enter an error state, indicated by a flashing red LED. To exit the error state, type BLTOUCH_DEBUG COMMAND=reset into the terminal to reset the probe.

The exact same error can happen when the push pin fails to deploy because it doesn’t detach from the metal insert at the top of the probe. Fortunately, the push pin can be pulled out, and the metal insert can be adjusted with a little hexagonal key. Just open the screw a little and reinsert the pin gently. Then, try again with the following commands until it works:

• BLTOUCH_DEBUG COMMAND=reset
• BLTOUCH_DEBUG COMMAND=pin_down
• BLTOUCH_DEBUG COMMAND=pin_up

Clones

If we’re dealing with a clone or a fake, there are numerous other issues that can arise. Klipper offers a range of solutions in their BLTouch documentation under the “BL-Touch ‘clones'” heading.