plus4的klipper版本

docs/Bed_Mesh.md

@@ -1,8 +1,8 @@
 # Bed Mesh
 
-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
+The Bed Mesh module may be used to compensate for bed surface irregularities
+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
@@ -46,7 +46,7 @@ probe_count: 5, 3
   _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
+  zig-zag fashion.  As with `mesh_min`, this coordinate is relative to
   the probe's location.
 
 - `probe_count: 5, 3`\
@@ -101,7 +101,7 @@ round_probe_count: 5
   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
+setting the `mesh_origin` to (-10, 0) allows us to specify a larger mesh radius
 of 85.
 
 ![bedmesh_round_basic](img/bedmesh_round_basic.svg)
@@ -114,7 +114,7 @@ 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
+While its possible to sample the probed matrix directly using simple bi-linear
 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,
@@ -142,7 +142,7 @@ bicubic_tension: 0.2
   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
+  points along X, 6 interpolated points along Y, which results in a 13x9
   mesh.  Note that if mesh_pps is set to 0 then mesh interpolation is
   disabled and the probed matrix will be sampled directly.
 
@@ -207,7 +207,7 @@ split_delta_z: .025
 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.
+out the optimal first layer.
 
 ### Mesh Fade
 
@@ -255,19 +255,24 @@ fade_target: 0
   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
+  setting the `fade_target` to .2, the homed area will expand by .2 mm, however,
+  the rest of the bed will be 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
+### Configuring the zero reference position
 
-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.
+Many probes are susceptible to "drift", ie: inaccuracies in probing introduced
+by heat or interference.  This can make calculating the probe's z-offset
+challenging, particularly at different bed temperatures.  As such, some
+printers use an endstop for homing the Z axis and a probe for calibrating the
+mesh. In this configuration it is possible offset the mesh so that the (X, Y)
+`reference position` applies zero adjustment.  The `reference postion` should
+be the location on the bed where a
+[Z_ENDSTOP_CALIBRATE](./Manual_Level#calibrating-a-z-endstop)
+paper test is performed.  The bed_mesh module provides the
+`zero_reference_position` option for specifying this coordinate:
 
 ```
 [bed_mesh]
@@ -275,23 +280,45 @@ speed: 120
 horizontal_move_z: 5
 mesh_min: 35, 6
 mesh_max: 240, 198
+zero_reference_position: 125, 110
 probe_count: 5, 3
-relative_reference_index: 7
+```
+- `zero_reference_position: `\
+  _Default Value: None (disabled)_\
+  The `zero_reference_position` expects an (X, Y) coordinate matching that
+  of the `reference position` described above.  If the coordinate lies within
+  the mesh then the mesh will be offset so the reference position applies zero
+  adjustment.  If the coordinate lies outside of the mesh then the coordinate
+  will be probed after calibration, with the resulting z-value used as the
+  z-offset.  Note that this coordinate must NOT be in a location specified as
+  a `faulty_region` if a probe is necessary.
+
+#### The deprecated relative_reference_index
+
+Existing configurations using the `relative_reference_index` option must be
+updated to use the `zero_reference_position`.  The response to the
+[BED_MESH_OUTPUT PGP=1](#output) gcode command will include the (X, Y)
+coordinate associated with the index;  this position may be used as the value for
+the `zero_reference_position`. The output will look similar to the following:
+
+```
+// bed_mesh: generated points
+// Index | Tool Adjusted | Probe
+// 0 | (1.0, 1.0) | (24.0, 6.0)
+// 1 | (36.7, 1.0) | (59.7, 6.0)
+// 2 | (72.3, 1.0) | (95.3, 6.0)
+// 3 | (108.0, 1.0) | (131.0, 6.0)
+... (additional generated points)
+// bed_mesh: relative_reference_index 24 is (131.5, 108.0)
 ```
 
-- `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.
+_Note:  The above output is also printed in `klippy.log` during initialization._
+
+Using the example above we see that the `relative_reference_index` is
+printed along with its coordinate.  Thus the `zero_reference_position`
+is `131.5, 108`.
+
 
-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.
 
 ### Faulty Regions
 
@@ -371,12 +398,12 @@ following parameters are available:
   - `MESH_ORIGIN`
   - `ROUND_PROBE_COUNT`
 - All beds:
-  - `RELATIVE_REFERNCE_INDEX`
   - `ALGORITHM`
 
 See the configuration documentation above for details on how each parameter
 applies to the mesh.
 
+
 ### Profiles
 
 `BED_MESH_PROFILE SAVE=<name> LOAD=<name> REMOVE=<name>`
@@ -390,15 +417,33 @@ 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:
+state is automatically saved to the _default_ profile. 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.
 
+
+#### Loading the default profile
+
+Previous versions of `bed_mesh` always loaded the profile named _default_
+on startup if it was present.  This behavior has been removed in favor of
+allowing the user to determine when a profile is loaded.  If a user wishes to
+load the `default` profile it is recommended to add
+`BED_MESH_PROFILE LOAD=default` to either their `START_PRINT` macro or their
+slicer's "Start G-Code" configuration, whichever is applicable.
+
+Alternatively the old behavior of loading a profile at startup can be
+restored with a `[delayed_gcode]`:
+
+```ini
+[delayed_gcode bed_mesh_init]
+initial_duration: .01
+gcode:
+  BED_MESH_PROFILE LOAD=default
+```
+
 ### Output
 
 `BED_MESH_OUTPUT PGP=[0 | 1]`