Deploying to gh-pages from @ Klipper3d/klipper@f3e89e25c5 🚀

G-Codes.html

@@ -5328,17 +5328,46 @@ state; issue a G28 afterwards to reset the kinematics. This command is
 intended for low-level diagnostics and debugging.</p>
 <h4 id="set_kinematic_position">SET_KINEMATIC_POSITION<a class="headerlink" href="#set_kinematic_position" title="Permanent link">&para;</a></h4>
 <p><code>SET_KINEMATIC_POSITION [X=&lt;value&gt;] [Y=&lt;value&gt;] [Z=&lt;value&gt;]
-[CLEAR=&lt;[X][Y][Z]&gt;]</code>: Force the low-level kinematic code to believe the
-toolhead is at the given cartesian position. This is a diagnostic and
-debugging command; use SET_GCODE_OFFSET and/or G92 for regular axis
-transformations. If an axis is not specified then it will default to the
-position that the head was last commanded to. Setting an incorrect or
-invalid position may lead to internal software errors. Use the CLEAR
-parameter to forget the homing state for the given axes. Note that CLEAR
-will not override the previous functionality; if an axis is not specified
-to CLEAR it will have its kinematic position set as per above. This
-command may invalidate future boundary checks; issue a G28 afterwards to
-reset the kinematics.</p>
+[SET_HOMED=&lt;[X][Y][Z]&gt;] [CLEAR_HOMED=&lt;[X][Y][Z]&gt;]</code>: Force the
+low-level kinematic code to believe the toolhead is at the given
+cartesian position and set/clear homed status. This is a diagnostic
+and debugging command; use SET_GCODE_OFFSET and/or G92 for regular
+axis transformations. Setting an incorrect or invalid position may
+lead to internal software errors.</p>
+<p>The <code>X</code>, <code>Y</code>, and <code>Z</code> parameters are used to alter the low-level
+kinematic position tracking. If any of these parameters are not set
+then the position is not changed - for example <code>SET_KINEMATIC_POSITION
+Z=10</code> would set all axes as homed, set the internal Z position to 10,
+and leave the X and Y positions unchanged. Changing the internal
+position tracking is not dependent on the internal homing state - one
+may alter the position for both homed and not homed axes, and
+similarly one may set or clear the homing state of an axis without
+altering its internal position.</p>
+<p>The <code>SET_HOMED</code> parameter defaults to <code>XYZ</code> which instructs the
+kinematics to consider all axes as homed. A bare
+<code>SET_KINEMATIC_POSITION</code> command will result in all axes being
+considered homed (and not change its current position). If it is not
+desired to change the state of homed axes then assign <code>SET_HOMED</code> to
+an empty string - for example:
+<code>SET_KINEMATIC_POSITION SET_HOMED= X=10</code>. It is also possible to
+request an individual axis be considered homed (eg, <code>SET_HOMED=X</code>),
+but note that non-cartesian style kinematics (such as delta
+kinematics) may not support setting an individual axis as homed.</p>
+<p>The <code>CLEAR_HOMED</code> parameter instructs the kinematics to consider the
+given axes as not homed. For example, <code>CLEAR_HOMED=XYZ</code> would request
+all axes to be considered not homed (and thus require homing prior to
+movement on those axes). The default is <code>SET_HOMED=XYZ</code> even if
+<code>CLEAR_HOMED</code> is present, so the command <code>SET_KINEMATIC_POSITION
+CLEAR_HOMED=Z</code> will set X and Y as homed and clear the homing state
+for Z.  Use <code>SET_KINEMATIC_POSITION SET_HOMED= CLEAR_HOMED=Z</code> if the
+goal is to clear only the Z homing state. If an axis is specified in
+neither <code>SET_HOMED</code> nor <code>CLEAR_HOMED</code> then its homing state is not
+changed and if it is specified in both then <code>CLEAR_HOMED</code> has
+precedence. It is possible to request clearing of an individual axis,
+but on non-cartesian style kinematics (such as delta kinematics) doing
+so may result in clearing the homing state of additional axes. Note
+the <code>CLEAR</code> parameter is currently an alias for the <code>CLEAR_HOMED</code>
+parameter, but this alias will be removed in the future.</p>
 <h3 id="gcode">[gcode]<a class="headerlink" href="#gcode" title="Permanent link">&para;</a></h3>
 <p>The gcode module is automatically loaded.</p>
 <h4 id="restart">RESTART<a class="headerlink" href="#restart" title="Permanent link">&para;</a></h4>