第4节 扩展 ESPHome 配置

本节在 第 3 节 的基础上，介绍如何按自己的硬件需求扩展 ESPHome 配置：从查阅官方组件文档、新增组件，到配置文件的组织手段与社区配置的复用。

1. 阅读 ESPHome 官方文档

ESPHome 几乎所有能力都来自一个个组件（Component）。每个组件具体怎么配置，以 esphome.io 上的官方文档为准。

1.1 文档的整体结构

最常用的入口是组件索引页 esphome.io/components（页面标题为 ESPHome Docs），它汇总了配置说明、芯片支持和全部组件。左侧导航栏分为几大块：

• Getting Started — 安装、入门、FAQ。
• Components / All Components — 组件总索引与全部组件列表，用得最多。
• Automations — 自动化、动作 / 触发器 / 条件、模板、lambda。
• Guides — YAML 配置、配置类型等基础说明。
• Cookbook — 组合用法的完整范例。

在组件索引页上，组件按功能类别分组列出，入门常用的有：

类别	对应 YAML 顶层键	在 HA 中表现为
Sensor Components	sensor:	温度、电压等数值实体
Binary Sensor Components	binary_sensor:	按键、触摸等「开/关」实体
Switch Components	switch:	继电器、GPIO 输出
Light Components	light:	第 3 节用过的 RGB LED
Display Components	display:	显示屏（不直接生成实体，靠 lambda 绘制）
Climate / Cover / Fan …	climate: / cover: / fan:	对应的设备卡片

类别下还会再细分。比如 Binary Sensor Components 又分 Core、Capacitive Touch、Mechanical、NFC/RFID 等子类——本节 2.1 要用的 GPIO 按键，就位于 Binary Sensor → Core 下的 GPIO 类型。

1.2 一个组件页怎么读

打开一个组件页（例如第 3 节用到的 esp32_rmt_led_strip），组件页面结构基本一致：

1. 开头的 YAML 示例 — 稍作修改即可使用，是最快的起点。
2. Configuration variables — 逐个字段说明，每项会标注：
   • Required（必填）还是 Optional（可选）；
   • 字段类型（如 Pin、Time 等，详见 配置类型）与默认值。
3. See Also — 相关组件与延伸阅读。

提示

官方文档只有英文版。社区有中文翻译，但更新通常滞后，配置字段一律以英文原文为准；翻译有歧义时，参照英文页的 YAML 示例。

2. 按组件类型扩展配置

下面以板载 BOOT 按钮为例，演示从查阅文档到写出完整配置的过程，随后简要介绍其他几类常见组件的配置方式。

2.1 BOOT 按钮

ESP32-S3-Zero 的 BOOT 按钮连接至 GPIO0，通常用于进入下载模式，固件启动后也可作为普通输入按键使用。

这里使用 binary_sensor 下的 gpio 平台读取（文档）。

在第 3 节创建的 esp32-s3-zero 设备 YAML 末尾追加以下内容：

binary_sensor:
  - platform: gpio
    name: "BOOT Button"
    pin:
      number: GPIO0
      mode:
        input: true
        pullup: true
      inverted: true

各字段含义：

• platform: gpio — 读取 GPIO 引脚的高低电平。
• pin.number: GPIO0 — BOOT 按钮所在的引脚。
• mode.pullup: true — 启用内部上拉，按钮未按下时引脚保持高电平。
• inverted: true — BOOT 按钮按下时引脚被拉到低电平，取反后「按下 = on」更符合直觉。

保存后，通过 OTA 方式烧录（INSTALL → Wirelessly）。烧录完成后，HA 设备页面中会自动出现 BOOT Button 实体，按下 BOOT 键时状态在「关 → 开」之间切换。

同样的写法也适用于外接按钮：把 pin.number 改成按钮所接的 GPIO 即可，其余字段不变。

备注

GPIO0 是 ESP32-S3 的启动模式引脚（strapping pin）：芯片上电瞬间会采样它的电平，以决定进入运行还是下载模式。启动完成后再把它当普通输入读取是安全的，但不要在它上面外接会在复位时把电平拉低的电路，否则可能导致开机进入下载模式而无法运行固件。

2.2 常见组件类型

下面介绍其他几类常用外设的配置片段。添加新外设的流程与 2.1 节的 BOOT 按钮一致：在 组件目录 中找到对应组件 → 填写必填字段 → 通过 name 为实体命名。引脚与具体型号按实际硬件替换。

数字输出 — 继电器 / 电平控制（switch: gpio）

switch:
  - platform: gpio
    name: "Relay"
    pin: GPIO2          # 换成你的引脚

控制一个 GPIO 的高低电平，HA 中表现为一个开关。详见 GPIO Switch。

模拟输入 — 电压检测（sensor: adc）

sensor:
  - platform: adc
    name: "Battery Voltage"
    pin: GPIO1          # 换成你的 ADC 引脚
    attenuation: 12db   # 量程，影响可测电压上限
    update_interval: 60s

读取引脚电压，HA 中表现为一个数值传感器。详见 ADC Sensor。

I²C 传感器（总线声明 + 设备）

大多数温湿度、气压、光照等传感器都走 I²C 总线。配置分两步：先声明一条 i2c: 总线，再在对应平台下挂载传感器。

# 第一步：声明 I²C 总线（一块板通常只需一条）
i2c:
  sda: GPIO8          # 换成你的 SDA 引脚
  scl: GPIO9          # 换成你的 SCL 引脚
  scan: true          # 上电时扫描总线，在 LOGS 中打印检测到的设备地址

# 第二步：在传感器组件下挂设备（platform 换成你的传感器型号）
sensor:
  - platform: <传感器组件名>
    address: 0x40
    update_interval: 60s
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"

具体某颗传感器支持哪些字段（地址、要暴露哪些测量值），以它在 传感器组件列表 中的文档为准。scan: true 扫描不到设备时，优先检查接线、上拉电阻和 I²C 地址。

显示屏（display:）

显示屏种类繁多（OLED、LCD、e-Paper……），它们一般不直接生成 HA 实体，而是通过 lambda 在屏幕上绘制内容，配置也相对复杂。这里不展开，需要时按屏幕的驱动型号在 Display 组件 中查找；第 5 节会给出一个完整的 RLCD 显示屏示例。

3. 配置文件的组织手段

随着组件变多，YAML 会越来越长，重复内容也越来越多。ESPHome 提供了几种手段对配置进行参数化和拆分。

3.1 substitutions：参数化

substitutions 用于定义一组变量，正文里通过 ${变量名} 引用。改一处即全局生效，特别适合引脚、设备名这类反复出现的值。

substitutions:
  device_name: esp32-s3-zero
  led_pin: GPIO21

esphome:
  name: ${device_name}

light:
  - platform: esp32_rmt_led_strip
    pin: ${led_pin}
    # ……其余字段同第 3 节

3.2 YAML 锚点：片段复用

YAML 原生支持用 &名字 定义锚点、*名字 引用，再配合合并键 <<: 把一组字段插入多个地方，适合复用「一组相同的字段」。

sensor:
  - platform: adc
    pin: GPIO1
    <<: &adc_defaults     # 定义锚点
      update_interval: 60s
      accuracy_decimals: 2
  - platform: adc
    pin: GPIO2
    <<: *adc_defaults     # 复用同一组字段

3.3 packages 与 !include：多文件组织

!include 把另一个 YAML 文件的内容原样插入当前位置；packages 则把配置拆成若干可复用的「包」，在多个设备共享同一份基础配置时尤其有用。

# 设备主配置
packages:
  wifi: !include common/wifi.yaml
  base: !include common/base.yaml

把 Wi-Fi、日志、OTA 等每个设备都一样的部分抽到 common/ 下，新设备直接引用即可，避免重复编写。详见 Packages 与 YAML 配置。

3.4 external_components：引入第三方组件

当某个硬件的驱动尚未合入 ESPHome 官方版本时，可以用 external_components 从 GitHub 等来源引入社区编写的组件。

external_components:
  - source: github://用户名/仓库名@分支
    components: [ 组件名 ]

第 5 节用到的 RLCD-4.2 显示屏，其 ST7305 驱动就是通过这种方式引入的，届时会有完整示例。

4. lambda 简介

ESPHome 的 YAML 是声明式的——你描述「有什么」，而不是「怎么做」。当遇到声明式语法表达不了的逻辑（比如对读数做自定义换算、按条件触发动作）时，可以写一小段 lambda 补上。

lambda 里写的是 C++ 代码。最常见的入门用法，是在传感器的 filters: 中做数值转换：

sensor:
  - platform: adc
    pin: GPIO1
    name: "Light Level"
    filters:
      - lambda: |-
          // x 是这一级收到的原始读数，返回值即为转换后的结果
          return x * 100.0;

备注

lambda 是通往 ESPHome 高级用法的入口，但它本质是 C++，深入使用需要一定编程基础，已超出本入门教程的范围。需要时请参考 Automations & Templates。

5. devices.esphome.io 与社区配置

devices.esphome.io 是一个社区维护的设备配置索引，收录了大量开发板和成品设备的现成 ESPHome 配置，可以作为查找的起点。

使用时请注意：

• 这些配置由社区贡献，不由微雪官方维护，质量与时效参差不齐。
• 引脚定义、组件版本可能与你手上的硬件或当前 ESPHome 版本不一致。

建议将社区配置作为参考，而非直接套用：复制后按第 1 节的方法逐段核对每个组件的字段，用 Validate 校验确认无误，再烧录测试。

6. 本节常见问题

• 改了 substitutions 但没生效：确认正文里用的是 ${变量名}，且变量名拼写一致；substitutions 块必须位于配置顶层。
• !include 报找不到文件：路径相对于主配置文件所在目录，注意 common/wifi.yaml 这类子目录写法。
• I²C 传感器在 LOGS 中扫描不到：检查 SDA/SCL 是否接反、是否缺上拉电阻、地址是否与文档一致；先打开 scan: true，看日志里实际报出的地址。
• external_components 拉取失败：多半是网络无法访问 GitHub，或 source 里的仓库/分支名写错。
• 加了组件后 HA 里没出现新实体：确认烧录成功且设备在线；只有带 name 的组件才会生成实体，纯总线声明（如 i2c:）不会。

7. 参考链接

• ESPHome 组件索引（ESPHome Docs）
• ESPHome YAML 配置
• ESPHome 配置类型（Config Types）
• ESPHome Cookbook
• ESPHome Automations & Templates
• ESPHome Packages
• GPIO Binary Sensor
• devices.esphome.io