diff --git a/docs/Config_checks.md b/docs/Config_checks.md index 8a43a85c4..b6fd6cda2 100644 --- a/docs/Config_checks.md +++ b/docs/Config_checks.md @@ -162,3 +162,6 @@ consider calibrating [pressure advance](Pressure_Advance.md). It may be necessary to perform other types of detailed printer calibration - a number of guides are available online to help with this (for example, do a web search for "3d printer calibration"). +As an example, if you experience the effect called ghosting or ringing, +you may try following [ghosting compensation](Ghosting_Compensation.md) +tuning guide. diff --git a/docs/Ghosting_Compensation.md b/docs/Ghosting_Compensation.md new file mode 100644 index 000000000..106a8cb18 --- /dev/null +++ b/docs/Ghosting_Compensation.md @@ -0,0 +1,457 @@ +Ghosting Compensation +==================== + +Klipper supports Input Shaping - a technique that can be used to reduce ghosting +in prints. [Input shaping](https://en.wikipedia.org/wiki/Input_shaping) is an +open-loop control technique which creates a commanding signal that cancels its +own vibrations. + +**Warning**: Input Shaping support is experimental. You should consider using it +only if you already have ghosting and ringing in prints, otherwise it is not +advised to enable it. Input shaping requires some tuning and measurements +before it can be enabled. + +Note that ghosting usually has mechanical origins: insufficiently rigid printer +frame, non-tight or too springy belts, alignment issues of mechanical parts, +heavy moving mass, etc. Those should be checked and fixed first. + +Tuning +=========================== + +Basic tuning requires measuring the ringing frequencies of the printer and +adding a few parameters to `printer.cfg` file. + + +Slice the ringing test model, which can be found in +[docs/prints/ringing_tower.stl](prints/ringing_tower.stl), in the slicer: + + * Suggested layer height is 0.2 or 0.25 mm. + * Infill and top layers can be set to 0. + * Use 1-2 perimeters, or even better the smooth vase mode with 1-2 mm base. + * Use sufficiently high speed, around 80-100 mm/sec, for *external* perimeters. + * Make sure that the minimum layer time is *at most* 3 seconds. + +## Ringing frequency + +First, measure the **ringing frequency**. + +1. Increase `max_accel` and `max_accel_to_decel` parameters in your + `printer.cfg` to 7000. +2. Restart the firmware: `RESTART`. +3. Disable Pressure Advance: `SET_PRESSURE_ADVANCE ADVANCE=0`. +4. If you have already added `[input_shaper]` section to the printer.cfg, + execute `SET_INPUT_SHAPER SHAPER_FREQ_X=0 SHAPER_FREQ_Y=0` command. If you + get "Unknown command" error, you can safely ignore it at this point and + continue with the measurements. +5. Execute the command + `TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1250 FACTOR=100 BAND=5`. + Basically, we try to make ringing more pronounced by setting different large + values for acceleration. +6. Print the test model sliced with the suggested parameters. +7. You can stop the print earlier if the ringing is clearly visible and you see + that acceleration gets too high for your printer (e.g. printer shakes too + much or starts skipping steps). +8. Measure the distance *D* (in mm) between *N* oscillations for X axis near + the notches, preferably skipping the first oscillation or two. Pay attention + to the notches X axis corresponds to - the test model has large 'X' and 'Y' + marks on the back side for convenience. Note that 'X' mark is on Y axis and + vice versa, it is not a mistake - ringing of X axis shows *along* Y axis. + To measure the distance between oscillations more easily, mark the + oscillations first, then measure the distance between the marks with a ruler + or calipers: + + |![Mark ringing](img/ringing-mark.jpg)|![Measure ringing](img/ringing-measure.jpg)| + |:--:|:--:| + +9. Compute the ringing frequency = *V* · *N* / *D* (Hz) where *V* is the + velocity for outer perimeters (mm/sec). For the example above, we marked 6 + oscillations, and the test was printed at 100 mm/sec velocity, so the + frequency is 100 * 6 / 12.14 ≈ 49.4 Hz. +10. Do (8) - (9) for Y axis as well. + +Note that ringing on the test print should follow the pattern of the curved +notches, as in the picture above. If it doesn't, then this defect is not really +a ringing and has a different origin - either mechanical, or an extruder issue. +It should be fixed first before enabling and tuning input shapers. + +If the measurements are not reliable because, say, the distance +between the oscillations is not stable, it might mean that the printer has +several resonance frequencies on the same axis. One may try to follow the +tuning process described in +[Unreliable measurements of ringing frequencies](#unreliable-measurements-of-ringing-frequencies) +section instead and still get something out of the input shaping technique. + +Ringing frequency can depend on the position of the model within the buildplate +and Z height, *especially on delta printers*; you can check if you see the +differences in frequencies at different positions along the sides of the test +model and at different heights. You can calculate the average ringing +frequencies over X and Y axes if that is the case. + +If the measured ringing frequency is very low (below approx 20-25 Hz), it might +be a good idea to invest into stiffening the printer or decreasing the moving +mass - depending on what is applicable in your case - before proceeding with +further input shaping tuning, and re-measuring the frequencies afterwards. For +many popular printer models there are often some solutions available already. + +Note that the ringing frequencies can change if the changes are made to the +printer that affect the moving mass or change the stiffness of the system, +for example: + + * Some tools are installed, removed or replaced on the toolhead that change + its mass, e.g. a new (heavier or lighter) stepper motor for direct extruder + or a new hotend is installed, heavy fan with a duct is added, etc. + * Belts are tightened. + * Some addons to increase frame rigidity are installed. + * Different bed is installed on a bed-slinger printer, or glass added, etc. + +If such changes are made, it is a good idea to at least measure the ringing +frequencies to see if they have changed. + +## Input shaper configuration + +After the ringing frequencies for X and Y axes are measured, you can add the +following section to your `printer.cfg`: +``` +[input_shaper] +shaper_freq_x: ... +shaper_freq_y: ... +``` + +For the example above, we get shaper_freq_x/y = 49.4. + +## Choosing input shaper + +Klipper supports several input shapers. They differ in their sensitivity to +errors determining the resonance frequency and how much smoothing they cause +in the printed parts. Also, some of the shapers like 2HUMP_EI and 3HUMP_EI +should usually not be used with shaper_freq = resonance frequency - they are +configured from different considerations to reduce several resonances at once. + +For most of the printers, either MZV or EI shapers can be recommended. This +section describes a testing process to choose between them, and figure out +a few other related parameters. + +Print the ringing test model as follows (assuming you already have +shaper_freq_x/y set and max_accel/max_accel_to_decel increased to 7000 in +printer.cfg file): + +1. Restart the firmware: `RESTART`. +2. Disable Pressure Advance: `SET_PRESSURE_ADVANCE ADVANCE=0`. +3. Execute `SET_INPUT_SHAPER SHAPER_TYPE=MZV`. +4. Execute the command + `TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1250 FACTOR=100 BAND=5`. +5. Print the test model sliced with the suggested parameters. + +If you see no ringing at this point, then MZV shaper can be recommended for use. + +If you do see some ringing, re-measure the frequencies using steps (8)-(10) +described in [Ringing frequency](#ringing-frequency) section. If the frequencies +differ significantly from the values you obtained earlier, a more complex input +shaper configuration is needed. You can refer to Technical details of +[Input shapers](#input-shapers) section. Otherwise, proceed to the next step. + +Now try EI input shaper. To try it, repeat steps (1)-(5) from above, but +executing at step 3 the following command instead: +`SET_INPUT_SHAPER SHAPER_TYPE=EI`. + +Compare two prints with MZV and EI input shaper. If EI shows noticeably better +results than MZV, use EI shaper, otherwise prefer MZV. Note that EI shaper will +cause more smoothing in printed parts (see the next section for further +details). Add `shaper_type: mzv` (or ei) parameter to [input_shaper] section, +e.g.: +``` +[input_shaper] +shaper_freq_x: ... +shaper_freq_y: ... +shaper_type: mzv +``` + +A few notes on shaper selection: + + * EI shaper may be more suited for bed slinger printers (if the resonance + frequency and resulting smoothing allows): as more filament is deposited + on the moving bed, the mass of the bed increases and the resonance frequency + will decrease. Since EI shaper is more robust to resonance frequency + changes, it may work better when printing large parts. + * Due to the nature of delta kinematics, resonance frequencies can differ a + lot in different parts of the build volume. Therefore, EI shaper can be a + better fit for delta printers rather than MZV or ZV, and should be + considered for the use. If the resonance frequency is sufficiently large + (more than 50-60 Hz), then one can even attempt to test 2HUMP_EI shaper + (by running the suggested test above with + `SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI`), but check the considerations in + the [section below](#selecting-max_accel) before enabling it. + +## Selecting max_accel + +You should have a printed test for the shaper you chose from the previous step. +Note that at very high accelerations, depending on the resonance frequency and +the input shaper you chose (e.g. EI shaper creates more smoothing than MZV), +input shaping may cause too much smoothing and rounding of the parts. So, +max_accel should be chosen such as to prevent that. Another parameter that can +impact smoothing is square_corner_velocity, so it is not advisable to increase +it above the default 5 mm/sec to prevent increased smoothing. + +Inspect the model for the chosen input shaper. Take a note at which +acceleration: + + * ringing is still small - that you are comfortable with it; + * corners of the test model still show 'bulges' from disabled pressure + advance - remember that **input shaping is not a replacement of PA**. + +Choose the minimum out of the two acceleration values, and put it as max_accel +into printer.cfg (you can delete max_accel_or_decel or revert it to the old +value). + +As a note, it may happen - especially at low ringing frequencies - that EI +shaper will cause too much smoothing even at lower accelerations. In this case, +MZV may be a better choice, because it may allow higher acceleration values. + +At very low ringing frequencies (~25 Hz and below) even MZV shaper may create +too much smoothing. If that is the case, you can also try to repeat the +steps in [Choosing input shaper](#choosing-input-shaper) section with ZV shaper, +by using `SET_INPUT_SHAPER SHAPER_TYPE=ZV` command instead. ZV shaper should +show even less smoothing than MZV, but is more sensitive to errors in measuring +the ringing frequencies. + +Another consideration is that if a resonance frequency is too low (below 20-25 +Hz), it might be a good idea to increase the printer stiffness or reduce the +moving mass. Otherwise, acceleration and printing speed may be limited due too +much smoothing now instead of ringing. + + +## Fine-tuning resonance frequencies + +Note that the precision of the resonance frequencies measurements using the +ringing test model is sufficient for most purposes, so further tuning is not +advised. If you still want to try to double-check your results (e.g. if you +still see some ringing after printing a test model with an input shaper of +your choice with the same frequencies as you have measured earlier), you can +follow the steps in this section. Note that if you see ringing at different +frequencies after enabling [input_shaper], this section will not help with that. + +Assuming that you have sliced the ringing model with suggested parameters and +increased `max_accel` and `max_accel_to_decel` parameters in the `printer.cfg` +to 7000 already, complete the following steps for each of the axes X and Y: + +1. Make sure Pressure Advance is disabled: `SET_PRESSURE_ADVANCE ADVANCE=0`. +2. Execute `SET_INPUT_SHAPER SHAPER_TYPE=ZV`. +2. From the existing ringing test model with your chosen input shaper select + the acceleration that shows ringing sufficiently well, and set it with: + `SET_VELOCITY_LIMIT ACCEL=...`. +4. Calculate the necessary parameters for the `TUNING_TOWER` command to tune + `shaper_freq_x` parameter as follows: start = shaper_freq_x * 83 / 132 and + factor = shaper_freq_x / 66, where `shaper_freq_x` here is the current value + in `printer.cfg`. +5. Execute the command + `TUNING_TOWER COMMAND=SET_INPUT_SHAPER PARAMETER=SHAPER_FREQ_X START=start FACTOR=factor BAND=5` + using `start` and `factor` values calculated at step (4). +6. Print the test model. +7. Reset the original frequency value: + `SET_INPUT_SHAPER SHAPER_FREQ_X=...`. +7. Find the band which shows ringing the least and count its number from the + bottom starting at 1. +8. Calculate the new shaper_freq_x value via old + shaper_freq_x * (39 + 5 * #band-number) / 66. + +Repeat these steps for the Y axis in the same manner, replacing references to X +axis with the axis Y (e.g. replace `shaper_freq_x` with `shaper_freq_y` in +the formulae and in the `TUNING_TOWER` command). + +As an example, let's assume you have had measured the ringing frequency for one +of the axis equal to 45 Hz. This gives start = 45 * 83 / 132 = 28.30 +and factor = 45 / 66 = 0.6818 values for `TUNING_TOWER` command. +Now let's assume that after printing the test model, the fourth band from the +bottom gives the least ringing. This gives the updated shaper_freq_? value +equal to 45 * (39 + 5 * 4) / 66 ≈ 40.23. + +After both new `shaper_freq_x` and `shaper_freq_y` parameters have been +calculated, you can update `[input_shaper]` section in `printer.cfg` with the +new `shaper_freq_x` and `shaper_freq_y` values. + +## Pressure Advance + +If you use Pressure Advance, it may need to be re-tuned. Follow the +[instructions](Pressure_Advance.md#tuning-pressure-advance) to find the +new value, if it differs from the previous one. Make sure to restore the +original values of `max_accel` and `max_accel_to_decel` parameters in the +`printer.cfg` and restart Klipper before tuning Pressure Advance. + +## Unreliable measurements of ringing frequencies + +If you are unable to measure the ringing frequencies, e.g. if the distance +between the oscillations is not stable, you may still be able to take advantage +of input shaping techniques, but the results may not be as good as with proper +measurements of the frequencies, and will require a bit more tuning and printing +the test model. Note that another possibility is to purchase and install an +accelerometer and measure the resonances with it (there is a separate +[branch](https://github.com/dmbutyugin/klipper/blob/adxl345-spi/docs/Measuring_Resonances.md) +with ADXL345 support) - but this option requires some crimping and soldering. + + +For tuning, add empty `[input_shaper]` section to your `printer.cfg`. Then, +assuming that you have sliced the ringing model with suggested parameters and +increased `max_accel` and `max_accel_to_decel` parameters in the `printer.cfg` +to 7000 already, print the test model 3 times as follows. First time, prior to +printing, run + +1. `RESTART` +2. `SET_PRESSURE_ADVANCE ADVANCE=0`. +3. `SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=60 SHAPER_FREQ_Y=60`. +4. `TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1250 FACTOR=100 BAND=5`. + +and print the model. Then print the model again, but before printing run instead + +1. `SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=50 SHAPER_FREQ_Y=50`. +2. `TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1250 FACTOR=100 BAND=5`. + +Then print the model for the 3rd time, but now run + +1. `SET_INPUT_SHAPER SHAPER_TYPE=2HUMP_EI SHAPER_FREQ_X=40 SHAPER_FREQ_Y=40`. +2. `TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1250 FACTOR=100 BAND=5`. + +Essentially, we are printing the ringing test model with TUNING_TOWER using +2HUMP_EI shaper with shaper_freq = 60 Hz, 50 Hz, and 40 Hz. + +If none of the models demonstrate improvements in ringing, then, unfortunately, +it does not look like the input shaping techniques can help with your case. + +Otherwise, it may be that all models show no ringing, or some show the ringing +and some - not so much. Choose the test model with the highest frequency that +still shows good improvements in ringing. For example, if 40 Hz and 50 Hz models +show almost no ringing, and 60 Hz model already shows some more ringing, stick +with 50 Hz. + +Now check if EI shaper would be good enough in your case. Choose EI shaper +frequency based on the frequency of 2HUMP_EI shaper you chose: + + * For 2HUMP_EI 60 Hz shaper, use EI shaper with shaper_freq = 50 Hz. + * For 2HUMP_EI 50 Hz shaper, use EI shaper with shaper_freq = 40 Hz. + * For 2HUMP_EI 40 Hz shaper, use EI shaper with shaper_freq = 33 Hz. + +Now print the test model one more time, running + +1. `SET_INPUT_SHAPER SHAPER_TYPE=EI SHAPER_FREQ_X=... SHAPER_FREQ_Y=...`. +2. `TUNING_TOWER COMMAND=SET_VELOCITY_LIMIT PARAMETER=ACCEL START=1250 FACTOR=100 BAND=5`. + +providing the shaper_freq_x=... and shaper_freq_y=... as determined previously. + +If EI shaper shows very comparable good results as 2HUMP_EI shaper, stick with +EI shaper and the frequency determined earlier, otherwise use 2HUMP_EI shaper +with the corresponding frequency. Add the results to `printer.cfg` as, e.g. +``` +[input_shaper] +shaper_freq_x: 50 +shaper_freq_y: 50 +shaper_type: 2hump_ei +``` + +Continue the tuning with [Selecting max_accel](#selecting-max_accel) section. + + +Troubleshooting and FAQ +======================= + +### I cannot get reliable measurements of resonance frequencies + +First, make sure it is not some other problem with the printer instead of +ghosting. If the measurements are not reliable because, say, the distance +between the oscillations is not stable, it might mean that the printer has +several resonance frequencies on the same axis. One may try to follow the +tuning process described in +[Unreliable measurements of ringing frequencies](#unreliable-measurements-of-ringing-frequencies) +section and still get something out of the input shaping technique. + +### After enabling [input_shaper], I get too smoothed printed parts and fine details are lost + +Check the considerations in [Selecting max_accel](#selecting-max_accel) section. +If the resonance frequency is low, one should not set too high max_accel or +increase square_corner_velocity parameters. It might also be better to choose +MZV or even ZV input shapers over EI (or 2HUMP_EI and 3HUMP_EI shapers). + + +### After successfully printing for some time without ghosting, it appears to come back + +It is possible that after some time the resonance frequencies have changed. +E.g. maybe the belts tension has changed (belts got more loose), etc. It is a +good idea to check and re-measure the ringing frequencies as described in +[Ringing frequency](#ringing-frequency) section and update your config file +if necessary. + +### Is dual carriage setup supported with input shapers? + +There is no dedicated support for dual carriages with input shapers, but it does +not mean this setup will not work. One should run the tuning twice for each +of the carriages, and calculate the ringing frequencies for X and Y axes for +each of the carriages independently. Then put the values for carriage 0 into +[input_shaper] section, and change the values on the fly when changing +carriages, e.g. as a part of some macro: +``` +SET_DUAL_CARRIAGE CARRIAGE=1 +SET_INPUT_SHAPER SHAPER_FREQ_X=... SHAPER_FREQ_Y=... +``` + +And similarly when switching back to carriage 0. + + +Technical details +================= + +## Input shapers + +Input shapers used in Klipper are rather standard, and one can find more +in-depth overview in the articles describing the corresponding shapers. +This section contains a brief overview of some technical aspects of the +supported input shapers. The table below shows some (usually approximate) +parameters of each shaper. + +| Input
shaper | Shaper
duration | Vibration reduction 20x
(5% vibration tolerance) | Vibration reduction 10x
(10% vibration tolerance) | +|:--:|:--:|:--:|:--:| +| ZV | 0.5 / shaper_freq | N/A | ± 5% shaper_freq | +| MZV | 0.75 / shaper_freq | ± 4% shaper_freq | -10%...+15% shaper_freq | +| ZVD | 1 / shaper_freq | ± 15% shaper_freq | ± 22% shaper_freq | +| EI | 1 / shaper_freq | ± 20% shaper_freq | ± 25% shaper_freq | +| 2HUMP_EI | 1.5 / shaper_freq | ± 35% shaper_freq | ± 40 shaper_freq | +| 3HUMP_EI | 2 / shaper_freq | -45...+50% shaper_freq | -50%...+55% shaper_freq | + +A note on vibration reduction: the values in the table above are approximate. +If the damping ratio of the printer is known for each axis, the shaper can be +configured more precisely and it will then reduce the resonances in a bit wider +range of frequencies. However, the damping ratio is usually unknown and is hard +to estimate without a special equipment, so Klipper uses 0.1 value by default, +which is a good all-round value. The frequency ranges in the table cover a +number of different possible damping ratios around that value (approx. from 0.05 +to 0.2). + +Also note that EI, 2HUMP_EI, and 3HUMP_EI are tuned to reduce vibrations to 5%, +so the values for 10% vibration tolerance are provided only for the reference. + +**How to use this table:** + + * Shaper duration affects the smoothing in parts - the larger it is, the more + smooth the parts are. This dependency is not linear, but can give a sense of + which shapers 'smooth' more for the same frequency. The ordering by + smoothing is like this: ZV < MZV < ZVD ≈ EI < 2HUMP_EI < 3HUMP_EI. Also, + it is rarely practical to set shaper_freq = resonance freq for shapers + 2HUMP_EI and 3HUMP_EI (they should be used to reduce vibrations for several + frequencies). + * One can estimate a range of frequencies in which the shaper reduces + vibrations. For example, MZV with shaper_freq = 35 Hz reduces vibrations + to 5% for frequencies [33.6, 36.4] Hz. 3HUMP_EI with shaper_freq = 50 Hz + reduces vibrations to 5% in range [27.5, 75] Hz. + * One can use this table to check which shaper they should be using if they + need to reduce vibrations at several frequencies. For example, if one has + resonances at 35 Hz and 60 Hz on the same axis: a) EI shaper needs to have + shaper_freq = 35 / (1 - 0.2) = 43.75 Hz, and it will reduce resonances + until 43.75 * (1 + 0.2) = 52.5 Hz, so it is not sufficient; b) 2HUMP_EI + shaper needs to have shaper_freq = 35 / (1 - 0.35) = 53.85 Hz and will + reduce vibrations until 53.85 * (1 + 0.35) = 72.7 Hz - so this is an + acceptable configuration. Always try to use as high shaper_freq as possible + for a given shaper (perhaps with some safety margin, so in this example + shaper_freq ≈ 50-52 Hz would work best), and try to use a shaper with as + small shaper duration as possible. + * If one needs to reduce vibrations at several very different frequencies + (say, 30 Hz and 100 Hz), they may see that the table above does not provide + enough information. In this case one may have more luck with + [scripts/graph_shaper.py](../scripts/graph_shaper.py) + script, which is more flexible. diff --git a/docs/img/ringing-mark.jpg b/docs/img/ringing-mark.jpg new file mode 100644 index 000000000..f0b1c4519 Binary files /dev/null and b/docs/img/ringing-mark.jpg differ diff --git a/docs/img/ringing-measure.jpg b/docs/img/ringing-measure.jpg new file mode 100644 index 000000000..23ff9e5d6 Binary files /dev/null and b/docs/img/ringing-measure.jpg differ