AirGradient ESPHome 配置指南

AirGradient ESPHome 配置指南

本指南旨在详细介绍GitHub上的开源项目 MallocArray/airgradient_esphome，这是一个用于AirGradient DIY设备的ESPHome定义，允许设备将数据发送到HomeAssistant和AirGradient服务器。我们将按步骤解析项目结构、启动文件以及配置文件的关键要素。

1. 目录结构及介绍

项目结构围绕着实现AirGradient设备与智能家居系统的集成，具体结构如下：

.
├── fonts                  # 字体文件夹，存放OLED显示屏使用的字体
├── full_config            # 包含完整配置的yaml文件，提供所有可能的配置参数
├── images                 # 图片资源，如README所需图片
│── README.md              # 主要的项目说明文件
├── licenses               # 许可证文件
│── airgradient-basic.bin   # 已编译的固件文件，适用于基本型号
│── airgradient-basic.yaml  # 基础型号的ESPHome配置文件
│── airgradient-one.*      # 针对AirGradient ONE模型的各种配置与固件
│── airgradient-pro.*      # 针对AirGradient PRO模型的配置与固件
│── secrets.yaml           # 存储敏感信息如API密钥的文件
└── packages               # ESPHome的自定义包，包含特定功能或硬件设置

每个型号的.yaml文件是核心配置所在，而.bin文件则为预编译的固件，可以直接闪存至ESP设备。packages目录包含了额外的功能包，如特定的板级支持或通信协议配置。

2. 启动文件介绍

虽然此项目没有一个单一的“启动文件”传统意义上的概念（如main.py在某些框架中），但其实际的“启动”逻辑隐藏于ESPHome的配置文件中，特别是.yaml文件里。例如，airgradient-basic.yaml代表了基本型号设备的启动配置。当设备启动时，它依据该文件中的指令加载固件、连接Wi-Fi、读取传感器数据，并执行相应的网络通信任务。

3. 项目的配置文件介绍

配置文件，尤其是.yaml文件，是整个项目的核心。以airgradient-basic.yaml为例，它的关键部分包括但不限于设备名、所使用的硬件板型、Wi-Fi设置、传感器配置（如SenseAir S8 CO2传感器）、显示配置（OLED屏幕的设置）、以及如何与AirGradient和HomeAssistant等系统交互的详细参数。这些配置遵循ESPHome的语法规则，允许用户通过简单的文本编辑来定制设备的行为，例如开启或关闭API上传、调整显示设置、以及配置自动校准等功能。

示例配置元素:

• 设备信息:

  name: AirGradientBasicDevice
  

• WiFi设置:

  wifi:
    ssid: "YourSSID"
    password: "SecurePassword"
  

• 硬件板型:

  board: esp32dev
  

• 传感器配置:

  plantower_pms5003:
    id: pm_sensor
  

• 显示配置:

  oled_display:
    sda: 4
    scl: 15
  

• AirGradient API通信:

  airgradient_api:
    host: api.airgradient.com
  

请注意，实际配置远比示例复杂，通常包括多个子节点和高级选项，通过阅读项目文档和参考.yaml文件中的注释来详细了解每项配置的含义和用途。此外，利用ESPHome提供的灵活性，开发者可以根据自己的需求，启用或禁用特定的特性，甚至通过自定义包来扩展功能。