✨ M493/M493 FT_MOTION (V2) (#608)

Co-authored-by: David Buezas <dbuezas@users.noreply.github.com>

Author: thinkyhead

_configuration/configuration.md

@@ -2738,66 +2738,91 @@ The Fixed-Time-based Motion Control (FTM) feature provides an alternative motion
 ```cpp
 /**
  * Fixed-time-based Motion Control -- BETA FEATURE
- * Enable/disable and set parameters with G-code M493.
+ * Enable/disable and set parameters with G-code M493 and M494.
  * See ft_types.h for named values used by FTM options.
  */
 //#define FT_MOTION
 #if ENABLED(FT_MOTION)
-  //#define FTM_IS_DEFAULT_MOTION                 // Use FT Motion as the factory default?
+  //#define FTM_IS_DEFAULT_MOTION               // Use FT Motion as the factory default?
+  //#define FT_MOTION_MENU                      // Provide a MarlinUI menu to set M493 and M494 parameters
+  //#define FTM_HOME_AND_PROBE                  // Use FT Motion for homing / probing. Disable if FT Motion breaks these functions.
+
   #define FTM_DEFAULT_DYNFREQ_MODE dynFreqMode_DISABLED // Default mode of dynamic frequency calculation. (DISABLED, Z_BASED, MASS_BASED)
+
+  #define FTM_LINEAR_ADV_DEFAULT_ENA   false    // Default linear advance enable (true) or disable (false)
+  #define FTM_LINEAR_ADV_DEFAULT_K      0.0f    // Default linear advance gain. (Acceleration-based scaling factor.)
+
   #define FTM_DEFAULT_SHAPER_X      ftMotionShaper_NONE // Default shaper mode on X axis (NONE, ZV, ZVD, ZVDD, ZVDDD, EI, 2HEI, 3HEI, MZV)
+  #define FTM_SHAPING_DEFAULT_FREQ_X   37.0f    // (Hz) Default peak frequency used by input shapers
+  #define FTM_SHAPING_ZETA_X            0.1f    // Zeta used by input shapers for X axis
+  #define FTM_SHAPING_V_TOL_X           0.05f   // Vibration tolerance used by EI input shapers for X axis
+
   #define FTM_DEFAULT_SHAPER_Y      ftMotionShaper_NONE // Default shaper mode on Y axis
-  #define FTM_SHAPING_DEFAULT_FREQ_X   37.0f      // (Hz) Default peak frequency used by input shapers
-  #define FTM_SHAPING_DEFAULT_FREQ_Y   37.0f      // (Hz) Default peak frequency used by input shapers
-  #define FTM_LINEAR_ADV_DEFAULT_ENA   false      // Default linear advance enable (true) or disable (false)
-  #define FTM_LINEAR_ADV_DEFAULT_K      0.0f      // Default linear advance gain. (Acceleration-based scaling factor.)
-  #define FTM_SHAPING_ZETA_X            0.1f      // Zeta used by input shapers for X axis
-  #define FTM_SHAPING_ZETA_Y            0.1f      // Zeta used by input shapers for Y axis
+  #define FTM_SHAPING_DEFAULT_FREQ_Y   37.0f    // (Hz) Default peak frequency used by input shapers
+  #define FTM_SHAPING_ZETA_Y            0.1f    // Zeta used by input shapers for Y axis
+  #define FTM_SHAPING_V_TOL_Y           0.05f   // Vibration tolerance used by EI input shapers for Y axis
+
+  //#define FTM_SHAPER_Z                        // Include Z shaping support
+  #define FTM_DEFAULT_SHAPER_Z      ftMotionShaper_NONE // Default shaper mode on Z axis
+  #define FTM_SHAPING_DEFAULT_FREQ_Z   21.0f    // (Hz) Default peak frequency used by input shapers
+  #define FTM_SHAPING_ZETA_Z            0.03f   // Zeta used by input shapers for Z axis
+  #define FTM_SHAPING_V_TOL_Z           0.05f   // Vibration tolerance used by EI input shapers for Z axis
+
+  //#define FTM_SHAPER_E                        // Include E shaping support
+                                                // Required to synchronize extruder with XYZ (better quality)
+  #define FTM_DEFAULT_SHAPER_E      ftMotionShaper_NONE // Default shaper mode on Extruder axis
+  #define FTM_SHAPING_DEFAULT_FREQ_E   21.0f    // (Hz) Default peak frequency used by input shapers
+  #define FTM_SHAPING_ZETA_E            0.03f   // Zeta used by input shapers for E axis
+  #define FTM_SHAPING_V_TOL_E           0.05f   // Vibration tolerance used by EI input shapers for E axis
+
+  //#define FTM_SMOOTHING                       // Smoothing can reduce artifacts and make steppers quieter
+                                                // on sharp corners, but too much will round corners.
+  #if ENABLED(FTM_SMOOTHING)
+    #define FTM_MAX_SMOOTHING_TIME      0.10f   // (s) Maximum smoothing time. Higher values consume more RAM.
+                                                // Increase smoothing time to reduce jerky motion, ghosting and noises.
+    #define FTM_SMOOTHING_TIME_X        0.00f   // (s) Smoothing time for X axis. Zero means disabled.
+    #define FTM_SMOOTHING_TIME_Y        0.00f   // (s) Smoothing time for Y axis
+    #define FTM_SMOOTHING_TIME_Z        0.00f   // (s) Smoothing time for Z axis
+    #define FTM_SMOOTHING_TIME_E        0.02f   // (s) Smoothing time for E axis. Prevents noise/skipping from LA by
+                                                //     smoothing acceleration peaks, which may also smooth curved surfaces.
+  #endif
 
-  #define FTM_SHAPING_V_TOL_X           0.05f     // Vibration tolerance used by EI input shapers for X axis
-  #define FTM_SHAPING_V_TOL_Y           0.05f     // Vibration tolerance used by EI input shapers for Y axis
+  #define FTM_TRAJECTORY_TYPE   TRAPEZOIDAL // Block acceleration profile (TRAPEZOIDAL, POLY5, POLY6)
+                                            // TRAPEZOIDAL: Continuous Velocity. Max acceleration is respected.
+                                            // POLY5:       Like POLY6 with 1.5x but cpu cheaper.
+                                            // POLY6:       Continuous Acceleration (aka S_CURVE).
+                                            // POLY trajectories not only reduce resonances without rounding corners, but also
+                                            // reduce extruder strain due to linear advance.
 
-  //#define FT_MOTION_MENU                        // Provide a MarlinUI menu to set M493 parameters
+  #define FTM_POLY6_ACCELERATION_OVERSHOOT 1.875f // Max acceleration overshoot factor for POLY6 (1.25 to 1.875)
 
   /**
    * Advanced configuration
    */
-  #define FTM_UNIFIED_BWS                         // DON'T DISABLE unless you use Ulendo FBS (not implemented)
+  #define FTM_UNIFIED_BWS                       // DON'T DISABLE unless you use Ulendo FBS (not implemented)
   #if ENABLED(FTM_UNIFIED_BWS)
-    #define FTM_BW_SIZE               100         // Unified Window and Batch size with a ratio of 2
+    #define FTM_BW_SIZE               100       // Unified Window and Batch size with a ratio of 2
   #else
-    #define FTM_WINDOW_SIZE           200         // Custom Window size for trajectory generation needed by Ulendo FBS
-    #define FTM_BATCH_SIZE            100         // Custom Batch size for trajectory generation needed by Ulendo FBS
+    #define FTM_WINDOW_SIZE           200       // Custom Window size for trajectory generation needed by Ulendo FBS
+    #define FTM_BATCH_SIZE            100       // Custom Batch size for trajectory generation needed by Ulendo FBS
   #endif
 
-  #define FTM_FS                     1000         // (Hz) Frequency for trajectory generation. (Reciprocal of FTM_TS)
-  #define FTM_TS                        0.001f    // (s) Time step for trajectory generation. (Reciprocal of FTM_FS)
+  #define FTM_FS                     1000       // (Hz) Frequency for trajectory generation
 
   #if DISABLED(COREXY)
-    #define FTM_STEPPER_FS          20000         // (Hz) Frequency for stepper I/O update
+    #define FTM_STEPPER_FS          20000       // (Hz) Frequency for stepper I/O update
 
     // Use this to adjust the time required to consume the command buffer.
     // Try increasing this value if stepper motion is choppy.
-    #define FTM_STEPPERCMD_BUFF_SIZE 3000         // Size of the stepper command buffers
+    #define FTM_STEPPERCMD_BUFF_SIZE 3000       // Size of the stepper command buffers
 
   #else
     // CoreXY motion needs a larger buffer size. These values are based on our testing.
     #define FTM_STEPPER_FS          30000
     #define FTM_STEPPERCMD_BUFF_SIZE 6000
   #endif
 
-  #define FTM_STEPS_PER_UNIT_TIME (FTM_STEPPER_FS / FTM_FS)       // Interpolated stepper commands per unit time
-  #define FTM_CTS_COMPARE_VAL (FTM_STEPS_PER_UNIT_TIME / 2)       // Comparison value used in interpolation algorithm
-  #define FTM_MIN_TICKS ((STEPPER_TIMER_RATE) / (FTM_STEPPER_FS)) // Minimum stepper ticks between steps
-
-  #define FTM_MIN_SHAPE_FREQ           10         // Minimum shaping frequency
-  #define FTM_RATIO (FTM_FS / FTM_MIN_SHAPE_FREQ) // Factor for use in FTM_ZMAX. DON'T CHANGE.
-  #define FTM_ZMAX (FTM_RATIO * 2)                // Maximum delays for shaping functions (even numbers only!)
-                                                  // Calculate as:
-                                                  //   ZV       : FTM_RATIO / 2
-                                                  //   ZVD, MZV : FTM_RATIO
-                                                  //   2HEI     : FTM_RATIO * 3 / 2
-                                                  //   3HEI     : FTM_RATIO * 2
+  #define FTM_MIN_SHAPE_FREQ           10       // (Hz) Minimum shaping frequency, lower consumes more RAM
 #endif // FT_MOTION
 ```
 

_development/code_structure.md

@@ -225,7 +225,7 @@ See [the Input Shaping page](/docs/features/input_shaping.html) for details on t
 ### Fixed-Time Motion
 Marlin 2.1.3 introduces Fixed-Time Motion as an alternative method to get more precise step and direction timing along with its own Linear Advance and Input Shaping handlers. Fixed-Time Motion also uses the Stepper ISR to do regular stepping, but it also has a periodic `idle` task to handle state changes.
 
-Since Fixed-Time motion requires significantly more resources than the standard motion system to pre-calculate its precise pulse timings, it requires a faster processor and more RAM.
+Since Fixed-Time Motion requires significantly more resources than the standard motion system to pre-calculate its precise pulse timings, it requires a faster processor and more RAM. However, FTM is also very optimized, so it requires fewer resources than you might expect, and should run well on leaner ARM boards.
 
 As this system matures it will likely become default for fast 32-bit boards, but the original motion system will be preserved for slower processors and for simpler motion systems that don't need the most precise timing.
 

_gcode/M493.md

@@ -10,23 +10,50 @@ requires: FT_MOTION
 eeprom: true
 
 codes: [ M493 ]
-related: [ M593 ]
+related: [ M494, M593 ]
 
 parameters:
 
 - tag: S
   optional: true
-  description: Set Fixed-Time motion mode OFF (0) / ON (1).
+  description: Set Fixed-Time Motion mode enabled / disabled.
   values:
-  - tag: bool
+  - tag: 0
+    description: Disabled
+  - tag: 1
+    description: Enabled
+
+- tag: T
+  optional: true
+  description: Set the state for Axis Synchronization.
+  values:
+  - tag: 0
+    description: Disabled
+  - tag: 1
+    description: Enabled
+
+- tag: P
+  optional: true
+  description: Enable/disable Linear Advance aka Pressure Advance.
+  values:
+  - type: bool
+    tag: state
 
-- tag: X|Y
+- tag: K
   optional: true
-  description: Set the vibration compensator [input shaper] mode for X / Y axis. Note.
-    Users and slicers must remember to set the mode for both axes!
+  description: Set the gain for Linear Advance aka Pressure Advance.
+  values:
+  - type: float
+    tag: gain
+
+- tag: C
+  optional: true
+  description: |
+    Set the vibration compensator [input shaper] mode for the specified axes.<br/>
+    NOTE: Users and slicers must remember to set the mode for both X and Y!
   values:
   - tag: 0
-    description: NONE (No input shaper)
+    description: No Input Shaper
   - tag: 1
     description: ZV (Zero Vibration)
   - tag: 2
@@ -44,23 +71,9 @@ parameters:
   - tag: 8
     description: MZV (Mass-based Zero Vibration)
 
-- tag: P
-  optional: true
-  description: Enable/disable Linear Advance.
-  values:
-  - type: bool
-    tag: state
-
-- tag: K
-  optional: true
-  description: Set the gain for Linear Advance.
-  values:
-  - type: float
-    tag: gain
-
 - tag: D
   optional: true
-  description: Set the Dynamic Frequency mode.
+  description: Set the Dynamic Frequency mode. (Available when there is a Z axis and/or Extruder to follow.)
   values:
   - tag: 0
     description: Disabled
@@ -71,39 +84,67 @@ parameters:
 
 - tag: A
   optional: true
-  description: Set the Base Frequency for Input Shaping on the X axis.
+  description: Set the Base Frequency for Input Shaping on the specified axes.
   values:
   - type: float
     tag: Hz
 
-- tag: B
+- tag: F
   optional: true
-  description: Set the Base Frequency for Input Shaping on the Y axis.
+  description: |
+    Set the Frequency Scaling factor for Input Shaping on the specified axes.<br/>
+    (Available when there is a Z axis and/or Extruder to follow.)
   values:
   - type: float
-    tag: Hz
+    tag: scale
 
-- tag: F
+- tag: I
   optional: true
-  description: Set the Frequency Scaling factor for Input Shaping on the X axis.
+  description: Set the Zeta for Input Shaping on the specified axes.
   values:
   - type: float
-    tag: scale
+    tag: zeta
+    range: [ 0.01, 1.0 ]
 
-- tag: H
+- tag: Q
   optional: true
-  description: Set the Frequency Scaling factor for Input Shaping on the Y axis.
+  description: Set the Vibration Tolerance for Input Shaping on the specified axes.
   values:
   - type: float
-    tag: scale
+    tag: vtol
+    range: [ 0.0, 1.0 ]
+
+- tag: X
+  optional: true
+  description: Flag to apply `A`,`C`,`F`,`I`,`Q` to the X axis. (If no axis parameters are given then XY is assumed.)
+  values:
+  - type: flag
+
+- tag: Y
+  optional: true
+  description: Flag to apply `A`,`C`,`F`,`I`,`Q` to the Y axis. (If no axis parameters are given then XY is assumed.)
+  values:
+  - type: flag
+
+- tag: Z
+  optional: true
+  description: Flag to apply `A`,`C`,`F`,`I`,`Q` to the Z axis. (If no axis parameters are given then XY is assumed.)
+  values:
+  - type: flag
+
+- tag: E
+  optional: true
+  description: Flag to apply `A`,`C`,`F`,`I`,`Q` to the E axis. (If no axis parameters are given then XY is assumed.)
+  values:
+  - type: flag
 
 example:
 
-- pre: Enable Fixed-Time motion with Linear Advance gain 0.22
+- pre: Enable Fixed-Time Motion with Linear Advance gain 0.22
   code: M493 S1 P1 K0.22
 
-- pre: Enable Fixed-Time motion with ZVD Input Shaping
-  code: M493 S1 X2 Y2 A37 B37 D0 P1 K0.18
+- pre: Enable Fixed-Time Motion with ZVD Input Shaping on X and Y
+  code: M493 S1 XY C2 A37 D0 P1 K0.18
   post: This also sets the IS Frequency to 37Hz for X and Y, disables Dynamic Frequency mode, and enables Linear Advance with a gain of 0.18.
 
 ---
@@ -124,21 +165,19 @@ Use a slicer that provides custom G-code macros for layer change. For example yo
 
 - In the the Starting G-code enable Fixed-Time Motion with something like:
   ```
-  M493 S1 X2 Y2 D0 ; Enable ZVD Input Shaping
+  M493 S1 XY C2 D0 ; Enable ZVD Input Shaping
   ```
 
 - In *Kiri:Moto* enable **Infill > Fill Type > Vase**. Then add the following under **Setup > Machine > Gcode Macros > Layer** to run a test range of 15Hz to 60Hz:
 
   ```
-  M493 A{(layer < 2 ? 0 : 15 + 45.0 * (layer - 2) / 297)} ; (Hz) X Input Shaping Test
-  M493 B{(layer < 2 ? 0 : 15 + 45.0 * (layer - 2) / 297)} ; (Hz) Y Input Shaping Test
+  M493 XY A{(layer < 2 ? 0 : 15 + 45.0 * (layer - 2) / 297)} ; (Hz) XY Input Shaping Test
   ```
 
 - In *Prusa Slicer* you'll enable **Spiral vase**. Then add the following to your **Printer Settings > After layer change G-code** to run a test range of 15Hz to 60Hz:
 
   ```
-  M493 A{(layer_num < 2 ? 0 : 15 + 45.0 * (layer_num - 2) / 297)} ; (Hz) X Input Shaping Test
-  M493 B{(layer_num < 2 ? 0 : 15 + 45.0 * (layer_num - 2) / 297)} ; (Hz) Y Input Shaping Test
+  M493 XY A{(layer_num < 2 ? 0 : 15 + 45.0 * (layer_num - 2) / 297)} ; (Hz) XY Input Shaping Test
   ```
 
 - In *Cura*, you'll first need to add the .py file in [this repository](//www.github.com/dsdanielko/cura-ringing-tower-script/) to your Cura "scripts" folder. Reopen Cura, enable **Spiralize Outer Contour** and set **Minimum Layer Time** to 0. Then go to **Extensions > Post Processing > Modify G-Code**. Click **Add a script** in the window that opens and use the dropdown menu to find **Input Shaping**. Make sure the **Motion planning type** dropdown is set to **M493**. The default frequency settings will let you test a range of 15Hz to 60Hz.