firmware_retraction: Support nozzle lifting on G10

.gitignore

@@ -4,3 +4,7 @@ out
 .config
 .config.old
 klippy/.version
+klippy/extras/_ToDos
+klippy/extras/tmc.py
+klippy/extras/gcode_shell_command.py
+.vscode

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "cmake.configureOnOpen": false
+}

docs/Config_Reference.md

@@ -1511,17 +1511,60 @@ allowing per-filament settings and runtime tuning.
 
 ```
 [firmware_retraction]
-#retract_length: 0
-#   The length of filament (in mm) to retract when G10 is activated,
-#   and to unretract when G11 is activated (but see
-#   unretract_extra_length below). The default is 0 mm.
-#retract_speed: 20
-#   The speed of retraction, in mm/s. The default is 20 mm/s.
-#unretract_extra_length: 0
-#   The length (in mm) of *additional* filament to add when
-#   unretracting.
-#unretract_speed: 10
-#   The speed of unretraction, in mm/s. The default is 10 mm/s.
+#retract_length: 0.0
+#   The length of filament (in mm) to retract when a G10 command is
+#   executed. When a G11 command is executed, the unretract_length
+#   is the sum of the retract_length and the unretract_extra_length
+#   (see below). The minimum value and default are 0 mm, which
+#   disables firmware retraction.
+#retract_speed: 20.0
+#   The speed of filament retraction moves (in mm/s).
+#   This value is typically set relatively high (>40 mm/s),
+#   except for soft and/oozy filaments like TPU and PETG
+#   (20 to 30 mm/s). The minimum value is 1 mm/s, the default value
+#   is 20 mm/s.
+#unretract_extra_length: 0.0
+#   The *additional* length (in mm) to add or the length to subtract
+#   from the filament move when unretracting compared to the retract
+#   move length. This allows priming the nozzle (positive extra length)
+#   or delaying extrusion after unretracting (negative length). The
+#   latter may help reduce blobbing. The minimum value is -1 mm
+#   (2.41 mm3 volume for 1.75 mm filament), the default value is 0 mm.
+#unretract_speed: 10.0
+#   The speed of filament unretraction moves (in mm/s).
+#   This parameter is not particularly critical, although often lower
+#   than retract_speed. The minimum value is 1 mm/s, the default value
+#   is 10 mm/s.
+#z_hop_height: 0.0
+#   The vertical height by which the nozzle is lifted from the print to
+#   prevent collisions with the print during travel moves when retracted.
+#   The minimum value is 0 mm, the default value is 0 mm, which disables
+#   zhop moves.
+#z_hop_style: standard
+#   The type of lifting movement of the nozzle if zhop moves are
+#   enabled. Supported move types are standard, helix and ramp.
+#   'standard' corresponds to a simple vertical lift movement. 'helix'
+#   combines the vertical lift movement with a circular movement of
+#   the nozzle. This increases the effective move length during nozzle
+#   lifting and therefore produces thinner strings that break faster. It
+#   may therefore be beneficial for oozy filaments and is the standard
+#   setting in BambuStudio. 'ramp' does not immediately cause the
+#   nozzle to lift vertically upon retraction but instead adds the
+#   corresponding vertical movement component to the travel move
+#   following the retraction. This reduces overall travel distance and
+#   may reduce print time slightly. The default value is 'standard'.
+#verbose: False
+#   This enables (True) or disables (False) user messages, which may
+#   be used for debugging when using firmware retraction in macros.
+#   The default value is False.
+#config_params_on_clear: True
+#   This allows the User to control the behavior of the module when
+#   the retraction state is cleared other than by using the G11
+#   command while filament moves are possible (hotend temperature
+#   above minimum for extrusion). If the retract state is cleared and
+#   'config_params_on_clear' is set to 'True', any changes made to the firmware
+#   retraction parameters, using the SET_RETRACTION command, will be reset to
+#   config values.
 ```
 
 ### [gcode_arcs]

docs/G-Codes.md

@@ -485,35 +485,84 @@ will be disabled, if set to 1 it is enabled.
 
 The following standard G-Code commands are available when the
 [firmware_retraction config section](Config_Reference.md#firmware_retraction)
-is enabled. These commands allow you to utilize the firmware
-retraction feature available in many slicers, to reduce stringing
-during non-extrusion moves from one part of the print to another.
-Appropriately configuring pressure advance reduces the length of
-retraction required.
-- `G10`: Retracts the extruder using the currently configured
-  parameters.
-- `G11`: Unretracts the extruder using the currently configured
-  parameters.
-
-The following additional commands are also available.
+is enabled. These commands allow utilizing the firmware
+retraction feature available in many slicers. Retraction is a strategy to
+reduce stringing during travel moves (non-extrusion) from one part of the
+print to another. Note that pressure advance should be properly configured
+before retraction parameters are tuned to ensure optimal results.
+- `G10`: Retracts the filament using the currently configured
+  parameters. If z_hop_height is set to a value greater cero,
+  besides retracting the filament, the nozzle is lifted by set value.
+- `G11`: Unretracts the filament using the currently configured
+  parameters. If z_hop_height is set to a value greater cero,
+  besides unretracting the filament, the nozzle is lowered back on the print
+  with a vertical movement.
+
+The following additional commands are available.
 
 #### SET_RETRACTION
 `SET_RETRACTION [RETRACT_LENGTH=<mm>] [RETRACT_SPEED=<mm/s>]
-[UNRETRACT_EXTRA_LENGTH=<mm>] [UNRETRACT_SPEED=<mm/s>]`: Adjust the
-parameters used by firmware retraction. RETRACT_LENGTH determines the
-length of filament to retract and unretract. The speed of retraction
-is adjusted via RETRACT_SPEED, and is typically set relatively
-high. The speed of unretraction is adjusted via UNRETRACT_SPEED, and
-is not particularly critical, although often lower than RETRACT_SPEED.
-In some cases it is useful to add a small amount of additional length
-on unretraction, and this is set via UNRETRACT_EXTRA_LENGTH.
-SET_RETRACTION is commonly set as part of slicer per-filament
-configuration, as different filaments require different parameter
-settings.
+[UNRETRACT_EXTRA_LENGTH=<mm>] [UNRETRACT_SPEED=<mm/s>] [Z_HOP_HEIGHT=<mm>]
+[Z_HOP_STYLE=<STANDARD,HELIX,RAMP>]`:
+Adjust the parameters used by firmware retraction.
+RETRACT_LENGTH determines the length of filament to retract (the minimum
+as well as standard value is 0 mm).
+RETRACT_SPEED determines the speed of the filament retraction move (the
+minimum value is 1 mm/s, the standard value is 20 mm/s). This value is
+typically set relatively high (>40 mm/s), except for soft and/or oozy filaments
+like TPU and PETG (20 to 30 mm/s).
+UNRETRACT_SPEED sets the speed of the filament unretract move (the
+minimum value is 1 mm/s, the standard value is 10 mm/s). This
+parameter is not particularly critical, although often lower than RETRACT_SPEED.
+UNRETRACT_EXTRA_LENGTH allows to add a small amount of length to the filament
+unretract move to prime the nozzle or to subtract a small amount of length from
+the filament unretract move to reduce blobbing at seams (the minimum value is
+-1 mm (2.41 mm3 volume for 1.75 mm filament), the standard value is 0 mm).
+Z_HOP_HEIGHT determines the vertical height by which the nozzle is lifted from
+the print to prevent collisions with the print during travel moves (the
+minimum value is 0 mm, the standard value is 0 mm, which disables Z-Hop moves).
+Z_HOP_STYLE allows you to choose the type of lifting movement of the nozzle.
+Three options are available: (1) Standard: vertical lift movement,
+(2) Helix: full circular movement combined with vertical lift and, (3) Ramp:
+vertical lift is performed while executing the travel move following the
+filament retraction move. Helix provides more effective move length during
+nozzle lifting and therefore thinner strings that break faster. It may therefore
+be beneficial for oozy filaments and is the standard setting in BambuStudio.
+Ramp style allows reducing the total retract-travel-unretract motion system move
+length and may have print time reduction benefits. SET_RETRACTION is commonly
+set as part of slicer per-filament configuration, as different filaments require
+different parameter settings. The command can be issued at runtime. If the
+printer is retracted while the command is issued, the command will be queued and
+executed directly after unretraction using the G11 command.
+
+#### CLEAR_RETRACTION
+`CLEAR_RETRACTION`: Clears the current retract state without extruder or
+motion system movement. All flags related to the retract state are reset to
+False, queued SET_RETRACTION commands are flushed and all changes to retraction
+parameters made via previous SET_RETRACTION commands are reset (if parameter
+`config_params_on_clear` is set to True in the config).
+NOTE: The Module contains a lot of redundancy for safety to prevent undesired
+behavior. When printing from virtual SD Card, the printer state is monitored and
+retraction state is cleared if a print is started, canceled or finished or if a
+virtual SD card file is reset. When printing via GCode streaming (e.g. using
+OctoPrint), the retract state is cleared when the steppers are disabled (M84,
+typically part of end gcode and standard behavior of OctoPrint if a print is
+canceled) or the printer is homed (G28, typically part of start gcode). Hence,
+upon ending or canceling a print as well as starting a new print via GCode
+streaming or virtual SD card, the printer should always be in unretracted state.
+Nevertheless, it is recommended to add `CLEAR_RETRACTION` to your start and end
+gcode to make sure the retract state is reset before and after each print. If a
+print is finished or canceled while retracted and the retract state is not
+cleared, either via `CLEAR_RETRACTION` without filament or motion system
+movement or G11, the nozzle will stay above the requested z coordinate by the
+set z_hop_height.
 
 #### GET_RETRACTION
-`GET_RETRACTION`: Queries the current parameters used by firmware
-retraction and displays them on the terminal.
+`GET_RETRACTION`: Queries the current parameters used by THE firmware retraction
+module as well as the retract state. RETRACT_LENGTH, RETRACT_SPEED,
+UNRETRACT_EXTRA_LENGTH, UNRETRACT_SPEED, Z_HOP_HEIGHT, Z_HOP_STYLE, RETRACTED
+(True, if retracted) and RAMP_MOVE (True, if upcoming move is raming up to Z-Hop
+height) are displayed on the terminal.
 
 ### [force_move]
 

docs/Status_Reference.md

@@ -162,11 +162,22 @@ objects:
 ## firmware_retraction
 
 The following information is available in the
-[firmware_retraction](Config_Reference.md#firmware_retraction) object:
-- `retract_length`, `retract_speed`, `unretract_extra_length`,
-  `unretract_speed`: The current settings for the firmware_retraction
-  module. These settings may differ from the config file if a
-  `SET_RETRACTION` command alters them.
+[firmware_retraction](Config_Reference.md#firmware_retraction) object ():
+- `retract_length`: Current setting for length of filament retract moves.
+- `retract_speed`: Current setting for speed of filament retract moves.
+- `unretract_extra_length`: Current setting for additional length of filament
+  unretract moves (positive values will result in filament extrusion, while
+  negative values up to 1 mm (2.41 mm3 for 1.75 mm filament) will result in
+  lagging extrusion of filament).
+- `unretract_speed`: Current setting for speed of unretract moves of filament.
+- `unretract_length`: Unretract move length (sum of retract and extra unretract
+   length).
+- `z_hop_height`: Current setting for the height of nozzle lifting move (Z-Hop).
+- `z_hop_style`: Current setting for the style of Z-Hop move.
+- Above settings for the firmware_retraction module may differ from the
+  config file if a `SET_RETRACTION` command altered them. Additional information
+  available is as follows.
+- `retract_state`: Returns 'True' if filament is retracted.
 
 ## gcode_button