MSA301 和 MSA311 传感器

组件/集线器

msa3xx 传感器平台允许您在 ESPHome 中使用 MSA301 和 MSA311 三轴低重力加速度传感器（数据手册。 需要在配置中设置 I²C 才能使此传感器正常工作。

MSA301 和 MSA311 几乎是完全相同的传感器。唯一的区别是 ADC 分辨率。MSA311 具有固定的 12 位分辨率，而 MSA301 的 ADC 为 14 位，可以配置为进行 8、10、12 或 14 位测量。

此组件提供以 m/s² 为单位的加速度数据、方向信息和敲击检测。XYZ 轴可以进行校准和变换，以匹配传感器的物理方向。

带有 MSA311 传感器的模块扩展板。

ESPHome 仪表板中 MSA3xx 传感器表示示例。

# 示例配置条目
msa3xx:
  type: msa301
  range: 4G
  resolution: 12
  update_interval: 10s

配置变量

配置由三部分组成：核心组件、加速度传感器、带方向信息的文本传感器，以及用于敲击和运动检测的二进制传感器。

基本配置：

• type (必需, string)：传感器类型。可以是 msa301 或 msa311。

• update_interval (可选, 时间)：加速度传感器的更新间隔。 默认值为 10s。

• range (可选, string)：传感器测量的范围。可选值为 2G、4G、8G、16G。 默认值为 2G，这意味着它可以检测 -2g 到 2g 之间的加速度。

• resolution (可选, int)：传感器的 ADC 分辨率（位）。msa301 支持的值为 8、10、12、14（默认值）。 对于 msa311，唯一支持的分辨率是 12（也是默认值）。

• calibration (可选)：

  • offset_x (可选, float)：X 轴零位校准，单位为 m/s²。范围 -4.5 到 4.5。默认值为 0。
  • offset_y (可选, float)：Y 轴零位校准，单位为 m/s²。范围 -4.5 到 4.5。默认值为 0。
  • offset_z (可选, float)：Z 轴零位校准，单位为 m/s²。范围 -4.5 到 4.5。默认值为 0。

• transform (可选)：

  • mirror_x (可选, boolean)：镜像 X 轴。默认值为 false。
  • mirror_y (可选, boolean)：镜像 Y 轴。默认值为 false。
  • mirror_z (可选, boolean)：镜像 Z 轴。默认值为 false。
  • swap_xy (可选, boolean)：交换 X 和 Y 轴。默认值为 false。

二进制传感器

有三个可用的二进制传感器。所有传感器都应用了 500 毫秒的内部防抖。 每个传感器都需要 name。二进制传感器的所有其他选项也可使用。 也可以使用简写形式。

binary_sensor:
  - platform: msa3xx
    tap: 单击          # 传感器的简写形式
    double_tap: 双击   # -- "" --
    active:                  # 常规形式，以便
      name: 活动状态           # 使用过滤器和其他选项
      filters:
        - delayed_off: 5000ms # 延长运动检测信号的示例

配置变量

• tap (可选)：单击检测。
• double_tap (可选)：双击检测。
• active (可选)：运动检测。

传感器

加速度数据可通过传感器配置获取。 您可以使用简写形式，如 acceleration_x: "加速度 X"，或使用常规形式。对于 常规形式，只需要 name。传感器的所有选项也可使用。

sensor:
  - platform: msa3xx
    acceleration_x: 加速度 X
    acceleration_y: 加速度 Y
    acceleration_z: 加速度 Z

配置变量

• acceleration_x (可选)：X 轴加速度，单位 m/s²。
• acceleration_y (可选)：Y 轴加速度，单位 m/s²。
• acceleration_Z (可选)：Z 轴加速度，单位 m/s²。

文本传感器

文本传感器提供方向信息。您可以使用简写形式，如 orientation_xy: "方向 XY"，或使用常规形式。

text_sensor:
  - platform: msa3xx
    orientation_xy: 方向 XY
    orientation_z: 方向 Z

配置变量

• orientation_xy (可选)：XY 方向。可以是以下值之一：Portrait Upright（竖屏正向）、 Portrait Upside Down（竖屏倒置）、Landscape Left（横屏左侧）、Landscape Right（横屏右侧）。

• orientation_z (可选)：Z 方向。可以是以下值之一：Upwards looking（朝上）、Downwards looking（朝下）

自动化

on_tap 触发器

当检测到单击时，此自动化将被触发。

msa3xx:
  type: msa301
  # ...
  on_tap:
    - then:
        - logger.log: "已敲击"

on_double_tap 触发器

当检测到双击时，此自动化将被触发。

msa3xx:
  type: msa301
  # ...
  on_double_tap:
    - then:
        - logger.log: "已双击"

on_active 触发器

当设备检测到运动变化时，此自动化将被触发。

msa3xx:
  type: msa301
  # ...
  on_active:
    - then:
        - logger.log: "检测到活动"

on_orientation 触发器

当设备相对于重力场矢量 g 的方向发生变化时，此自动化将被触发。

msa3xx:
  type: msa301
  # ...
  on_orientation:
    - then:
        - logger.log: "检测到方向变化"

同时使用 MSA301 和 MSA311

如果您希望在同一个配置中使用两个传感器，可以通过为每个传感器指定 ID 来实现。

msa3xx:
  - id: my_msa301_sensor
    type: msa301
    # ...
  - id: my_msa311_sensor
    type: msa311

sensor:
  - platform: msa3xx
    msa3xx_id: my_msa311_sensor
    acceleration_x: 加速度 X
    acceleration_y: 加速度 Y
    acceleration_z: 加速度 Z

binary_sensor:
  - platform: msa3xx
    msa3xx_id: my_msa301_sensor
    tap: 单击

另请参阅

• 传感器过滤器
• API Reference: msa3xxx.h