diff --git a/docs/Config_Reference.md b/docs/Config_Reference.md index 5d1b1b0d..04030887 100644 --- a/docs/Config_Reference.md +++ b/docs/Config_Reference.md @@ -1414,7 +1414,9 @@ In order to use most of the functionality of this module, additional software dependencies must be installed; refer to [Measuring Resonances](Measuring_Resonances.md) and the [command reference](G-Codes.md#resonance-testing-commands) for more -information. +information. See the [Max smoothing](Measuring_Resonances.md#max-smoothing) +section of the measuring resonances guide for more information on +`max_smoothing` parameter and its use. ``` [resonance_tester] @@ -1438,6 +1440,11 @@ information. # 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. +#max_smoothing: +# Maximum input shaper smoothing to allow for each axis during shaper +# auto-calibration (with 'SHAPER_CALIBRATE' command). By default no +# maximum smoothing is specified. Refer to Measuring_Resonances guide +# for more details on using this feature. #min_freq: 5 # Minimum frequency to test for resonances. The default is 5 Hz. #max_freq: 120 diff --git a/docs/G-Codes.md b/docs/G-Codes.md index 72cc3fea..951b01bf 100644 --- a/docs/G-Codes.md +++ b/docs/G-Codes.md @@ -739,13 +739,17 @@ is enabled (also see the "YYYYMMDD_HHMMSS" format. - `SHAPER_CALIBRATE [AXIS=] [NAME=] [FREQ_START=] [FREQ_END=] - [HZ_PER_SEC=]`: Similarly to `TEST_RESONANCES`, runs the - resonance test as configured, and tries to find the optimal - parameters for the input shaper for the requested axis (or both X - and Y axes if `AXIS` parameter is unset). The results of the tuning - are printed to the console, and the frequency responses and the - different input shapers values are written to a CSV file(s) - `/tmp/calibration_data__.csv`. Unless specified, NAME + [HZ_PER_SEC=] [MAX_SMOOTHING=]`: + Similarly to `TEST_RESONANCES`, runs the resonance test as configured, + and tries to find the optimal parameters for the input shaper for the + requested axis (or both X and Y axes if `AXIS` parameter is unset). + If `MAX_SMOOTHING` is unset, its value is taken from `[resonance_tester]` + section, with the default being unset. See the + [Max smoothing](Measuring_Resonances.md#max-smoothing) of the measuring + resonances guide for more information on the use of this feature. + The results of the tuning are printed to the console, and the frequency + responses and the different input shapers values are written to a CSV + file(s) `/tmp/calibration_data__.csv`. Unless specified, NAME defaults to the current time in "YYYYMMDD_HHMMSS" format. Note that the suggested input shaper parameters can be persisted in the config by issuing `SAVE_CONFIG` command. diff --git a/docs/Measuring_Resonances.md b/docs/Measuring_Resonances.md index 9efa16ca..7dbd5938 100644 --- a/docs/Measuring_Resonances.md +++ b/docs/Measuring_Resonances.md @@ -168,22 +168,22 @@ recommended for your setup. For example: ![Resonances](img/calibrate-y.png) ``` -Fitted shaper 'zv' frequency = 56.7 Hz (vibrations = 23.2%) -Fitted shaper 'mzv' frequency = 52.9 Hz (vibrations = 10.9%) -Fitted shaper 'ei' frequency = 62.0 Hz (vibrations = 8.9%) -Fitted shaper '2hump_ei' frequency = 59.0 Hz (vibrations = 4.9%) -Fitted shaper '3hump_ei' frequency = 65.0 Hz (vibrations = 3.3%) -Recommended shaper is 2hump_ei @ 59.0 Hz +Fitted shaper 'zv' frequency = 37.0 Hz (vibrations = 29.1%, smoothing ~= 0.115) +Fitted shaper 'mzv' frequency = 35.4 Hz (vibrations = 15.9%, smoothing ~= 0.163) +Fitted shaper 'ei' frequency = 42.0 Hz (vibrations = 15.1%, smoothing ~= 0.183) +Fitted shaper '2hump_ei' frequency = 45.6 Hz (vibrations = 9.7%, smoothing ~= 0.260) +Fitted shaper '3hump_ei' frequency = 59.0 Hz (vibrations = 7.5%, smoothing ~= 0.235) +Recommended shaper is 3hump_ei @ 59.0 Hz ``` The suggested configuration can be added to `[input_shaper]` section of -`printer.cfg`: +`printer.cfg`, e.g.: ``` [input_shaper] -shaper_freq_x: 59.0 -shaper_type_x: 2hump_ei -shaper_freq_y: ... -shaper_type_y: ... +shaper_freq_x: ... +shaper_type_x: ... +shaper_freq_y: 59.0 +shaper_type_y: 3hump_ei ``` or you can choose some other configuration yourself based on the generated charts: peaks in the power spectral density on the charts correspond to @@ -223,11 +223,82 @@ probe_points: ... Then the commands `TEST_RESONANCES AXIS=X` and `TEST_RESONANCES AXIS=Y` will use the correct accelerometer for each axis. +## Max smoothing + +Keep in mind that the input shaper can create some smoothing in parts. +Automatic tuning of the input shaper performed by `calibrate_shaper.py` +script or `SHAPER_CALIBRATE` command tries not to exacerbate the smoothing, +but at the same time they try to minimize the resulting vibrations. +Sometimes they can make a sub-optimal choice of the shaper frequency, or +maybe you simply prefer to have less smoothing in parts at the expense of +a larger remaining vibrations. In these cases, you can request to limit +the maximum smoothing from the input shaper. + +Let's consider the following results from the automatic tuning: + +![Resonances](img/calibrate-x.png) +``` +Fitted shaper 'zv' frequency = 62.2 Hz (vibrations = 36.9%, smoothing ~= 0.046) +Fitted shaper 'mzv' frequency = 35.6 Hz (vibrations = 18.1%, smoothing ~= 0.161) +Fitted shaper 'ei' frequency = 54.6 Hz (vibrations = 19.3%, smoothing ~= 0.108) +Fitted shaper '2hump_ei' frequency = 46.2 Hz (vibrations = 9.2%, smoothing ~= 0.253) +Fitted shaper '3hump_ei' frequency = 50.0 Hz (vibrations = 7.2%, smoothing ~= 0.328) +Recommended shaper is 2hump_ei @ 46.2 Hz +``` +Note that the reported `smoothing` values are some abstract projected values. +These values can be used to compare different configurations: the higher the +value, the more smoothing a shaper will create. However, these smoothing scores +do not represent any real measure of smoothing, because the actual smoothing +depends on [`max_accel`](#selecting-max-accel) and `square_corner_velocity` +parameters. Therefore, you should print some test prints to see how much +smoothing exactly a chosen configuration creates. + +In the example above the suggested shaper parameters are not bad, but what if +you want to get less smoothing on the X axis? You can try to limit the maximum +shaper smoothing using the following command: +``` +~/klipper/scripts/calibrate_shaper.py /tmp/resonances_x_*.csv -o /tmp/shaper_calibrate_x.png --max_smoothing=0.2 +``` +which limits the smoothing to 0.2 score. Now you can get the following result: + +![Resonances](img/calibrate-x-max-smoothing.png) +``` +Fitted shaper 'zv' frequency = 55.2 Hz (vibrations = 34.2%, smoothing ~= 0.057) +Fitted shaper 'mzv' frequency = 33.8 Hz (vibrations = 17.4%, smoothing ~= 0.178) +Fitted shaper 'ei' frequency = 47.4 Hz (vibrations = 17.6%, smoothing ~= 0.143) +Fitted shaper '2hump_ei' frequency = 52.0 Hz (vibrations = 11.9%, smoothing ~= 0.200) +Fitted shaper '3hump_ei' frequency = 75.0 Hz (vibrations = 9.7%, smoothing ~= 0.146) +Recommended shaper is 3hump_ei @ 75.0 Hz +``` + +If you compare to the previously suggested parameters, the vibrations are a bit +larger, but the smoothing is significantly smaller than previously. + +When deciding which `max_smoothing` parameter to choose, you can use a +trial-and-error approach. Try a few different values and see which results +you get. Note however that if you request the script to find a configuration +for your printer with an unrealistically small smoothing, it will be unable +to find a reasonable configuration. The suggested parameters will have a poor +performance in this case and you can get too much remaining ringing as a result. +So, always double-check the projected remaining vibrations and make sure they +are not too high. + +Note that if you chose a good `max_smoothing` value for both of your axes, you +can store it in the `printer.cfg` as +``` +[resonance_tester] +accel_chip: ... +probe_points: ... +max_smoothing: 0.25 # an example +``` +Then, if you [rerun](#input-shaper-re-calibration) the input shaper auto-tuning +using `SHAPER_CALIBRATE` Klipper command in the future, it will use the stored +`max_smoothing` value as a reference. + ## Selecting max_accel -Keep in mind that the input shaper can create some smoothing in parts, -especially at high accelerations. Therefore, after the calibration -is finished, you will still need to choose the `max_accel` value that +Since the input shaper can create some smoothing in parts, especially at high +accelerations, you will still need to choose the `max_accel` value that does not create too much smoothing in the printed parts. Follow [this](Resonance_Compensation.md#selecting-max_accel) part of the input shaper tuning guide and print the test model. @@ -237,6 +308,10 @@ The same notice applies to the input shaper `SHAPER_CALIBRATE` command: it is still necessary to choose the right `max_accel` value after the auto-calibration. +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. + # Input Shaper auto-calibration diff --git a/docs/img/calibrate-x-max-smoothing.png b/docs/img/calibrate-x-max-smoothing.png new file mode 100644 index 00000000..d2693630 Binary files /dev/null and b/docs/img/calibrate-x-max-smoothing.png differ diff --git a/docs/img/calibrate-x.png b/docs/img/calibrate-x.png new file mode 100644 index 00000000..f16dcf15 Binary files /dev/null and b/docs/img/calibrate-x.png differ diff --git a/docs/img/calibrate-y.png b/docs/img/calibrate-y.png index 520eecc1..1b1df487 100644 Binary files a/docs/img/calibrate-y.png and b/docs/img/calibrate-y.png differ