v4.1.0

Shake&Tune v4.1.0

This is a small release to fix a couple of annoying bugs and to improve the behavior of the belt graph generation.

Changes

• Fixed an "out of bounds" error that could occur in the previous version when Klipper displayed PSDs of different lengths in the belt graph. Now everything is interpolated to a known length to avoid this.
• Changed the belt similarity estimation to use the Pearson correlation coefficient to avoid instability with outliers (which are almost always there when the belt graph is funky). This solves the negative or very high values that some of you experienced. Note that your actual value may be slightly different from the previous Shake&Tune version.
• Improved synchronization when drawing paired peak points to avoid overlapping labels when the frequency difference between them is small. Now they don't need to be at exact frequency, but within 1Hz of each other to be considered aligned and plotted into a single label.

Full Changelog: v4.0.2...v4.1.0

v4.0.2

Shake&Tune v4.0.2

Changes

• A regression that broke compatibility with Klipper < v0.12.0-239 was fixed. So now everything is back to normal condition for users using older Klipper versions.
• Added a GitHub Action to do automated testing of the PRs! Thanks a lot to @Laikulo for this!
• Another attempt to fix the Timer Too Close error that was still happening to a few users. I forgot to update the CSV file writing function in v4.0.1 and this is now done in this version. Hopefully this will finally solve the problem!

New Contributors

• @delisjr made their first contribution in #129
• @Laikulo made their first contribution in #134

Full Changelog: v4.0.1...v4.0.2

v4.0.1

Shake&Tune v4.0.1

Changes

• I've got great news! This release contains a potential fix for the random "Timer too close" or "Move queue overflow" Klipper crashes that some of you experienced. It should not be a problem anymore, but please don't hesitate to open a new issue if you still have it.
• The is also slight changes to the macros to make the FREQ_START and FREQ_END parameters default on your [resonance_tester] klipper config section.

New Contributors

• @Zeanon made their first contribution in #119

Full Changelog: v4.0.0...v4.0.1

v4.0.0

Shake&Tune v4.0.0

This new version is a complete rewrite of Shake&Tune to make it a real and proper Klipper plugin (thanks to @ozelentok to have initiated the move with his PR!). While this doesn't change much in terms of usability, it's a lot for me, and it will help provide new features more integrated into Klipper in the future! But that's not all: this release also contains the first set of new features made possible by this rewrite!

Breaking changes

Since Shake&Tune now runs from within Klipper, there are some changes that need to be made to the way it is installed on your machine:

1. After the update using your WebUI, you will need to run the install script manually again using this command in SSH:

cd ~/klippain_shaketune && ./install.sh

2. Then you will need to update your moonraker.conf using this new template:

[update_manager Klippain-ShakeTune]
type: git_repo
origin: https://github.com/Frix-x/klippain-shaketune.git
path: ~/klippain_shaketune
virtualenv: ~/klippy-env
requirements: requirements.txt
system_dependencies: system-dependencies.json
primary_branch: main
managed_services: klipper

3. Then follow the new installation instructions to add the [shaketune] section to your printer.cfg. The old [include ./K-ShakeTune/*.cfg] can be safely removed!

New Features

• Shake&Tune runs inside Klipper and was fully rewritten in Python... No custom macros anymore!
• The belt comparison macro has been updated to remove the spectrogram, which was not really useful. However, a new graph has been added to replace it, and this should give a good and easy overview of the belts' behavior and how much they match: if the plot line is in the green zone, everything is fine on your belt's side and you can continue to the next tool. Quick and easy!
• Added the ability to test CoreXZ kinematics in the belt comparison tool to help you tension your belts on this type of machine. This is quite experimental and a new feature only possible because it's now a Klipper plugin. Note: The tested kinematics info is printed on the graph to make it easy to share it and avoid confusion.
• Updated the way belt similarity and mechanical health are calculated on the belt comparison graph. Now it should be more "precise" -> easier to get 100% and avoid bullshit and chasing unicorns, but it can also be quite low if there are real mechanical problems on the machine. The mechanical health indicator should also be more accurate and give less false positives.
• The ACCEL_PER_HZ is now a parameter for the macros that use it. So it can be changed at runtime and you don't have to change it in your config anymore. Also, it's now printed on the graphs so you can quickly see and remember which run was done at which accel per hz.
• Paired peaks in belts comparison plots now use the Greek alphabet to avoid confusion with A and B belts, as was often the case in the past... The way the amplitude delta (in the small table) is calculated has also been updated to have the same reference in the calculation and to make it easier to compare one value to the other. This should make it more accurate and easier to interpret.
• Updated the way the input shaper filters are recommended (Performance Shaper vs. Low Vibration Shaper), as it was a bit too conservative since Shake&Tune v2.6, where I started including damping ratio and SCV in the calculation. Now it should be more correct: performance shaper should be preferred and low vibration should be used if the performance shaper is not enough to filter out ringing.
• Added the PWM target freq when running TMC Autotune on the vibrations graph to tweak it and record its effects
• Completely reworked the axes map calibration macro: now it finally works correctly and gives the correct orientation! It also generates a graph with a few more insights to diagnose if your accelerometer is working correctly.
• Another new type of graph is the one that accompanies the static frequency excitation macro. This is optional, as your ears should be more than enough to find problematic components, but if you want to record things and compare the effect of this or that, you can do it. Be careful and read the corresponding documentation to avoid getting into the pitfalls of this recording, as it can be potentially misleading if not used correctly: that's why it's optional and your ears should be preferred first.

Fixes

• Because of all the new features, the documentation has been updated to reflect all the changes to the new graphs. There are also some additions like a suggested tuning workflow.
• Better CSV file filtering to avoid including CSV files from other plugins in the /tmp folder. Now it should be more robust in this aspect.
• Since Shake&Tune is now more tightly coupled with Klipper, it was easier to manage the accelerometers. So now the ACCEL_CHIP parameter is mostly not needed anymore and Shake&Tune should automatically select the right accelerometer for the test. You can still force one for the macros that still provide the parameter. This also has the side effect of fixing the use of non-standard accelerometer configurations with a custom name or multi-accelerometer configurations like bed swinger printers!

New Contributors

• @ozelentok made their first contribution in #100
• @dependabot made their first contribution in #41

Full Changelog: v3.0.0...v4.0.0

v3.0.0

Shake&Tune v3.0.0

This new version introduces a small breaking change with the macro names, which have changed to better reflect their usage. They are now COMPARE_BELTS_RESPONSES, AXES_SHAPER_CALIBRATION, and CREATE_VIBRATIONS_PROFILE.

New Features

• Significantly improved the vibration measurement tool to increase its accuracy and make it really useful. It's a long work that has been going on for several months now with the community! Thanks to everyone who helped! I'm quite happy with the results, because now it's able to measure at the same speed range, but also extrapolate how the motors will behave at all angles! So the recommended speed ranges for your slicer will take this into account. Documentation is available here
• Due to a major change in Klipper in February, S&T v2.6 was released to accommodate the change. It also provided a way to use SCV and the real damping ratio in the filter recommendations, but it also broke compatibility with older Klipper versions... Now with Shake&Tune v3.0.0 you have a "compatibility mode" that uses the old mechanism to calculate the filter recommendations if an older Klipper version is detected. This also has the side effect of making Shake&Tune compatible with the DangerKlipper bleeding edge branch again!
• Macro names have been changed to better reflect their use, as noted in the first line of this changelog. They are now COMPARE_BELTS_RESPONSES, AXES_SHAPER_CALIBRATION and CREATE_VIBRATIONS_PROFILE.

Fixes

• Updated the way the damping ratio is calculated to fix a potential crash when the signal is not perfect to calculate it (main spike near 0Hz). Now, if the damping ratio is not computable, the script will not crash and will take this into account when generating graphs.
• Numerous fixes for permission errors, parameter handling bugs, etc.
• Fixed a bug related to CSV format expectations that could happen in some edge cases.

Code Quality and Maintenance

• Changed repository architecture to decouple Python and Klipper macros. A lot of refactoring and code cleaning was done at the same time to use proper OOP code with Python modules. This is a first step towards a real Klipper plugin in the future.
• Added a pyproject.toml and set up linting and formatting rules using the Ruff formatter. Numerous refactoring and linting passes were done, targeting Python >=3.9 to avoid compatibility issues and have a cleaner and more consistent code.
• Complete move to pathlib for better path management throughout the project. This should provide a more robust implementation of all file handling parts of Shake&Tune.
• Improved error handling throughout the system to provide easier to understand errors in most cases.

v2.6.1

What's Changed

• Following the recent Klipper breaking change about the way accels are managed, max_accel_to_decel was replaced with minimum_cruise_ratio in order to account for it. This means that you will need to use a newer Klipper version to be able to update to S&T v2.6.1
• Fixed a typo from v2.6.0 (it was already fixed from a long time ago but now it's officially "in" a tagged release)
• Some documentation improvements, especially about the problematic LIS2DW chip

New Contributors

• @FOG-Yamato made their first contribution in #53

Full Changelog: v2.6.0...v2.6.1

v2.6.0

Prerequisite

Klipper introduced some changes in the way resonance testing work that broke S&T. I had to make modifications to S&T in order to fix and support this, but this also means that you need to update Klipper : Please update Klipper to a version after Feb 17, 2024.

What's Changed

• More accurate damping ratio calculation by using the half-quadratic gain method, which should be more accurate than the half-power method used in previous S&T versions for higher damping ratio values (above 0.05).
• Fixed the bug introduced in the latest Klipper commits.
• The last point now also allows S&T to use the current machine square corner velocity value (or define your own) and the calculated damping ratio to further improve and personalize the results. You will probably notice some changes, but now the results should be more accurate to what will actually happen in your machine. For instance, using a higher SCV will cause more smoothing and result in lower acceleration values (this was not taken into account before). Moreover, the shaper recommendations are now calculated by taking into account your real damping ratio, and not the default value of 0.1 that was used before.
• Finally, you will now be able to define a maximum smoothing value that you want to allow for the shaper recommendations.

Documentation Changes

• Added a bunch of details about the LIS2DW chip to the documentation, since it's known to produce a lot of aliasing and can be a bit problematic.
• Changed and improved several parts of the documentation...

New Contributors

• @shinanca made their first contribution

v2.5.0

This release is primarily a major rework of Shake&Tune. Around 75-80% of the code was modified after some tracing and analysis in order to optimize it and lower the memory requirements. This leads to improvements in memory usage and speed. For example, on my testing rig, I was able to lower the RAM requirement by 75% and speed up the belt graph generation by 10x. Moreover, the updated code is confirmed to be functional on devices with limited resources, like the PiZero2W and Rpi2, using a total of around 100MB of RAM!

Breaking change

As I discovered that moonraker is not calling the install script automatically, the new dependencies are not added correctly. So after the update, please replace your moonraker update section by the new one (to fix it for the next updates):

[update_manager Klippain-ShakeTune]
type: git_repo
origin: https://github.com/Frix-x/klippain-shaketune.git
path: ~/klippain_shaketune
virtualenv: ~/klippain_shaketune-env
requirements: requirements.txt
system_dependencies: system-dependencies.json
primary_branch: main
managed_services: klipper

And for this time, run over SSH:

cd ~/klippain_shaketune && git pull
./install.sh

Other changes and new features

• Motor shaft resonance analysis added to the vibration measurements. While currently, it doesn't offer immediate practical applications, it enables the measurement of the motor shaft's main resonance in your machine. It's important to note that this data represents a physical parameter of the motor and serves primarily as informational for now. However, exciting future plans are in the works on this topic – stay tuned!

• Alongside the code optimizations, a major refactoring of the code was done in order to avoid code duplication and keep it easier to maintain and understand. I hope this will make it easier for the community to create PRs on Shake&Tune :)

• Shake&Tune entrypoint script parameters handling was improved in order to be more flexible and robust. This update allows users to adjust settings like the number of results to retain in the folder, and whether to keep CSV files alongside the PNG result graphs directly from the Klipper macros! These improvements aim to make Shake&Tune more user-friendly and adaptable to various needs.

• The last point also allowed to also use the accelerometer chip name as a parameter as well. This means that Shake&Tune now supports a wider range of accelerometer chips beyond the ADXL345, including the LIS2DW that start to become more common, but also all the others compatible accelerometer with Klipper.

• Added a small watermark in the top right corner to indicate the Shake&Tune version used. This allows easier debugging and understanding of the data for every graph shared on the internet.

• Improved some parts of the documentation and especially added some bits about the new motor frequency profile of the vibration measurement graphs.

Full Changelog: v2.0.0...v2.5.0

v2.0.0

Breaking change

This release may introduce a small breaking change on some older Debian installs as it need 2 system packages that are not installed by default. If you get an error after the update about Numpy complaining some libopenblas missing, you can fix it by manually running:

rm -R ~/klippain_shaketune*
sudo apt update && sudo apt install libopenblas-dev libatlas-base-dev -y
wget -O - https://raw.githubusercontent.com/Frix-x/klippain-shaketune/main/install.sh | bash

What's Changed

• Updated documentation for clarity, incorporating subtle enhancements throughout for a more intuitive user experience.
• Transitioned to a dedicated Python Virtual Environment for K-Shake&Tune installation, ensuring isolation from system Python packages to minimize conflicts and outdated library issues. The environement should be created automatically with the install script upon update for everyone.
• Adopted Scipy for more robust and efficient spectrogram generation, replacing the older matplotlib.mlab.specgram function. This significant upgrade also addresses the notorious bug #7, happening randomly on 32-bit systems.
• Introduced the AXES_MAP_CALIBRATION macro, an experimental feature for automatic accelerometer orientation measurement to facilitate the correct "axes_map" configuration in your Klipper config (do not hesitate to tell me if this macro gives wrong results).
• Upgraded the belt differential spectrogram with a new color-coded system to easily identify and diagnose belt-specific issues. The expected visual remains a white rectangle featuring a diagonal line, now represented in a mix of purple and orange to distinguish each belt impact.
• Segregated the different macros definition in multiple files, allowing for selective inclusion based on printer type. This modular approach allow users to only load macros relevant to their setup, such as for example, omitting belt graphs macros for Cartesian printers. This is just a convenient way to include the macros but using *.cfg is still working correctly if you want all of them :)
• A lot of code cleanup and optimization were done in order to speed up the graphs generation or consume less RAM. These changes allowed to reduce by half the belt graphs generation time on my Pi3 for example. So it should definitely help you get a better user experience, especially on lower end SBC like the BTT CB1 or PiZero2W.

Full Changelog: v1.2...v2.0.0

v1.2.0

What's Changed

• Fixed a bug that occasionally produced irrelevant graphs. This issue was caused by asynchronous file operations on low-performing filesystems, which sometimes led to corrupted CSV files. Now, the system ensures that file operations are completed before using the CSV files for graph generation.
• Enhanced documentation user experience by introducing clickable image links. These links provide quick navigation to the corresponding sections of the documentation.
• Introduced an ACCEL parameter for vibration measurements with a proper default value. This allows users to set a specific acceleration value if needed (but most of the time this doesn't need to be changed). Be careful: using printer maximum acceleration on very dynamic printers may result in irrelevant readings due to toolhead oscillations at corners and you should use a low value instead. Note: the acceleration is restored to the previous setting at the end of the test.
• Improved the axis selection functionality in the EXCITATE_AXIS_AT_FREQ macro. It now allows for more straightforward selection of X, Y axes or A, B belts.

New Contributors

• @Fragmon made their first contribution in #14

Full Changelog: v1.1.2...v1.2