This document describes the method for calibrating the X, Y, and Zoffsets of an "automatic z probe" in Klipper. This is useful for usersthat have a [probe] or [bltouch] section in their config file.
Calibrating probe X and Y offsets¶
To calibrate the X and Y offset, navigate to the OctoPrint "Control"tab, home the printer, and then use the OctoPrint jogging buttons tomove the head to a position near the center of the bed.
Place a piece of blue painters tape (or similar) on the bed underneaththe probe. Navigate to the OctoPrint "Terminal" tab and issue a PROBEcommand:
PROBEPlace a mark on the tape directly under where the probe is (or use asimilar method to note the location on the bed).
Issue a GET_POSITION command and record the toolhead XY locationreported by that command. For example if one sees:
Recv: // toolhead: X:46.500000 Y:27.000000 Z:15.000000 E:0.000000then one would record a probe X position of 46.5 and probe Y positionof 27.
After recording the probe position, issue a series of G1 commandsuntil the nozzle is directly above the mark on the bed. For example,one might issue:
G1 F300 X57 Y30 Z15to move the nozzle to an X position of 57 and Y of 30. Once one findsthe position directly above the mark, use the GET_POSITION commandto report that position. This is the nozzle position.
The x_offset is then the nozzle_x_position - probe_x_position andy_offset is similarly the nozzle_y_position - probe_y_position.Update the printer.cfg file with the given values, remove thetape/marks from the bed, and then issue a RESTART command so thatthe new values take effect.
Calibrating probe Z offset¶
Providing an accurate probe z_offset is critical to obtaining highquality prints. The z_offset is the distance between the nozzle andbed when the probe triggers. The Klipper PROBE_CALIBRATE tool can beused to obtain this value - it will run an automatic probe to measurethe probe's Z trigger position and then start a manual probe to obtainthe nozzle Z height. The probe z_offset will then be calculated fromthese measurements.
Start by homing the printer and then move the head to a position nearthe center of the bed. Navigate to the OctoPrint terminal tab and runthe PROBE_CALIBRATE command to start the tool.
This tool will perform an automatic probe, then lift the head, movethe nozzle over the location of the probe point, and start the manualprobe tool. If the nozzle does not move to a position above theautomatic probe point, then ABORT the manual probe tool and performthe XY probe offset calibration described above.
Once the manual probe tool starts, follow the steps described at"the paper test" to determine theactual distance between the nozzle and bed at the given location. Oncethose steps are complete one can ACCEPT the position and save theresults to the config file with:
SAVE_CONFIGNote that if a change is made to the printer's motion system, hotendposition, or probe location then it will invalidate the results ofPROBE_CALIBRATE.
If the probe has an X or Y offset and the bed tilt is changed (eg, byadjusting bed screws, running DELTA_CALIBRATE, running Z_TILT_ADJUST,running QUAD_GANTRY_LEVEL, or similar) then it will invalidate theresults of PROBE_CALIBRATE. After making any of the above adjustmentsit will be necessary to run PROBE_CALIBRATE again.
If the results of PROBE_CALIBRATE are invalidated, then any previousbed mesh results that were obtained using the probe arealso invalidated - it will be necessary to rerun BED_MESH_CALIBRATEafter recalibrating the probe.
Repeatability check¶
After calibrating the probe X, Y, and Z offsets it is a good idea toverify that the probe provides repeatable results. Start by homing theprinter and then move the head to a position near the center of thebed. Navigate to the OctoPrint terminal tab and run thePROBE_ACCURACY command.
This command will run the probe ten times and produce output similarto the following:
Recv: // probe accuracy: at X:0.000 Y:0.000 Z:10.000Recv: // and read 10 times with speed of 5 mm/sRecv: // probe at -0.003,0.005 is z=2.506948Recv: // probe at -0.003,0.005 is z=2.519448Recv: // probe at -0.003,0.005 is z=2.519448Recv: // probe at -0.003,0.005 is z=2.506948Recv: // probe at -0.003,0.005 is z=2.519448Recv: // probe at -0.003,0.005 is z=2.519448Recv: // probe at -0.003,0.005 is z=2.506948Recv: // probe at -0.003,0.005 is z=2.506948Recv: // probe at -0.003,0.005 is z=2.519448Recv: // probe at -0.003,0.005 is z=2.506948Recv: // probe accuracy results: maximum 2.519448, minimum 2.506948, range 0.012500, average 2.513198, median 2.513198, standard deviation 0.006250Ideally the tool will report an identical maximum and minimum value.(That is, ideally the probe obtains an identical result on all tenprobes.) However, it's normal for the minimum and maximum values todiffer by one Z "step distance" or up to 5 microns (.005mm). A "stepdistance" isrotation_distance/(full_steps_per_rotation*microsteps). The distancebetween the minimum and the maximum value is called the range. So, inthe above example, since the printer uses a Z step distance of .0125,a range of 0.012500 would be considered normal.
If the results of the test show a range value that is greater than 25microns (.025mm) then the probe does not have sufficient accuracy fortypical bed leveling procedures. It may be possible to tune the probespeed and/or probe start height to improve the repeatability of theprobe. The PROBE_ACCURACY command allows one to run tests withdifferent parameters to see their impact - see theG-Codes document for further details. Ifthe probe generally obtains repeatable results but has an occasionaloutlier, then it may be possible to account for that by using multiplesamples on each probe - read the description of the probe samplesconfig parameters in the config referencefor more details.
If new probe speed, samples count, or other settings are needed, thenupdate the printer.cfg file and issue a RESTART command. If so, itis a good idea tocalibrate the z_offset again. Ifrepeatable results can not be obtained then don't use the probe forbed leveling. Klipper has several manual probing tools that can beused instead - see the Bed Level document for furtherdetails.
Location Bias Check¶
Some probes can have a systemic bias that corrupts the results of theprobe at certain toolhead locations. For example, if the probe mounttilts slightly when moving along the Y axis then it could result inthe probe reporting biased results at different Y positions.
This is a common issue with probes on delta printers, however it canoccur on all printers.
One can check for a location bias by using the PROBE_CALIBRATEcommand to measuring the probe z_offset at various X and Y locations.Ideally, the probe z_offset would be a constant value at every printerlocation.
For delta printers, try measuring the z_offset at a position near theA tower, at a position near the B tower, and at a position near the Ctower. For cartesian, corexy, and similar printers, try measuring thez_offset at positions near the four corners of the bed.
Before starting this test, first calibrate the probe X, Y, and Zoffsets as described at the beginning of this document. Then home theprinter and navigate to the first XY position. Follow the steps atcalibrating probe Z offset to run thePROBE_CALIBRATE command, TESTZ commands, and ACCEPT command, butdo not run SAVE_CONFIG. Note the reported z_offset found. Thennavigate to the other XY positions, repeat these PROBE_CALIBRATEsteps, and note the reported z_offset.
If the difference between the minimum reported z_offset and themaximum reported z_offset is greater than 25 microns (.025mm) then theprobe is not suitable for typical bed leveling procedures. See theBed Level document for manual probe alternatives.
Temperature Bias¶
Many probes have a systemic bias when probing at differenttemperatures. For example, the probe may consistently trigger at alower height when the probe is at a higher temperature.
It is recommended to run the bed leveling tools at a consistenttemperature to account for this bias. For example, either always runthe tools when the printer is at room temperature, or always run thetools after the printer has obtained a consistent print temperature.In either case, it is a good idea to wait several minutes after thedesired temperature is reached, so that the printer apparatus isconsistently at the desired temperature.
To check for a temperature bias, start with the printer at roomtemperature and then home the printer, move the head to a positionnear the center of the bed, and run the PROBE_ACCURACY command. Notethe results. Then, without homing or disabling the stepper motors,heat the printer nozzle and bed to printing temperature, and run thePROBE_ACCURACY command again. Ideally, the command will reportidentical results. As above, if the probe does have a temperature biasthen be careful to always use the probe at a consistent temperature.
