Klipper BL Touch guide
This is a text guide that follows alongside my BL Touch Klipper video. This article is meant to get you up and running with your BL Touch on Klipper. From adding the necessary sections for configuration, to maximizing your probing grid, this covers article covers end to end and everything in-between!
Nov 28, 2022
Creating the correct sections in the printer.cfg
In order to enable the bl touch(or similar auto bed leveler) you need to add sections to the printer configuration file. These will be incomplete at first, or more accurately they’ll be complete but incorrect, and through testing you will find the values for your printer.
First, edit the section ‘stepper_z’
[stepper_z]
…
endstop_pin: probe:z_virtual_endstop #this section needs to be edited exactly like this
#position_endstop: -0.5 this section needs to be commented out or deleted
Then, add the following sections:
[bltouch]
sensor_pin: ^PB1 #this is unique to your mainboard
control_pin: PB0 #this is unique to your mainboard
x_offset: -54 #this is unique to your mounting situation
y_offset: -25 #follow this short video to learn how to calculate this
samples: 2
speed: 2
z_offset: 0.0 #this will get calculated and commented out after calibration
[safe_z_home]
home_xy_position: 125,125 # Change coordinates to the center of your print bed
speed: 50
z_hop: 10 # Move up 10mm
z_hop_speed: 5
[bed_mesh]
speed: 80
horizontal_move_z: 7
mesh_min: 10, 10 #this will likely be a good starting pos
mesh_max: 178, 219 #this will need to be calculated
probe_count: 5,5 #number of x,y probing points
mesh_pps: 2,2 #number of points to interpret between each probing point
fade_start: 1 #height in millimeters to begin fading out the applied effect of the mesh
fade_end: 10 #height in millimeters to end the applied effect of the mesh. If you want to disable fade make this value lower than the value of fade_start
fade_target: 0
Perform Function Tests
Before moving onto the calibrations we need to perform some basic function tests to make sure the bl touch is operating as expected
Initial startup
Upen powering the printer the bl touch should probe twice and end in a retracted state. The internal light should remain lit
If the self test reports errors (i.e. the probe is flashing or the pin has not fully retracted) check the wiring for possible power/connectivity issues
Now you can begin to run some commands from the terminal line to check the physical operation is performing. First run the command:
BLTOUCH_DEBUG COMMAND=pin_down
This should cause the probe pin to extend from the housing and the internal light to shut off
If the self test reports errors (i.e. the probe is flashing or the pin has not fully extended) check the wiring for possible power/connectivity issues
Next the command:
BLTOUCH_DEBUG COMMAND=pin_up
This should cause the probe to retract and the internal light to once again illuminate
If the self test reports errors (i.e. the probe is flashing or the pin has not fully retracted) check the wiring for possible power/connectivity issues
With those tests finished you can now test if the sensor pin is working as expected. Run the command:
BLTOUCH_DEBUG COMMAND=pin_down
The pin should extend and the light shut off
Now the commands:
BLTOUCH_DEBUG COMMAND=touch_mode
QUERY_PROBE
The printer should respond ‘probe:open’ on the command line
The possible responses are either ‘probe:open’ or ‘probe:TRIGGERED’
probe:open - this should be the status while the probe pin is extended
probe:TRIGGERED - this should be the status after the probe has fully retracted
Now, using your finger, gently push the bottom of the probe tip upwards, so it retracts into the housing. Then run the command:
QUERY_PROBE
The printer should respond ‘probe:TRIGGERED’ on the command line
If the probe responded as expected perform an Auto home (G28)
Before this first auto home manually raise the x axis a large distance from the bed by manually spinning the z coupler
You may have to ‘disable motors’ in the stepper section of your front end to do this
While the printer is homing the Z axis, using your finger or something equally rigid, activate the probe pin by placing it underneath it while it descends.
Verify that the printer does in fact stop when the probe is activated
Be ready to ‘Emergency shut off’ the printer if the printer continues to home after the probe has been activated
If all the above tests returned positive results you can move onto the next section of calibration [X and Y bl touch offsets]. If not follow the steps below:
If your probe failed the function tests
QUERY_PROBE returned no results
It’s reported some bl touch clones do not support touch mode, meaning the above section would have no effect
However it’s possible that the probe can still work as intended. To check this perform an auto-home and after the printer extends the probe tip, and attempts to home the Z axis, gently stop it with your finger by pushing the probe tip upward.
If the probe retracts and acts in a normal fashion(i.e finishes homing and does not remain in a flashing state) then you should be alright, it’s just that your particular device does not support the ‘touch_mode’ testing procedure
DO NOT enable ‘probe_with_touch_mode’
“BL Touch failed to verify sensor state”
If this error is reported in the terminal and all of the test commands are returning correct answers then you may have to add the following section to [bltouch]
pin_up_touch_mode_reports_triggered: False
Be extremely cautious when enabling this feature as it could damage your printer. Make sure to monitor your printer while it is homing
“BL Touch failed to raise probe”
If this error is reported in the terminal and all of the test commands are returning ‘TRIGGERED’, it’s likely you have the wrong pin assigned to sensor pin under [bltouch] in the printer.cfg
If this error is reported in the terminal and all of the test commands are returning correct answers then you may have to add the following section to [bltouch]
pin_up_reports_not_triggered: False
Be extremely cautious when enabling this feature as it could damage your printer. Make sure to monitor your printer while it is homing
Probe takes a while to trigger/nozzle crashes into bed before probe can trigger but the probe does still trigger
the probe tip needs adequate space to be able to probe. Generally the distance in height from the tip of the probe to the tip of the nozzle should be within 2.3-4.3mm If there is not enough clearance the probe will not activate in time and the nozzle can crash into the bed
add spacers between the probe and the mount to create a larger gap between probe tip and nozzle tip
adding a pull-up in the printer.cfg
most sensor pins use a pull-up resistor and those need to be noted within the printer.cfg specifically under the [bltouch] section
notating a pull-up is done with the ‘^’ character, and it should precede the pin.
[bltouch]
…
sensor_pin: ^PB1 # the ^ at the beginning of the pin denotes the pullup. if your config does not have this then adding it may help
If you have a BL Touch V3.0 or V3.1
some of these devices may require the addition, within the [bl_touch] section, of the line:
probe_with_touch_mode: true
Measure the X and Y offsets
To find the offsets for the bl touch you will need a piece of paper that can stick to the print bed, and a pen or marker. I use a post-it note but painter’s tape works just as well. For this part of the tutorial I will assume you are using a post-it note
Draw a dot on the post it note and place the post it note on the bed with the dot under the probe tip
Do not add full pressure at this point, you still need to move the post-it a bit
I find it easiest if you make your mark on the writeable(matte) side of the post it note opposite the sticky side. So the portion of the post-it with the dot adheres the best, and remains flat, on the bed
Home your printer then line the dot up as best as you can directly under the probe tip of the bl touch. Once it is directly under the tip, stick the post-it to the bed with pressure
As you move the dot under the probe tip, you can use the ‘drop-pin’ and ‘raise-pin’ commands to touch the dot with the probe tip for the highest accuracy
BLTOUCH_DEBUG COMMAND=pin_down
BLTOUCH_DEBUG COMMAND=pin_up
This may send the bl touch into an error state and you will likely need to reset the probe after raising it. Issue the following command:
BLTOUCH_DEBUG COMMAND=reset
Once you’re satisfied with the placement of the post-it note, record the current X and Y coordinates of the nozzle. (i.e. x125, y125)
The x,y, and z coordinates can be found on the home screen of your front end under the ‘TOOL’ section.
If using Octoprint, it may be necessary to run the following command to get the axes location:
M114 // get_position
Now, using the onboard controls, move the nozzle so it is directly above the dot, just as the probe tip was.
Movement controls for the nozzle(hotend) can be found under the ‘TOOL’ section of your front end
To get increased accuracy it may be necessary to lower the nozzle to z=0 or similar
You will likely be making large movements at first (10mm increments), but as you get closer make sure to make smaller and more accurate movements (1mm or 0.1mm)
When you have the nozzle directly above the dot on the post-it note, record the current X and Y coordinates. (i.e. x70, y 120)
The x,y, and z coordinates can be found on the home screen of your front end under the ‘TOOL’ section.
If using Octoprint, it may be necessary to run the following command to get the axes location:
M114 // get_position
The following formula will return the current X and Y offsets for your bl touch. It’s ok if this gives you a negative number
Ending coordinates - starting coordinates = bl touch offsets
Ending (x, y) - Starting (x, y) = (x, y) bltouch offsets
Ending (70, 120) - Starting (125, 125) = (-45, -5)
Go to the configuration menu, open the printer.cfg, find the [bltouch] section, and amend the x and y offset sections with your results.
[bltouch]
…
x_offset: -45
y_offset: -5
Save and restart the firmware and the X and Y offsets are finished!
Adjusting the Z offset
This calibration is run using onboard Klipper commands. You will need a feeler gauge for this test to determine the space between the bed and the nozzle (preferably around the thickness of your initial layer height), I use a post-it note. This is a ‘dry’ z-offset calibration, a live calibration will be performed during an initial print to hone in the correct offset
Home the printer (G28) and start the probe calibration test by running the following command:
PROBE_CALIBRATE
This command will re-home the z-axis and then move the nozzle into position.
A menu will open that has all the necessary information for this calibration, and it’s what you will use to move the nozzle closer or further from the bed
Using the menu move the nozzle close to the bed. As the nozzle gets close to the bed, place your feeler gauge between the bed and the nozzle.
Negative movements(-) move the nozzle closer to the bed, and positive(+) movements move the nozzle further from the bed
The nozzle will likely begin far from the bed (<=10mm), and you will use large adjustments to bring the nozzle close to the bed (1mm)
As the nozzle gets close to the bed begin using smaller increments to adjust (0.1mm, 0.025mm)
Note: the nozzle will move up before it moves down when using any increment less than 1mm, this is a feature not a bug.
Continue to lower the nozzle while moving your feeler gauge between the bed and nozzle until you get adequate tension
Adequate tension is when you feel tension or pulling on the feeler gauge but are still able to move it.
If the feeler gauge becomes trapped it’s too close, you need to raise the nozzle.
don’t be afraid to raise the nozzle. You select when to save the offset, it doesn’t matter how you got there, only that the tension is correct when you save
When you have tension you feel is appropriate hit the Accept button
To save the z-offset you calibrated you need to use the Save_config comand
Hitting the ‘accept’ button is not enough to save this data
When you hit the accept button the command SAVE_CONFIG will appear in the terminal. Click on it to populate it in the terminal line, and then execute the command by hitting ‘enter’
You can also perform a ‘Save and Restart’ through a disc icon at the top of the page
When the firmware restarts navigate to the configuration page and open the printer.cfg to see if the calibration saved
In the section titled [bltouch] the line z_offset should be commented out
[bltouch]
…
#z-offset:
At the bottom of the page a new section titled ‘Save Config’ should have been created
Underneath this section there should be a value for z-offset.
The z-offset is a negative number but it will be shown as a positive number in the save_config portion
The final step is to perform a live z-offset adjustment (known as babystepping) during an initial print. It is covered further in this guide as it is the last step in the process.
Find the MOVABLE min and max
Finding the X and Y minimums and maximums is important for computing the probing bed mesh. This topic is probably what gives people the most issues, and it has to do with a ‘probe/nozzle position out of range’ error. Klipper determines the min and max probing points relative to the probe, not relative to the nozzle. Which means to create a probing grid it wants the location the probe is going to be while probing, not the location the nozzle is going to be. To get the probe locations we first need to find out what the minimum and maximum movable bounds are for the printhead. Why do we care about min/max movable bounds? Because the bl touch will rarely be directly in line with the nozzle. We use these minimum/maximum bounds to determine how far the printhead can move across the bed, and then use that area to maximize the probing range of the BL Touch.
In order to get accurate maximum bounds we must first make sure our printhead is correctly aligned over the origin point(minimum bounds). In our coordinate system the origin is (x=0, y=0). This location is determined by a feature in the (you guessed it) printer.cfg, and it is called ‘position_endstop’. Each stepper has this definition, and the ones we are interested in are [stepper_x] and [stepper_y]. The information position_endstop represents is the physical location of the endstop. What Klipper does not know is where the nozzle is in relation to that position, which we will calibrate below.
This step should be performed prior to finding the max bounds.
Enter the configuration tab of your front end and open printer.cfg
Find the section for [stepper_x] and modify the min_position and position_endstop.
Position_min becomes a negative number, I usually set mine to -10
Position_endstop becomes 0
It’s likely the definition for position_min is not within these sections and you will need to add them
[stepper_x]
…
position_endstop: 0
position_min: -10
Still in printer.cfg find [stepper_y] and amend it the same way
[stepper_y]
…
position_endstop: 0
position_min: -10
Save and restart the firmware
Auto home the printer
In the ‘TOOl’ section enter the coordinates 0, 0 for the X and Y coordinates of the toolhead. The printhead moves to location x=0 y=0.
This position is known as the origin, and at this location the nozzle should be over the corner of the bed closest to the endstop.
If the nozzle is not over the corner use the movement controls for the printhead and move it there
This should not be a far distance to move
Use the left and right arrows under the ‘TOOL’ section to move the nozzle over the correct location - the corner of the bed
Left and right arrows control the X axis while the front to back arrows command the Y axis.
It is important during this procedure that the nozzle ends over the bed and not outside its bounds.
If at any point the printhead is physically stopped by the frame of the printer take a note of the coordinates directly before that location. Those coordinates will become the origin, use that location data in the next section
i.e if the printhead hit a stop at x=-2 then the position before that, x=-1, becomes the minimum position
When the nozzle is over the corner of the bed, record the coordinates.
i.e the coordinates may now be (x-10, y5)
If the printhead was physically stopped, use the coordinates directly before that location.
At your front end, re-enter the Configuration tab and open printer.cfg
Find the section for [stepper_x] and [stepper_y], then add your results.
the position_endstop value becomes the inverse of the value you just recorded.
i.e. if your recorded value for x was -2 then under [stepper_x], the positionendstop would be the inverse of that number, it would be 2
i.e. if your recorded value for y was 6 then under [stepper_y], the positionendstop would be the inverse of that number, it would be -6.
If your position_endstop is a negative number then you must copy that same number under position_min
if your position_endstop is a positive number then you can delete position_min
If using the above coordinates as an example
[stepper_x]
…
position_endstop: 2
#position_min: 0 this can be deleted
[stepper_y]
…
position_endstop: -6
position_min: -6
Save and Restart the firmware for the changes to take effect.
this change will place the nozzle at the corner of the bed while at the origin (x0, y0)
*or as close as possible if the printhead is physically restricted otherwise
You now have the correctly set up the minimum bounds for your 3d printer!
Now to find the Maximum bounds
Enter the configuration tab of your front end and open printer.cfg
Find the section for [stepper_x] and modify the max position to 100 over the current value. (i.e. the current value is 225, so I make it 325)
[stepper_x]
…
position_max: 325
Still in printer.cfg find [stepper_y] and amend it the same way, adding 100 to the current value
[stepper_y]
…
position_max: 325
Save and restart the firmware
The first value you will find is the maximum bounds along the X axis.
Home the printer
Using the movement controls (found in the ‘TOOL’ section) move the printhead to its maximum position as determined by the printer.cfg before you amended it. (i.e. x=225 as in the above example)
This is a maximum position so the printhead coordinates should be increasing along the X axis (i.e 200,125 // 210,125 // 220,125 // etc)
i.e. the printhead should be moving away from the position endstop
It’s important to note this position does not care if the nozzle is above the bed, only that the printhead can physically move to these bounds. Maximum printing bounds are set within the slicer so now print movements leave the print bed
if your printhead hits a physical stop while moving to the pre-determined max bounds (i.e. 225), restart your firmware and begin at a smaller value (i.e. 220)
In general moving the printhead is done by selecting an increment on your front end(usually in millimeters) and clicking an arrow in the direction the printhead needs to travel.
At first you can use large increments (50mm, 25mm, 10mm) but as you get closer to the side rail you will need to use smaller increments (1mm)
The maximum_position will either be:
when the printhead is physically stopped by the side rails or
when the printhead begins to drift up or down because the gantry is rubbing on something close to the side rail
This is as much a visual calibration as it is a physical one. You need to watch the printhead as it gets close to its maximum location and move it in small increments (1mm).
Make sure the printhead does not start to move up or down. If the printhead begins to creep upwards, for instance because the v rollers are riding up something, then the position directly before that is your maximum_position, even if it can physically move further it does not matter.
If there is no drift, when the printhead ‘hits’ the maximum position you should be able to tell. There should be an audible ‘bang’ as the printhead contacts the side rail. When this happens the position directly before this becomes your maximum distance.
i.e. the x axis hit a physical stop at 248, so your max position is then 247, the position directly before that
The coordinate system is no longer accurate on that axis, the stepper motor will have missed a step and the positions will not be correct. So it’s important to make small movements and record the x axis position as you get close to (what you see) is the maximum
If using Octoprint, it may be necessary to run the following command to get the axes location:
M114 // get_position
You will now be determining the maximum bounds in the y axis. These instructions will be for a bed slinger style 3d printer, which is any printer where the movement of the bed front to back corresponds to the Y axis (i.e. Ender 3, Aquila X2). These instructions can also be applied to a core-XY style printer, like an Ender 5, just wherever the word ‘print bed’(or like) appears, substitute the word ‘printhead’.
**Spoiler alert, finding this value is basically identical to finding the X value so most of what you will read here is a repeat*
Home the machine
Using the movement controls (found in the ‘TOOL’ section) move the printbed to its maximum position as determined by the printer.cfg before you amended it. (i.e. y=225 as in the above example)
This is a maximum position so the print bed coordinates should be increasing along the Y axis (i.e 125, 200 // 125, 210 // 125, 220 // etc)
i.e. the print bed should be moving away from the position endstop
if your print bed hits a physical stop while moving to the pre-determined max bounds (i.e. 225), restart your firmware and begin at a smaller value (i.e. 220)
It’s important to note this position does not care if the nozzle is above the bed, only that the print bed can physically move to these bounds. Maximum printing bounds are set within the slicer, to prevent print movements from leaving the print bed
In general moving the print bed is done by selecting an increment (usually in millimeters) and clicking an arrow in the direction the print bed needs to travel.
At first you can use large increments (50mm, 25mm, 10mm) but as you get closer to the front frame you will need to use smaller increments (1mm)
The maximum_position will either be:
when the print bed is physically stopped by the rails/frame or
when the print bed begins to drift up or down because the gantry is rubbing on something
*This is less of an issue for when dealing with a print bed as the Y-axis
This is as much a visual calibration as it is a physical one. You need to watch the print bed as it gets close to its maximum location and move it in small increments (1mm).
Make sure the print bed does not start to move up or down. If the print bed begins to creep upwards, for instance because the v rollers are riding up something, then the position directly before that is your maximum_position, even if it can physically move further it does not matter.
If there is no drift, when the print bed ‘hits’ the maximum position you should be able to tell. There should be an audible ‘bang’ as the print bed contacts the front rail. When this happens the position directly before this becomes your maximum distance.
i.e. the y axis hit a physical stop at 240, so your max position is then 239, the position directly before that
The coordinate system is no longer accurate, the stepper motor will have missed a step and the positions will not be correct. So it’s important to make small movements and record the y axis position as you get close to (what you see) is the maximum
If using Octoprint, it may be necessary to run the following command to get the axes location:
M114 // get_position
At this point you will have found your maximum positions in both the X and axis, but you should perform one more check to be certain your values are correct.
Restart your firmware
this step is imperative. The stepper motors likely skipped and the readings will be inaccurate. In order to insure you have the correct values we need the stepper motors reading properly
Home the printer
Enter the maximum position you recorded for the X axis in the coordinate system
the print head should travel to that location without issue
Enter the maximum position you recorded for the Y axis in the coordinate system
the print bed should travel to that location without issue
If both of those coordinates worked without issue you have found your max bounds
If any of those coordinates caused the printhead/bed to bang into an axis you need to RESTART your firmware and perform the calibration for that axis again. Be sure to check it in the same manner afterwards.
After checking the max values are correct you need to input those values into printer.cfg and restart the firmware
Enter the configuration tab of your front end and open printer.cfg
find and amend the stepper sections with the max calculations you found in the previous step
[stepper_x]
…
position_max: 247 # this is where you enter your measured value for the x axis
[stepper_y]
…
position_max: 239 # this is where you enter your measured value for the y axis
Save and Restart your firmware