docs: add initial temperature_probe documentation

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>

3 files changed, 183 insertions, 0 deletions

diff --git a/docs/Config_Reference.md b/docs/Config_Reference.md
index b192e736..9be53dfa 100644
--- a/docs/Config_Reference.md
+++ b/docs/Config_Reference.md
@@ -2401,6 +2401,65 @@ temperature sensors that are reported via the M105 command.
 #   parameter.
 ```
 
+### [temperature_probe]
+
+Reports probe coil temperature.  Includes optional thermal drift
+calibration for eddy current based probes.   A `[temperature_probe]`
+section may be linked to a `[probe_eddy_current]` by using the same
+postfix for both sections.
+
+```
+[temperature_probe my_probe]
+#sensor_type:
+#sensor_pin:
+#min_temp:
+#max_temp:
+#   Temperature sensor configuration.
+#   See the "extruder" section for the definition of the above
+#   parameters.
+#smooth_time:
+#   A time value (in seconds) over which temperature measurements will
+#   be smoothed to reduce the impact of measurement noise. The default
+#   is 2.0 seconds.
+#gcode_id:
+#   See the "heater_generic" section for the definition of this
+#   parameter.
+#speed:
+#   The travel speed [mm/s] for xy moves during calibration.  Default
+#   is the speed defined by the probe.
+#horizontal_move_z:
+#   The z distance [mm] from the bed at which xy moves will occur
+#   during calibration. Default is 2mm.
+#resting_z:
+#   The z distance [mm] from the bed at which the tool will rest
+#   to heat the probe coil during calibration.  Default is .4mm
+#calibration_position:
+#   The X, Y, Z position where the tool should be moved when
+#   probe drift calibration initializes.  This is the location
+#   where the first manual probe will occur.  If omitted, the
+#   default behavior is not to move the tool prior to the first
+#   manual probe.
+#calibration_bed_temp:
+#   The maximum safe bed temperature (in C) used to heat the probe
+#   during probe drift calibration.  When set, the calibration
+#   procedure will turn on the bed after the first sample is
+#   taken.  When the calibration procedure is complete the bed
+#   temperature will be set to zero.  When omitted the default
+#   behavior is not to set the bed temperature.
+#calibration_extruder_temp:
+#   The extruder temperature (in C) set probe during drift calibration.
+#   When this option is supplied the procedure will wait for until the
+#   specified temperature is reached before requesting the first manual
+#   probe.  When the calibration procedure is complete the extruder
+#   temperature will be set to 0.  When omitted the default behavior is
+#   not to set the extruder temperature.
+#extruder_heating_z: 50.
+#   The Z location where extruder heating will occur if the
+#   "calibration_extruder_temp" option is set.  Its recommended to heat
+#   the extruder some distance from the bed to minimize its impact on
+#   the probe coil temperature.  The default is 50.
+```
+
 ## Temperature sensors
 
 Klipper includes definitions for many types of temperature sensors.
diff --git a/docs/Eddy_Probe.md b/docs/Eddy_Probe.md
index 221c855b..5fa7fc4d 100644
--- a/docs/Eddy_Probe.md
+++ b/docs/Eddy_Probe.md
@@ -54,3 +54,91 @@ result in changes in reported Z height. Changes in either the bed
 surface temperature or sensor hardware temperature can skew the
 results. It is important that calibration and probing is only done
 when the printer is at a stable temperature.
+
+## Thermal Drift Calibration
+
+As with all inductive probes, eddy current probes are subject to
+significant thermal drift.  If the eddy probe has a temperature
+sensor on the coil it is possible to configure a `[temperature_probe]`
+to report coil temperature and enable software drift compensation. To
+link a temperature probe to an eddy current probe the
+`[temperature_probe]` section must share a name with the
+`[probe_eddy_current]` section.  For example:
+
+```
+[probe_eddy_current my_probe]
+# eddy probe configuration...
+
+[temperature_probe my_probe]
+# temperature probe configuration...
+```
+
+See the [configuration reference](Config_Reference.md#temperature_probe)
+for further details on how to configure a `temperature_probe`.  It is
+advised to configure the `calibration_position`,
+`calibration_extruder_temp`, `extruder_heating_z`, and
+`calibration_bed_temp` options, as doing so will automate some of the
+steps outlined below.
+
+Eddy probe manufacturers may offer a stock drift calibration that can be
+manually added to `drift_calibration` option of the `[probe_eddy_current]`
+section. If they do not, or if the stock calibration does not perform well on
+your system, the `temperature_probe` module offers a manual calibration
+procedure via the `TEMPERATURE_PROBE_CALIBRATE` gcode command.
+
+Prior to performing calibration the user should have an idea of what the
+maximum attainable temperature probe coil temperature is.  This temperature
+should be used to set the `TARGET` parameter of the
+`TEMPERATURE_PROBE_CALIBRATE` command.  The goal is to calibrate across the
+widest temperature range possible, thus its desirable to start with the printer
+cold and finish with the coil at the maximum temperature it can reach.
+
+Once a `[temperature_probe]` is configured, the following steps may be taken
+to perform thermal drift calibration:
+
+- The probe must be calibrated using `PROBE_EDDY_CURRENT_CALIBRATE`
+  when a `[temperature_probe]` is configured and linked.  This captures
+  the temperature during calibration which is necessary to perform
+  thermal drift compensation.
+- Make sure the nozzle is free of debris and filament.
+- The bed, nozzle, and probe coil should be cold prior to calibration.
+- The following steps are required if the `calibration_position`,
+  `calibration_extruder_temp`, and `extruder_heating_z` options in
+  `[temperature_probe]` are **NOT** configured:
+  - Move the tool to the center of the bed.  Z should be 30mm+ above the bed.
+  - Heat the extruder to a temperature above the maximum safe bed temperature.
+    150-170C should be sufficient for most configurations.  The purpose of
+    heating the extruder is to avoid nozzle expansion during calibration.
+  - When the extruder temperature has settled, move the Z axis down to about 1mm
+    above the bed.
+- Start drift calibration.  If the probe's name is `my_probe` and the maximum
+  probe temperature we can achieve is 80C, the appropriate gcode command is
+  `TEMPERATURE_PROBE_CALIBRATE PROBE=my_probe TARGET=80`.  If configured, the
+  tool will move to the X,Y coordinate specified by the `calibration_position`
+  and the Z value specified by `extruder_heating_z`.  After heating the extruder
+  to the specified temperature the tool will move to the Z value specified
+  by the`calibration_position`.
+- The procedure will request a manual probe.  Perform the manual probe with
+  the paper test and `ACCEPT`.  The calibration procedure will take the first
+  set of samples with the probe then park the probe in the heating position.
+- If the `calibration_bed_temp` is **NOT** configured turn on the bed heat
+  to the maximum safe temperature.  Otherwise this step will be performed
+  automatically.
+- By default the calibration procedure will request a manual probe every
+  2C between samples until the `TARGET` is reached.  The temperature delta
+  between samples can be customized by setting the `STEP` parameter in
+  `TEMPERATURE_PROBE_CALIBRATE`.  Care should be taken when setting a custom
+  `STEP` value, a value too high may request too few samples resulting in
+  a poor calibration.
+- The following additional gcode commands are available during drift
+  calibration:
+  - `TEMPERATURE_PROBE_NEXT` may be used to force a new sample before the step
+    delta has been reached.
+  - `TEMPERATURE_PROBE_COMPLETE` may be used to complete calibration before the
+    `TARGET` has been reached.
+  - `ABORT` may be used to end calibration and discard results.
+- When calibration is finished use `SAVE_CONFIG` to store the drift
+  calibration.
+
+As one may conclude, the calibration process outlined above is more challenging
+and time consuming than most other procedures.  It may require practice and several attempts to achieve an optimal calibration.
diff --git a/docs/G-Codes.md b/docs/G-Codes.md
index e55fba35..2444c53b 100644
--- a/docs/G-Codes.md
+++ b/docs/G-Codes.md
@@ -1415,3 +1415,39 @@ command will probe the points specified in the config and then make independent
 adjustments to each Z stepper to compensate for tilt. See the PROBE command for
 details on the optional probe parameters. The optional `HORIZONTAL_MOVE_Z`
 value overrides the `horizontal_move_z` option specified in the config file.
+
+### [temperature_probe]
+
+The following commands are available when a
+[temperature_probe config section](Config_Reference.md#temperature_probe)
+is enabled.
+
+#### TEMPERATURE_PROBE_CALIBRATE
+`TEMPERATURE_PROBE_CALIBRATE [PROBE=<probe name>] [TARGET=<value>] [STEP=<value>]`:
+Initiates probe drift calibration for eddy current based probes.  The `TARGET`
+is a target temperature for the last sample.  When the temperature recorded
+during a sample exceeds the `TARGET` calibration will complete.  The `STEP`
+parameter sets temperature delta (in C) between samples. After a sample has
+been taken, this delta is used to schedule a call to `TEMPERATURE_PROBE_NEXT`.
+The default `STEP` is 2.
+
+#### TEMPERATURE_PROBE_NEXT
+`TEMPERATURE_PROBE_NEXT`: After calibration has started this command is run to
+take the next sample.  It is automatically scheduled to run when the delta
+specified by `STEP` has been reached, however its also possible to manually run
+this command to force a new sample.  This command is only available during
+calibration.
+
+#### TEMPERATURE_PROBE_COMPLETE:
+`TEMPERATURE_PROBE_COMPLETE`:  Can be used to end calibration and save the
+current result before the `TARGET` temperature is reached.  This command
+is only available during calibration.
+
+#### ABORT
+`ABORT`:  Aborts the calibration process, discarding the current results.
+This command is only available during drift calibration.
+
+### TEMPERATURE_PROBE_ENABLE
+`TEMPERATURE_PROBE_ENABLE ENABLE=[0|1]`: Sets temperature drift
+compensation on or off. If ENABLE is set to 0, drift compensation
+will be disabled, if set to 1 it is enabled.