From edae40c36ff6186e08003574a5caa327826b58a9 Mon Sep 17 00:00:00 2001 From: Arksine Date: Wed, 18 Dec 2019 19:40:41 -0500 Subject: [PATCH] docs: Update documentation to reflect bed_mesh changes Also add new bed_mesh.md documentation. Signed-off-by: Eric Callahan --- config/example-extras.cfg | 38 ++-- docs/Bed_Mesh.md | 359 ++++++++++++++++++++++++++++++ docs/G-Codes.md | 18 +- docs/img/bedmesh_interpolated.svg | 3 + docs/img/bedmesh_rect_basic.svg | 3 + docs/img/bedmesh_round_basic.svg | 3 + 6 files changed, 399 insertions(+), 25 deletions(-) create mode 100644 docs/Bed_Mesh.md create mode 100644 docs/img/bedmesh_interpolated.svg create mode 100644 docs/img/bedmesh_rect_basic.svg create mode 100644 docs/img/bedmesh_round_basic.svg diff --git a/config/example-extras.cfg b/config/example-extras.cfg index 540cb018..8ea42f0d 100644 --- a/config/example-extras.cfg +++ b/config/example-extras.cfg @@ -46,28 +46,34 @@ #horizontal_move_z: 5 # The height (in mm) that the head should be commanded to move to # just prior to starting a probe operation. The default is 5. -#bed_radius: -# Defines the radius to probe for round beds. Note that the radius -# is relative to the nozzle's origin, if using a probe be sure to -# account for its offset. This parameter must be provided for round -# beds and omitted for rectangular beds. -#min_point: -# Defines the minimum x,y position to probe when for rectangular -# beds. Note that this refers to the nozzle position, take care that -# you do not define a point that will move the probe off of the bed. -# This parameter must be provided for rectangular beds. -#max_point: -# Defines the maximum x,y position to probe when for rectangular -# beds. Follow the same precautions as listed in min_point. Also note -# that this does not necessarily define the last point probed, only -# the maximum coordinate. This parameter must be provided. +#mesh_radius: +# Defines the radius of the mesh to probe for round beds. Note that the +# radius is relative to the coordinate specified by the mesh_origin option. +# This parameter must be provided for round beds and omitted for rectangular +# beds. +#mesh_origin: +# Defines the center x,y coordinate of the mesh for round beds. This +# coordinate is relative to the probe's location. It may be useful +# to adjust the mesh_origin in an effort to maximize the size of the +# mesh radius. Default is 0,0. This parameter must be omitted for +# rectangular beds. +#mesh_min: +# Defines the minimum x,y coodinate of the mesh for rectangular beds. This +# coordinate is relative to the probe's location. This will be the first +# point probed, nearest to the origin. This parameter must be provided for +# rectangular beds. +#mesh_max: +# Defines the maximum x,y coordinate of the mesh for rectangular beds. +# Adheres to the same principle as mesh_min, however this will be the +# furthest point probed from the bed's origin. This parameter must be +# provided for rectangular beds. #probe_count: 3,3 # For rectangular beds, this is a comma separate pair of integer # values (X,Y) defining the number of points to probe along each axis. # A single value is also valid, in which case that value will be applied # to both axes. Default is 3,3. #round_probe_count: 5 -# For round beds, this is integer value defines the maximum number of +# For round beds, this integer value defines the maximum number of # points to probe along each axis. This value must be an odd number. # Default is 5. #fade_start: 1.0 diff --git a/docs/Bed_Mesh.md b/docs/Bed_Mesh.md new file mode 100644 index 00000000..c33063be --- /dev/null +++ b/docs/Bed_Mesh.md @@ -0,0 +1,359 @@ +The Bed Mesh module may be used to compensate for bed surface irregularties to +achieve a better first layer across the entire bed. It should be noted that +software based correction will not achieve perfect results, it can only +approximate the shape of the bed. Bed Mesh also cannot compensate for +mechanical and electrical issues. If an axis is skewed or a probe is not +accurate then the bed_mesh module will not receive accurate results from +the probing process. + +Prior to Mesh Calibration you will need to be sure that your Probe's +Z-Offset is calibrated. If using an endstop for Z homing it will need +to be calibrated as well. See [Probe_Calibrate](Probe_Calibrate.md) +and Z_ENDSTOP_CALIBRATE in [Manual_Level](Manual_Level.md) for more +information. + +## Basic Configuration + +### Rectangular Beds +This example assumes a printer with a 250 mm x 220 mm rectangular +bed and a probe with an x-offset of 24 mm and y-offset of 5 mm. + +``` +[bed_mesh] +speed: 120 +horizontal_move_z: 5 +mesh_min: 35,6 +mesh_max: 240, 198 +probe_count: 5,3 +``` + +- `speed: 120`\ + _Default Value: 50_\ + The speed in which the tool moves between points. + +- `horizontal_move_z: 5`\ + _Default Value: 5_\ + The Z coordinate the probe rises to prior to traveling between points. + +- `mesh_min: 35,6`\ + _Required_\ + The first probed coordinate, nearest to the origin. This coordinate + is relative to the probe's location. + +- `mesh_max: 240,198`\ + _Required_\ + The probed coordinate farthest farthest from the origin. This is not + necessarily the last point probed, as the probing process occurs in a + zig-zag fashion. As with `mesh_min`, this coordiante is relative to + the probe's location. + +- `probe_count: 5,3`\ + _Default Value: 3,3_\ + The number of points to probe on each axis, specified as x,y integer + values. In this example 5 points will be probed along the X axis, with + 3 points along the Y axis, for a total of 15 probed points. Note that + if you wanted a square grid, for example 3x3, this could be specified + as a single integer value that is used for both axes, ie `probe_count: 3`. + Note that a mesh requires a minimum probe_count of 3 along each axis. + +The illustration below demonstrates how the `mesh_min`, `mesh_max`, and +`probe_count` options are used to generate probe points. The arrows indicate +the direction of the probing procedure, beginning at `mesh_min`. For reference, +when the probe is at `mesh_min` the nozzle will be at (11, 1), and when the probe +is at `mesh_max`, the nozzle will be at (206, 193). + +![bedmesh_rect_basic](img/bedmesh_rect_basic.svg) + +### Round beds +This example assumes a printer equipped with a round bed radius of 100mm. +We will use the same probe offsets as the rectangular example, 24 mm on X +and 5 mm on Y. + +``` +[bed_mesh] +speed: 120 +horizontal_move_z: 5 +mesh_radius: 75 +mesh_origin: 0,0 +round_probe_count: 5 +``` + +- `mesh_radius: 75`\ + _Required_\ + The radius of the probed mesh in mm, relative to the `mesh_origin`. Note + that the probe's offsets limit the size of the mesh radius. In this example, + a radius larger than 76 would move the tool beyond the range of the printer. + +- `mesh_origin: 0,0`\ + _Default Value: 0,0_\ + The center point of the mesh. This coordinate is relative to the probe's + location. While the default is 0,0, it may be useful to adjust the origin + in an effort to probe a larger portion of the bed. See the illustration + below. + +- `round_probe_count: 5`\ + _Default Value: 5_\ + This is an integer value that defines the maximum number of probed points + along the X and Y axes. By "maximum", we mean the number of points probed + along the mesh origin. This value must be an odd number, as it is required + that the center of the mesh is probed. + +The illustration below shows how the probed points are generated. As you can see, +setting the `mesh_origin` to (-10, 0) allows us to specifiy a larger mesh radius +of 85. + +![bedmesh_round_basic](img/bedmesh_round_basic.svg) + +## Advanced Configuration + +Below the more advanced configuration options are explained in detail. Each +example will build upon the basic rectangular bed configuration shown above. +Each of the advanced options apply to round beds in the same manner. + +### Mesh Interpolation + +While its possible to sample the probed matrix directly using simple bilinear +interpolation to determine the Z-Values between probed points, it is often +useful to interpolate extra points using more advanced interpolation algorithms +to increase mesh density. These algorithms add curvature to the mesh, +attempting to simulate the material properties of the bed. Bed Mesh offers +lagrange and bicubic interpolation to accomplish this. + +``` +[bed_mesh] +speed: 120 +horizontal_move_z: 5 +mesh_min: 35,6 +mesh_max: 240, 198 +probe_count: 5,3 +mesh_pps: 2,3 +algorithm: bicubic +bicubic_tension: 0.2 +``` + +- `mesh_pps: 2,3`\ + _Default Value: 2,2_\ + The `mesh_pps` option is shorthand for Mesh Points Per Segment. This + option specifies how many points to interpolate for each segment along + the x and y axes. Consider a 'segment' to be the space between each + probed point. Like `probe_count`, `mesh_pps` is specified as an x,y + integer pair, and also may be specified a single integer that is applied + to both axes. In this example there are 4 segments along the X axis + and 2 segments along the Y axis. This evaluates to 8 interpolated + points along X, 6 interpolated points along Y, which results in a 13x8 + mesh. Note that if mesh_pps is set to 0 then mesh interpolation is + disabled and the probed matrix will be sampled directly. + +- `algorithm: lagrange`\ + _Default Value: lagrange_\ + The algorithm used to interpolate the mesh. May be `lagrange` or `bicubic`. + Lagrange interpolation is capped at 6 probed points as oscillation tends to + occur with a larger number of samples. Bicubic interpolation requires a + minimum of 4 probed points along each axis, if less than 4 points are + specified then lagrange sampling is forced. If `mesh_pps` is set to 0 then + this value is ignored as no mesh interpolation is done. + +- `bicubic_tension: 0.2`\ + _Default Value: 0.2_\ + If the `algorithm` option is set to bicubic it is possible to specify the + tension value. The higher the tension the more slope is interpolated. Be + careful when adjusting this, as higher values also create more overshoot, + which will result in interpolated values higher or lower than your probed + points. + +The illustration below shows how the options above are used to generate an +interpolated mesh. + +![bedmesh_interpolated](img/bedmesh_interpolated.svg) + +### Move Splitting + +Bed Mesh works by intercepting gcode move commands and applying a transform +to their Z coordinate. Long moves must be and split into smaller moves +to correctly follow the shape of the bed. The options below control the +splitting behavior. + +``` +[bed_mesh] +speed: 120 +horizontal_move_z: 5 +mesh_min: 35,6 +mesh_max: 240, 198 +probe_count: 5,3 +move_check_distance: 5 +split_delta_z: .025 +``` + +- `move_check_distance: 5`\ + _Default Value: 5_\ + The minimum distance to check for the desired change in Z before performing + a split. In this example, a move longer than 5mm will be traversed by the + algorithm. Each 5mm a mesh Z lookup will occur, comparing it with the Z + value of the previous move. If the delta meets the threshold set by + `split_delta_z`, the move will be split and traversal will continue. This + process repeats until the end of the move is reached, where a final + adjustment will be applied. Moves shorter than the `move_check_distance` + have the correct Z adjustment applied directly to the move without + traversal or splitting. + +- `split_delta_z: .025`\ + _Default Value: .025_\ + As mentioned above, this is the minimum deviation required to trigger a + move split. In this example, any Z value with a deviation +/- .025mm + will trigger a split. + +Generally the default values for these options are sufficient, in fact the +default value of 5mm for the `move_check_distance` may be overkill. However an +advanced user may wish to experiment with these options in an effort to squeeze +out the optimial first layer. + +### Mesh Fade + +When "fade" is enabled Z adjustment is phased out over a distance defined +by the configuration. This is accomplished by applying small adjustments +to the layer height, either increasing or decreasing depending on the shape +of the bed. When fade has completed, Z adjustment is no longer applied, +allowing the top of the print to be flat rather than mirror the shape of the +bed. Fade also may have some undesirable traits, if you fade too quickly it +can result in visible artifacts on the print. Also, if your bed is +significantly warped, fade can shrink or stretch the Z height of the print. +As such, fade is disabled by default. + +``` +[bed_mesh] +speed: 120 +horizontal_move_z: 5 +mesh_min: 35,6 +mesh_max: 240, 198 +probe_count: 5,3 +fade_start: 1 +fade_end: 10 +fade_target: 0 +``` + +- `fade_start: 1`\ + _Default Value: 1_\ + The Z height in which to start phasing out adjustment. It is a good idea + to get a few layers down before starting the fade process. + +- `fade_end: 10`\ + _Default Value: 0_\ + The Z height in which fade should complete. If this value is lower than + `fade_start` then fade is disabled. This value may be adjusted depending + on how warped the print surface is. A significantly warped surface should + fade out over a longer distance. A near flat surface may be able to reduce + this value to phase out more quickly. 10mm is a sane value to begin with if + using the default value of 1 for `fade_start`. + +- `fade_target: 0`\ + _Default Value: The average Z value of the mesh_\ + The `fade_target` can be thought of as an additional Z offset applied to the + entire bed after fade completes. Generally speaking we would like this value + to be 0, however there are circumstances where it should not be. For + example, lets assume your homing position on the bed is an outlier, its + .2 mm lower than the average probed height of the bed. If the `fade_target` + is 0, fade will shrink the print by an average of .2 mm across the bed. By + setting the `fade_target` to .2, the homed area will expand by .2 mm, however + the rest of the bed will have an accurately sized. Generally its a good idea + to leave `fade_target` out of the configuration so the average height of the + mesh is used, however it may be desirable to manually adjust the fade target + if one wants to print on a specific portion of the bed. + +### The Relative Reference Index + +Most probes are suceptible to drift, ie: inaccuracies in probing introduced by +heat or interference. This can make calculating the probe's z-offset +challenging, particuarly at different bed temperatures. As such, some printers +use an endstop for homing the Z axis, and a probe for calibrating the mesh. +These printers can benefit from configuring the relative reference index. + +``` +[bed_mesh] +speed: 120 +horizontal_move_z: 5 +mesh_min: 35,6 +mesh_max: 240, 198 +probe_count: 5,3 +relative_reference_index: 7 +``` + +- `relative_reference_index: 7`\ + _Default Value: None (disabled)_\ + When the probed points are generated they are each assigned an index. You + can look up this index in klippy.log or by using BED_MESH_OUTPUT (see the + section on Bed Mesh GCodes below for more information). If you assign an + index to the `relative_reference_index` option, the value probed at this + coordinate will replace the probe's z_offset. This effectively makes + this coordinate the "zero" reference for the mesh. + +When using the relative reference index, you should choose the index nearest +to the spot on the bed where Z endstop calibration was done. Note that +when looking up the index using the log or BED_MESH_OUTPUT, you should use +the coordinates listed under the "Probe" header to find the correct index. + +## Bed Mesh Gcodes + +### Calibration + +`BED_MESH_CALIBRATE METHOD=[manual | automatic]`\ +_Default Method: automatic if a probe is detected, otherwise manual_ + +Initiates the probing procedure for Bed Mesh Calibration. If `METHOD=manual` +is selected then manual probing will occur. When switching between automatic +and manual probing the generated mesh points will automatically be adjusted. + +### Profiles + +`BED_MESH_PROFILE SAVE=name LOAD=name REMOVE=name` + +After a BED_MESH_CALIBRATE has been performed, it is possible to save the +current mesh state into a named profile. This makes it possible to load +a mesh without re-probing the bed. After a profile has been saved using +`BED_MESH_PROFILE SAVE=name` the `SAVE_CONFIG` gcode may be executed +to write the profile to printer.cfg. + +Profiles can be loaded by executing `BED_MESH_PROFILE LOAD=name`. + +It should be noted that each time a BED_MESH_CALIBRATE occurs, the current +state is automatically saved to the _default_ profile. If this profile +exists it is automatically loaded when Klipper starts. If this behavior +is not desirable the _default_ profile can be removed as follows: + +`BED_MESH_PROFILE REMOVE=default` + +Any other saved profile can be removed in the same fashion, replacing +_default_ with the named profile you wish to remove. + +### Output + +`BED_MESH_OUTPUT PGP=[0 | 1]` + +Outputs the current mesh state to the terminal. Note that the mesh itself +is output + +The PGP parameter is shorthand for "Print Generated Points". If `PGP=1` is +set, the generated probed points will be output to the terminal: + +``` +// bed_mesh: generated points +// Index | Tool Adjusted | Probe +// 0 | (11.0, 1.0) | (35.0, 6.0) +// 1 | (62.2, 1.0) | (86.2, 6.0) +// 2 | (113.5, 1.0) | (137.5, 6.0) +// 3 | (164.8, 1.0) | (188.8, 6.0) +// 4 | (216.0, 1.0) | (240.0, 6.0) +// 5 | (216.0, 97.0) | (240.0, 102.0) +// 6 | (164.8, 97.0) | (188.8, 102.0) +// 7 | (113.5, 97.0) | (137.5, 102.0) +// 8 | (62.2, 97.0) | (86.2, 102.0) +// 9 | (11.0, 97.0) | (35.0, 102.0) +// 10 | (11.0, 193.0) | (35.0, 198.0) +// 11 | (62.2, 193.0) | (86.2, 198.0) +// 12 | (113.5, 193.0) | (137.5, 198.0) +// 13 | (164.8, 193.0) | (188.8, 198.0) +// 14 | (216.0, 193.0) | (240.0, 198.0) +``` + +The "Tool Adjusted" points refer to the nozzle location for each point, and +the "Probe" points refer to the probe location. Note that when manually +probing the "Probe" points will refer to both the tool and nozzle locations. diff --git a/docs/G-Codes.md b/docs/G-Codes.md index ea77ddd1..0eff01c2 100644 --- a/docs/G-Codes.md +++ b/docs/G-Codes.md @@ -335,15 +335,15 @@ section is enabled: specified then the manual probing tool is activated - see the MANUAL_PROBE command above for details on the additional commands available while this tool is active. -- `BED_MESH_OUTPUT`: This command outputs the current probed z values - and current mesh values to the terminal. -- `BED_MESH_MAP`: This command probes the bed in a similar fashion - to BED_MESH_CALIBRATE, however no mesh is generated. Instead, - the probed z values are serialized to json and output to the - terminal. This allows octoprint plugins to easily capture the - data and generate maps approximating the bed's surface. Note - that although no mesh is generated, any currently stored mesh - will be cleared. +- `BED_MESH_OUTPUT PGP=[<0:1>]`: This command outputs the current probed + z values and current mesh values to the terminal. If PGP=1 is specified + the x,y coordinates generated by bed_mesh, along with their associated + indices, will be output to the terminal. +- `BED_MESH_MAP`: Like to BED_MESH_OUTPUT, this command prints the current + state of the mesh to the terminal. Instead of printing the values in a + human readable format, the state is serialized in json format. This allows + octoprint plugins to easily capture the data and generate height maps + approximating the bed's surface. - `BED_MESH_CLEAR`: This command clears the mesh and removes all z adjustment. It is recommended to put this in your end-gcode. - `BED_MESH_PROFILE LOAD= SAVE= REMOVE=`: This diff --git a/docs/img/bedmesh_interpolated.svg b/docs/img/bedmesh_interpolated.svg new file mode 100644 index 00000000..6086ae3c --- /dev/null +++ b/docs/img/bedmesh_interpolated.svg @@ -0,0 +1,3 @@ + + +
Origin: (0,0)
[Not supported by viewer]
mesh_min: (35, 6)
[Not supported by viewer]
mesh_max: (240, 198)
[Not supported by viewer]
Legend
Legend
Probed Point
Probed Point
Interpolated Point
Interpolated Point
Segment
Segment
mesh_pps
Y = 3
mesh_pps<br>Y = 3
mesh_pps X = 2
mesh_pps X = 2 \ No newline at end of file diff --git a/docs/img/bedmesh_rect_basic.svg b/docs/img/bedmesh_rect_basic.svg new file mode 100644 index 00000000..4daa7d9b --- /dev/null +++ b/docs/img/bedmesh_rect_basic.svg @@ -0,0 +1,3 @@ + + +
Origin: (0,0)
[Not supported by viewer]
mesh_min: (35, 6)
[Not supported by viewer]
mesh_max: (240, 198)
[Not supported by viewer]
probe_count
X = 5
probe_count<br>X = 5
probe_count Y = 3
[Not supported by viewer] \ No newline at end of file diff --git a/docs/img/bedmesh_round_basic.svg b/docs/img/bedmesh_round_basic.svg new file mode 100644 index 00000000..0e97a3e6 --- /dev/null +++ b/docs/img/bedmesh_round_basic.svg @@ -0,0 +1,3 @@ + + +
mesh_origin
(-10, 0)
mesh_origin<br>(-10, 0)
Start (-10, -85)
Start (-10, -85)
(-95, 0)
(-95, 0)
(75, 0)
(75, 0)
(-10, 85)
(-10, 85)
Start
(0, -75)
[Not supported by viewer]
(-75, 0)
(-75, 0)
(75, 0)
(75, 0)
(0, 75)
(0, 75)
mesh_origin
(0, 0)
mesh_origin<br>(0, 0)
Mesh Radius = 75, Mesh Origin = (0,0)
<font style="font-size: 26px">Mesh Radius = 75, Mesh Origin = (0,0)</font>
Mesh Radius = 85, Mesh Origin = (-10,0)
<font style="font-size: 26px">Mesh Radius = 85, Mesh Origin = (-10,0)</font> \ No newline at end of file