From 32a5f2b042ba32b071892b3268d06e6756b0c15d Mon Sep 17 00:00:00 2001 From: Kevin O'Connor Date: Fri, 26 Dec 2025 21:28:41 -0500 Subject: [PATCH] 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 --- docs/Config_Changes.md | 5 +++++ docs/Load_Cell.md | 4 ++-- docs/Status_Reference.md | 16 ++++++++++++---- klippy/extras/probe.py | 7 ++++++- 4 files changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/Config_Changes.md b/docs/Config_Changes.md index 384908727..cf2d53fd9 100644 --- a/docs/Config_Changes.md +++ b/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 diff --git a/docs/Load_Cell.md b/docs/Load_Cell.md index 8345cae49..c6cf9ce49 100644 --- a/docs/Load_Cell.md +++ b/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} diff --git a/docs/Status_Reference.md b/docs/Status_Reference.md index 4e4ed5c76..1f6704acc 100644 --- a/docs/Status_Reference.md +++ b/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 diff --git a/klippy/extras/probe.py b/klippy/extras/probe.py index fcf8cc697..e6471219e 100644 --- a/klippy/extras/probe.py +++ b/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