Connecting BL-Touch¶
A warning before you start: Avoid touching the BL-Touch pin withyour bare fingers, since it is quite sensitive to finger grease. Andif you do touch it, be very gentle, in order to not bend or pushanything.
Hook up the BL-Touch "servo" connector to a control_pin according tothe BL-Touch documentation or your MCU documentation. Using theoriginal wiring, the yellow wire from the triple is the control_pinand the white wire from the pair is the sensor_pin. You need toconfigure these pins according to your wiring. Most BL-Touch devicesrequire a pullup on the sensor pin (prefix the pin name with "^"). Forexample:
[bltouch]sensor_pin: ^P1.24control_pin: P1.26If the BL-Touch will be used to home the Z axis then set endstop_pin:probe:z_virtual_endstop and remove position_endstop in the [stepper_z] config section,then add a [safe_z_home] config section to raise the z axis, home the xy axes,move to the center of the bed, and home the z axis. For example:
[safe_z_home]home_xy_position: 100, 100 # Change coordinates to the center of your print bedspeed: 50z_hop: 10 # Move up 10mmz_hop_speed: 5It's important that the z_hop movement in safe_z_home is high enoughthat the probe doesn't hit anything even if the probe pin happens tobe in its lowest state.
Initial tests¶
Before moving on, verify that the BL-Touch is mounted at the correctheight, the pin should be roughly 2 mm above the nozzle when retracted
When you turn on the printer, the BL-Touch probe should perform aself-test and move the pin up and down a couple of times. Once theself-test is completed, the pin should be retracted and the red LED onthe probe should be lit. If there are any errors, for example theprobe is flashing red or the pin is down instead of up, please turnoff the printer and check the wiring and configuration.
If the above is looking good, it's time to test that the control pinis working correctly. First run BLTOUCH_DEBUG COMMAND=pin_down inyour printer terminal. Verify that the pin moves down and that the redLED on the probe turns off. If not, check your wiring andconfiguration again. Next issue a BLTOUCH_DEBUG COMMAND=pin_up,verify that the pin moves up, and that the red light turns onagain. If it's flashing then there's some problem.
The next step is to confirm that the sensor pin is working correctly.Run BLTOUCH_DEBUG COMMAND=pin_down, verify that the pin moves down,run BLTOUCH_DEBUG COMMAND=touch_mode, run QUERY_PROBE, and verifythat command reports "probe: open". Then while gently pushing the pinup slightly with the nail of your finger run QUERY_PROBE again.Verify the command reports "probe: TRIGGERED". If either query doesnot report the correct message then it usually indicates an incorrectwiring or configuration (though some clones mayrequire special handling). At the completion of this test runBLTOUCH_DEBUG COMMAND=pin_up and verify that the pin moves up.
After completing the BL-Touch control pin and sensor pin tests, it isnow time to test probing, but with a twist. Instead of letting theprobe pin touch the print bed, let it touch the nail on your finger.Position the toolhead far from the bed, issue a G28 (or PROBE ifnot using probe:z_virtual_endstop), wait until the toolhead starts tomove down, and stop the movement by very gently touching the pin withyour nail. You may have to do it twice, since the default homingconfiguration probes twice. Be prepared to turn off the printer if itdoesn't stop when you touch the pin.
If that was successful, do another G28 (or PROBE) but this timelet it touch the bed as it should.
BL-Touch gone bad¶
Once the BL-Touch is in inconsistent state, it starts blinking red.You can force it to leave that state by issuing:
BLTOUCH_DEBUG COMMAND=reset
This may happen if its calibration is interrupted by the probe beingblocked from being extracted.
However, the BL-Touch may also not be able to calibrate itselfanymore. This happens if the screw on its top is in the wrong positionor the magnetic core inside the probe pin has moved. If it has movedup so that it sticks to the screw, it may not be able to lower its pinanymore. With this behavior you need to open the screw and use aball-point pen to push it gently back into place. Re-Insert the pininto the BL-Touch so that it falls into the extracted position.Carefully readjust the headless screw into place. You need to find theright position so it is able to lower and raise the pin and the redlight turns on and of. Use the reset, pin_up and pin_downcommands to achieve this.
BL-Touch "clones"¶
Many BL-Touch "clone" devices work correctly with Klipper using thedefault configuration. However, some "clone" devices may not supportthe QUERY_PROBE command and some "clone" devices may requireconfiguration of pin_up_reports_not_triggered orpin_up_touch_mode_reports_triggered.
Important! Do not configure pin_up_reports_not_triggered orpin_up_touch_mode_reports_triggered to False without first followingthese directions. Do not configure either of these to False on agenuine BL-Touch. Incorrectly setting these to False can increaseprobing time and can increase the risk of damaging the printer.
Some "clone" devices do not support touch_mode and as a result theQUERY_PROBE command does not work. Despite this, it may still bepossible to perform probing and homing with these devices. On thesedevices the QUERY_PROBE command during theinitial tests will not succeed, however thesubsequent G28 (or PROBE) test does succeed. It may be possible touse these "clone" devices with Klipper if one does not utilize theQUERY_PROBE command and one does not enable theprobe_with_touch_mode feature.
Some "clone" devices are unable to perform Klipper's internal sensorverification test. On these devices, attempts to home or probe canresult in Klipper reporting a "BLTouch failed to verify sensor state"error. If this occurs, then manually run the steps to confirm thesensor pin is working as described in theinitial tests section. If the QUERY_PROBE commandsin that test always produce the expected results and "BLTouch failedto verify sensor state" errors still occur, then it may be necessaryto set pin_up_touch_mode_reports_triggered to False in the Klipperconfig file.
A rare number of old "clone" devices are unable to report when theyhave successfully raised their probe. On these devices Klipper willreport a "BLTouch failed to raise probe" error after every home orprobe attempt. One can test for these devices - move the head far fromthe bed, run BLTOUCH_DEBUG COMMAND=pin_down, verify the pin hasmoved down, run QUERY_PROBE, verify that command reports "probe:open", run BLTOUCH_DEBUG COMMAND=pin_up, verify the pin has movedup, and run QUERY_PROBE. If the pin remains up, the device does notenter an error state, and the first query reports "probe: open" whilethe second query reports "probe: TRIGGERED" then it indicates thatpin_up_reports_not_triggered should be set to False in the Klipperconfig file.
BL-Touch v3¶
Some BL-Touch v3.0 and BL-Touch 3.1 devices may require configuringprobe_with_touch_mode in the printer config file.
If the BL-Touch v3.0 has its signal wire connected to an endstop pin(with a noise filtering capacitor), then the BL-Touch v3.0 may not beable to consistently send a signal during homing and probing. If theQUERY_PROBE commands in the initial tests sectionalways produce the expected results, but the toolhead does not alwaysstop during G28/PROBE commands, then it is indicative of this issue. Aworkaround is to set probe_with_touch_mode: True in the config file.
The BL-Touch v3.1 may incorrectly enter an error state after asuccessful probe attempt. The symptoms are an occasional flashinglight on the BL-Touch v3.1 that lasts for a couple of seconds after itsuccessfully contacts the bed. Klipper should clear this errorautomatically and it is generally harmless. However, one may setprobe_with_touch_mode in the config file to avoid this issue.
Important! Some "clone" devices and the BL-Touch v2.0 (and earlier)may have reduced accuracy when probe_with_touch_mode is set to True.Setting this to True also increases the time it takes to deploy theprobe. If configuring this value on a "clone" or older BL-Touchdevice, be sure to test the probe accuracy before and after settingthis value (use the PROBE_ACCURACY command to test).
Multi-probing without stowing¶
By default, Klipper will deploy the probe at the start of each probeattempt and then stow the probe afterwards. This repetitive deployingand stowing of the probe may increase the total time of calibrationsequences that involve many probe measurements. Klipper supportsleaving the probe deployed between consecutive probes, which canreduce the total time of probing. This mode is enabled by configuringstow_on_each_sample to False in the config file.
Important! Setting stow_on_each_sample to False can lead to Klippermaking horizontal toolhead movements while the probe is deployed. Besure to verify all probing operations have sufficient Z clearanceprior to setting this value to False. If there is insufficientclearance then a horizontal move may cause the pin to catch on anobstruction and result in damage to the printer.
Important! It is recommended to use probe_with_touch_mode configuredto True when using stow_on_each_sample configured to False. Some"clone" devices may not detect a subsequent bed contact ifprobe_with_touch_mode is not set. On all devices, using thecombination of these two settings simplifies the device signaling,which can improve overall stability.
Note, however, that some "clone" devices and the BL-Touch v2.0 (andearlier) may have reduced accuracy when probe_with_touch_mode is setto True. On these devices it is a good idea to test the probe accuracybefore and after setting probe_with_touch_mode (use thePROBE_ACCURACY command to test).
Calibrating the BL-Touch offsets¶
Follow the directions in the Probe Calibrateguide to set the x_offset, y_offset, and z_offset config parameters.
It's a good idea to verify that the Z offset is close to 1mm. If not,then you probably want to move the probe up or down to fix this. Youwant it to trigger well before the nozzle hits the bed, so thatpossible stuck filament or a warped bed doesn't affect any probingaction. But at the same time, you want the retracted position to be asfar above the nozzle as possible to avoid it touching printed parts.If an adjustment is made to the probe position, then rerun the probecalibration steps.
BL-Touch output mode¶
A BL-Touch V3.0 supports setting a 5V or OPEN-DRAIN output mode, a BL-Touch V3.1 supports this too, but can also store this in its internal EEPROM. If your controller board needs the fixed 5V high logic level of the 5V mode you may set the 'set_output_mode' parameter in the [bltouch] section of the printer config file to "5V".
Only use the 5V mode if your controller boards input line is5V tolerant. This is why the default configuration of these BL-Touchversions is OPEN-DRAIN mode. You could potentially damage yourcontroller boards CPU
So therefore:If a controller board NEEDs 5V mode AND it is 5V tolerant on itsinput signal line AND if
- you have a BL-Touch Smart V3.0, you need the use 'set_output_mode: 5V' parameter to ensure this setting at each startup, since the probe cannot remember the needed setting.
- you have a BL-Touch Smart V3.1, you have the choice of using 'set_output_mode: 5V' or storing the mode once by use of a 'BLTOUCH_STORE MODE=5V' command manually and NOT using the parameter 'set_output_mode:'.
- you have some other probe: Some probes have a trace on the circuit board to cut or a jumper to set in order to (permanently) set the output mode. In that case, omit the 'set_output_mode' parameter completely.
If you have a V3.1, do not automate or repeat storing the output mode toavoid wearing out the EEPROM of the probe.The BLTouch EEPROM is good forabout 100.000 updates. 100 stores per day would add up to about 3 yearsof operation prior to wearing it out. Thus, storing the output mode in aV3.1 is designed by the vendor to be a complicated operation (the factorydefault being a safe OPEN DRAIN mode) and is not suited to be repeatedlyissued by any slicer, macro or anything else, it is preferably only to beused when first integrating the probe into a printers electronics.
