docs: dual_carriage

Added an STL for calibration, some gcode macros to the sample idex config, and an entire document on configuring an idex printer.

Signed-off-by: Charles Pickering <[email protected]>

config/sample-idex.cfg

@@ -1,7 +1,13 @@
 # This file contains a configuration snippet for a dual extruder
 # printer using dual carriages (an "IDEX" printer).
 
+# The most common IDEX setup is to have 2 X carraiges, but 2 Y
+# carraiges is also possible. You will need to update the macros
+# and stepper definitions accordingly to do this.
+
 # See docs/Config_Reference.md for a description of parameters.
+# See docs/Dual_Carriage.md for further details on certain modules in
+# this document.
 
 # Definition for the primary carriage (holding the primary extruder)
 [stepper_x]
@@ -94,3 +100,53 @@ gcode:
     ACTIVATE_EXTRUDER EXTRUDER=extruder1
     SET_DUAL_CARRIAGE CARRIAGE=1
     SET_GCODE_OFFSET Y=15
+
+[gcode_macro calibrate_separation]
+# YOU MUST CALIBRATE YOUR ROTATION_DISTANCE BEFORE THIS IS USEFUL!!!
+# Configure this to draw 2 line segments perpendicular to the dual_carraige axis
+# that meet in the middle of the bed. Both lines should have the same coordinate
+# on the axis of the dual_carraige. If they don't print inline, adjust your endstop
+# settings.
+gcode:
+    G28
+    G90
+    M83
+    T0 ; test T0
+    G1 X120 Y150 Z.2 F4800
+    G1 Y75 E10
+    T1 ; test T1
+    G1 X120 Y0 Z.2
+    G1 Y75 E10
+
+# The following is for if your carraiges have their own part cooling fans.
+# Since this macro overrides M106, you cannot also have a [fan] section defined.
+# If your printer only has one part cooling fan, don't copy this section
+[fan_generic part_fan_0]
+pin: PE5
+
+[fan_generic part_fan_1]
+pin: PD13
+
+[gcode_macro M106]
+gcode:
+    {% if params.S is defined %}
+        {% set fanspeed = params.S|int %}
+    {% endif %}
+    {% if fanspeed < 0 %}
+        {% set fanspeed = 0 %}
+    {% endif %}
+    {% if fanspeed > 255 %}
+        {% set fanspeed = 255 %}
+    {% endif %}
+    {% if params.P is defined %}
+        {% if params.P|int == 0 %}
+            {% set target = "part_fan_0" %}
+        {% endif %}
+        {% if params.P|int == 1 %}
+            {% set target = "part_fan_1" %}
+        {% endif %}
+    {% else %}
+            {% set target = "part_fan_0" %}
+    {% endif %}
+    {% set internalSpeed = fanspeed / 255 %}
+    SET_FAN_SPEED FAN={target} SPEED={internalSpeed}

docs/Dual_Carriage.md

@@ -0,0 +1,98 @@
+This document provides **general** information on configuring and
+calibrating a standard IDEX printer. Klipper has support for very
+complex IDEX configurations, with multiple hotends and extruders on a
+single carriage, independent or grouped cooling fans, and much more,
+which are not covered in this document.
+
+# General configuration
+Start with studying, and possibly using parts of the [example config](../config/sample-idex.cfg)
+for IDEX printers. It has some distinct items that you may or may not
+wish to use.
+* Definition for `dual_carriage` on the X-axis, which you can change to
+be on the Y axis if that is how your printer is configured.
+* Sample macros for parking and switching toolheads. You should check
+these to make sure they make sense for your setup and update the
+position values with those that match your printer
+* Configuration for multiple part cooling fans. The `[fan]` module in
+Klipper only supports a single controllable fan. If you would like to
+have independently controlled part cooling fans, do not configure a
+`[fan]` section and use the template provided in the file.
+* A macro for calibrating carriage separation described later in this
+document.
+
+# Tuning
+If you want to use both extruders to print different features of a
+single object, Klipper will need to know the positions of the extruders
+relative to each other.
+
+Because Klipper configures this by the endstop position, you will
+need to calibrate your [rotation distance](Rotation_Distance.md) first.
+
+## Step 1 (~5mm)
+Start by literally eyeballing it. Put a piece of tape on your bed or
+use a line or other graphic already on your bed as a reference point.
+
+Move the first carriage to this point and note it's position on the
+axis with both carriages. Then, park carriage 1, and move carriage 2 to
+the same physical position. Note it's position (where Klipper "thinks"
+it is) and calculate the difference.
+
+In a standard setup where the carriages home to the sides with the
+primary on the left, you move the logical coordinate system for the
+secondary extruder to the right by lowering it's `position_endstop`
+value.
+
+Once you are within a few mm of accuracy, proceed to step 2
+
+## Step 2 (~1mm)
+Configure the `calibrate_separation` macro in [the sample config](../config/sample-idex.cfg)
+for your bed size and dual_carriage axis, and add heating commands to
+it for the filament you'll be using.
+
+Load filament in both extruders, and run the macro.
+
+The test with the standard axis configuration should look as follows:
+
+![measuring print](img/separation-lines.png)
+
+Note the lines should be colinear. If they are not, adjust your
+`position_endstop` setting as noted in step 1. Once they are visually
+aligned, proceed to step 3.
+
+## Step 3 (~0.05mm)
+While the measuring process of this step accounts for symmetric
+horizontal expansion, you will likely achieve better results by
+calibrating the flow, temperature, and pressure advance for the
+filament you'll be using first. You'll also do better with a filament
+that is known to have better dimensional stability. Look for filaments
+that can be printed without a heated bed.
+
+Use a slicer to generate g-code for the multi-part print found in
+[docs/prints/calibrate_idex.stl](prints/calibrate_idex.stl).
+Align the slot down the middle with the axis of your `dual_carriage`.
+Configure your slicer to print the 2 parts using extruders on opposite
+carriages. I highly recommend using identical filaments printed with
+the same temperature, etc. Nothing else matters as long as the wall
+quality is smooth. Print the object.
+
+Use calipers to measure the inner and outer distances as follows.
+Average your inner and outer measurements, calculate the difference
+from the nominal value (which is 40mm), and adjust your `position_endstop`
+setting as noted in step 1.
+
+![measuring print](img/separation-block.png)
+
+# Next steps
+At this point you should re-tune your mins and maxes for each axis when
+the other is parked by issuing slow, small movements until they
+collide.
+
+Configure a homing override to make sure that the inactive carriage is
+fully parked in all scenarios.
+
+If you want to use [input shaping](Resonance_compensation.md),
+calibrate the input shaper for each carriage separately and add g-code
+to your `T0` and `T1` etc commands to configure the input shaper when
+the active carriage changes.
+
+Print a few objects to ensure everything is working as expected!

docs/Overview.md

@@ -52,6 +52,8 @@ communication with the Klipper developers.
   perfectly square.
 - [PWM tools](Using_PWM_Tools.md): Guide on how to use PWM controlled
   tools such as lasers or spindles.
+- [IDEX printers](Dual_Carriage.md): Guide on setting up and calibrating
+  an IDEX printer.
 - [G-Codes](G-Codes.md): Information on commands supported by Klipper.
 
 ## Developer Documentation