Klippain Shake&Tune 共振分析插件

Klippain Shake&Tune 是一个 Klipper 共振分析与输入整形校准插件，能够对加速度计采集的振动数据生成可视化图表，帮助排查机械问题并优化 Input Shaper 滤波器。

FlyOS-FAST 用户

FlyOS-FAST v1.3.5 及以上版本已预装 Shake&Tune，无需手动安装。只需在 printer.cfg 中添加 [shaketune] 配置段并重启即可使用。

完整配置参数与说明请参考：FlyOS-FAST Shake&Tune 插件说明

安装

请使用 SSH 工具连接到上位机，并确认以下条件：

1. 上位机已安装 Klipper 固件。
2. 已安装并正确配置加速度计（ADXL345、LIS2DW 等），ACCELEROMETER_QUERY 能正常返回数据。
3. printer.cfg 中已定义 [resonance_tester] 段。

拉取或更新插件

此步骤需要连接 GitHub。确认拉取成功后，再运行安装脚本。

cd ~
if [ -d ~/klippain-shaketune/.git ]; then
  git -C ~/klippain-shaketune pull --ff-only
else
  git clone https://github.com/Frix-x/klippain-shaketune.git ~/klippain-shaketune
fi

运行安装脚本

cd ~/klippain-shaketune
chmod +x install.sh
./install.sh
systemctl restart klipper

如果使用 FlyOS-FAST 系统，安装路径应调整为 /data/ 目录，具体请参考上方 FlyOS-FAST 专用文档。

添加配置段

在 printer.cfg 中添加：

[shaketune]
# result_folder: ~/printer_data/config/ShakeTune_results
#    处理结果保存路径，文件夹不存在时自动创建
# number_of_results_to_keep: 10
#    保留的最近结果数量，超出后自动清理旧文件
# keep_raw_data: False
#    设为 True 可同时保存原始 .stdata 文件，便于排查问题或提交反馈
# show_macros_in_webui: True
#    在 Fluidd / Mainsail 网页中显示 Shake&Tune 宏按钮
# timeout: 600
#    图表生成超时时间（秒），低性能设备可适当增大

保存并重启 Klipper。

验证安装

systemctl is-active klipper

返回 active 后，在网页控制台输入 TEST_RESONANCES 等宏命令，确认命令可以被识别。

可用宏命令

安装完成后，以下宏命令可在网页控制台或 G-code 中使用：

宏命令	用途
TEST_RESONANCES AXIS=X	测量 X 轴共振并生成频谱图与建议的 Input Shaper 参数
TEST_RESONANCES AXIS=Y	测量 Y 轴共振并生成频谱图
TEST_RESONANCES AXIS=X OUTPUT=raw_data	仅采集原始数据，不自动生成图表
COMPARE_RESONANCES	对比最近两次共振测量结果，便于观察调整效果
BELTS_SHAPER_TUNING	专用皮带共振测试，生成 Hanning 窗口的频谱对比图

每次执行完成后，Shake&Tune 会在 result_folder 中生成 PNG 图表文件，可通过 Fluidd / Mainsail 的文件管理器直接查看。

与 Klipper 内置命令的区别

Shake&Tune 不替代 Klipper 内置的 SHAPER_CALIBRATE，而是在其基础上提供更丰富的可视化分析：

功能	Klipper 内置	Shake&Tune
自动计算 Input Shaper 参数	SHAPER_CALIBRATE 直接写入配置	TEST_RESONANCES 生成图表供参考
频谱可视化图表	无	自动生成 PNG 频谱图
皮带张力对比	无	BELTS_SHAPER_TUNING 生成对比图
多次测量对比	无	COMPARE_RESONANCES 对比最近结果

内置命令适合快速自动校准；Shake&Tune 适合需要查看详细频谱、排查机械问题或对比皮带张力的场景。

常见问题

图表生成超时

低性能设备生成图表时可能超时。适当增大 [shaketune] 中的 timeout 值，例如 timeout: 900。

结果文件夹没有生成

确认 result_folder 路径存在且 Klipper 有写入权限。

安装后 ACCELEROMETER_QUERY 报错

Shake&Tune 不影响加速度计底层通信。如果安装后出现通信错误，请先按 加速度计测试与校准 排查硬件和配置问题。

加速度计配置与测试：查看加速度计测试与校准

共振补偿与 Input Shaper 调优：查看共振补偿与压力提前配置问题