🐛 Fix Tool Change priming (#21142)

Marlin/Configuration_adv.h

@@ -2442,12 +2442,16 @@
     #define TOOLCHANGE_FS_FAN_SPEED          255  // 0-255
     #define TOOLCHANGE_FS_FAN_TIME            10  // (seconds)
 
-    // Swap uninitialized extruder (using TOOLCHANGE_FS_PRIME_SPEED feedrate)
-    // (May break filament if not retracted beforehand.)
-    //#define TOOLCHANGE_FS_INIT_BEFORE_SWAP
+    // Use TOOLCHANGE_FS_PRIME_SPEED feedrate the first time each extruder is primed
+    //#define TOOLCHANGE_FS_SLOW_FIRST_PRIME
 
-    // Prime on the first T0 (For other tools use TOOLCHANGE_FS_INIT_BEFORE_SWAP)
-    // Enable with M217 V1 before printing to avoid unwanted priming on host connect
+    /**
+     * Prime T0 the first time T0 is sent to the printer:
+     *  [ Power-On -> T0 { Activate & Prime T0 } -> T1 { Retract T0, Activate & Prime T1 } ]
+     * If disabled, no priming on T0 until switching back to T0 from another extruder:
+     *  [ Power-On -> T0 { T0 Activated } -> T1 { Activate & Prime T1 } -> T0 { Retract T1, Activate & Prime T0 } ]
+     * Enable with M217 V1 before printing to avoid unwanted priming on host connect.
+     */
     //#define TOOLCHANGE_FS_PRIME_FIRST_USED
 
     /**

Marlin/src/gcode/config/M217.cpp

@@ -34,28 +34,28 @@
 #include "../../MarlinCore.h" // for SP_X_STR, etc.
 
 /**
- * M217 - Set SINGLENOZZLE toolchange parameters
+ * M217 - Set toolchange parameters
  *
  *  // Tool change command
  *  Q           Prime active tool and exit
  *
  *  // Tool change settings
- *  S[linear]   Swap length
- *  B[linear]   Extra Swap length
- *  E[linear]   Prime length
- *  P[linear/m] Prime speed
- *  R[linear/m] Retract speed
- *  U[linear/m] UnRetract speed
- *  V[linear]   0/1 Enable auto prime first extruder used
- *  W[linear]   0/1 Enable park & Z Raise
- *  X[linear]   Park X (Requires TOOLCHANGE_PARK)
- *  Y[linear]   Park Y (Requires TOOLCHANGE_PARK)
- *  I[linear]   Park I (Requires TOOLCHANGE_PARK and LINEAR_AXES >= 4)
- *  J[linear]   Park J (Requires TOOLCHANGE_PARK and LINEAR_AXES >= 5)
- *  K[linear]   Park K (Requires TOOLCHANGE_PARK and LINEAR_AXES >= 6)
- *  Z[linear]   Z Raise
- *  F[linear]   Fan Speed 0-255
- *  G[linear/s] Fan time
+ *  S[linear]     Swap length
+ *  B[linear]     Extra Swap resume length
+ *  E[linear]     Extra Prime length (as used by M217 Q)
+ *  P[linear/min] Prime speed
+ *  R[linear/min] Retract speed
+ *  U[linear/min] UnRetract speed
+ *  V[linear]     0/1 Enable auto prime first extruder used
+ *  W[linear]     0/1 Enable park & Z Raise
+ *  X[linear]     Park X (Requires TOOLCHANGE_PARK)
+ *  Y[linear]     Park Y (Requires TOOLCHANGE_PARK)
+ *  I[linear]     Park I (Requires TOOLCHANGE_PARK and NUM_AXES >= 4)
+ *  J[linear]     Park J (Requires TOOLCHANGE_PARK and NUM_AXES >= 5)
+ *  K[linear]     Park K (Requires TOOLCHANGE_PARK and NUM_AXES >= 6)
+ *  Z[linear]     Z Raise
+ *  F[speed]      Fan Speed 0-255
+ *  D[seconds]    Fan time
  *
  * Tool migration settings
  *  A[0|1]      Enable auto-migration on runout
@@ -79,8 +79,8 @@ void GcodeSuite::M217() {
     if (parser.seenval('R')) { const int16_t v = parser.value_linear_units(); toolchange_settings.retract_speed = constrain(v, 10, 5400); }
     if (parser.seenval('U')) { const int16_t v = parser.value_linear_units(); toolchange_settings.unretract_speed = constrain(v, 10, 5400); }
     #if TOOLCHANGE_FS_FAN >= 0 && HAS_FAN
-      if (parser.seenval('F')) { const int16_t v = parser.value_linear_units(); toolchange_settings.fan_speed = constrain(v, 0, 255); }
-      if (parser.seenval('G')) { const int16_t v = parser.value_linear_units(); toolchange_settings.fan_time = constrain(v, 1, 30); }
+      if (parser.seenval('F')) { const uint16_t v = parser.value_ushort(); toolchange_settings.fan_speed = constrain(v, 0, 255); }
+      if (parser.seenval('D')) { const uint16_t v = parser.value_ushort(); toolchange_settings.fan_time = constrain(v, 1, 30); }
     #endif
   #endif
 
@@ -159,7 +159,7 @@ void GcodeSuite::M217_report(const bool forReplay/*=true*/) {
     SERIAL_ECHOPGM(" R", LINEAR_UNIT(toolchange_settings.retract_speed),
                    " U", LINEAR_UNIT(toolchange_settings.unretract_speed),
                    " F", toolchange_settings.fan_speed,
-                   " G", toolchange_settings.fan_time);
+                   " D", toolchange_settings.fan_time);
 
     #if ENABLED(TOOLCHANGE_MIGRATION_FEATURE)
       SERIAL_ECHOPGM(" A", migration.automode);

Marlin/src/inc/SanityCheck.h

@@ -390,6 +390,8 @@
   #error "ENDSTOP_NOISE_FILTER is now ENDSTOP_NOISE_THRESHOLD [2-7]."
 #elif defined(RETRACT_ZLIFT)
   #error "RETRACT_ZLIFT is now RETRACT_ZRAISE."
+#elif defined(TOOLCHANGE_FS_INIT_BEFORE_SWAP)
+  #error "TOOLCHANGE_FS_INIT_BEFORE_SWAP is now TOOLCHANGE_FS_SLOW_FIRST_PRIME."
 #elif defined(TOOLCHANGE_PARK_ZLIFT) || defined(TOOLCHANGE_UNPARK_ZLIFT)
   #error "TOOLCHANGE_PARK_ZLIFT and TOOLCHANGE_UNPARK_ZLIFT are now TOOLCHANGE_ZRAISE."
 #elif defined(SINGLENOZZLE_TOOLCHANGE_ZRAISE)

Marlin/src/lcd/menu/menu_configuration.cpp

@@ -124,8 +124,8 @@ void menu_advanced_settings();
       EDIT_ITEM_FAST(int4, MSG_SINGLENOZZLE_UNRETRACT_SPEED, &toolchange_settings.unretract_speed, 10, 5400);
       EDIT_ITEM(float3, MSG_FILAMENT_PURGE_LENGTH, &toolchange_settings.extra_prime, 0, max_extrude);
       EDIT_ITEM_FAST(int4, MSG_SINGLENOZZLE_PRIME_SPEED, &toolchange_settings.prime_speed, 10, 5400);
-      EDIT_ITEM_FAST(int4, MSG_SINGLENOZZLE_FAN_SPEED, &toolchange_settings.fan_speed, 0, 255);
-      EDIT_ITEM_FAST(int4, MSG_SINGLENOZZLE_FAN_TIME, &toolchange_settings.fan_time, 1, 30);
+      EDIT_ITEM_FAST(uint8, MSG_SINGLENOZZLE_FAN_SPEED, &toolchange_settings.fan_speed, 0, 255);
+      EDIT_ITEM_FAST(uint8, MSG_SINGLENOZZLE_FAN_TIME, &toolchange_settings.fan_time, 1, 30);
     #endif
     EDIT_ITEM(float3, MSG_TOOL_CHANGE_ZLIFT, &toolchange_settings.z_raise, 0, 10);
     END_MENU();