Docs update for v4 (#113)

README.md

@@ -1,32 +1,21 @@
 # Klipper Shake&Tune plugin
 
-This "Shake&Tune" repository is a standalone module from the [Klippain](https://github.com/Frix-x/klippain) ecosystem, designed to automate and calibrate the input shaper system on your Klipper 3D printer with a streamlined workflow and insightful vizualisations. This can be installed on any Klipper machine. It is not limited to those using Klippain.
+Shake&Tune is a Klipper plugin from the [Klippain](https://github.com/Frix-x/klippain) ecosystem, designed to create insightful visualizations to help you troubleshoot your mechanical problems and give you tools to better calibrate the input shaper filters on your 3D printer. It can be installed on any Klipper machine and is not limited to those using the full Klippain.
+
+Check out the **[detailed documentation here](./docs/README.md)**.
 
 ![logo banner](./docs/banner.png)
 
-It operates in two steps:
-  1. Utilizing specially tailored Klipper macros, it initiates tests on either the belts or the printer X/Y axis to measure the machine axes behavior. This is basically an automated call to the Klipper `TEST_RESONANCES` macro with custom parameters.
-  2. Then a custom Python script is called to: 
-     1. Generate insightful and improved graphs, aiding in parameter tuning for the Klipper `[input_shaper]` system (including best shaper choice, resonant frequency and damping ratio) or diagnosing and rectifying mechanical issues (like belt tension, defective bearings, etc..)
-     2. Relocates the graphs and associated CSV files to your Klipper config folder for easy access via Mainsail/Fluidd to eliminate the need for SSH.
-     3. Manages the folder by retaining only the most recent results (default setting of keeping the latest three sets).
-
-Check out the **[detailed documentation of the Shake&Tune module here](./docs/README.md)**. You can also look at the documentation for each type of graph by directly clicking on them below to better understand your results and tune your machine!
-
-| [Belts graph](./docs/macros/belts_tuning.md) | [Axis input shaper graphs](./docs/macros/axis_tuning.md) | [Vibrations graph](./docs/macros/vibrations_profile.md) |
-|:----------------:|:------------:|:---------------------:|
-| [<img src="./docs/images/belts_example.png">](./docs/macros/belts_tuning.md) | [<img src="./docs/images/axis_example.png">](./docs/macros/axis_tuning.md) | [<img src="./docs/images/vibrations_example.png">](./docs/macros/vibrations_profile.md) |
-
 
 ## Installation
 
-Follow these steps to install the Shake&Tune module in your printer:
+Follow these steps to install Shake&Tune on your printer:
   1. Be sure to have a working accelerometer on your machine and a `[resonance_tester]` section defined. You can follow the official [Measuring Resonances Klipper documentation](https://www.klipper3d.org/Measuring_Resonances.html) to configure it.
-  1. Install the Shake&Tune package by running over SSH on your printer:
+  1. Install Shake&Tune by running over SSH on your printer:
      ```bash
      wget -O - https://raw.githubusercontent.com/Frix-x/klippain-shaketune/main/install.sh | bash
      ```
-  1. Then, append the following to your `printer.cfg` file and restart Klipper (if prefered, you can include only the needed macros: using `*.cfg` is a convenient way to include them all at once):
+  1. Then, append the following to your `printer.cfg` file and restart Klipper:
      ```
      [shaketune]
      # result_folder: ~/printer_data/config/ShakeTune_results
@@ -43,14 +32,3 @@ Follow these steps to install the Shake&Tune module in your printer:
      # timeout: 300
      #    The maximum time in seconds to let Shake&Tune process the CSV files and generate the graphs.
      ```
-
-## Usage
-
-Ensure your machine is homed, then invoke one of the following macros as needed:
-  - `EXCITATE_AXIS_AT_FREQ` to maintain a specific excitation frequency, useful to inspect and find out what is resonating.
-  - `AXES_MAP_CALIBRATION` to automatically find Klipper's `axes_map` parameter for your accelerometer orientation (be careful, this is experimental for now and known to give bad results).
-  - `COMPARE_BELTS_RESPONSES` for a differential belt resonance graph, useful for checking relative belt tensions and belt path behaviors on a CoreXY printer.
-  - `AXES_SHAPER_CALIBRATION` for standard input shaper graphs, used to mitigate ringing/ghosting by tuning Klipper's input shaper filters.
-  - `CREATE_VIBRATIONS_PROFILE` for vibrations graphs as a function of toolhead direction and speed, used to find problematic ranges where the printer could be exposed to more VFAs and optimize your slicer speed profiles and TMC driver parameters.
-
-For further insights on the usage of these macros and the generated graphs, refer to the [K-Shake&Tune module documentation](./docs/README.md).

docs/README.md

@@ -1,16 +1,27 @@
-# Klipper Shake&Tune plugin documentation
+# Shake&Tune documentation
 
 ![](./banner_long.png)
 
 
 When perfecting 3D prints and tuning your printer, there is all that resonance testing stuff that Shake&Tune will try to help you with. But keep in mind that it's part of a complete process, and Shake&Tune alone won't magically make your printer print at lightning speed. Also, when using the tools, **it's important to get back to the original need: good prints**.
 
-While there are some ideal goals described in this documentation, you need to understand that it's not always possible to achieve the ideal resonance graphs due to a variety of factors unique to each printer, such as precision of the assembly, quality and brand of components, components wear, etc. Even a different accelerometer can give different results. But that's not a problem; the primary goal is to produce clean and satisfactory prints. If your test prints look good and meet your standards, even if the response curves aren't perfect, you're on the right track. **Trust your printer and your print results more than chasing ideal graphs!** If it's satisfactory, there's no need for further adjustments.
+While there are some ideal goals described in this documentation, you need to understand that it's not always possible to achieve them due to a variety of factors unique to each printer, such as assembly precision, components quality and brand, components wear, etc. Even a different accelerometer can give different results. But that's not a problem; the primary goal is to produce clean and satisfactory prints. If your test prints look good and meet your standards, even if the response curves aren't perfect, you're on the right track. **Trust your printer and your print results more than chasing ideal graphs!** If it's satisfactory, there's no need for further adjustments.
 
-First, you might want to check out the **[input shaping and tuning generalities](./is_tuning_generalities.md)** documentation to understand how it all works and what to look for when taking these measurements.
+First, you may want to read the **[input shaping and tuning generalities](./is_tuning_generalities.md)** documentation to understand how it all works and what to look for when taking these measurements.
 
 
-## Resonance testing
+## Shake&Tune macros
+
+| Shake&Tune command | Resulting graphs example |
+|:------|:-------:|
+|[`AXES_MAP_CALIBRATION`](./macros/axes_map_calibration.md)<br /><br />Verify that your accelerometer is working correctly and automatically find its Klipper's `axes_map` parameter | [<img src="./images/axesmap_example.png">](./macros/axes_map_calibration.md) |
+|[`COMPARE_BELTS_RESPONSES`](./macros/compare_belts_responses.md)<br /><br />Generate a differential belt resonance graph to verify relative belt tensions and belt path behaviors on a CoreXY or CoreXZ printer | [<img src="./images/belts_example.png">](./macros/compare_belts_responses.md) |
+|[`AXES_SHAPER_CALIBRATION`](./macros/axes_shaper_calibrations.md)<br /><br />Create the usual input shaper graphs to tune Klipper's input shaper filters and reduce ringing/ghosting | [<img src="./images/axis_example.png">](./macros/axes_shaper_calibrations.md) |
+|[`CREATE_VIBRATIONS_PROFILE`](./macros/create_vibrations_profile.md)<br /><br />Measure your global machine vibrations as a function of toolhead direction and speed to find problematic ranges where the printer could be exposed to more VFAs in order to optimize your slicer speed profiles and TMC drivers parameters | [<img src="./images/vibrations_example.png">](./macros/create_vibrations_profile.md) |
+|[`EXCITATE_AXIS_AT_FREQ`](./macros/excitate_axis_at_freq.md)<br /><br />Maintain a specific excitation frequency, useful to inspect parasite peaks and find out what is resonating | [<img src="./images/excitate_at_freq_example.png">](./macros/excitate_axis_at_freq.md) |
+
+
+## Resonance testing workflow
 
 A standard tuning workflow might look something like this:
 
@@ -64,55 +75,6 @@ flowchart TB
     class tensionBelts,checkmotion,SnT_Belts,SnT_IS,SnT_Vibrations,pressureAdvance,extrusionMultiplier,testPrint,checkTMC standard;
 ```
 
-You can access the documentation for each graph type by clicking on it in the table below.
-
-| [Belt response comparison](./macros/belts_tuning.md) | [Axis input shaper graphs](./macros/axis_tuning.md) | [Vibrations profile](./macros/vibrations_profile.md) |
-|:----------------:|:------------:|:---------------------:|
-| [<img src="./images/belts_example.png">](./macros/belts_tuning.md) | [<img src="./images/axis_example.png">](./macros/axis_tuning.md) | [<img src="./images/vibrations_example.png">](./macros/vibrations_profile.md) |
-
-
-## Additional macros
-
-### AXES_MAP_CALIBRATION (experimental)
-
-All graphs generated by this package show plots based on accelerometer measurements, typically labeled with the X, Y, and Z axes. It's important to note that if the accelerometer is rotated, its axes may not align correctly with the machine axes, making the plots more difficult to interpret, analyze, and understand. The `AXES_MAP_CALIBRATION` is designed to automatically measure the alignement of the accelerometer in order to set it correctly.
-
-  > **Note**:
-  >
-  > This misalignment doesn't affect the measurements because the total sum across all axes is used to set the input shaper filters. It's just an optional but convenient way to configure Klipper's `[adxl345]` (or whichever accelerometer you have) "axes_map" parameter.
-
-Here are the parameters available when calling this macro:
-
-| 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|
-
-The machine will move slightly in +X, +Y, and +Z, and output in the console: `Detected axes_map: -z,y,x`.
-
-Use this value in your `printer.cfg` config file:
-```
-[adxl345] # replace "adxl345" by your correct accelerometer name
-axes_map: -z,y,x
-```
-
-### EXCITATE_AXIS_AT_FREQ
-
-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. By touching different components during the excitation, you can identify the source of the vibration, as contact usually stops it.
-
-Here are the parameters available when calling this macro:
-
-| parameters | default value | description |
-|-----------:|---------------|-------------|
-|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|10|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|
-
 
 ## Complementary ressources
 

docs/macros/axes_map_calibration.md

@@ -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)

docs/macros/axes_shaper_calibrations.md

@@ -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 on IS graphs
-
-### Generalities
 
 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.
 

docs/macros/compare_belts_responses.md

@@ -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

docs/macros/create_vibrations_profile.md

@@ -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|
+|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|
+|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.|
 |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|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.|
-|ACCEL_CHIP|"adxl345"|accelerometer chip name in the config|
+|TRAVEL_SPEED|120|speed in mm/s used for all the travels moves|
-|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|
+|ACCEL_CHIP|None|accelerometer chip name from your Klipper config that you want to force for the test|
-|KEEP_CSV|0|Weither or not to keep the CSV data files alonside the PNG graphs (archived in a tarball)|
-
-
-## Graphs description
 
 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.
 

docs/macros/excitate_axis_at_freq.md

@@ -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.