配置类型

ESPHome 的配置文件有几种配置类型。本页面描述它们。

ID

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

因为 ESPHome 将您的配置转换为 C++ 代码，而 ID 实际上只是 C++ 变量名，它们还必须遵守 C++ 的命名约定…

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

NOTE

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

引脚

ESPHome 始终使用芯片内部 GPIO 编号。这些内部编号始终是整数，如 16，可以前缀 GPIO。例如，要使用内部 GPIO 编号 16 的引脚，您可以输入 GPIO16 或只是 16。

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

some_config_option:
  pin: GPIO16

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

引脚模式

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

some_config_option:
  # 基本：
  pin: GPIOXX

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

配置变量：

number（必需，引脚）：引脚编号。
inverted（可选，布尔值）：是否应将所有读取和写入的值视为反转。默认为 false。
allow_other_uses（可选，布尔值）：引脚是否也在配置的其他地方指定。默认情况下，多次使用同一引脚将被标记为错误。此选项将抑制错误，适用于引脚在多个组件之间共享的罕见情况。默认为 false。
mode（可选，字符串或映射）：将引脚配置为以不同模式运行，如输入或输出。默认值取决于上下文。接受速记字符串或每个功能可单独启用/禁用的映射：
- input（可选，布尔值）：如果为 true，将引脚配置为输入。
- output（可选，布尔值）：如果为 true，将引脚配置为输出。
- pullup（可选，布尔值）：激活引脚上的内部上拉电阻。
- pulldown（可选，布尔值）：激活引脚上的内部下拉电阻。
- open_drain（可选，布尔值）：将引脚设置为开漏（而不是推挽）。活动引脚状态将导致高阻抗状态。
为兼容性，也可以使用某些速记模式。
- INPUT
- OUTPUT
- OUTPUT_OPEN_DRAIN
- ANALOG
- INPUT_PULLUP
- INPUT_PULLDOWN
- INPUT_OUTPUT_OPEN_DRAIN

高级选项：

drive_strength（可选，字符串）：在带有 esp-idf 框架的 ESP32 上，还可以设置焊盘驱动强度，即最大电流量。默认为 20mA。选项为 5mA、10mA、20mA、40mA。
ignore_strapping_warning（可选，布尔值）：ESP32 上的某些引脚被指定为 strapping pins，在复位时由芯片读取以配置初始操作，例如启用引导模式。应避免使用此类引脚进行 I/O，如果 I/O 配置在 strapping 引脚上，ESPHome 将发出警告。

有关更多详情，请参阅为什么我会收到关于 strapping 引脚的警告？。

如果您绝对确定您以不会导致问题的方式使用 strapping 引脚进行 I/O，您可以在引脚配置中将此选项设置为 true 来抑制警告。
ignore_pin_validation_error（可选，布尔值）：ESP32 芯片上的某些引脚保留用于内部功能，如闪存接口（例如，大多数 ESP32 变体上的 GPIO 6-11）。如果您尝试使用这些保留引脚，ESPHome 将引发错误。

但是，某些 ESP32 开发板设计连接了特定的闪存配置，使某些引脚可用于一般用途。如果您绝对确定您的特定开发板设计允许使用通常保留的引脚，您可以通过将此选项设置为 true 来抑制错误。默认为 false。

时间

在 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 相同

配置类型

ID

引脚

引脚模式

时间

另见