reijii/klippain-shaketune-telegramm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs update for v4 (#113)

Browse Source
This commit is contained in:
Félix Boisselier
2024-06-09 23:12:36 +02:00
committed by GitHub
parent da51082b44
commit 9739f6220e
10 changed files with 128 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
docs/macros/axes_map_calibration.md Normal file
View File

@@ -0,0 +1,51 @@
# Accelerometer "axes_map" calibration
All graphs generated by Shake&Tune show plots based on accelerometer measurements, typically labeled with the X, Y, and Z axes. If the accelerometer is rotated, its axes may not align correctly with the machine axes, making the plots more challenging to interpret, analyze, and understand. The `AXES_MAP_CALIBRATION` macro is designed to automatically measure the alignment of the accelerometer in order to set it correctly, making it easier than ever to get the most out of your data!
> **Note**:
>
> This misalignment doesn't affect the accuracy of the measurements because the total sum across all axes is used in most Shake&Tune tools. It's just an optional but convenient way to configure Klipper's `[adxl345]` (or whichever accelerometer you have) "axes_map" parameter.
## Usage
Call the `AXES_MAP_CALIBRATION` macro and look for the graphs in the results folder. Here are the parameters available:
| parameters | default value | description |
|-----------:|---------------|-------------|
|Z_HEIGHT|20|z height to put the toolhead before starting the movements. Be careful, if your accelerometer is mounted under the nozzle, increase it to avoid crashing it on the bed of the machine|
|SPEED|80|speed of the toolhead in mm/s for the movements|
|ACCEL|1500 (or max printer accel)|accel in mm/s^2 used for all the moves|
|TRAVEL_SPEED|120|speed in mm/s used for all the travels moves|
> **Note**:
>
> This command only works if you can move the same accelerometer in the 3 directions, like on a Voron V2.4 printer. If you have 2 accelerometers on your machine, like on a Prusa, Switchwire or Ender3, it won't work because it's impossible to detect the accelerometer orientation with only one movement (like for the bed).
![](../images/axesmap_example.png)
During the measurement, the machine will move slightly in +X, +Y, and +Z. This allow to automatically detect the orientation of the accelerometer.
Use this value in your `printer.cfg` config file:
```
[adxl345] # replace "adxl345" by your correct accelerometer name
axes_map: -z,y,x
```
### Acceleration plot
This plot shows the acceleration data over time for the X, Y, and Z axes after removing the gravity offset. Look for patterns in the acceleration data for each axis: you should have exactly 2 spikes for each subplot (for the start and stop of the motion) that break away from the global noise. This can help identify any anomalies or inconsistencies in your accelerometer behavior.
The detected gravity offset is printed in the legend to give some context to the readings and their scale: if it's too far from the standard 9.8-10 m/s², this means that your accelerometer is not working properly and should be fixed or calibrated.
The average noise in the accelerometer measurement is calculated (using wavelet transform decomposition) and displayed at the top of the image. Usually values <500mm/s² are ok, but a note is automatically added by Shake&Tune in case your accelerometer has too much noise.
### Estimated 3D movement path
This graph visualizes the estimated path of the tool head as recorded by the accelerometer in 3D space. Keep in mind that even though Shake&Tune uses some mathematical tricks to get something as accurate as possible, we don't have a gyroscope to compensate for accelerometer drift, and this plot is still pretty much an "estimate".
When examining it, look for path consistency by checking the smoothness of the paths (orange dotted lines): they should be mostly linear. Ideally, you should expect the computed direction vectors (in purple) to appear aligned along one of the primary axes (X, Y, or Z), with minimal angular error, indicating accurate alignment of the accelerometer chip with the machine axis.
Keep in mind that since this graph is an estimate, there may be some variation between successive runs, especially in the calculated angles. For example, on my machine I had these results over 20 consecutive runs (mean square error about 3 to 5 degrees):
![](../images/axes_map_inaccuracy.png)

15
docs/macros/axis_tuning.md → docs/macros/axes_shaper_calibrations.md
View File

@@ -1,6 +1,6 @@
# Axis measurements
# Input shaper filters calibration
The `AXES_SHAPER_CALIBRATION` macro is used to measure and plot the axis behavior in order to tune Klipper's input shaper system.
The `AXES_SHAPER_CALIBRATION` macro is used to measure and plot your machine axis frequency profiles in order to tune Klipper's input shaper system.
## Usage
@@ -21,14 +21,9 @@ Then, call the `AXES_SHAPER_CALIBRATION` macro and look for the graphs in the re
|TRAVEL_SPEED|120|speed in mm/s used for all the travel movements (to go to the start position prior to the test)|
|Z_HEIGHT|None|Z height wanted for the test. This value can be used if needed to override the Z value of the probe_point set in your `[resonance_tester]` config section|
## Graphs description
![](../images/shaper_graphs/shaper_graph_explanation.png)
## Analysis of the results
### Generalities
## Generalities on IS graphs
To effectively analyze input shaper graphs, there is no one-size-fits-all approach due to the variety of factors that can impact the 3D printer's performance or input shaper measurements. However, here are some hints on reading the graphs:
- A graph with a **single and thin peak** well detached from the background noise is ideal, as it can be easily filtered by input shaping. But depending on the machine and its mechanical configuration, it's not always possible to obtain this shape. The key to getting better graphs is a clean mechanical assembly with a special focus on the rigidity and stiffness of everything, from the table the printer sits on to the frame and the toolhead.
@@ -46,7 +41,7 @@ For setting your Input Shaping filters, rely on the auto-computed values display
- **The remaining vibrations** (`vibr`): This directly correlates to ringing. Ideally, you want a filter with minimal remaining vibrations.
- **Shaper recommendations**: This script will give you some tailored recommendations based on your graphs. Pick the one that suit your needs:
* The "performance" shaper, which should be good for most people as it's a compromise for high accelerations, with little residual vibrations that should remove most ringing on your parts.
* The "low vibration" shaper aims for a lower level of remaining vibration to ensure the best print quality with minimal ringing. This should can be used in case the performance shaper is not good enough for your needs.
* The "low vibration" shaper aims for a lower level of remaining vibration to ensure the best print quality with minimal ringing. This should be used in case the performance shaper is not good enough for your needs.
* Sometimes only a single recommendation is given as the "best" shaper. This means that either no suitable "performance" shaper was found (due to a high level of residual vibrations or too much smoothing), or that the "low vibration" shaper is the same as the "performance" shaper.
- **Damping Ratio**: At the end, you will see an estimate based on your measured data, which will be used to better tailor the shaper recommendations to your machine. You need to define it in the `[input_shaper]` section.
@@ -61,7 +56,7 @@ damping_ratio_x: ... # damping ratio for the X axis
damping_ratio_y: ... # damping ratio for the Y axis
```
### Useful facts and myths debunking
## Useful facts and myths debunking
Some people suggest to cap data at 100 Hz by manually editing the .csv file, thinking values beyond that are wrong. But this can be misleading. The excitation and system's response frequencies differ, and aren't directly linked. You might see vibrations beyond the excitation range, and removing them from the file just hides potential issues. Though these high-frequency vibrations might not always affect print quality, they could signal mechanical problems. Instead of hiding them, look into resolving these issues.

15
docs/macros/belts_tuning.md → docs/macros/compare_belts_responses.md
View File

@@ -1,11 +1,15 @@
# Belt relative difference measurements
# Measuring belts relative differences
The `COMPARE_BELTS_RESPONSES` macro is dedicated for CoreXY machines where it can help you to diagnose belt path problems by measuring and plotting the differences between their behavior. It will also help you tension your belts at the same tension. Using it on Cartesian printers doesn't really make sense, as it's normal to have different responses in that case.
The `COMPARE_BELTS_RESPONSES` macro is dedicated for CoreXY or CoreXZ machines where it can help you to diagnose belt path problems by measuring and plotting the differences between their behaviors. It will also help you tension your belts at the same tension.
> **Note**:
>
> While it might be tempting to use it on other kinds of printers, such as Cartesian printers, it's probably not the best idea. After all, it's normal to have different responses in that case due to the belts paths being not symmetric.
## Usage
**Before starting, ensure that the belts are properly tensioned**. For example, you can follow the [Voron belt tensioning documentation](https://docs.vorondesign.com/tuning/secondary_printer_tuning.html#belt-tension). You need a good starting point before starting to iterate from it!
**Before starting, ensure that the belts are properly tensioned**. For example, you can follow the [Voron belt tensioning documentation](https://docs.vorondesign.com/tuning/secondary_printer_tuning.html#belt-tension). You've got to have a solid foundation to build on!
Then, call the `COMPARE_BELTS_RESPONSES` macro and look for the graphs in the results folder. Here are the parameters available:
@@ -18,9 +22,6 @@ Then, call the `COMPARE_BELTS_RESPONSES` macro and look for the graphs in the re
|TRAVEL_SPEED|120|speed in mm/s used for all the travel movements (to go to the start position prior to the test)|
|Z_HEIGHT|None|Z height wanted for the test. This value can be used if needed to override the Z value of the probe_point set in your `[resonance_tester]` config section|
## Graphs description
![](../images/belts_example.png)
### Belts frequency profiles
@@ -49,7 +50,7 @@ Paired peaks of exactly the same frequency will be on the same point (labeled α
> **Note**:
>
> If you are using this tool to check or adjust the tension after installing new belts, you will need to measure again after a few hours of printing, as the tension can change slightly as the belts stretch and settle to their final tension. Usually 24 hours should be sufficient.
> If you're using this tool to check or adjust the tension after installing new belts, you'll want to measure again after a few hours of printing. This is because the tension can change slightly as the belts stretch and settle to their final tension. But don't worry, a few hours of printing should be more than enough!
## Advanced explanation on why 1 or 2 peaks

15
docs/macros/vibrations_profile.md → docs/macros/create_vibrations_profile.md
View File

@@ -13,18 +13,13 @@ Call the `CREATE_VIBRATIONS_PROFILE` macro with the speed range you want to meas
| parameters | default value | description |
|-----------:|---------------|-------------|
|SIZE|100|maximum size in mm of the circle in which the recorded movements take place|
|Z_HEIGHT|20|z height to put the toolhead before starting the movements. Be careful, if your accelerometer is mounted under the nozzle, increase it to avoid crashing it on the bed of the machine|
|ACCEL|3000 (or max printer accel)|accel in mm/s^2 used for all moves. Try to keep it relatively low to avoid dynamic effects that alter the measurements, but high enough to achieve a constant speed for >~70% of the segments. 3000 is a reasonable default for most printers, unless you want to record at very high speed, in which case you will want to increase SIZE and decrease ACCEL a bit.|
|SIZE|100|diameter in mm of the circle in which the recorded movements take place|
|Z_HEIGHT|20|Z height to put the toolhead before starting the movements. Be careful, if your accelerometer is mounted under the nozzle, increase it to avoid crashing it on the bed of the machine|
|MAX_SPEED|200|maximum speed of the toolhead in mm/s to record for analysis|
|SPEED_INCREMENT|2|toolhead speed increments in mm/s between each movement|
|TRAVEL_SPEED|200|speed in mm/s used for all the travels moves|
|ACCEL_CHIP|"adxl345"|accelerometer chip name in the config|
|KEEP_N_RESULTS|3|Total number of results to keep in the result folder after running the test. The older results are automatically cleaned up|
|KEEP_CSV|0|Weither or not to keep the CSV data files alonside the PNG graphs (archived in a tarball)|
## Graphs description
|ACCEL|3000|accel in mm/s^2 used for all moves. Try to keep it relatively low to avoid dynamic effects that alter the measurements, but high enough to achieve a constant speed for >~70% of the segments. 3000 is a reasonable default for most printers, unless you want to record at very high speed, in which case you will want to increase SIZE and decrease ACCEL a bit.|
|TRAVEL_SPEED|120|speed in mm/s used for all the travels moves|
|ACCEL_CHIP|None|accelerometer chip name from your Klipper config that you want to force for the test|
The `CREATE_VIBRATIONS_PROFILE` macro results are constituted of a set of 6 plots. At the top of the figure you can also see all the detected motor, current and TMC driver parameters. These notes are just for reference in case you want to tinker with them and don't forget what you changed between each run of the macro.

38
docs/macros/excitate_axis_at_freq.md Normal file
View File

@@ -0,0 +1,38 @@
# Diagnosing problematic peaks
The `EXCITATE_AXIS_AT_FREQ` macro is particularly useful for troubleshooting mechanical vibrations or resonance issues. This macro allows you to maintain a specific excitation frequency for a set duration, enabling hands-on diagnostics.
## Usage
Here are the parameters available:
| parameters | default value | description |
|-----------:|---------------|-------------|
|CREATE_GRAPH|0|whether or not to record the accelerometer data and create an associated graph during the excitation|
|FREQUENCY|25|excitation frequency (in Hz) that you want to maintain. Usually, it's the frequency of a peak on one of the graphs|
|DURATION|30|duration in second to maintain this excitation|
|ACCEL_PER_HZ|None|accel per Hz value used for the test. If unset, it will use the value from your `[resonance_tester]` config section (75 is the default)|
|AXIS|x|axis you want to excitate. Can be set to either "x", "y", "a", "b"|
|TRAVEL_SPEED|120|speed in mm/s used for all the travel movements (to go to the start position prior to the test)|
|Z_HEIGHT|None|Z height wanted for the test. This value can be used if needed to override the Z value of the probe_point set in your `[resonance_tester]` config section|
|ACCEL_CHIP|None|accelerometer chip name from your Klipper config that you want to force for the test|
**By default, this macro does not generate a graph**, because by touching the various components of your machine with your fingers, you will dampen the vibrations and be able to easily identify those that are source of problems: touching them will stop the noise.
However, if you have something that is difficult to diagnose with your ears, or if you want to record your experiments or document the exact consequences and effects of your modifications with a more scientific approach, you can enable the creation of a graph. Just **keep in mind that since the accelerometer is usually mounted on the toolhead, the recording will correspond to the toolhead vibrations and not necessarily reflect another problematic component somewhere on the machine**, unless it's vibrating a lot and its vibrations are being transmitted up to the toolhead. So keep this in mind when looking at the graphs generated by this macro, and you may want to move the accelerometer to other locations to get a full overview.
![](../images/excitate_at_freq_example.png)
### Spectrogram and vibrations harmonics
The time-frequency spectrogram visualizes how the frequency content of the signal changes over time. This plot helps identify dominant frequencies and harmonics of the excitated vibration. Each vertical line is one of them and a piece of the vibrations and noise that you can hear.
### Energy accumulation plot
The energy accumulation plot shows the cumulative energy over time, integrated over all frequencies. Basically, this plot is the sum of all the vibrations at a given moment during the test. So it can help you assess the periods of significant vibration and how much things change when you touch this or that part of the machine. In the example above, I vibrated my machine's X-axis at its main resonance frequency (i.e., its main resonance peak on the IS graphs) and touched 3 components:
- From the 4th to the 8th second of the test, I touched the toolhead, which has the most vibration reduction because it's the main component vibrating at that frequency and touching it dampens it a lot.
- From the 14th to the 18th second, I touched the belts and this reduced the vibration a bit, but not as much as touching the toolhead.
- From the 23rd to the 27th second, I touched the left XY joint of my machine and it didn't have any noticeable effect on the vibrations.
But as mentioned above, **remember that this doesn't mean that the left XY joint doesn't contribute to the vibrations**. It means that its vibrations aren't causing a problem in the recorded toolhead vibrations (because the accelerometer was mounted on the toolhead!!!), but if you find that this actually also reduces the global noise to your ears, you may want to start a new recording by sticking the accelerometer directly on the XY joint (or the problematic component) instead to continue diagnosing.