Air Quality v1.1 ESPHome 集成

Air Quality v1.1 的 ESPHome 集成包含空气质量传感器、按键、电子纸显示和 RTC 组件。

1. 设备简介

项目	信息
产品名称	Air Quality v1.1
SKU	K131-V11
主要功能	CO2、颗粒物、温湿度、VOC/NOx、电子纸显示
通信接口	I2C、SPI、GPIO
ESPHome 组件	`scd4x`、`sen5x`、`adc`、`gpio`、`ledc`、`output`、`waveshare_epaper`、`bm8563`
ESPHome 版本要求	`2025.5.0` 及以上

2. 组件说明

SCD40 CO2 传感器

SCD40 使用 ESPHome 官方 SCD4x Platform，提供 CO2、温度和湿度实体：

i2c:
  sda: GPIO11
  scl: GPIO12

sensor:
  - platform: scd4x
    co2:
      id: scd40_co2
      name: "CO2"
    temperature:
      id: scd40_temp
      name: "SCD40 Temperature"
    humidity:
      id: scd40_humi
      name: "SCD40 Humidity" 

SEN55 空气质量传感器

SEN55 使用 ESPHome 官方 SEN5x Platform，提供 PM1.0、PM2.5、PM4.0、PM10、温度、湿度、VOC 和 NOx 实体：

sensor:
  - platform: sen5x
    id: sen55
    pm_1_0:
      id: sen55_pm_1_0
      name: "PM <1µm Weight concentration"
    pm_2_5:
      id: sen55_pm_2_0
      name: "PM <2.5µm Weight concentration"
    pm_4_0:
      id: sen55_pm_4_0
      name: "PM <4µm Weight concentration"
    pm_10_0:
      id: sen55_pm_10_0
      name: "PM <10µm Weight concentration"
    temperature:
      id: sen55_temp
      name: "SEN55 Temperature"
    humidity:
      id: sen55_humi
      name: "SEN55 Humidity"
    voc:
      id: sen55_voc
      name: "VOC"
    nox:
      id: sen55_nox
      name: "NOX" 

电池电压采样

电池电压通过 ESPHome 官方 ADC Sensor Platform 从 GPIO14 读取。分压电路使 ADC 输入为实际电池电压的一半，因此使用 multiply: 2 还原电压值：

sensor:
  - platform: adc
    id: battery
    pin: GPIO14
    name: "Battery Voltage"
    attenuation: 12db
    accuracy_decimals: 2
    filters:
      - multiply: 2 

按键输入

USER_A、USER_B 和 WAKE 使用 ESPHome 官方 GPIO Binary Sensor Platform，将三个板载按键暴露为 Binary Sensor 实体。

按键	GPIO	输入配置
USER_A	GPIO0	低电平有效
USER_B	GPIO8	低电平有效、内部上拉
WAKE	GPIO42	低电平有效

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO0
      ignore_strapping_warning: true
      inverted: true
    name: "USER_A"
    on_press:
      - logger.log: "USER_A pressed"

  - platform: gpio
    pin:
      number: GPIO8
      inverted: true
      mode:
        input: true
        pullup: true
    name: "USER_B"

  - platform: gpio
    pin:
      number: GPIO42
      inverted: true
    name: "WAKE" 

蜂鸣器控制

蜂鸣器由 GPIO9 驱动。基础配置使用 LEDC Output 生成输出，并通过 Output Switch 暴露为 BEEP 开关实体：

output:
  - platform: ledc
    id: buzzer
    pin: GPIO9

switch:
  - platform: output
    name: "BEEP"
    id: beep_switch
    output: buzzer 

电子纸显示

电子纸使用 ESPHome 官方 Waveshare E-Paper Platform，型号配置为 1.54inv2。下面的最小配置仅输出固定文字，用于确认显示驱动工作正常：

spi:
  clk_pin: GPIO5
  mosi_pin: GPIO6

font:
  - file: "gfonts://Montserrat@500"
    id: display_font
    size: 18

display:
  - platform: waveshare_epaper
    cs_pin: GPIO4
    dc_pin:
      number: GPIO3
      ignore_strapping_warning: true
    busy_pin: GPIO1
    reset_pin: GPIO2
    data_rate: 40000000
    model: 1.54inv2
    full_update_every: 360
    update_interval: 60s
    lambda: |-
      it.print(0, 0, id(display_font), "Air Quality v1.1"); 

RTC

设备使用 ESPHome 官方 BM8563 Platform。启动时先读取 RTC；Home Assistant 完成时间同步后，再将时间写回 RTC：

time:
  - platform: bm8563
    id: rtc_time
    address: 0x51
    update_interval: never
  - platform: homeassistant
    on_time_sync:
      then:
        - bm8563.write_time: 

电源控制与关机注意事项

基础配置声明了两个 GPIO Output：GPIO10 的 sens_power 用于传感器供电控制，GPIO46 的 hold 用于整机电源保持。

output:
  - platform: gpio
    pin: GPIO10
    id: sens_power

  - platform: gpio
    pin:
      number: GPIO46
      ignore_strapping_warning: true
      inverted: true
    id: hold 

电源时序

当前基础配置只声明了 sens_power 和 hold，没有调用 output.turn_on 或 output.turn_off，因此不能认为配置中已经实现了传感器上电时序。二次开发如需控制传感器电源，应在启动自动化中明确设置 GPIO10 状态，并在传感器开始采样前预留稳定时间。

关机控制

产品在无 USB 外部供电时，将 HOLD（GPIO46）拉低会关机。由于 hold 配置了 inverted: true，调用 output.turn_on: hold 会使物理引脚输出低电平，可能直接触发关机；修改电源逻辑时需要特别注意反相关系。

3. 参考案例

完整整机配置可通过 packages 引入：

packages:
  air_quality_base_config:
    url: https://github.com/m5stack/esphome-yaml
    files: common/air-quality-v1-rev1-base.yaml
    ref: main
    refresh: 1d 

源码：

设备接入 Home Assistant 后，可查看空气质量与电池电压等实体：

按下 USER_A/USER_B 可以切换电子纸页面：

使用提示：传感器需要完成采样后才会输出稳定数据。持续开启 Wi-Fi 会增加功耗，建议连接电源使用。

4. 相关链接

5. 相关视频

Next 目录索引

Page Tools

PDF

Home Assistant

HAOS

ESPHome

主控与整机

摄像头

扩展模块

传感器

灯光控制

输入交互

开关与继电器

音频设备

接口扩展

应用案例

语音助手

媒体播放

Dashboard