Deploying to gh-pages from @ Klipper3d/klipper@79189203e2 🚀

Config_Changes.html

@@ -1412,6 +1412,9 @@ are not backwards compatible. It is a good idea to review this
 document when upgrading the Klipper software.</p>
 <p>All dates in this document are approximate.</p>
 <h2 id="changes">Changes<a class="headerlink" href="#changes" title="Permanent link">&para;</a></h2>
+<p>20251122: An option <code>axis</code> has been added to <code>[carriage &lt;name&gt;]</code> sections
+for <code>generic_cartesian</code> kinematics, allowing arbitrary names for primary
+carriages. Users are encouraged to explicitly specify <code>axis</code> option now.</p>
 <p>20251106: The status fields <code>{printer.toolhead.position}</code>,
 <code>{printer.gcode_move.position}</code>,
 <code>{printer.gcode_move.gcode_position}</code>, and

Config_Reference.html

@@ -4676,9 +4676,11 @@ max_accel:
 #max_z_accel:
 </code></pre></div>
 
-<p>Then a user must define the following three carriages: <code>[carriage x]</code>,
-<code>[carriage y]</code>, and <code>[carriage z]</code>, e.g.</p>
-<div class="highlight"><pre><span></span><code>[carriage x]
+<p>Then a user must define three carriages for X, Y, and Z axes, e.g.:</p>
+<div class="highlight"><pre><span></span><code>[carriage carriage_x]
+axis:
+#   Axis of a carriage, either x, y, or z. This parameter must be provided,
+#   unless a carriage name is x, y, or z itself.
 endstop_pin:
 #   Endstop switch detection pin. If this endstop pin is on a
 #   different mcu than the stepper motor(s) moving this carriage,
@@ -4719,7 +4721,8 @@ for instance</p>
 carriages:
 #   A string describing the carriages the stepper moves. All defined
 #   carriages can be specified here, as well as their linear combinations,
-#   e.g. x, x+y, y-0.5*z, x-z, etc. This parameter must be provided.
+#   e.g. carriage_x, carriage_x+carriage_y, carriage_y-0.5*carriage_z,
+#   carriage_x-carriage_z, etc. This parameter must be provided.
 step_pin:
 dir_pin:
 enable_pin:
@@ -4732,26 +4735,27 @@ microsteps:
 
 <p>See <a href="#stepper">stepper</a> section for more information on the regular
 stepper parameters. The <code>carriages</code> parameter defines how the stepper
-affects the motion of the carriages. For example, <code>x+y</code> indicates that
-the motion of the stepper in the positive direction by the distance <code>d</code>
-moves the carriages <code>x</code> and <code>y</code> by the same distance <code>d</code> in the positive
-direction, while <code>x-0.5*y</code> means the motion of the stepper in the positive
-direction by the distance <code>d</code> moves the carriage <code>x</code> by the distance <code>d</code>
-in the positive direction, but the carriage <code>y</code> will travel distance <code>d/2</code>
-in the negative direction.</p>
+affects the motion of the carriages. For example, <code>carriage_x+carriage_y</code>
+indicates that the motion of the stepper in the positive direction by the
+distance <code>d</code> moves the carriages <code>carriage_x</code> and <code>carriage_y</code> by the same
+distance <code>d</code> in the positive direction, while <code>carriage_x-0.5*carriage_y</code>
+means the motion of the stepper in the positive direction by the distance
+<code>d</code> moves the carriage <code>carriage_x</code> by the distance <code>d</code> in the positive
+direction, but the carriage <code>carriage_y</code> will travel distance <code>d/2</code> in
+the negative direction.</p>
 <p>More than a single stepper motor can be defined to drive the same axis
 or belt. For example, on a CoreXY AWD setups two motors driving the same
 belt can be defined as</p>
-<div class="highlight"><pre><span></span><code>[carriage x]
+<div class="highlight"><pre><span></span><code>[carriage carriage_x]
 endstop_pin: ...
 ...
 
-[carriage y]
+[carriage carriage_y]
 endstop_pin: ...
 ...
 
 [stepper a0]
-carriages: x-y
+carriages: carriage_x-carriage_y
 step_pin: ...
 dir_pin: ...
 enable_pin: ...
@@ -4759,7 +4763,7 @@ rotation_distance: ...
 ...
 
 [stepper a1]
-carriages: x-y
+carriages: carriage_x-carriage_y
 step_pin: ...
 dir_pin: ...
 enable_pin: ...
@@ -4772,7 +4776,7 @@ sharing the same <code>carriages</code> and corresponding endstops.</p>
 <p>There are situations when a user wants to have more than one endstop
 per axis. Examples of such configurations include Y axis driven by
 two independent stepper motors with belts attached to both ends of the
-X beam, with effectively two carriages on Y axis each having an
+X gantry, with effectively two carriages on Y axis each having an
 independent endstop, and multi-stepper Z axis with each stepper having
 its own endstop (not to be confused with the configurations with
 multiple Z motors but only a single endstop). These configurations
@@ -4787,12 +4791,12 @@ endstop_pin:
 </code></pre></div>
 
 <p>and the corresponding stepper motors, for example:</p>
-<div class="highlight"><pre><span></span><code>[extra_carriage y1]
-primary_carriage: y
+<div class="highlight"><pre><span></span><code>[extra_carriage carriage_y1]
+primary_carriage: carriage_y
 endstop_pin: ...
 
 [stepper sy1]
-carriages: y1
+carriages: carriage_y1
 ...
 </code></pre></div>
 
@@ -6223,7 +6227,7 @@ from the configuration described above:</p>
 <div class="highlight"><pre><span></span><code>[dual_carriage my_dc_carriage]
 primary_carriage:
 #   Defines the matching primary carriage of this dual carriage and
-#   the corresponding IDEX axis. Valid choices are x, y, z.
+#   the corresponding IDEX axis. Must match a name of a defined `[carriage]`.
 #   This parameter must be provided.
 #safe_distance:
 #   The minimum distance (in mm) to enforce between the dual and the primary
@@ -6250,18 +6254,18 @@ position_max:
 on the regular <code>carriage</code> parameters.</p>
 <p>Then a user must define one or more stepper motors moving the dual carriage
 (and other carriages as appropriate), for instance</p>
-<div class="highlight"><pre><span></span><code>[carriage x]
+<div class="highlight"><pre><span></span><code>[carriage carriage_x]
 ...
 
-[carriage y]
+[carriage carriage_y]
 ...
 
-[dual_carriage u]
-primary_carriage: x
+[dual_carriage carriage_u]
+primary_carriage: carriage_x
 ...
 
 [stepper dc_stepper]
-carriages: u-y
+carriages: carriage_u-carriage_y
 ...
 </code></pre></div>
 
@@ -6276,15 +6280,15 @@ example above:</p>
 [delayed_gcode init_shaper]
 initial_duration: 0.1
 gcode:
-  SET_DUAL_CARRIAGE CARRIAGE=u
-  SET_INPUT_SHAPER SHAPER_TYPE_X=&lt;dual_carriage_x_shaper&gt; SHAPER_FREQ_X=&lt;dual_carriage_x_freq&gt; SHAPER_TYPE_Y=&lt;y_shaper&gt; SHAPER_FREQ_Y=&lt;y_freq&gt;
-  SET_DUAL_CARRIAGE CARRIAGE=x
-  SET_INPUT_SHAPER SHAPER_TYPE_X=&lt;primary_carriage_x_shaper&gt; SHAPER_FREQ_X=&lt;primary_carriage_x_freq&gt; SHAPER_TYPE_Y=&lt;y_shaper&gt; SHAPER_FREQ_Y=&lt;y_freq&gt;
+  SET_DUAL_CARRIAGE CARRIAGE=carriage_u
+  SET_INPUT_SHAPER SHAPER_TYPE_X=&lt;carriage_u_shaper&gt; SHAPER_FREQ_X=&lt;carriage_x_freq&gt; SHAPER_TYPE_Y=&lt;carriage_y_shaper&gt; SHAPER_FREQ_Y=&lt;carriage_y_freq&gt;
+  SET_DUAL_CARRIAGE CARRIAGE=carriage_x
+  SET_INPUT_SHAPER SHAPER_TYPE_X=&lt;carriage_x_shaper&gt; SHAPER_FREQ_X=&lt;carriage_x_freq&gt; SHAPER_TYPE_Y=&lt;carriage_y_shaper&gt; SHAPER_FREQ_Y=&lt;carriage_y_freq&gt;
 </code></pre></div>
 
 <p>Note that <code>SHAPER_TYPE_Y</code> and <code>SHAPER_FREQ_Y</code> must be the same in both
 commands in this case, since the same motors drive Y axis when either
-of the <code>x</code> and <code>u</code> carriages are active.</p>
+of the <code>carriage_x</code> and <code>carriage_u</code> carriages are active.</p>
 <p>It is worth noting that <code>generic_cartesian</code> kinematic can support two
 dual carriages for X and Y axes. For reference, see for instance a
 <a href="https://github.com/Klipper3d/klipper/blob/master/config/sample-corexyuv.cfg">sample</a> of CoreXYUV configuration.</p>

G-Codes.html

@@ -5559,11 +5559,11 @@ stepper at a time, some sequences of changes can lead to invalid
 intermediate kinematic configurations, even if the final configuration
 is valid. In such cases a user can pass <code>DISABLE_CHECKS=1</code> parameters to
 all but the last command to disable intermediate checks. For example,
-if <code>stepper a</code> and <code>stepper b</code> initially have <code>x-y</code> and <code>x+y</code> carriages
-correspondingly, then the following sequence of commands will let a user
-effectively swap the carriage controls:
-<code>SET_STEPPER_CARRIAGES STEPPER=a CARRIAGES=x+y DISABLE_CHECKS=1</code>
-and <code>SET_STEPPER_CARRIAGES STEPPER=b CARRIAGES=x-y</code>, while
+if <code>stepper a</code> and <code>stepper b</code> initially have <code>carriage_x-carriage_y</code> and
+<code>carriage_x+carriage_y</code> carriages correspondingly, then the following
+sequence of commands will let a user effectively swap the carriage controls:
+<code>SET_STEPPER_CARRIAGES STEPPER=a CARRIAGES=carriage_x+carriage_y DISABLE_CHECKS=1</code>
+and <code>SET_STEPPER_CARRIAGES STEPPER=b CARRIAGES=carriage_x-carriage_y</code>, while
 still validating the final kinematics state.</p>
 <h3 id="hall_filament_width_sensor">[hall_filament_width_sensor]<a class="headerlink" href="#hall_filament_width_sensor" title="Permanent link">&para;</a></h3>
 <p>The following commands are available when the

Resonance_Compensation.html

@@ -2047,7 +2047,9 @@ gcode:
   SET_INPUT_SHAPER SHAPER_TYPE_X=<primary_carriage_shaper> SHAPER_FREQ_X=<primary_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq>
 </code></pre></div>
 
-<p>Note that <code>SHAPER_TYPE_Y</code> and <code>SHAPER_FREQ_Y</code> should be the same in both
+<p>However, users of <code>generic_cartesian</code> kinematics should specify carriage names
+in <code>CARRIAGE=</code> parameters of <code>SET_DUAL_CARRIAGE</code> instead of their numbers.
+Note that <code>SHAPER_TYPE_Y</code> and <code>SHAPER_FREQ_Y</code> should be the same in both
 commands. If you need to configure an input shaper for Z axis, include
 its parameters in both <code>SET_INPUT_SHAPER</code> commands.</p>
 <p>Besides <code>delayed_gcode</code>, it is also possible to put a similar snippet into