Clean up and document load/unload/pause/resume

Marlin/src/feature/pause.cpp

@@ -83,6 +83,15 @@ float filament_change_unload_length[EXTRUDERS],
   }
 #endif
 
+/**
+ * Ensure a safe temperature for extrusion
+ *
+ * - Fail if the TARGET temperature is too low
+ * - Display LCD placard with temperature status
+ * - Return when heating is done or aborted
+ *
+ * Returns 'true' if heating was completed, 'false' for abort
+ */
 static bool ensure_safe_temperature(const AdvancedPauseMode mode=ADVANCED_PAUSE_MODE_PAUSE_PRINT) {
 
   #if ENABLED(PREVENT_COLD_EXTRUSION)
@@ -115,7 +124,19 @@ static void do_pause_e_move(const float &length, const float &fr) {
   set_current_from_destination();
 }
 
-bool load_filament(const float &load_length/*=0*/, const float &extrude_length/*=0*/, const int8_t max_beep_count/*=0*/,
+/**
+ * Load filament into the hotend
+ *
+ * - Fail if the a safe temperature was not reached
+ * - If pausing for confirmation, wait for a click or M108
+ * - Show "wait for load" placard
+ * - Load and purge filament
+ * - Show "Purge more" / "Continue" menu
+ * - Return when "Continue" is selected
+ *
+ * Returns 'true' if load was completed, 'false' for abort
+ */
+bool load_filament(const float &load_length/*=0*/, const float &purge_length/*=0*/, const int8_t max_beep_count/*=0*/,
                           const bool show_lcd/*=false*/, const bool pause_for_user/*=false*/,
                           const AdvancedPauseMode mode/*=ADVANCED_PAUSE_MODE_PAUSE_PRINT*/
 ) {
@@ -158,15 +179,15 @@ bool load_filament(const float &load_length/*=0*/, const float &extrude_length/*
   }
 
   #if ENABLED(ULTIPANEL)
-    if (show_lcd) // Show "load" message
+    if (show_lcd) // Show "wait for load" message
       lcd_advanced_pause_show_message(ADVANCED_PAUSE_MESSAGE_LOAD, mode);
   #endif
 
   // Load filament
-  do_pause_e_move(load_length, FILAMENT_CHANGE_LOAD_FEEDRATE);
+  if (load_length) do_pause_e_move(load_length, FILAMENT_CHANGE_LOAD_FEEDRATE);
 
   do {
-    if (extrude_length > 0) {
+    if (purge_length > 0) {
       // "Wait for filament purge"
       #if ENABLED(ULTIPANEL)
         if (show_lcd)
@@ -174,10 +195,10 @@ bool load_filament(const float &load_length/*=0*/, const float &extrude_length/*
       #endif
 
       // Extrude filament to get into hotend
-      do_pause_e_move(extrude_length, ADVANCED_PAUSE_EXTRUDE_FEEDRATE);
+      do_pause_e_move(purge_length, ADVANCED_PAUSE_EXTRUDE_FEEDRATE);
     }
 
-    // Show "Extrude More" / "Resume" menu and wait for reply
+    // Show "Purge More" / "Resume" menu and wait for reply
     #if ENABLED(ULTIPANEL)
       if (show_lcd) {
         KEEPALIVE_STATE(PAUSED_FOR_USER);
@@ -188,7 +209,7 @@ bool load_filament(const float &load_length/*=0*/, const float &extrude_length/*
       }
     #endif
 
-    // Keep looping if "Extrude More" was selected
+    // Keep looping if "Purge More" was selected
   } while (
     #if ENABLED(ULTIPANEL)
       show_lcd && advanced_pause_menu_response == ADVANCED_PAUSE_RESPONSE_EXTRUDE_MORE
@@ -200,6 +221,16 @@ bool load_filament(const float &load_length/*=0*/, const float &extrude_length/*
   return true;
 }
 
+/**
+ * Unload filament from the hotend
+ *
+ * - Fail if the a safe temperature was not reached
+ * - Show "wait for unload" placard
+ * - Retract, pause, then unload filament
+ * - Disable E stepper (on most machines)
+ *
+ * Returns 'true' if unload was completed, 'false' for abort
+ */
 bool unload_filament(const float &unload_length, const bool show_lcd/*=false*/,
                             const AdvancedPauseMode mode/*=ADVANCED_PAUSE_MODE_PAUSE_PRINT*/
 ) {
@@ -242,6 +273,19 @@ bool unload_filament(const float &unload_length, const bool show_lcd/*=false*/,
 
 // public:
 
+/**
+ * Pause procedure
+ *
+ * - Abort if already paused
+ * - Send host action for pause, if configured
+ * - Abort if TARGET temperature is too low
+ * - Display "wait for start of filament change" (if a length was specified)
+ * - Initial retract, if current temperature is hot enough
+ * - Park the nozzle at the given position
+ * - Call unload_filament (if a length was specified)
+ *
+ * Returns 'true' if pause was completed, 'false' for abort
+ */
 uint8_t did_pause_print = 0;
 
 bool pause_print(const float &retract, const point_t &park_point, const float &unload_length/*=0*/, const bool show_lcd/*=false*/) {
@@ -277,7 +321,7 @@ bool pause_print(const float &retract, const point_t &park_point, const float &u
   #if ENABLED(SDSUPPORT)
     if (card.sdprinting) {
       card.pauseSDPrint();
-      ++did_pause_print;
+      ++did_pause_print; // Indicate SD pause also
     }
   #endif
   print_job_timer.pause();
@@ -302,6 +346,13 @@ bool pause_print(const float &retract, const point_t &park_point, const float &u
   return true;
 }
 
+/**
+ * - Show "Insert filament and press button to continue"
+ * - Wait for a click before returning
+ * - Heaters can time out, reheated before accepting a click
+ *
+ * Used by M125 and M600
+ */
 void wait_for_filament_reload(const int8_t max_beep_count/*=0*/) {
   bool nozzle_timed_out = false;
 
@@ -388,12 +439,29 @@ void wait_for_filament_reload(const int8_t max_beep_count/*=0*/) {
   KEEPALIVE_STATE(IN_HANDLER);
 }
 
-void resume_print(const float &load_length/*=0*/, const float &extrude_length/*=ADVANCED_PAUSE_EXTRUDE_LENGTH*/, const int8_t max_beep_count/*=0*/) {
-  bool nozzle_timed_out = false;
-
+/**
+ * Resume or Start print procedure
+ *
+ * - Abort if not paused
+ * - Reset heater idle timers
+ * - Load filament if specified, but only if:
+ *   - a nozzle timed out, or
+ *   - the nozzle is already heated.
+ * - Display "wait for print to resume"
+ * - Re-prime the nozzle...
+ *   -  FWRETRACT: Recover/prime from the prior G10.
+ *   - !FWRETRACT: Retract by resume_position[E], if negative.
+ *                 Not sure how this logic comes into use.
+ * - Move the nozzle back to resume_position
+ * - Sync the planner E to resume_position[E]
+ * - Send host action for resume, if configured
+ * - Resume the current SD print job, if any
+ */
+void resume_print(const float &load_length/*=0*/, const float &purge_length/*=ADVANCED_PAUSE_EXTRUDE_LENGTH*/, const int8_t max_beep_count/*=0*/) {
   if (!did_pause_print) return;
 
   // Re-enable the heaters if they timed out
+  bool nozzle_timed_out = false;
   HOTEND_LOOP() {
     nozzle_timed_out |= thermalManager.is_heater_idle(e);
     thermalManager.reset_heater_idle_timer(e);
@@ -401,7 +469,7 @@ void resume_print(const float &load_length/*=0*/, const float &extrude_length/*=
 
   if (nozzle_timed_out || thermalManager.hotEnoughToExtrude(active_extruder)) {
     // Load the new filament
-    load_filament(load_length, extrude_length, max_beep_count, true, nozzle_timed_out);
+    load_filament(load_length, purge_length, max_beep_count, true, nozzle_timed_out);
   }
 
   #if ENABLED(ULTIPANEL)
@@ -415,7 +483,7 @@ void resume_print(const float &load_length/*=0*/, const float &extrude_length/*=
     if (fwretract.retracted[active_extruder])
       do_pause_e_move(-fwretract.retract_length, fwretract.retract_feedrate_mm_s);
   #else
-    // If resume_position negative
+    // If resume_position is negative
     if (resume_position[E_AXIS] < 0) do_pause_e_move(resume_position[E_AXIS], PAUSE_PARK_RETRACT_FEEDRATE);
   #endif
 

Marlin/src/gcode/feature/pause/M125.cpp

@@ -50,11 +50,11 @@
  */
 void GcodeSuite::M125() {
   // Initial retract before move to filament change position
-  const float retract = parser.seen('L') ? parser.value_axis_units(E_AXIS) : 0
+  const float retract = -FABS(parser.seen('L') ? parser.value_axis_units(E_AXIS) : 0
     #ifdef PAUSE_PARK_RETRACT_LENGTH
-      - (PAUSE_PARK_RETRACT_LENGTH)
+      + (PAUSE_PARK_RETRACT_LENGTH)
     #endif
-  ;
+  );
 
   point_t park_point = NOZZLE_PARK_POINT;
 

Marlin/src/gcode/feature/pause/M600.cpp

@@ -56,7 +56,7 @@ void GcodeSuite::M600() {
 
   if (get_target_extruder_from_command()) return;
 
-  // Show initial message
+  // Show initial "wait for start" message
   #if ENABLED(ULTIPANEL)
     lcd_advanced_pause_show_message(ADVANCED_PAUSE_MESSAGE_INIT, ADVANCED_PAUSE_MODE_PAUSE_PRINT, target_extruder);
   #endif

Marlin/src/gcode/feature/pause/M701_M702.cpp

@@ -59,7 +59,7 @@ void GcodeSuite::M701() {
   const float load_length = FABS(parser.seen('L') ? parser.value_axis_units(E_AXIS) :
                                                     filament_change_load_length[target_extruder]);
 
-  // Show initial message
+  // Show initial "wait for load" message
   #if ENABLED(ULTIPANEL)
     lcd_advanced_pause_show_message(ADVANCED_PAUSE_MESSAGE_LOAD, ADVANCED_PAUSE_MODE_LOAD_FILAMENT, target_extruder);
   #endif
@@ -112,7 +112,7 @@ void GcodeSuite::M702() {
   // Z axis lift
   if (parser.seenval('Z')) park_point.z = parser.linearval('Z');
 
-  // Show initial message
+  // Show initial "wait for unload" message
   #if ENABLED(ULTIPANEL)
     lcd_advanced_pause_show_message(ADVANCED_PAUSE_MESSAGE_UNLOAD, ADVANCED_PAUSE_MODE_UNLOAD_FILAMENT, target_extruder);
   #endif