docs: Documentation for Z axis input shaper and resonance measurements

Signed-off-by: Dmitry Butyugin <dmbutyugin@google.com>

docs/Config_Reference.md

@@ -1780,17 +1780,22 @@ the [command reference](G-Codes.md#input_shaper).
 #   input shapers, this parameter can be set from different
 #   considerations. The default value is 0, which disables input
 #   shaping for Y axis.
+#shaper_freq_z: 0
+#   A frequency (in Hz) of the input shaper for Z axis. The default
+#   value is 0, which disables input shaping for Z axis.
 #shaper_type: mzv
-#   A type of the input shaper to use for both X and Y axes. Supported
+#   A type of the input shaper to use for all axes. Supported
 #   shapers are zv, mzv, zvd, ei, 2hump_ei, and 3hump_ei. The default
 #   is mzv input shaper.
 #shaper_type_x:
 #shaper_type_y:
-#   If shaper_type is not set, these two parameters can be used to
-#   configure different input shapers for X and Y axes. The same
+#shaper_type_z:
+#   If shaper_type is not set, these parameters can be used to
+#   configure different input shapers for X, Y, and Z axes. The same
 #   values are supported as for shaper_type parameter.
 #damping_ratio_x: 0.1
 #damping_ratio_y: 0.1
+#damping_ratio_z: 0.1
 #   Damping ratios of vibrations of X and Y axes used by input shapers
 #   to improve vibration suppression. Default value is 0.1 which is a
 #   good all-round value for most printers. In most circumstances this
@@ -1967,6 +1972,10 @@ section of the measuring resonances guide for more information on
 #   and on the toolhead (for X axis). These parameters have the same
 #   format as 'accel_chip' parameter. Only 'accel_chip' or these two
 #   parameters must be provided.
+#accel_chip_z:
+#   A name of the accelerometer chip to use for measurements of Z axis.
+#   This parameter has the same format as 'accel_chip'. The default is
+#   not to configure an accelerometer for Z axis.
 #max_smoothing:
 #   Maximum input shaper smoothing to allow for each axis during shaper
 #   auto-calibration (with 'SHAPER_CALIBRATE' command). By default no
@@ -1979,6 +1988,8 @@ section of the measuring resonances guide for more information on
 #   Minimum frequency to test for resonances. The default is 5 Hz.
 #max_freq: 135
 #   Maximum frequency to test for resonances. The default is 135 Hz.
+#max_freq_z: 100
+#   Maximum frequency to test Z axis for resonances. The default is 100 Hz.
 #accel_per_hz: 60
 #   This parameter is used to determine which acceleration to use to
 #   test a specific frequency: accel = accel_per_hz * freq. Higher the
@@ -1986,6 +1997,9 @@ section of the measuring resonances guide for more information on
 #   a lower than the default value if the resonances get too strong on
 #   the printer. However, lower values make measurements of high-frequency
 #   resonances less precise. The default value is 60 (mm/sec).
+#accel_per_hz_z: 15
+#   This parameter has the same meaning as accel_per_hz, but applies to
+#   Z axis specifically. The default is 15 (mm/sec).
 #hz_per_sec: 1
 #   Determines the speed of the test. When testing all frequencies in
 #   range [min_freq, max_freq], each second the frequency increases by
@@ -1994,6 +2008,8 @@ section of the measuring resonances guide for more information on
 #   (Hz/sec == sec^-2).
 #sweeping_accel: 400
 #   An acceleration of slow sweeping moves. The default is 400 mm/sec^2.
+#sweeping_accel_z: 50
+#   Same as sweeping_accel above, but for Z axis. The default is 50 mm/sec^2.
 #sweeping_period: 1.2
 #   A period of slow sweeping moves. Setting this parameter to 0
 #   disables slow sweeping moves. Avoid setting it to a too small

docs/G-Codes.md

@@ -828,15 +828,17 @@ been enabled (also see the
 
 #### SET_INPUT_SHAPER
 `SET_INPUT_SHAPER [SHAPER_FREQ_X=<shaper_freq_x>]
-[SHAPER_FREQ_Y=<shaper_freq_y>] [DAMPING_RATIO_X=<damping_ratio_x>]
-[DAMPING_RATIO_Y=<damping_ratio_y>] [SHAPER_TYPE=<shaper>]
-[SHAPER_TYPE_X=<shaper_type_x>] [SHAPER_TYPE_Y=<shaper_type_y>]`:
+[SHAPER_FREQ_Y=<shaper_freq_y>] [SHAPER_FREQ_Y=<shaper_freq_z>]
+[DAMPING_RATIO_X=<damping_ratio_x>] [DAMPING_RATIO_Y=<damping_ratio_y>]
+[DAMPING_RATIO_Z=<damping_ratio_z>] [SHAPER_TYPE=<shaper>]
+[SHAPER_TYPE_X=<shaper_type_x>] [SHAPER_TYPE_Y=<shaper_type_y>]
+[SHAPER_TYPE_Z=<shaper_type_z>]`:
 Modify input shaper parameters. Note that SHAPER_TYPE parameter resets
-input shaper for both X and Y axes even if different shaper types have
+input shaper for all axes even if different shaper types have
 been configured in [input_shaper] section. SHAPER_TYPE cannot be used
-together with either of SHAPER_TYPE_X and SHAPER_TYPE_Y parameters.
-See [config reference](Config_Reference.md#input_shaper) for more
-details on each of these parameters.
+together with any of SHAPER_TYPE_X, SHAPER_TYPE_Y, and SHAPER_TYPE_Z
+parameters. See [config reference](Config_Reference.md#input_shaper)
+for more details on each of these parameters.
 
 ### [led]
 
@@ -1284,13 +1286,14 @@ all enabled accelerometer chips.
 [POINT=x,y,z] [INPUT_SHAPING=<0:1>]`: Runs the resonance
 test in all configured probe points for the requested "axis" and
 measures the acceleration using the accelerometer chips configured for
-the respective axis. "axis" can either be X or Y, or specify an
-arbitrary direction as `AXIS=dx,dy`, where dx and dy are floating
+the respective axis. "axis" can either be X, Y or Z, or specify an
+arbitrary direction as `AXIS=dx,dy[,dz]`, where dx, dy, dz are floating
 point numbers defining a direction vector (e.g. `AXIS=X`, `AXIS=Y`, or
-`AXIS=1,-1` to define a diagonal direction). Note that `AXIS=dx,dy`
-and `AXIS=-dx,-dy` is equivalent. `chip_name` can be one or
-more configured accel chips, delimited with comma, for example
-`CHIPS="adxl345, adxl345 rpi"`. If POINT is specified it will override the point(s)
+`AXIS=1,-1` to define a diagonal direction in XY plane, or `AXIS=0,1,1`
+to define a direction in YZ plane). Note that `AXIS=dx,dy` and `AXIS=-dx,-dy`
+is equivalent. `chip_name` can be one or more configured accel chips,
+delimited with comma, for example `CHIPS="adxl345, adxl345 rpi"`.
+If POINT is specified it will override the point(s)
 configured in `[resonance_tester]`. If `INPUT_SHAPING=0` or not set(default),
 disables input shaping for the resonance testing, because
 it is not valid to run the resonance testing with the input shaper

docs/Measuring_Resonances.md

@@ -697,6 +697,95 @@ If you are doing a shaper re-calibration and the reported smoothing for the
 suggested shaper configuration is almost the same as what you got during the
 previous calibration, this step can be skipped.
 
+### Measuring the resonances of Z axis
+
+Measuring the resonances of Z axis is similar in many aspects to measuring
+resonances of X and Y axes, with some subtle differences. Similarly to other
+axes measurements, you will need to have an accelerometer mounted on the
+moving parts of Z axis - either the bed itself (if the bed moves over Z axis),
+or the toolhead (if the toolhead/gantry moves over Z). You will need to
+add the appropriate chip configuration to `printer.cfg` and also add it to
+`[resonance_tester]` section, e.g.
+```
+[resonance_tester]
+accel_chip_z: <accelerometer full name>
+```
+Also make sure that `probe_points` configured in `[resonance_tester]` allow
+sufficient clearance for Z axis movements (20 mm above bed surface should
+provide enough clearance with the default test parameters).
+
+The next consideration is that Z axis can typically reach lower maximum
+speeds and accelerations that X and Y axes. Default parameters of the test
+take that into consideration and are much less agressive, but it may still
+be necessary to increase `max_z_accel` and `max_z_velocity`. If you have
+them configured in `[printer]` section, make sure to set them to at least
+```
+[printer]
+max_z_velocity: 20
+max_z_accel: 1550
+```
+but only for the duration of the test, afterwards you can revert them back
+to their original values if necessary. And if you use custom test parameters
+for Z axis, `TEST_RESONANCES` and `SHAPER_CALIBRATE` will provide the minimum
+required limits if necessary for your specific case.
+
+After all changes to `printer.cfg` have been made, restart Klipper and run
+either
+```
+TEST_RESONANCES AXIS=Z
+```
+or
+```
+SHAPER_CALIBRATE AXIS=Z
+```
+and proceed from there accordingly how you would for other axes.
+For example, after `TEST_RESONANCES` command you can run
+`calibrate_shaper.py` script and get shaper recommendations and
+the chart of resonance response:
+
+![Resonances](img/calibrate-z.png)
+
+After the calibration, the shaper parameters can be stored in the
+`printer.cfg`, e.g. from the example above:
+```
+[input_shaper]
+...
+shaper_type_z: mzv
+shaper_freq_z: 42.6
+```
+
+Also, given the movements of Z axis are slow, you can easily consider
+more aggressive input shapers, e.g.
+```
+[input_shaper]
+...
+shaper_type_z: 2hump_ei
+shaper_freq_z: 63.0
+```
+
+If the test produces bogus results, you may try to increase
+`accel_per_hz_z` parameter in `[resonance_tester]` from its
+default value 15 to a larger value in the range of 20-30, e.g.
+```
+[resonance_tester]
+accel_per_hz_z: 25
+```
+and repeat the test. Increasing this value will likely require
+increasing `max_z_accel` and `max_z_velocity` parameters as well.
+You can run `TEST_RESONANCES AXIS=Z` command to get the required
+minimum values.
+
+However, if you are unable to measure the resonances of Z axis,
+you can consider just using
+```
+[input_shaper]
+...
+shaper_type_z: 3hump_ei
+shaper_freq_z: 65
+```
+as an acceptable all-round choice, given that the smoothing of
+Z axis movements is not of particular concerns.
+
 ### Unreliable measurements of resonance frequencies
 
 Sometimes the resonance measurements can produce bogus results, leading to

docs/Resonance_Compensation.md

@@ -439,9 +439,12 @@ gcode:
   SET_INPUT_SHAPER SHAPER_TYPE_X=<primary_carriage_shaper> SHAPER_FREQ_X=<primary_carriage_freq> SHAPER_TYPE_Y=<y_shaper> SHAPER_FREQ_Y=<y_freq>
 ```
 Note that `SHAPER_TYPE_Y` and `SHAPER_FREQ_Y` should be the same in both
-commands. It is also possible to put a similar snippet into the start g-code
-in the slicer, however then the shaper will not be enabled until any print
-is started.
+commands. If you need to configure an input shaper for Z axis, include
+its parameters in both `SET_INPUT_SHAPER` commands.
+
+Besides `delayed_gcode`, it is also possible to put a similar snippet into
+the start g-code in the slicer, however then the shaper will not be enabled
+until any print is started.
 
 Note that the input shaper only needs to be configured once. Subsequent changes
 of the carriages or their modes via `SET_DUAL_CARRIAGE` command will preserve
@@ -453,6 +456,18 @@ No, `input_shaper` feature has pretty much no impact on the print times by
 itself. However, the value of `max_accel` certainly does (tuning of this
 parameter described in [this section](#selecting-max_accel)).
 
+### Should I enable and tune input shaper for Z axis?
+
+Most of the users are not likely to see improvements in the quality of
+the prints directly, much unlike X and Y shapers. However, users of
+delta printers, printers with flying gantry, or printers with heavy
+moving beds may be able to increase the `max_z_accel` and `max_z_velocity`
+kinematics limits and thus get faster Z movements. This can be especially
+useful e.g. for toolchangers, but also when Z-hops are enabled in slicer.
+And in general, after enabling Z input shaper many users will hear that
+Z axis operates more smoothly, which may increase the comfort of printer
+operation, and may somewhat extend lifespan of Z axis parts.
+
 ## Technical details
 
 ### Input shapers