Accelerometer Usage

Power Off Required

Before starting, completely turn off the printer and disconnect the power supply. Do not plug or unplug wiring harnesses, adjust connector wire order, or touch terminals while the power is on.

Interface Conflict Warning

It is prohibited to use the TFT screen, SPI accelerometer interface, and RRF expansion interface simultaneously!

Reason for conflict: The TFT screen interface (FPC-TFT), SPI accelerometer interface (ZH1.5-6P), and RRF expansion interface share the same set of SPI resources at the hardware level.
Consequence: If connected simultaneously, it will cause abnormal screen display and severe accelerometer data errors.
Solution: Please ensure that only one of these devices is connected and used at a time.

Motherboard Wiring

Configuration

[mcu host]
serial: /tmp/klipper_host_mcu

[adxl345]
cs_pin: host:None
spi_bus: spidev0.0

[resonance_tester]
accel_chip: adxl345
probe_points:
    100, 100, 20  # an example

Usage

加速度计测试与校准

依赖包安装

注意事项

若设备已运行 FlyOS-FAST 系统，系统已预装所需依赖，可跳过此步骤。
若使用 非 FLY 上位机，请务必完成以下安装操作。
建议使用 MobaXterm、PuTTY 等 SSH 工具连接后再进行操作。
本教程基于树莓派，其他平台仅供参考。

安装步骤

依次执行以下命令安装依赖包。
安装时间取决于 CPU 性能和网络状况，通常需要 10–20 分钟，请耐心等待直至安装完成。
若设备内存 (RAM) 过小，可能会导致安装失败。

步骤一：安装系统依赖包

sudo apt install python3-numpy python3-matplotlib libatlas-base-dev

步骤二：安装 Klipper 虚拟环境依赖包

~/klippy-env/bin/pip install matplotlib numpy

加速度计测试

前提条件

打印机已执行 归位 (Homing) 操作。
确保 Klipper 配置文件中已正确启用加速度计。

测试指令

在 Klipper 控制台中输入以下命令：

ACCELEROMETER_QUERY

若连接了多个加速度计，可指定芯片进行测试：

ACCELEROMETER_QUERY CHIP=<ADXL芯片名称>

请将 <ADXL芯片名称> 替换为实际的加速度计标识（如 adxl345）。

提示

部分旧版 Klipper 需要执行两次 ACCELEROMETER_QUERY 后才能获取到加速度数据。

常见问题处理

断电操作

检查、重新插拔或更换加速度计线束前，请完全关闭打印机并断开电源供应。不要在通电状态下插拔 ADXL/LIS2DW/MPU/ICM 模块或触碰裸露引脚。

首次执行失败：部分 Klipper 版本可能存在命令识别延迟，若首次执行未返回数据，请重新执行一次相同命令。
命令无法识别：如多次执行仍提示未知命令，可能是 Klipper 版本过低导致，建议：
- 更新 Klipper 至最新版本
- 或重新刷写最新版系统（如 FlyOS-FAST 最新版本）
Invalid adxl345 id：若提示 Invalid adxl345 id (got xx vs e5)，先立即重新执行一次 ACCELEROMETER_QUERY；如果仍报错，优先更换成品加速度计线束、转接板或传感器模块交叉测试，不建议客户自行补焊或维修焊点。
Invalid lis2dw / mpu / icm id：若使用 LIS2DW、MPU9250、ICM20948 等传感器，请确认配置段名称、通信总线和芯片型号与实际硬件一致。
Unable to obtain response / timeout：通常表示上位机与加速度计 MCU 通信异常，请检查 USB/CAN 连接、[mcu] ID、cs_pin、spi_bus 或 i2c_bus。

BatchBulkHelper / spi_transfer_response

报错信息：执行 ACCELEROMETER_QUERY、TEST_RESONANCES 或 SHAPER_CALIBRATE 时出现：

BatchBulkHelper start callback error
BatchBulkHelper stop callback error
Unable to obtain 'spi_transfer_response' response

报错性质：spi_transfer_response 表示 Klipper 没有收到 SPI 请求的应答，但它不一定是第一根因。近期日志案例中，MCU 先因 Timer too close 进入 shutdown，随后 ADXL 批量采集才提示无法取得 SPI 应答；此时应先处理前面的 shutdown，而不是直接判断加速度计损坏。

排查方法：

在完整 klippy.log 中找到第一条 BatchBulkHelper，再向上搜索更早的 Timer too close、Lost communication with MCU、MCU shutdown 或 Serial connection closed。
如果存在更早的 shutdown，先按系统与超时报错处理根因；后面的 spi_transfer_response 通常会随连接恢复而消失。
如果没有更早的 shutdown，且每次执行 ACCELEROMETER_QUERY 都立即报错，请核对加速度计的 [mcu]、cs_pin、spi_bus 和芯片类型。

断电操作

重新插拔或更换加速度计线束、转接板或模块前，请完全关闭打印机并断开电源供应。不要在通电状态下插拔 SPI/I2C 线束或触碰裸露引脚。

断电后更换成品线束、转接板或传感器模块交叉测试；不要让普通客户自行补焊或飞线。
如果只在共振测试开始或结束时出现，临时关闭摄像头、屏幕和其他高负载服务后复测，并保留完整日志供进一步分析。

结果判断

正常输出：若返回连续的数据流（如下图所示），表明加速度计工作正常，可进行共振补偿测量。
错误输出：若提示超时、无数据或通信错误，请依次检查：
1. 断电后确认加速度计接线是否牢固
2. 配置文件中传感器配置与 SPI 是否正确
3. 优先通过更换成品线束、转接板或传感器模块判断供电/通信问题

共振测试常见报错

报错信息	常见原因	处理方法
`No data received from accelerometer`	加速度计未连接、SPI/I2C 线序错误、供电异常	先执行 `ACCELEROMETER_QUERY` 确认通信正常，再重新测试
`Insufficient axis data for shaper calibration`	运动范围太小、加速度过低、传感器读数噪声过大	增大测试范围或 `accel_per_hz`，检查加速度计是否固定牢靠
`Frequency range too narrow`	皮带过松、机器机械共振频率超出测量范围	检查皮带张力、机械结构紧固；必要时调低 `max_freq` 或提高 `accel_per_hz`
共振图全是噪声，无明显峰值	传感器未固定牢靠、风扇振动干扰、线束晃动	断电后重新固定传感器，测试时关闭风扇，信号线与电机线分开走线
`SHAPER_CALIBRATE` 执行后无输出或报错退出	Python 依赖缺失（numpy/matplotlib）、内存不足	按本文开头的依赖安装步骤补装；大尺寸共振图计算可能需要更大内存
`Cannot test Z axis together with other axes`	`TEST_RESONANCES` 同时指定了 Z 轴和 X/Y 轴	Z 轴需要单独测试，不要与 X/Y 混合
`Invalid POINT parameter`	`POINT=` 坐标格式错误，或缺少 `x,y,z` 三个数值	按 `POINT=100,100,20` 这种格式填写
`Invalid NAME parameter`	输出名称为空、含特殊字符或与命令要求不匹配	使用英文、数字、下划线或短横线命名
`No accelerometer measurements found`	测试过程中没有采集到有效加速度数据	先执行 `ACCELEROMETER_QUERY`，再检查传感器固定和通信
`Unsupported output`	`OUTPUT=` 参数填写了不支持的类型	按 Klipper 支持的输出类型填写，常用为 `resonances`

如果 ACCELEROMETER_QUERY 正常但共振测试始终失败，优先用以下顺序排查：

断电后确认加速度计表面紧贴被测部件，没有缓冲材料或双面胶松动。
测试时临时关闭模型散热风扇、热端风扇和腔体风扇。
确保测试过程中没有线束拉扯传感器或被运动轴勾住。
增大测试振幅：在 [resonance_tester] 中将 accel_per_hz 从默认 75 逐步提高到 100–150。
如果使用工具板（USB/CAN）上的加速度计，确认通信线未靠近电机线或热床线。

加速度计方向配置

加速度计的安装方向会影响共振测量结果。如果 axes_map 配置与实际安装方向不一致，TEST_RESONANCES 或 SHAPER_CALIBRATE 会给出错误的频率响应，导致 Input Shaper 补偿失效。

什么是 axes_map

axes_map 用于将加速度计自身的坐标轴映射到打印机的 X/Y/Z 坐标。不同工具板、喷头外壳或加速度计模块的安装方向可能不同，因此必须根据实际安装方式配置。

如果没有填写 axes_map，Klipper 默认使用 x,y,z，即加速度计的 X/Y/Z 直接对应打印机的 X/Y/Z。

[adxl345]
cs_pin: toolboard:PB12
spi_bus: spi1
axes_map: x,y,z    # 根据实际安装方向调整

axes_map 支持交换轴顺序和取反（在轴前加 -）：

安装情况	配置示例
加速度计 X/Y 与打印机一致	`axes_map: x,y,z`
加速度计旋转 90°，X/Y 互换	`axes_map: y,x,z`
加速度计倒装，Z 轴反向	`axes_map: x,y,-z`
加速度计侧装，Y/Z 互换	`axes_map: x,z,y`

提示

[adxl345]、[lis2dw]、[mpu9250]、[bmi160]、[icm20948] 等加速度计配置段都使用相同的 axes_map 规则。

通过 ACCELEROMETER_QUERY 初步判断方向

静止状态下，加速度计会检测到约 1g 的重力加速度。通过观察哪个轴显示接近 ±1g，可以初步判断加速度计的朝向：

执行 ACCELEROMETER_QUERY，记录各轴读数。
将打印机（或加速度计）分别沿 X、Y、Z 方向倾斜，观察哪个轴的读数变化最大。
如果倾斜打印机 X 方向时，加速度计的 Y 轴读数变化最大，说明需要交换 X/Y 映射。
如果某轴读数符号相反（如倾斜正向时读数为负），则在对应轴前加 -。

通过 Shake&Tune 验证方向

前提

以下方法需要已安装 Klippain Shake&Tune 插件。FlyOS-Fast v1.3.5 及以上版本已预装。

Shake&Tune 生成的频谱图可以直观验证 axes_map 是否正确：

分别执行 X 轴和 Y 轴的共振测试：
```
TEST_RESONANCES AXIS=X
TEST_RESONANCES AXIS=Y
```
查看生成的频谱图：
- 方向正确：X 轴测试的频谱图应显示清晰的 X 方向共振峰，Y 轴测试显示清晰的 Y 方向共振峰，两者频率通常不同。
- 方向错误：如果 X 轴测试和 Y 轴测试的频谱图几乎相同，或共振峰位置异常接近，说明 axes_map 可能需要调整。
修改 axes_map 后执行 RESTART，再重新运行测试对比结果。

注意

axes_map 配置错误不会导致通信报错，ACCELEROMETER_QUERY 仍然能正常返回数据。只有共振测量结果会异常，因此容易被忽略。

axes_map 详细排查：查看共振补偿与压力提前配置问题中的 axes_map 章节

加速度计校准

使用 Shake&Tune 获得更详细的分析

如果系统已安装 Klippain Shake&Tune 插件，TEST_RESONANCES 命令会自动生成频谱图表和皮带对比图，比内置 SHAPER_CALIBRATE 提供更直观的可视化分析。FlyOS-Fast v1.3.5 及以上版本已预装该插件。

校准步骤

确保打印机已归位。
在控制台输入以下命令，开始自动校准 X、Y 轴：
```
SHAPER_CALIBRATE
```
校准完成后，保存配置：
```
SAVE_CONFIG
```

单轴校准

若只需校准单个轴，可使用：

SHAPER_CALIBRATE AXIS=X

或将 X 替换为 Y。

安全提示

校准过程中打印机可能产生剧烈振动，若振动过大，请立即按下急停按钮或发送 M112 命令紧急停止。

调节振动强度

若测试时振动过于强烈，可适当降低 accel_per_hz 参数值（默认 75）：

[resonance_tester]
accel_per_hz: 50

配置与调优问题：加速度计硬件正常但启用共振补偿后效果不佳、shaper_freq 设置不当、Pressure Advance 与 Input Shaper 冲突等问题，请参考共振补偿与压力提前配置问题。

说明：以上步骤适用于大多数基于 Klipper 的 3D 打印机共振补偿配置。请根据实际硬件与系统环境进行调整。

Motherboard Wiring​

Configuration​

Usage​

依赖包安装​

安装步骤​

加速度计测试​

前提条件​

测试指令​

常见问题处理​

BatchBulkHelper / spi_transfer_response​

结果判断​

共振测试常见报错​

加速度计方向配置​

什么是 axes_map​

通过 ACCELEROMETER_QUERY 初步判断方向​

通过 Shake&Tune 验证方向​

加速度计校准​

校准步骤​

单轴校准​

调节振动强度​