idex_modes: COPY and MIRROR mode implementation (#6297)

COPY and MIRROR mode implementation

Correctly apply input shaper params to new dual_carriage

Added SAVE_/RESTORE_IDEX_STATE commands

Documentation updates for the new IDEX modes

Signed-off-by: Dmitry Butyugin <dmbutyugin@google.com>

5 files changed, 89 insertions, 24 deletions

diff --git a/docs/Config_Changes.md b/docs/Config_Changes.md
index 6e4ebf31..8f8ec37a 100644
--- a/docs/Config_Changes.md
+++ b/docs/Config_Changes.md
@@ -8,6 +8,11 @@ All dates in this document are approximate.
 
 ## Changes
 
+20230729: The exported status for `dual_carriage` is changed. Instead of
+exporting `mode` and `active_carriage`, the individual modes for each
+carriage are exported as `printer.dual_carriage.carriage_0` and
+`printer.dual_carriage.carriage_1`.
+
 20230619: The `relative_reference_index` option has been deprecated
 and superceded by the `zero_reference_position` option.  Refer to the
 [Bed Mesh Documentation](./Bed_Mesh.md#the-deprecated-relative_reference_index)
diff --git a/docs/Config_Reference.md b/docs/Config_Reference.md
index b36c47a9..b64b9cf1 100644
--- a/docs/Config_Reference.md
+++ b/docs/Config_Reference.md
@@ -2007,14 +2007,24 @@ for an example configuration.
 
 ### [dual_carriage]
 
-Support for cartesian printers with dual carriages on a single
-axis. The active carriage is set via the SET_DUAL_CARRIAGE extended
-g-code command. The "SET_DUAL_CARRIAGE CARRIAGE=1" command will
-activate the carriage defined in this section (CARRIAGE=0 will return
-activation to the primary carriage). Dual carriage support is
-typically combined with extra extruders - the SET_DUAL_CARRIAGE
-command is often called at the same time as the ACTIVATE_EXTRUDER
-command. Be sure to park the carriages during deactivation.
+Support for cartesian and hybrid_corexy/z printers with dual carriages
+on a single axis. The carriage mode can be set via the
+SET_DUAL_CARRIAGE extended g-code command. For example,
+"SET_DUAL_CARRIAGE CARRIAGE=1" command will activate the carriage defined
+in this section (CARRIAGE=0 will return activation to the primary carriage).
+Dual carriage support is typically combined with extra extruders - the
+SET_DUAL_CARRIAGE command is often called at the same time as the
+ACTIVATE_EXTRUDER command. Be sure to park the carriages during deactivation.
+Additionally, one could use "SET_DUAL_CARRIAGE CARRIAGE=1 MODE=COPY" or
+"SET_DUAL_CARRIAGE CARRIAGE=1 MODE=MIRROR" commands to activate either copying
+or mirroring mode of the dual carriage, in which case it will follow the
+motion of the carriage 0 accordingly. These commands can be used to print
+two parts simultaneously - either two identical parts (in COPY mode) or
+mirrored parts (in MIRROR mode). Note that COPY and MIRROR modes also require
+appropriate configuration of the extruder on the dual carriage, which can
+typically be achieved with
+"SYNC_EXTRUDER_MOTION MOTION_QUEUE=extruder EXTRUDER=<dual_carriage_extruder>"
+or a similar command.
 
 See [sample-idex.cfg](../config/sample-idex.cfg) for an example
 configuration.
@@ -2024,6 +2034,15 @@ configuration.
 axis:
 #   The axis this extra carriage is on (either x or y). This parameter
 #   must be provided.
+#safe_distance:
+#   The minimum distance (in mm) to enforce between the dual and the primary
+#   carriages. If a G-Code command is executed that will bring the carriages
+#   closer than the specified limit, such a command will be rejected with an
+#   error. If safe_distance is not provided, it will be inferred from
+#   position_min and position_max for the dual and primary carriages. If set
+#   to 0 (or safe_distance is unset and position_min and position_max are
+#   identical for the primary and dual carraiges), the carriages proximity
+#   checks will be disabled.
 #step_pin:
 #dir_pin:
 #enable_pin:
diff --git a/docs/G-Codes.md b/docs/G-Codes.md
index a6d056bf..470f40a5 100644
--- a/docs/G-Codes.md
+++ b/docs/G-Codes.md
@@ -310,9 +310,33 @@ The following command is available when the
 enabled.
 
 #### SET_DUAL_CARRIAGE
-`SET_DUAL_CARRIAGE CARRIAGE=[0|1]`: This command will set the active
-carriage. It is typically invoked from the activate_gcode and
-deactivate_gcode fields in a multiple extruder configuration.
+`SET_DUAL_CARRIAGE CARRIAGE=[0|1] [MODE=[PRIMARY|COPY|MIRROR]]`:
+This command will change the mode of the specified carriage.
+If no `MODE` is provided it defaults to `PRIMARY`. Setting the mode
+to `PRIMARY` deactivates the other carriage and makes the specified
+carriage execute subsequent G-Code commands as-is. `COPY` and `MIRROR`
+modes are supported only for `CARRIAGE=1`. When set to either of these
+modes, carriage 1 will then track the subsequent moves of the carriage 0
+and either copy relative movements of it (in `COPY` mode) or execute them
+in the opposite (mirror) direction (in `MIRROR` mode).
+
+#### SAVE_DUAL_CARRIAGE_STATE
+`SAVE_DUAL_CARRIAGE_STATE [NAME=<state_name>]`: Save the current positions
+of the dual carriages and their modes. Saving and restoring DUAL_CARRIAGE
+state can be useful in scripts and macros, as well as in homing routine
+overrides. If NAME is provided it allows one to name the saved state
+to the given string. If NAME is not provided it defaults to "default".
+
+#### RESTORE_DUAL_CARRIAGE_STATE
+`RESTORE_DUAL_CARRIAGE_STATE [NAME=<state_name>] [MOVE=[0|1] [MOVE_SPEED=<speed>]]`:
+Restore the previously saved positions of the dual carriages and their modes,
+unless "MOVE=0" is specified, in which case only the saved modes will be
+restored, but not the positions of the carriages. If positions are being
+restored and "MOVE_SPEED" is specified, then the toolhead moves will be
+performed with the given speed (in mm/s); otherwise the toolhead move will
+use the rail homing speed. Note that the carriages restore their positions
+only over their own axis, which may be necessary to correctly restore COPY
+and MIRROR mode of the dual carraige.
 
 ### [endstop_phase]
 
diff --git a/docs/Resonance_Compensation.md b/docs/Resonance_Compensation.md
index d168748f..aaeaf7ab 100644
--- a/docs/Resonance_Compensation.md
+++ b/docs/Resonance_Compensation.md
@@ -418,18 +418,34 @@ if necessary.
 
 ### Is dual carriage setup supported with input shapers?
 
-There is no dedicated support for dual carriages with input shapers, but it does
-not mean this setup will not work. One should run the tuning twice for each
-of the carriages, and calculate the ringing frequencies for X and Y axes for
-each of the carriages independently. Then put the values for carriage 0 into
-[input_shaper] section, and change the values on the fly when changing
-carriages, e.g. as a part of some macro:
+Yes. In this case, one should measure the resonances twice for each carriage.
+For example, if the second (dual) carriage is installed on X axis, it is
+possible to set different input shapers for X axis for the primary and dual
+carriages. However, the input shaper for Y axis should be the same for both
+carriages (as ultimately this axis is driven by one or more stepper motors each
+commanded to perform exactly the same steps). One possibility to configure
+the input shaper for such setups is to keep `[input_shaper]` section empty and
+additionally define a `[delayed_gcode]` section in the `printer.cfg` as follows:
 ```
-SET_DUAL_CARRIAGE CARRIAGE=1
-SET_INPUT_SHAPER SHAPER_FREQ_X=... SHAPER_FREQ_Y=...
+[input_shaper]
+# Intentionally empty
+
+[delayed_gcode init_shaper]
+initial_duration: 0.1
+gcode:
+  SET_DUAL_CARRIAGE CARRIAGE=1
+  SET_INPUT_SHAPER SHAPER_TYPE_X=<dual_carriage_shaper> SHAPER_FREQ_X=<dual_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq>
+  SET_DUAL_CARRIAGE CARRIAGE=0
+  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>
 ```
+Note that `SHAPER_TYPE_Y` and `SHAPER_FREQ_Y` should be the same in both
+commands. It is also possible to put a similar snippet into the start g-code
+in the slicer, however then the shaper will not be enabled until any print
+is started.
 
-And similarly when switching back to carriage 0.
+Note that the input shaper only needs to be configured once. Subsequent changes
+of the carriages or their modes via `SET_DUAL_CARRIAGE` command will preserve
+the configured input shaper parameters.
 
 ### Does input_shaper affect print time?
 
diff --git a/docs/Status_Reference.md b/docs/Status_Reference.md
index 48aeb0fd..dc32f02a 100644
--- a/docs/Status_Reference.md
+++ b/docs/Status_Reference.md
@@ -503,10 +503,11 @@ The following information is available in the `toolhead` object
 
 The following information is available in
 [dual_carriage](Config_Reference.md#dual_carriage)
-on a hybrid_corexy or hybrid_corexz robot
-- `mode`: The current mode. Possible values are: "FULL_CONTROL"
-- `active_carriage`: The current active carriage.
-Possible values are: "CARRIAGE_0", "CARRIAGE_1"
+on a cartesian, hybrid_corexy or hybrid_corexz robot
+- `carriage_0`: The mode of the carriage 0. Possible values are:
+  "INACTIVE" and "PRIMARY".
+- `carriage_1`: The mode of the carriage 1. Possible values are:
+  "INACTIVE", "PRIMARY", "COPY", and "MIRROR".
 
 ## virtual_sdcard