跳转到内容
ESPHome - 让智能家居更简单2026.7.0

配置类型

ESPHome 的配置文件有几种配置类型。本页面将对其进行说明。

ID

Section titled “ID”

ESPHome 中一个非常重要的方面是”ID”。它们用于连接不同域中的组件。例如，你定义一个带有 ID 的输出组件，然后在灯光组件中指定相同的 ID。ID 在配置中应始终唯一，如果尝试使用相同的 ID 两次，ESPHome 将发出警告。

由于 ESPHome 会将你的配置转换为 C++ 代码，而 ID 实际上就是 C++ 变量名，因此它们必须遵循 C++ 的命名约定…

  • …必须以字母开头，可以以数字结尾。
  • …名称中不能有空格。
  • …不能包含特殊字符，除了下划线（”_”）。
  • …不能是关键字。

NOTE

这些 ID 仅在 ESPHome 内部使用，不会转换为 Home Assistant 的实体 ID。

引脚

Section titled “引脚”

ESPHome 始终使用芯片内部的 GPIO 编号。这些内部编号始终是像 16 这样的整数，并且可以添加 GPIO 前缀。例如，要使用内部 GPIO 编号为 16 的引脚，你可以输入 GPIO16 或仅输入 16。

然而，大多数开发板对某些引脚有别名。例如，NodeMCU ESP8266 使用引脚名称 D0 到 D8 作为内部 GPIO 引脚编号的别名。每个开发板（在 ESPHome 部分 中定义）都有自己的别名，因此并非所有别名都已被支持。例如，NodeMCU ESP8266 上的 D0 引脚（如 PCB 丝印所示）的内部 GPIO 名称为 GPIO16，但也有一个别名 D0。因此，在配置中使用这两个名称中的任何一个都会得到相同的结果。

some_config_option:
  pin: GPIO16


some_config_option:
  # NodeMCU ESP8266 上的别名：
  pin: D0

引脚模式

Section titled “引脚模式”

在某些地方，ESPHome 还支持更高级的”引脚模式”。

some_config_option:
  # 基本：
  pin: GPIOXX


  # 高级：
  pin:
    number: GPIOXX
    inverted: true
    mode:
      input: true
      pullup: true

配置变量：

  • number (必选, pin): 引脚编号。

  • inverted (可选, boolean): 是否应将所有读取和写入的值视为反转。默认为 false。

  • allow_other_uses (可选, boolean): 该引脚是否也在配置的其他地方指定。 默认情况下，多次使用同一引脚将被标记为错误。此选项将抑制该错误，适用于引脚在多个组件之间共享的少数情况。默认为 false。

  • mode (可选, string 或 mapping): 配置引脚以不同的模式运行，如输入或输出。默认值取决于上下文。 接受简写字符串或映射，其中每个功能可以单独启用/禁用：

    • input (可选, boolean): 如果为 true，将引脚配置为输入。
    • output (可选, boolean): 如果为 true，将引脚配置为输出。
    • pullup (可选, boolean): 激活引脚上的内部上拉电阻。
    • pulldown (可选, boolean): 激活引脚上的内部下拉电阻。
    • open_drain (可选, boolean): 将引脚设置为开漏（相对于推挽）。 引脚激活状态将导致高阻抗状态。

    为兼容性，也可以使用一些简写模式。

    • INPUT
    • OUTPUT
    • OUTPUT_OPEN_DRAIN
    • ANALOG
    • INPUT_PULLUP
    • INPUT_PULLDOWN
    • INPUT_OUTPUT_OPEN_DRAIN

高级选项：

  • drive_strength (可选, string): 在带有 esp-idf 框架的 ESP32 上，还可以设置焊盘驱动强度，即最大电流量。默认为 20mA。 选项为 5mA、10mA、20mA、40mA。

  • ignore_strapping_warning (可选, boolean): ESP32 上的某些引脚被指定为启动引脚，芯片在复位时读取这些引脚以配置初始操作，例如启用引导模式。 应避免使用此类引脚进行 I/O，ESPHome 会在配置了启动引脚上的 I/O 时发出警告。

    更多详情请参见为什么我会收到关于启动引脚的警告？。

    如果你绝对确定你正在以不会引起问题的方式使用启动引脚进行 I/O，你可以通过在引脚配置中将此选项设置为 true 来抑制警告。

  • ignore_pin_validation_error (可选, boolean): ESP32 芯片上的某些引脚保留用于内部功能，如闪存接口（例如，大多数 ESP32 变体上的 GPIO 6-11）。ESPHome 会在你尝试使用这些保留引脚时引发错误。

    然而，某些 ESP32 开发板设计采用特定的闪存配置，从而释放某些引脚供通用使用。 如果你绝对确定你的特定开发板设计允许使用通常保留的引脚，你可以通过将此选项设置为 true 来抑制错误。默认为 false。

时间

Section titled “时间”

在 ESPHome 的许多地方，你需要定义时间段。有几种方法可以做到这一点。请参阅下面的示例，了解如何指定时间段：

some_config_option:
  some_time_option: 1000us  # 1000 微秒 = 1ms
  some_time_option: 1000ms  # 1000 毫秒
  some_time_option: 1.5s  # 1.5 秒
  some_time_option: 0.5min  # 半分钟
  some_time_option: 2h  # 2 小时


  # 确保将这些用引号括起来
  some_time_option: '2:01'  # 2 小时 1 分钟
  some_time_option: '2:01:30'  # 2 小时 1 分钟 30 秒


  # 10ms + 30s + 25min + 3h
  some_time_option:
    milliseconds: 10
    seconds: 30
    minutes: 25
    hours: 3
    days: 0


  # 对于所有 'update_interval' 选项，也可以
  update_interval: never  # 从不更新
  update_interval: 0ms  # 在每个 loop() 迭代中更新
  update_interval: always # 与 0ms 相同

参见

Section titled “参见”