Motion Component (IMU)

motion 中枢组件允许你定义从惯性测量单元（IMU）（如加速度计和陀螺仪）读取数据的传感器。并非所有 IMU 芯片都支持所有类型的测量，详情请参见各个平台的文档。

# 示例配置条目
motion:
  - platform: ...
    accelerometer_range: 4G # 此处的平台相关选项

sensor:
  - platform: motion
    type: acceleration_x
    name: "Accel X"
  - platform: motion
    type: angular_rate_x
    name: "Gyro X"
  - platform: motion
    type: pitch
    name: "Pitch Angle"

配置变量

基础配置

axis_map（可选，mapping）：重新映射或反转传感器的物理轴，以匹配你的板子方向。每个键（x、y、z）映射到它应该读取的物理轴，可选择性地以 - 作为前缀来反转。必须包含所有三个轴，且每个物理轴只能出现一次。与 transform_matrix 互斥。
```
# 示例：交换 X 和 Y，反转 Z
motion:
  - platform: ...
    axis_map:
      x: y
      y: x
      z: "-z"
```
transform_matrix（可选，list of floats）：应用于原始加速度计和陀螺仪读数的 3×3 变换矩阵。这允许超出简单轴重映射的任意校准。可以指定为 9 个值的平面列表（行优先顺序），或指定为 3×3 嵌套列表。与 axis_map 互斥。
```
# 示例：3x3 嵌套格式
motion:
  - platform: ...
    transform_matrix:
      - [0.998, 0.010, -0.050]
      - [-0.010, 0.999, 0.020]
      - [0.050, -0.020, 0.998]
```
```
# 示例：平面格式
motion:
  - platform: ...
    transform_matrix: [0.998, 0.010, -0.050, -0.010, 0.999, 0.020, 0.050, -0.020, 0.998]
```
该矩阵可从下面描述的运行时校准操作中获取——校准后，计算出的矩阵将以可直接复制到配置中的格式记录在日志中，以便持久使用。
update_interval（可选，Time）：读取传感器数据的间隔。默认为 250ms。
id（可选，ID）：手动指定用于代码生成的 ID。

传感器配置

type（必需，string）：要暴露的测量类型。可选：
- acceleration_x：X 轴加速度，单位为 g。
- acceleration_y：Y 轴加速度，单位为 g。
- acceleration_z：Z 轴加速度，单位为 g。
- angular_rate_x：X 轴角速度，单位为 °/s。
- angular_rate_y：Y 轴角速度，单位为 °/s。
- angular_rate_z：Z 轴角速度，单位为 °/s。
- gyroscope_x：angular_rate_x 的同义词。
- gyroscope_y：angular_rate_y 的同义词。
- gyroscope_z：angular_rate_z 的同义词。
- pitch：俯仰角，单位为 °。
- roll：滚转角，单位为 °。
传感器的所有其他选项。

操作

`motion.calibrate_level` 操作

此操作计算一个校准矩阵，使当前加速度计读数映射为 [0, 0, 1]（设备平坦，Z 轴朝上）。将设备放置在水平表面上并触发此操作。它会替换当前的 transform_matrix。

save（可选，boolean）：将生成的矩阵保存到 NVS 闪存，以便下次启动时自动恢复。默认为 false。
on_success（可选，Automation）：校准成功时执行的操作。
on_error（可选，Automation）：校准失败时执行的操作（例如，传感器读取失败或倾斜不足）。

on_...:
  then:
    - motion.calibrate_level:
        id: my_motion
        save: true
        on_success:
          - logger.log: "Level calibration succeeded"
        on_error:
          - logger.log: "Level calibration failed"

执行后，生成的矩阵将以 INFO 级别记录在日志中，其格式可直接复制到 transform_matrix 配置中，用于持久化校准。

`motion.calibrate_heading` 操作

此操作在校准水平后校正航向（绕 Z 轴旋转）。仅绕 Y 轴倾斜设备（向前或向后俯仰），然后触发此操作。它会在现有矩阵上叠加 Z 轴旋转校正，使水平加速度分量完全落在 X 轴上，并保留其符号。

save（可选，boolean）：将生成的矩阵保存到 NVS 闪存。默认为 false。
on_success（可选，Automation）：校准成功时执行的操作。
on_error（可选，Automation）：校准失败时执行的操作。

on_...:
  then:
    - motion.calibrate_heading:
        id: my_motion
        save: true
        on_success:
          - logger.log: "Heading calibration succeeded"

`motion.clear_calibration` 操作

此操作丢弃任何运行时校准，并恢复由 axis_map 或 transform_matrix 定义的内建时间矩阵（如果两者均未配置，则为单位矩阵）。用于在无需重新刷写固件的情况下撤销 motion.calibrate_level / motion.calibrate_heading 序列。

save（可选，boolean）：同时清除 NVS 闪存中保存的校准，使重置在重启后持续有效。默认为 false。当为 false 时，内存中的矩阵会被重置，但之前保存的校准将在下次启动时再次恢复。

on_...:
  then:
    - motion.clear_calibration:
        id: my_motion
        save: true

校准持久化

当校准操作以 save: true 运行时，生成的矩阵会存储在 NVS 闪存中，并在下次启动时自动恢复，优先于 axis_map / transform_matrix 配置。保存的校准与配置的基础矩阵绑定：如果你更改 axis_map 或 transform_matrix 并重新刷写固件，过期的保存校准将自动丢弃，并使用新配置。要在运行时显式返回到配置的基础值，请使用 motion.clear_calibration。

校准流程

将设备放置在平坦水平的表面上。
触发 motion.calibrate_level。这将使 Z 轴与重力对齐。
仅绕 Y 轴倾斜设备（例如，沿 X 方向将一条边缘抬起）。
触发 motion.calibrate_heading。这将固定 X/Y 航向。

新的校准矩阵现已生效，可按需保存到闪存中。如果你可以监控日志，可以通过查找带有结果矩阵的 INFO 日志条目来验证校准是否成功，该矩阵格式适合直接复制到配置中。