probe: Deprecate last_z_result and add new last_probe_position

Deprecate the PROBE command's exported value
`{printer.probe.last_z_result}`.  This value effectively returns the
toolhead Z position when the probe triggers and user's then need to
adjust the result using the probe's configured z_offset.

Introduce a new `{printer.probe.last_probe_position}` as a
replacement.  This replacement has an easier to understand behavior -
it states that the probe hardware estimates that if the toolhead is
commanded to last_probe_position.x, last_probe_position.y and descends
then the tip of the toolhead should first make contact at a Z height
of last_probe_position.z .  That is, the new exported value already
takes into account the probe's configured xyz offsets.

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>

docs/Config_Changes.md

@@ -8,6 +8,11 @@ All dates in this document are approximate.
 
 ## Changes
 
+20260109: The status value `{printer.probe.last_z_result}` is
+deprecated; it will be removed in the near future. Use
+`{printer.probe.last_probe_position}` instead, and note that this new
+value already has the probe's configured xyz offsets applied.
+
 20260109: The g-code console text output from the `PROBE`,
 `PROBE_ACCURACY`, and similar commands has changed. Now Z heights are
 reported relative to the nominal bed Z position instead of relative to

docs/Load_Cell.md

@@ -252,12 +252,12 @@ macro. This requires setting up
 Here is a simple macro that can accomplish this. Note that the
 `_HOME_Z_FROM_LAST_PROBE` macro has to be separate because of the way macros
 work. The sub-call is needed so that the `_HOME_Z_FROM_LAST_PROBE` macro can
-see the result of the probe in `printer.probe.last_z_result`.
+see the result of the probe in `printer.probe.last_probe_position`.
 
 ```gcode
 [gcode_macro _HOME_Z_FROM_LAST_PROBE]
 gcode:
-    {% set z_probed = printer.probe.last_z_result %}
+    {% set z_probed = printer.probe.last_probe_position.z %}
     {% set z_position = printer.toolhead.position[2] %}
     {% set z_actual = z_position - z_probed %}
     SET_KINEMATIC_POSITION Z={z_actual}

docs/Status_Reference.md

@@ -419,10 +419,18 @@ is defined):
   during the last QUERY_PROBE command. Note, if this is used in a
   macro, due to the order of template expansion, the QUERY_PROBE
   command must be run prior to the macro containing this reference.
-- `last_z_result`: Returns the Z result value of the last PROBE
-  command. Note, if this is used in a macro, due to the order of
-  template expansion, the PROBE (or similar) command must be run prior
-  to the macro containing this reference.
+- `last_probe_position`: The results of the last `PROBE` command. This
+  value is encoded as a [coordinate](#accessing-coordinates). The
+  probe hardware estimates that if one were to command the toolhead to
+  XY position `last_probe_position.x`,`last_probe_position.y` and
+  descend then the tip of the toolhead would first contact the bed at
+  a Z height of `last_probe_position.z`. These coordinates are
+  relative to the frame (that is, they use the coordinate system
+  specified in the config file).  Note, if this is used in a macro,
+  due to the order of template expansion, the `PROBE` command must be
+  run prior to the macro containing this reference.
+- `last_z_result`: This value is deprecated; it will be removed in the
+  near future.
 
 ## pwm_cycle_time
 

klippy/extras/probe.py

@@ -49,6 +49,7 @@ class ProbeCommandHelper:
         gcode.register_command('QUERY_PROBE', self.cmd_QUERY_PROBE,
                                desc=self.cmd_QUERY_PROBE_help)
         # PROBE command
+        self.last_probe_position = gcode.Coord((0., 0., 0.))
         self.last_z_result = 0.
         gcode.register_command('PROBE', self.cmd_PROBE,
                                desc=self.cmd_PROBE_help)
@@ -69,6 +70,7 @@ class ProbeCommandHelper:
     def get_status(self, eventtime):
         return {'name': self.name,
                 'last_query': self.last_state,
+                'last_probe_position': self.last_probe_position,
                 'last_z_result': self.last_z_result}
     cmd_QUERY_PROBE_help = "Return the status of the z-probe"
     def cmd_QUERY_PROBE(self, gcmd):
@@ -84,8 +86,11 @@ class ProbeCommandHelper:
         pos = run_single_probe(self.probe, gcmd)
         gcmd.respond_info("Result: at %.3f,%.3f estimate contact at z=%.6f"
                           % (pos.bed_x, pos.bed_y, pos.bed_z))
+        gcode = self.printer.lookup_object('gcode')
+        self.last_probe_position = gcode.Coord((pos.bed_x, pos.bed_y,
+                                                pos.bed_z))
         x_offset, y_offset, z_offset = self.probe.get_offsets()
-        self.last_z_result = pos.bed_z + z_offset # XXX
+        self.last_z_result = pos.bed_z + z_offset # Deprecated
     def probe_calibrate_finalize(self, mpresult):
         if mpresult is None:
             return