Probing with Smoothie

A probe is a switch ( much like an Endstop ) used to find where something is located automatically.

Smoothie will use it to move until the probe is “triggered” and stop there.

It can be used on CNC mills to :

  • Find the length of a tool and how far it's bottom is from the 0 position in Z
  • Find the touching point between the workpiece and the tool

It can be used on 3D printers to :

  • Find the touching point between the actuator and the bed
  • Calibrate Delta geometry
  • Do grid-based bed leveling to compensate for bed height irregularities

Different strategies are useful for different geometries of machines, click on one to go to it :

NOTE When G30 stores the probe position or prints out the value, it is in actuator units not necessarily in mm. This is only an issue for rotary deltas where the actuator units are degrees not mm. Most other configurations it will be mm.



A servo-controlled retractable probe


Making the probe retractable allows the probe not to be in the way of the plastic when it is not used.

toc

Hardware requirements

You will need a probe switch attached to the machine's actuator, or a bed able to trigger an end stop input when the hotend touches it. A point detection is best as the actual position is important for probing. (proximity probes are suboptimal as they do not detect the point position).

Homing

A probe is not an endstop and therefore cannot be used to Home the Z axis. You need a Z endstop to use G28 to home the Z axis. Below are some instructions on how you can set the bed Z height using a probe (G30). NOTE that gamma_max in the endstop configuration IS used to set the maximum default travel for a probe command (G30) ONLY IF zprobe.max_z is not defined.

A bit more : You have two choices : 

  • Configure your probe as an endstop ( in the endstop module ), in which case you can use G28 to use it to seek the bed, but you can't use it in the zprobe module
  • Configure your probe as a probe ( in the probe module ), in which case you can't use it with G28 ( the endstop module ) to seek the bed, but you can use it with G30 to seek the bed, and you can use it with G31/G32 etc to level/calibrate ( this is likely what you want to do ).

The point is you configure your sensor as *either* a probe or an endstop, not both. You can still use it for both levelling/calibration *and* bed seeking, it's just that if it's a probe ( and not an endstop ), you use a different Gcode ( G30 ) than if it were an endstop ( G28 ).

Types of probes

Here is a table of the common sensor types, with their pro, cons, and our advice

Type Uses Pros Cons Our rating Advice
Mechanical switch Endstops, retractable Z-probes Cheap, very durable, very precise/repeatable None This is the simplest, and also by chance the best sensor. Don't use anything else unless you have a very good reason to. Just getting a fancier sensor because it feels cool to do so, is most likely going to bite you in the back quickly
Optical switch Endstops, retractable Z-probes Cheap, durable, very precise/repeatable Dust can block light path after some time This can be used in place of mechanical switches in most situations, has similar advantages, and doesn't produce any sound.
Hall effect Endstops, bed probe Fairly cheap, non-contact, variable precision/repeatability Requires magnets, which accumulates ambient metal dust, can lack repeatability A fair non-contact option if contact is an issue in your setup
Inductive Endstops, bed probe Non-contact Expensive, difficult to wire, substandard repeatability, 24-36V requirement, endstop input protection ( voltage divider ) required You probably shouldn't use these unless you have a very good reason
Capacitive Endstops, bed probe Non-contact, can be used with glass bed Expensive, difficult to wire, substandard repeatability, 24-36V requirement, endstop input protection ( voltage divider ) required You probably shouldn't use these unless you have a very good reason
Force sensitive resistor ( FSR ) Bed probe Can be used under a glass bed, non-contact, can be very reliable if set up correctly Difficult to set up correctly, finicky, expensive, analog meaning it requires an adapter, more complex to wire You probably shouldn't use these unless you have a very good reason
IR probes Z probe, bed probe Non-contact Expensive, analog meaning it requires an adapter, terrible repeatability/accuracy, more complex to wire You probably shouldn't use these unless you have a very good reason
Bltouch Retractable Z-probes Cheap, very durable, very precise/repeatable, retractable ( equivalent to a servo-mounted mechanical switch ) None, other than the added complexity of retracting The mechanical switches are the best sensors by far, but this is very similar, essentially emulating a servo-mounted mechanical switch

The Reprap probe page also has information on this that you might find helpful.

2022/07/17 17:35

Configuration

Add the following to the config file : 

gamma_min_endstop            nc                 # normally 1.28. Change to nc to prevent conflict, not needed on Azteeg X5

zprobe.enable                true               # set to true to enable a zprobe
zprobe.probe_pin             1.28!^             # pin probe is attached to if NC remove the !, Azteeg X5 this is 1.29
zprobe.slow_feedrate         5                  # mm/sec probe feed rate
#zprobe.debounce_ms          1                  # set if noisy
zprobe.fast_feedrate         100                # move feedrate
zprobe.probe_height          5                  # how much above bed to start probe NB only needed for G32 on delta
zprobe.return_feedrate       0                  # feedrate after a probe, default 0 is double of slow_feedrate (mm/s)
zprobe.max_z                 200                # maximum default travel for the probe command, will use gamma_max if not defined

Note

The Slow_feedrate is the speed the probe moves down to find the bed, it returns (probe up) at 2 * Slow_feedrate or Return_feedrate. Fast_feedrate is only used for any XY moves done during probing.

First test the zprobe with M119, make sure that the probe is 1 when triggered and 0 when not triggered.

G30 will probe from the current position until it hits the bed and the probe triggers, it will report the distance traveled then return to where it started.

G30 Znnn will probe until it hits the bed then sets Z to nnn (by doing G92 Znnn), this can be used to set the nozzle height if nnn is the probes Z offset from the nozzle in the Z direction.

G30 Fxxx will run the probe at xxx mm/min overriding the slow_feedrate.

G38.2, G38.3, G38.4, G38.5 ( for probing in X and Y ) are also implemented as documented here NOTE probing in X or Y on a delta is not recommended due to non linear movement issues.

If there are multiple levelling strategies selected the Pn parameter will select which one to send leveling codes to, 0 being the first defined one, 1 the second and so on. eg G29 P1 will send G29 to the second defined levelling strategy.

There are several M670 parameters that can set different settings for zprobe overriding the config settings, these are all saved with M500

M670 S0.50 K2.00 R2.5 Set Probe feedrates slow/fast/return (mm/sec)
M670 Z200.00 Set Probe max_z (mm)
M670 H2.00 Set Probe height (mm)
M670 I1 Temporarily invert the sense of the probe pin (Not saved with M500)

Leveling strategies

If a leveling-strategy.xxx.enable is set to True this enables one of the bed leveling strategies described below.

NOTE that most leveling strategies cannot be run from a web interface, if using network use telnet to run them, or use the USB serial port.

Configuration options

Option Example value Explanation
zprobe.enable true Set to true to enable the Z-probe module. This is used to scan surfaces, and to calibrate parameters and compensate for non-planar surfaces.
zprobe.probe_pin 1.28!^ Pin the probe is connected to.
zprobe.slow_feedrate 5 Speed in millimetres/second at which the probe seeks a surface.
zprobe.fast_feedrate 100 Speed in millimetres/second at which the probe does fast moves.
zprobe.return_feedrate 50 Speed in millimetres/second at which the probe does the return after a probe.
zprobe.debounce_ms 1 Debounce the probe pin over this number of millisceconds. Set to 1 or 2 if your probe is too noisy and gives false readings.
zprobe.probe_height 5 Distance above the bed at which the probing is started, once the bed's height is known.
zprobe.max_z 200 Maximum Z (was gamma_max)
zprobe.dwell_before_probing 0.2 Dwell time in seconds before probing
2022/07/17 17:35

Probing for linear delta machines

Delta calibration

Note

This calibrates the endstops and delta radius only, it is designed to be run once and done, no need to run it before each print. Just run it and save the results. It does not set the Z height, that can be done in several different ways as described later.

Make sure the config has Delta_homing true set and that Zprobe.max_z is set to about 20-30mm shorter than the distance to the bed, otherwise it will crash into the bed at high speed.

Also in the config set : 

leveling-strategy.delta-calibration.enable   true            # basic delta calibration
leveling-strategy.delta-calibration.radius   100             # the probe radius
leveling-strategy.delta-calibration.initial_height 10        # height above bed to stop initial move
#the initial height above the bed we stop the initial move down after home to find the bed
#this should be a height that is enough that the probe will not hit the bed and is an offset from zprobe.max_z (can be set to 0 if zprobe.max_z takes into account the probe offset)

Radius

Note that leveling-strategy.delta-calibration.radius should optimally be set such that the probe points are on the circumference of a circle that is equidistant from the center of the bed to the towers.

This minimizes the effect one endstop has on the others when adjusted.

This will usually put the probe points close to the edge of the glass bed.

Calibration routine

Issuing the G32 command will run the full calibration sequence automatically.

It will cycle several times to converge on a good result.

If the result is good use M500 to save the M666 settings.

What will happen is it will home the probe down to find the bed, then home again then move down to 5mm above the bed (or whatever you set Zprobe.probe_height to).

Then it will probe the three towers at the specified leveling-strategy.delta-calibration.radius from the center, and will print out the results, it will set the endstop trims and home, this will repeat 3-4 times, each time the difference between the three probes should get smaller, once it has completed 4 probes or the difference is under 0.03mm it will home one last time then probe the three points to confirm the calibration, then probe the center.

It will also adjust the delta radius (M665 Rnnn) to get the center the same height as the outside points.

Configuration options

Option Example value Explanation
leveling-strategy.delta-calibration.enable true Set to true to enable the delta calibration levelling strategy. This uses the probe to figure out the plane's tilt and arm's radius in a delta machine
leveling-strategy.delta-calibration.radius 100 Radius at which to probe the three points
leveling-strategy.delta-calibration.initial_height 10 the initial height above the bed we stop the initial move down after home to find the bed. This should be a height that is enough that the probe will not hit the bed and is the absolute Z position
2022/07/17 17:35

Example configuration

To activate this leveling strategy, copy/paste the following to your configuration file and edit it accordingly : 

leveling-strategy.delta-calibration.enable                true      # Set to true to enable the delta calibration levelling strategy. 
                                                                    # This uses the probe to figure out the plane's tilt and arm's radius 
                                                                    # in a delta machine
leveling-strategy.delta-calibration.radius                100       # Radius at which to probe the three points
leveling-strategy.delta-calibration.initial_height        10        # The initial height above the bed we stop the initial move down after home 
                                                                    # to find the bed. This should be a height that is enough that the probe
                                                                    # will not hit the bed

Uses

These are the different ways to use the calibration routine :

G29 will probe the seven points on your bed, you can use this to see how well the bed is leveled.
G29.1 will probe the seven points on your bed,and output the data that can be fed into some offline least errors scripts to adjust tower offsets
G32 Does the full calibration sequence, endstop and delta radius
G32 R0 Will only do delta radius calibration
G32 E0 Will only do endstop calibration
G32 I0.02 Will set the target to within 0.02mm
G32 K0 Will keep the current endstop trim settings and check them, without K the trims are cleared to zero and a full calibration is performed
G32 J110.0 will set the probe radius to 110.0 mm for this session
M500 saves the probe points
M503 displays the current settings

Example use : 

    G28 (Home XYZ)
    (Move Z at least 30mm away from the bed if it's not, and attach probe if you have a removable probe)
    G32 ( Calibrate the machine )
    (Remove probe if you have a removable probe)
    M500 (to save probe results)
    G28 (Home XYZ)
    (Manually: jog down to touch the plate)
    M306 Z0
    M500 (to save homing offset)
    G28
    (Machine is now calibrated and knows it's correct height above the bed)

Z height

You will need to set the z height after calibration using one of the several methods available mentioned here Delta

Offsets

There are NO probe offsets for delta calibration, so the probe should be within 10-20mm of the nozzle. This is by design as the calibration works solely on relative positions.

To be clear : there are no offsets in Smoothie, and they would not be useful as calibration is relative. This can be confusing to Marlin users. Just use it and you'll see.

If you are getting the Calibration failed to complete error, or the probe crashes into the bed on the initial probe, it usually means you need to increase the leveling-strategy.delta-calibration.initial_height config setting to a bigger value, try 10 or 20 or bigger. With the recent version it should move fast to just above the bed then move to the bed slowly, if it hits the bed on the first fast move then you need to set initial-height bigger.

See http://minow.blogspot.com/ for more details of calibrating a delta.

A probing height map


Nothing is perfect

Delta Grid Compensation

Probes delta_grid.size points in X and Y (total probes size * size) and stores the relative offsets from the 0,0 Z height. When enabled every move will calculate the Z offset based on interpolating the height offset within the grids nearest 4 points.

Should be used in conjunction with the delta calibration strategy above.

First calibrate with G32 then if needed do G31 to set the grid compensation. If you want to save the grid, do M374.

Note

For use on linear delta machines only, do not use for a cartesian machine.

The delta-grid.radius specified should be at least as big as the largest X,Y position likely to be moved to. It gets very inaccurate if you try to print outside of the radius you specified.

Note

G31 is the probe command on this not G32.

Configuration

The strategy must be enabled in the config as well as zprobe. 

leveling-strategy.delta-grid.enable         true

The radius of the bed must be specified with… 

leveling-strategy.delta-grid.radius        50

This needs to be at least as big as the maximum printing radius as moves outside of this will not be compensated for correctly

The size of the grid can be set with… 

leveling-strategy.delta-grid.size        7

This is the X and Y size of the grid, it must be an odd number, the default is 7 which is 49 probe points 

leveling-strategy.delta-grid.do_home         true

This must be set on a Delta printer (although it should default to true).

If you are not using all 3 endstops (or prefer to home manually before G32): 

leveling-strategy.delta-grid.do_home        false

Note

You are responsible to make sure that (0,0) is in a repeatable location if Do_home is set to False.

Optionally probe offsets from the nozzle or tool head can be defined with… 

leveling-strategy.delta-grid.probe_offsets  0,0,0  # probe offsets x,y,z  (Z should always be 0)

They may also be set with M565 X0 Y0 Z0.

Note

Setting probe offsets on a delta will make the grid less effective the further the probe is from the head, this is especially true if you are using it to correct geometry errors, as they depend on the actuator position not the head position. So having a probe offset from the head will try to compensate for errors which are offset from where the head actually is. There is no easy way to overcome this other than have the probe as close to the nozzle as possible.

If the saved grid is to be loaded on boot then this must be set in the config… 

leveling-strategy.delta-grid.save        true

Then when M500 is issued it will save M375 which will cause the grid to be loaded on boot. The default is to not autoload the grid on boot.

Note

The grid size and the radius is saved in the file, and restored when it is loaded with M375. If the grid size is different from the one in config it will NOT load. If the radius is different, then the radius will be set to whatever was saved overriding the one set in config.

DO NOT call M375 from a gcode file as that will cause the system to run out of memory and crash.

Optionally an initial_height can be set that tell the initial probe where to stop the fast decent before it probes, this should be around 5-10mm above the bed 

leveling-strategy.delta-grid.initial_height  10

Configuration options

Option Example value Explanation
leveling-strategy.delta-grid.enable true The strategy must be enabled in the config, as well as the zprobe module.
leveling-strategy.delta-grid.size 7 The size of the grid, for example, 7 causes a 7×7 grid with 49 points. Must be an odd number.
leveling-strategy.delta-grid.probe_offsets 0,0,0 Optional probe offsets from the nozzle or tool head NOTE Z must be 0
leveling-strategy.delta-grid.save false If the saved grid is to be loaded on boot then this must be set to true
leveling-strategy.delta-grid.initial_height 10 Optionally an initial_height can be set that tell the initial probe where to stop the fast decent before it probes, this should be around 5-10mm above the bed
2022/07/17 17:35

Example configuration

To activate this leveling strategy, copy/paste the following to your configuration file and edit it accordingly : 

leveling-strategy.delta-grid.enable               true     # The strategy must be enabled in the config, as well as the zprobe module.
leveling-strategy.delta-grid.radius               50       # Radius of the bed, must be specified. This needs to be at least as big as 
                                                           # the maximum printing radius as moves outside of this will not 
                                                           # be compensated for correctly
leveling-strategy.delta-grid.size                 7 	   # The size of the grid, for example, 7 causes a 7x7 grid with 49 points. 
                                                           # Must be an odd number.
leveling-strategy.delta-grid.probe_offsets        0,0,0    # Optional probe offsets from the nozzle or tool head
leveling-strategy.delta-grid.save                 false    # If the saved grid is to be loaded on boot then this must be set to true
leveling-strategy.delta-grid.initial_height       10       # Optionally an initial_height can be set that tell the intial probe 
                                                           # where to stop the fast decent before it probes, this should be 
                                                           # around 5-10mm above the bed

Usage

G29 test probes in a grid pattern within the radius producing a map of offsets, this can be imported into a graphing program to visualize the bed (NOTE if delta calibration is also enabled then this is executed with G29 P1). optional parameters In sets the number of points to the value n, Jn sets the radius for this probe.
G29.1 test probes in a spiral pattern within the radius producing a map of offsets, this can be imported into a graphing program to visualize the bed heights (NOTE if delta calibration is also enabled then this is executed with G29 P1). optional parameters In sets the number of points to the value n, Jn sets the radius for this probe.
G31 probes the grid and turns the compensation on, this will remain in effect until reset or M561/M370 optional parameters Jn sets the radius for this probe.
M370 clears the grid and turns off compensation (NOTE you must home after this)
M374 Save grid to /sd/delta.grid
M374.1 delete /sd/delta.grid
M375 Load the grid from /sd/delta.grid and enable compensation (NOTE you must home after this)
M375.1 display the current grid
M561 clears the grid and turns off compensation (NOTE you must home after this)
M565 defines the probe offsets from the nozzle or tool head
M500 saves the probe points
M503 displays the current settings

Example use : 

    G28 (Home XYZ)
    (Move Z at least 30mm away from the bed if it's not, and attach probe if you have a removable probe)
    G31 ( Probe the grid )
    M374 ( Save grid to sdcard)
    (Remove probe if you have a removable probe)
    M500 (write M375 to override file to auto load grid if leveling-strategy.delta-grid.save is set to true)
    G28 (Home XYZ)
    (Manually: jog down to touch the plate)
    M306 Z0
    M500 (to save homing offset)
    G28
    (Machine is now grid-levelled and knows it's correct height above the bed)

Probing for Cartesian machines

Three point platform compensation for Cartesians

Also incorrectly called bed leveling.

Do not use on deltas

It just won't work. Use the delta-specific strategy above.

The following third party user guide is helpful

However note it is NOT recommended to automate the probe sequence in your gcode as suggested in that post.

Three-point levelling


If your plate is perfectly flat, but not perfectly level, this is all you need

Summary

Probes three user specified points on the bed and determines the plane of the bed relative to the probe.

As the head moves in X and Y it will adjust Z to keep the head tram with the bed.

Note

The probe does not set the bed height, the probes find the relative level of the bed based on the first probe point, so after you have defined the bed plane with G32, you then set the bed height at the first probe point and use M206 or M306 to set the homing offset. Once saved you do not need to do zprobe or bed height again. In this case it is best to have a Z endstop as well as the ZProbe. the Z endstop is used to set the bed height after the probe. This is different to other Firmware and is deliberate. This allows people to use temporary Z probes and not have a permanent z probe or know the exact Z offset of the probe in relation to the nozzle. In addition the z component of the .probe_offsets should always be zero.

Note

The three probe points MUST be the three corners of a triangle, they MUST NOT be on a straight line or the math and coordinate system will get corrupt and you will need to reset.

Configuration

The strategy must be enabled in the config as well as zprobe. 

leveling-strategy.three-point-leveling.enable         true

Three probe points must be defined, these are best if they are the three points of an equilateral triangle, as far apart as possible. They can be defined in the config file as:- 

leveling-strategy.three-point-leveling.point1         100.0,0.0   # the first probe point (x,y)
leveling-strategy.three-point-leveling.point2         200.0,200.0 # the second probe point (x,y)
leveling-strategy.three-point-leveling.point3         0.0,200.0   # the third probe point (x,y)

Or the probe points may be defined (and saved with M500) using M557 P0 X30 Y40.5 where P is 0,1,2

Probe offsets from the nozzle or tool head can be defined with : 

leveling-strategy.three-point-leveling.probe_offsets  0,0,0  # probe offsets x,y,z (Z should always be 0)

The probe offsets may also be set with M565 X0 Y0 Z0

To force homing in X and Y before G32 does the probe, the following can be set in config (this is the default) 

leveling-strategy.three-point-leveling.home_first    true   # disable by setting to false

The probe tolerance can be set using the config 

leveling-strategy.three-point-leveling.tolerance   0.03    # the probe tolerance in mm, default is 0.03mm

You can save the bed plane so it can be used again without probing again presuming the bed stays flat etc. to do this you must enable the feature 

leveling-strategy.three-point-leveling.save_plane   true    #

For this to be effective you must do your Z home to the first probe point defined when creating the plane. Set the Z height to zero at the first probe point, then the bed plane should be relative from that point on. You save it with M500, although it will not display with M503 as it is not a user settable function.

Configuration options

Option Example value Explanation
leveling-strategy.three-point-leveling.enable true Set to true to enable the leveling strategy that probes three points to define a plane and then keeps the Z parallel to that plane. This is useful if your Z plate/bed is not perfectly aligned with your XY gantry
leveling-strategy.three-point-leveling.point1 100.0,0.0 The first probe point (X, Y)
leveling-strategy.three-point-leveling.point2 200.0,200.0 The second probe point (X, Y)
leveling-strategy.three-point-leveling.point3 0.0,200.0 The third probe point (X, Y)
leveling-strategy.three-point-leveling.home_first true Home the X and Y axes before probing
leveling-strategy.three-point-leveling.tolerance 0.03 The probe tolerance in millimetres, anything less that this will be ignored, default is 0.03mm
leveling-strategy.three-point-leveling.probe_offsets 0,0,0 The probe offset from nozzle, must be X,Y,Z (Z should always be 0), default is no offset. This is used if your nozzle is not exactly at the same position as where your tool would be.
leveling-strategy.three-point-leveling.save_plane false Set to true to allow the bed plane to be saved with M500, default is false
2022/07/17 17:36

Example configuration

To activate this leveling strategy, copy/paste the following to your configuration file and edit it accordingly : 

leveling-strategy.three-point-leveling.enable       true            # Set to true to enable the leveling strategy that probes three points to define
                                                                    # a plane and then keeps the Z parallel to that plane. This is useful if 
                                                                    # your Z plate/bed is not perfectly aligned with your XY gantry
leveling-strategy.three-point-leveling.point1        100.0,0.0      # The first probe point (X, Y)
leveling-strategy.three-point-leveling.point2        200.0,200.0    # The second probe point (X, Y)
leveling-strategy.three-point-leveling.point3        0.0,200.0      # The third probe point (X, Y)
leveling-strategy.three-point-leveling.home_first    true           # Home the X and Y axes before probing
leveling-strategy.three-point-leveling.tolerance     0.03           # The probe tolerance in millimetres, anything less that this will be
                                                                    # ignored, default is 0.03mm
leveling-strategy.three-point-leveling.probe_offsets 0,0,0          # The probe offset from nozzle, must be X,Y,Z (Z should always be 0), 
                                                                    # default is no offset. This is used if your nozzle is not exactly 
                                                                    # at the same position as where your tool would be.
leveling-strategy.three-point-leveling.save_plane    false          # Set to true to allow the bed plane to be saved with M500, default is false

Usage

The machine must be homed in X and Y before running the probe. If you need to set the bed height after probing you must set the height at the first probe point, and save it with homing offsets. (M206 or M306)

G29 probes the three probe points and reports the Z at each point, if a plane is active it will be used to level the probe.
G32 Probes the three probe points and defines the bed plane, this will remain in effect until reset or M561
G31 Reports the status
M557 Defines the probe points
M561 Clears the plane and the bed leveling is disabled until G32 is run again (NOTE you must home after this)
M565 Defines the probe offsets from the nozzle or tool head
M500 Saves the probe points and the probe offsets
M503 Displays the current settings

Example use : (This only works if you have a Z endstop as well as a probe). 

    G28 (Home XYZ)
    (Move Z up to about 30mm and attach probe if you have a removable probe)
    G32
    (Remove probe if you have a removable probe)
    M500 (to save probe results)
    G28 (Home XYZ)
    (Move to the Probe P0 point (first probe point))
    (jog down to touch the plate)
    M306 Z0
    M500 (to save homing offset)
    G28
    (Move to 0,0 check Z height)
    (Move to P0 check Z height ditto for P1 and P2)

A probing height map


Nothing is perfect

Rectangular Grid Compensation

This leveling strategy probes rectangular-grid.size points in X and Y (total probes size * size) and stores the relative offsets from the 0,0 Z height.

When enabled every move will calculate the Z offset based on interpolating the height offset within the grids nearest 4 points.

NOTE there is NO extrapolation in this version, However the very latest firmware will not jump when outside the probed area, it will just use the nearest edge heights instead.

NOTE you MUST set Z0 correctly (or close) before issuing the G32 probe as it may move to the specified initial_height (if set) before it starts to probe so it needs to know where Z0 is approximately.

Configuration

The strategy must be enabled in the config as well as zprobe. 

leveling-strategy.rectangular-grid.enable         true

Also the the bed size must be set:

  • set x_size and y_size to the size of the bed to probe for arbitrary rectangular bed
leveling-strategy.rectangular-grid.x_size        75
leveling-strategy.rectangular-grid.y_size        50

The size of the grid (the number of probe points in X and Y) MUST be set with…

For square bed: 

leveling-strategy.rectangular-grid.size        7

This is the X and Y size of the grid, it must be an odd number ( like 7, 9, 11, 13 ), the default is 7 which is 49 probe points ( 7×7 is 49 ).

For rectangular bed (x_size differ from y_size): 

leveling-strategy.rectangular-grid.grid_x_size        9
leveling-strategy.rectangular-grid.grid_y_size        7
leveling-strategy.rectangular-grid.do_home         true

This can be set if you want the leveling strategy to home before probing.

If you are not using all 3 endstops (or prefer to home manually before G32): 

leveling-strategy.rectangular-grid.do_home        false

Note

You are responsible to make sure that (0,0) is in a repeatable location if you set Do_home to False.

Optionally probe offsets from the nozzle or tool head can be defined with… 

leveling-strategy.rectangular-grid.probe_offsets  0,0,0  # probe offsets x,y,z  (Z should always be 0)

Probe offsets may also be set with M565 X0 Y0 Z0.

The head of your printer will be moved to the X and Y bed sizes set above, PLUS any X and/or Y offset. Make sure your printer's mechanism will allow moves to these locations. For example, if your probe is 60mm down from your nozzle in the Y direction (M565 X0 Y-60 Z0), and you bed is set to 200x200mm, the top row of probes will be done with the nozzle at Y=260 mm

Grid Offset

The first point of the grid is always at (0,0). If your printer can't reach this point with its probe due to the probe's offset you have several options:

1. Set the homing offset to allow for the probe offset and/or reduce the grids x/y size to accommodate the probe offsets. 2. You could invert one or multiple axis so (0,0) is in an accessible position. 3. You can set 

leveling-strategy.rectangular-grid.only_by_two_corners        true

and specify the offset in Gcode using additional parameters to the G32 command.
See more on that in the PCB milling section: PCB Milling.

4. You can use the R1 option to set the probe start position at the current head position. This is especially useful for probing just a small part of the bed rather than the entire bed. NOTE that probes using R1 will not be saved. (more on this here PCB Milling).

If the saved grid is to be loaded on boot then this must be set in the config… 

leveling-strategy.rectangular-grid.save        true

Then when M500 is issued it will save M375 which will cause the grid to be loaded on boot. The default is to not autoload the grid on boot.

Note

The grid size and the rectangle size is saved in the file, and restored when it is loaded with M375. If the grid size is different from the one in config it will NOT load. If the rectangle is different, then the rectangle will be set to whatever was saved overriding the one set in config.

DO NOT call M375 from a gcode file as that will cause the system to run out of memory and crash.

An initial_height may be set that tells the probe where to start the first probe from, this should be around 5-10mm above the probe height above the bed, it will move to the absolute Z position specified here before it starts the first probe. Fir instance this is useful for bltouch probes that are deployed automatically as it will lift the probe off the bed before moving to the first probe position. 

leveling-strategy.rectangular-grid.initial_height  10 # move to Z10 before first probe.

If you prefer for compensation algorithm to slowly decrease after some point, you can use the new feature configurations to do so now. First you have to set up these two configs: 

leveling-strategy.rectangular-grid.dampening_start  0.5 # algorithm will be applied less and less from this height onwards
leveling-strategy.rectangular-grid.height_limit     1   # algorithm will stop applying compensation from this point onwards

Dampening settings

Both of these settings are needed to be defined in your configuration file for dampening compensation feature to work. If any of them is missing, the compensation will be applied through all heights (the old and default behavior). Be careful using these settings, as they may appear to totally disable any compensation. It is advised to not set these until the leveling has been tested and verified to work. NOTE the height_limit and dampening_start are in Machine coordinates, so if you have set Z with G92 or equivalent it may not stop at the height you think it will.

By setting the configuration as above, the compensation will be applied until MCS is 0.5 millimeters, then it starts to decrease slowly until MCS is at 1 millimeter, and not applied from 1 mm and onward.

Limits

It's not advised to set “height_limit” less then the maximum bent height that your bed has; because then you will lose the benefit compensation gives to you. As starting values, you can set “dampening_start” 0.1 mm more than the maximum height point your bed map shows, and set “height_limit” to twice that value - so that you get best of both worlds.

Old maps are still valid!

This new dampening configuration doesn't modify how mesh-maps are stored in any way, so you can still use this config without having to recalibrate your bed. This allows you to experiment it and turn the feature off if you don't like it, without any cost!

IMPORTANT set mm_per_line_segment: 

mm_per_line_segment 1 # necessary for cartesians using rectangular-grid

To learn how to use the grid levelling for PCB milling, see PCB Milling

Configuration options

Option Example value Explanation
leveling-strategy.rectangular-grid.enable true The strategy must be enabled in the config, as well as the zprobe module.
leveling-strategy.rectangular-grid.x_size 190 the distance from homed position to the right edge of the bed in mm
leveling-strategy.rectangular-grid.y_size 180 the distance from homed position to the top edge edge in mm
leveling-strategy.rectangular-grid.size 7 The size of the grid (X size == Y size), for example, 7 causes a 7×7 grid with 49 points. Must be an odd number.
leveling-strategy.rectangular-grid.grid_x_size 9 The X size of the grid. For X size != Y size. Must be an odd number.
leveling-strategy.rectangular-grid.grid_y_size 7 The Y size of the grid. For X size != Y size. Must be an odd number.
leveling-strategy.rectangular-grid.probe_offsets 0,0,0 Optional probe offsets from the nozzle or tool head in mm
leveling-strategy.rectangular-grid.save false If the saved grid is to be loaded on boot then this must be set to true
leveling-strategy.rectangular-grid.initial_height 10 The initial_height (in mm) tells the initial probe where to move to in Z before it probes, this should be around 5-10mm above the bed
leveling-strategy.rectangular-grid.human_readable true Human readable formatting of probe table
leveling-strategy.rectangular-grid.only_by_two_corners true G29/31/32 will not work without providing XYAB parameters: XY - start point, AB rectangle size from starting point. “Two corners”“ not absolutely correct name for this mode, because it use only one corner and rectangle size. This mode designed for PCB milling when you work with board size differ from bed size. More about this mode in PCB milling
leveling-strategy.rectangular-grid.dampening_start 0.5 Compansation normally is applied for all heights, with full power. If you set this setting to a height, the compensation will start to be applied less and less (linearly) until “height_limit” is reached. Any height before this setting is still will be compensated fully
leveling-strategy.rectangular-grid.height_limit 1 The compensation algorithm will stop working after this limit, starting from the “dampening_start” parameter. After the height goes through this limit, no more compansation will be applied
leveling-strategy.rectangular-grid.before_probe_gcode M280 automatically deploy a bltouch probe before the probing
leveling-strategy.rectangular-grid.after_probe_gcode M281 automatically stow the bltouch after probing
2022/07/17 17:35

Example configuration

To activate this leveling strategy, copy/paste the following to your configuration file and edit it accordingly : 

leveling-strategy.rectangular-grid.enable               true     # The strategy must be enabled in the config, as well as the zprobe module.
leveling-strategy.rectangular-grid.x_size               75       # size of bed in the X axis
leveling-strategy.rectangular-grid.y_size               50       # size of bed in the Y axis
leveling-strategy.rectangular-grid.size                 7 	 # The size of the grid, for example, 7 causes a 7x7 grid with 49 points. 
                                                                 # Must be an odd number.
leveling-strategy.rectangular-grid.do_home              true              
leveling-strategy.rectangular-grid.probe_offsets        0,0,0    # Optional probe offsets from the nozzle or tool head
leveling-strategy.rectangular-grid.save                 false    # If the saved grid is to be loaded on boot then this must be set to true
leveling-strategy.rectangular-grid.initial_height       10       # will move to Z10 before the first probe
mm_per_line_segment                                     1        # necessary for cartesians using rectangular-grid
#leveling-strategy.rectangular-grid.before_probe_gcode   M280     # uncomment if you have a bltouch
#leveling-strategy.rectangular-grid.after_probe_gcode    M281     # uncomment if you have a bltouch

Usage

G29 test probes in a grid pattern within the size specified starting at the current head position, producing a map of offsets, this can be imported into a graphing program to visualize the bed. Required parameters Xn sets the width for this probe, and Yn sets the length for this probe. optional parameters In and Jn sets the grid size (default is set in config).
G32 probes the grid and turns the compensation on, this will remain in effect until reset or M561/M370 optional parameters Jn sets the radius for this probe.
M370 clears the grid and turns off compensation (NOTE you must home after this)
M374 Save grid to /sd/cartesian.grid
M374.1 delete /sd/cartesian.grid
M375 Load the grid from /sd/cartesian.grid and enable compensation (NOTE you must home after this)
M375.1 display the current grid
M561 clears the grid and turns off compensation (NOTE you must home after this)
M565 defines the probe offsets from the nozzle or tool head
M500 saves the probe points
M503 displays the current settings

Example use : 

    G28 (Home XYZ)
    (Move Z at least 30mm away from the bed if it's not, and attach probe if you have a removable probe)
    G32 ( Probe the grid )
    (Remove probe if you have a removable probe)
    M500 (to save probe results)
    G28 (Home XYZ)
    (jog down to touch the plate)
    M306 Z0
    M500 (to save homing offset)
    G28
    (Machine is now grid-levelled and knows it's correct height above the bed)

Tuning machine height

Configuring Z height

After homing ( with G28 ), the machine knows it is at Z maximum position if your machine homes to max, and at Z minimum position if your machine homes to min.

Because of this, it will read the configuration option Gamma_max or Gamma_min depending and set the current Z position to that value.

So after homing, the Z position is set to Gamma_max or Gamma_min.

This means for example if you home to max that if your hotend is 300mm above your bed after homing, and you set Gamma_max to 300, after homing, you can just tell the machine to go to Z position 0, and it will go to the bed's height.

To put it simply, setting Gamma_max or Gamma_min is your way of telling Smoothie what the distance is between your bed, and the hotend, when the machine has just homed.

To find the right value for Gamma_max or Gamma_min do one of the following :

First home the machine : 

G28

Then move to the point the machine currently thinks is Z 0 : 

G0 Z0

Then move the head to the bed by jogging, using Pronterface's arrows, the panel, the web interface or whatever other method is adequate in your case.

Finally issue the M306 Z0 command which will use the current Z position as a homing offset:

NOTE You cannot use M306 unless you have Z homing endstops, if you can't home Z then you can't set homing offsets. 

M306 Z0

Then save to the SD card with M500 : 

M500

Next time you home, the machine will know how high above the bed it is.

Height adjustment


Finding gamma_max manually

First home the machine : 

G28

Then set the current Z position to 0 : 

G92 Z0

Then move the head to the bed by jogging, using Pronterface's arrows, the panel, the web interface or whatever other method is adequate in your case.

Once the head is exactly at the bed, issue this command : 

M114

This will return the position of all axes. The current position of the Z axis is the value you must use as your Gamma_max value.

Now simply edit the configuration file to set this value, and reset the board.

Alternatively (delta only) you can use the M665 Z(distance) command to set the value in the config override system, and M500 to save that value to the SD card.

The Gamma_max value in the configuration file is ignored if M665 is set and saved.

Next time you home, the machine will know how high above the bed it is.

Finding gamma_max with a probe

If you have some sort of probe attached to your head ( or below your head ), which triggers when the hotend gets close to the bed, then you can use this to find your gamma_max value without manually jogging.

Now there are two different cases here :

  • Either when the probe is triggered, the hotend is exactly at bed level ( this is the case of probes under the bed, or probes that trigger when the hotend itself is pushed )
  • Or, when the probe is triggered, the hotend is above the bed by a given distance, which we will call the z probe offset ( this is the case of servo-retracted probes, bltouch, inductive probes, IR probes, etc ).

Probe offset


First home the machine : 

G28

Then ask the probe to go find the bed : 

G30

This will report the distance traveled by the probe.

Your Gamma_max value is that reported distance, plus the z probe offset ( distance between the probe triggering point, and the bed ).

For example, if you home, then do G30, and it reports a height of 311mm, and your probe is 7mm bellow your hotend, then your Gamma_max is 311 + 7 = 318mm.

Simply edit the configuration file to set this value, and reset the board.

Alternatively you can use the M665 Z(distance) command to set the value in the config override system, and M500 to save that value to the SD card.

The Gamma_max value in the configuration file is ignored if M665 is set and saved.

Next time you home, the machine will know how high above the bed it is.

Automatically finding the bed with a probe

Smoothie allows you to save both the Z height, and the delta calibration data, to the SD card.

This means you do not need to probe every time you start the machine, you only need to do it once, and save the values, which will then stay valid as long as your machine's geometry doesn't change.

This means you can have a removable probe that you only connect and attach to the head at the rare occasions when you need it.

However, if for whatever reason you have a fixed ( or retractable ) probe on your head ( or sensors bellow your bed ), then you might want to automatically probe at the beginning of each print.

To do so, simply change your slicing program's “beginning of file” G-code sequence, and replace : 

G28

with : 

G28
G30 Znnn

When Nnn is the distance between your probe's triggering point, and the bed ( or probe offset ) :

Probe offset


The G30 Znnn command moves the head until the probe triggers, then sets the current Z height to Nnn

So for example if your probe triggers when the hotend is 5mm above the bed, do G30 Z5, and if your probe triggers exactly when the hotend touches the bed, do G30 Z0.

NOTE behind the scenes G30 Z0 does a G92 Z0, so you can save this if you set save_g92 true in config and issue M500 that saves the offset at 0. Note that G92 is creating a new coordinate system called the Workspace coordinate system (or WCS) it is worth reading up on how that works.

If you are doing this manually you can save time by jogging the Z to within 5mm of the bed then issue the G30 Z0

2022/07/17 17:35
2022/07/17 17:35

Going further

If you want to learn more about this module, or are curious about how it works, Smoothie is Open-Source and you can simply go look at the code, here.

Additional resources

Using FSRs and proximity detectors as a probe

A message about FSRs and other non contact probes

If you use these and do not get a good calibration result, look closely at the probe repeatability on different parts of the bed, before you blame Smoothie. Also for grid probes and the like you need a probe that detects the bed at a point, whereas things like proximity and IR probes detect an area not a point, this makes the grid points less than reliable.

FSRs need to be mounted in a very particular way so they do not trigger by vibration, and do not need too much force before triggering. Proximity probes tend to give different results depending on where they are on the bed, different densities of the underlying metal and less metal at the edges affects this, making the calibration results less than optimal.

Setting up FSRs to work reliably is tricky…

To use FSR's with the smoothieboard an aux board is needed to interface the FSR's to the smoothieboard's endstop input. Smoothieware will accept this input as if it was a simple mechanical switch.

JohnSL on Github has created such a board. It is available via AndOrNot, TriD Printing & UltiBots. See John's blog post about the board. This board is powered from the endstop pins. Also see AndOrNot's write up on FSR's design for a delta printer FSR pad design.

There is also a 4-point FSR controller called “Toucher” on Github suitable for square heat beds on cartesian machines. Reference FSR mount design is published on Thingiverse.

The Deltabot group is where most discussion on using FSR's is located. Topics to look for are:

  • Alternative boards like the arduino mini.
  • WingWong's trinket derived design.
  • Mounting of FSR's
2022/07/17 17:35

BLTouch or servo-retractable touch probe.

The BLTouch is supposed to emulate a servo-deployed switch probe. It is wired, configured and interfaced the same way as a servo and a switch. However it does NOT behave exactly like a microswitch, the activate is a pulse not an on/off and hence does not work well with M119, and the servo PWM is slightly different.

BLTouch probe


How to wire a bltouch probe, old versions ( presumably before 3.1, bltouch isn't great at giving us accurate documentation ) . For most accurate/up to date information, please check out the official documentation page at Antclabs .

BLTouch probe


How to wire a bltouch probe, updated version ( 3.1 )

Or in a copy/paste-friendly format : 

# Switch module for Bltouch control
switch.servo.enable                        true          # Activate this new module
switch.servo.input_on_command              M280          # Command to set PWM value
switch.servo.input_off_command             M281          # Command to turn off switch
switch.servo.output_pin                    1.23          # This must be a PWM pin, see smoothieware.org/pinout   
switch.servo.output_type                   hwpwm         # Hardware PWM, as software PWM is not adequate for servo/bltouch
switch.servo.pwm_period_ms                 20            # 20ms period, or 50Hz

Note that this wiring is also valid for a servo and a switch probe, as this is what the bltouch emulates. When connecting the bltouch the yellow wire on the 3pin connector needs to be connected to a HWPWM pin on the smoothieboard, valid pins are 1.23, 2.4, 3.25 or 3.26 as seen on the wirediagram on antlabs webge: https://www.antclabs.com/wiring32

UPDATE on the latest Smoothie firmware you can now use software emulated PWM, which means you can use any pin for the control pin, just change the following config lines… 

# Switch module for Bltouch control using S/W PWM
# Note in the latest firmware with these settings you can just issue M280 to deploy and M281 to stow
switch.servo.enable                        true      # Activate this new module
switch.servo.input_on_command              M280      # Command to set PWM value
switch.servo.input_off_command             M281      # Command to turn off switch
switch.servo.output_pin                    2.11      # This must can be ANY spare pin   
switch.servo.output_type                   swpwm     # Software emulated PWM
switch.servo.pwm_period_ms                 20        # 20ms period, or 50Hz
switch.servo.startup_state                 false     # use startup_value as initial setting
switch.servo.startup_value                 7.43      # On boot it will go into stow mode
switch.servo.default_on_value              3.3       # value set if M280 is issued without the S parameter, also value set if startup_state is true
Command BLTouch status
M280 S3.0 Push-pin down
M280 S7.0 Push-pin up
M280 S10.6 Alarm release
M280 S8.4 Self-test
M280 S5.5 ZMin test mode (for M119)

Custom command codes examples for BLT probing 

custom_menu.blt_probe_out.enable           true            #
custom_menu.blt_probe_out.name             BLT_Probe_Out   #
custom_menu.blt_probe_out.command          M280S3          #

custom_menu.blt_probe_In.enable           true             #
custom_menu.blt_probe_In.name             BLT_Probe_In     #
custom_menu.blt_probe_In.command          M280S7           #

custom_menu.blt_reset_alarm.enable        true             #
custom_menu.blt_reset_alarm.name          BLT_Reset_Alarm  #
custom_menu.blt_reset_alarm.command       M280S10.6        #

custom_menu.blt_test_alarm.enable         true             #
custom_menu.blt_test_alarm.name           BLT_Test_Alarm   #
custom_menu.blt_test_alarm.command        M280S8.4|G4S15|M280S10.6|M280S7 #Runs Self Test 15secs resets and pulls pin up

custom_menu.blt_probe_bed.enable          true                             #
custom_menu.blt_probe_bed.name            BLT_Probe_Bed                    #
custom_menu.blt_probe_bed.command         M280_S3.0|G32|M280_S7.0|G1X10Y10 #

This video shows an example of a probing sequence ( which can for example be put at the beginning of your Gcode files ) using a bltouch :

Bltouch official Smoothieboard video :

If you have a 5XC

Note that on a Smoothieboard 5XC, the pin 1.23 is used by the third big mosfet, so you can not use it for a bltouch, you need to use another pin. That other pin must also be PWM-capable, see pinout to find another pin that will work. You can also use SWPWM and any spare pin.

Inductive proximity probes

Note  these probes are generally much less reliable than a simple mechanical switch for grid probing. This is because they sense a general area whereas grid probing needs to sense a point contact area to be accurate. Also they tend to vary the detection distance the closer to the edge they are, so you need to probe well within the center mass of the bed. However, if it is what you own, here is a video about them:

Using a servo to retract the probe

If you want to be able to deploy and retract your probe using a small servo motor, see the Switch module documentation.

Baby steps

This isn't strictly probe related, but probe users are likely to be looking for this. If you need to do small live adjustment to your Z height, take a look at This page