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

ESP8266 平台

此组件包含针对 ESP8266 平台的平台特定选项。

# Example configuration entry
esp8266:
  board: nodemcuv2
  framework:
    version: recommended

配置变量

Section titled “配置变量”

  • board (Required, string): 应使用的 PlatformIO 开发板 ID。从 此列表中选择合适的开发板（名称旁的图标可用于复制开发板 ID）。这只会影响引脚别名、闪存大小和一些内部设置，如果不确定， 请选择 Espressif 的通用开发板，如 esp01_1m。

  • framework (Optional): ESPHome 所使用的底层框架的选项。

  • restore_from_flash (Optional, boolean): 是否将一些持久化偏好设置存储在闪存中。默认为 false。

  • board_flash_mode (Optional, string): 闪存芯片的 SPI 模式。可取 qio、qout、dio 和 dout 之一。默认为 dout 以兼容所有芯片。注意：在下次 OTA 更新时，实际的闪存模式会被自动检测并更改为合适的模式。

  • early_pin_init (Optional, boolean): 指定引脚是否应尽早初始化为已知值。当涉及开关时建议使用 false，因为在更新固件或重新启动设备时这些会切换状态。默认为 true。

  • enable_serial (Optional, boolean): 强制启用 Arduino 的 Serial 对象（UART0），用于在 lambda 或外部库中使用。大多数用户永远不需要此选项，因为 logger 和 uart 组件会自动启用所需的 Serial 对象。仅当你在 lambda 中直接访问 Serial 并出现编译错误时才使用此选项。如有可能，请改用 UART 组件，因为它在所有平台上都有效。默认为自动检测。

  • enable_serial1 (Optional, boolean): 强制启用 Arduino 的 Serial1 对象（UART1），用于在 lambda 或外部库中使用。大多数用户永远不需要此选项，因为 logger 和 uart 组件会自动启用所需的 Serial 对象。仅当你在 lambda 中直接访问 Serial1 并出现编译错误时才使用此选项。如有可能，请改用 UART 组件，因为它在所有平台上都有效。默认为自动检测。

  • enable_full_printf (Optional, boolean): 启用完整的基于 FILE* 的 printf 支持。默认情况下，ESPHome 使用轻量级桩函数包装 printf()、vprintf() 和 fprintf()，这些桩函数使用 vsnprintf() + fwrite()，可节省约 1.6 KB 闪存。ESPHome 日志通过 Arduino 的 Serial 直接写入 UART，而非 libc printf，因此除非外部组件调用这些函数，否则它们通常不会被使用。仅当某个外部组件需要完整的基于 FILE* 的 printf 时才设置为 true。默认为 false。

  • enable_scanf_float (Optional, boolean): 为 scanf()/sscanf() 启用浮点支持。默认情况下，ESPHome 移除 -u _scanf_float 链接器标志以节省约 8 KB 闪存。这意味着带 %f 的 sscanf() 将静默地无法解析浮点数。ESPHome 自身没有使用 scanf；仅当你在 lambda 中使用了带 %f 的 sscanf() 时才设置为 true。默认为 false。

GPIO 引脚编号

Section titled “GPIO 引脚编号”

许多开发板对外露引脚的引脚编号与内部使用的 编号不同。ESPHome 尝试将丝印引脚号映射到内部引脚号，但这只适用于少数 开发板，对于通用的 ESP8266 开发板，通常需要使用内部引脚号。 要做到这一点，只需在所有引脚前加上 GPIO 前缀，例如内部引脚 号为 0 的引脚写作 GPIO0。

关于引脚的一些说明：

  • GPIO6 - GPIO11、GPIO0、GPIO2 和 GPIO15 通常已被内部 闪存接口和启动模式检测使用。因此最好避免使用这些引脚。

  • GPIO17 额外连接了一个 ADC。参见 Adc 以读取此引脚上的电压（范围 0 到 1.0V）。

# Example configuration entry
esphome:
  name: livingroom


esp8266:
  board: nodemcuv2


binary_sensor:
  - platform: gpio
    name: "Pin GPIO17"
    pin: GPIO17

特殊引脚

Section titled “特殊引脚”
GPIO0控制启动模式
GPIO1UART TX 引脚
GPIO2控制启动模式
GPIO3UART RX 引脚
GPIO6SDIO/Flash CLK 引脚
GPIO7SDIO/Flash 数据 0 引脚
GPIO8SDIO/Flash 数据 1 引脚
GPIO9SDIO/Flash 数据 2 引脚（仅 qio/qout）
GPIO10SDIO/Flash 数据 3 引脚（仅 qio/qout）
GPIO11SDIO/Flash CMD 引脚
GPIO12连接到硬件 SPI 控制器 MISO
GPIO13连接到硬件 SPI 控制器 MOSI
GPIO14连接到硬件 SPI 控制器 CLK
GPIO15控制启动模式；连接到硬件 SPI 控制器 CS
GPIO16可从 RTC 访问的特殊引脚，也是深度睡眠唤醒引脚
TOUT 即 GPIO17用于测量电压的 ADC 引脚，只能作为模拟输入引脚使用

这意味着实际上只有以下引脚可以用作通用 GPIO：

引脚限制复位后的状态
GPIO0启动时若为高电平弱上拉
GPIO2启动时若为高电平弱上拉
GPIO4高阻抗
GPIO5高阻抗
GPIO6弱上拉
GPIO12弱上拉
GPIO13弱上拉
GPIO14弱上拉
GPIO15启动时若为低电平弱上拉
GPIO16有下拉（但没有上拉）电阻弱下拉

启动模式

Section titled “启动模式”

每次启动时，ESP8266 都会检查三个引脚以决定进入哪种启动模式。 共有三种启动模式：

模式GPIO0GPIO2GPIO15boot mode:
从闪存启动（正常）HIGHHIGHLOW3
从 UART 下载代码LOWHIGHLOW1
从 SD 卡启动ANYANYHIGH4-7

你可以在启动时查看 UART 输出来识别这些模式，boot mode: 行中的第一个数字 会告诉你选择了哪种模式

ets Jan  8 2013,rst cause:4, boot mode:(3,6)

查看 UART 日志时的第一行可能包含无法识别的字符。这是因为 ESP8266 引导加载程序的有效波特率为 74800，而程序使用 115200。

复位原因

Section titled “复位原因”

此外，第一行还包含复位原因。 这些复位原因已有文档说明：

0未定义
1上电重启
2外部复位或深度睡眠唤醒
4硬件看门狗复位

软件复位后，复位原因不会改变。

崩溃处理器

Section titled “崩溃处理器”

ESPHome 会自动捕获上一次启动时的崩溃数据并在启动时记录。这适用于 所有崩溃类型：异常（空指针解引用、非法指令）、软件看门狗 复位和硬件看门狗复位。

当发生崩溃时，异常原因、故障 PC 以及最多 16 个栈扫描返回地址会在 重启后保留并以 ERROR 级别记录。ESPHome CLI 会自动将这些 地址解码为函数名。

[E][esp8266]: *** CRASH DETECTED ON PREVIOUS BOOT ***
[E][esp8266]:   Reason: Exception - StoreProhibit (exccause=29)
[E][esp8266]:   PC: 0x40212EC5
[E][esp8266]:   BT0: 0x40212F5A
[E][esp8266]:   BT1: 0x40203B10
[E][esp8266]:   BT2: 0x40203270

无需任何配置——崩溃处理器始终处于启用状态。

电气特性

Section titled “电气特性”
参数最小典型最大单位
工作温度-40125°C
工作电压 V_IO2.53.33.6V
V_IL - 视为 LOW 的输入电压电平-0.30.25*V_IOV
V_IH - 视为 HIGH 的输入电压电平0.75*V_IO3.6V
V_OL - 对应 LOW 的输出电压电平0.1*V_IOV
V_OH - 对应 HIGH 的输出电压电平0.8*V_IOV
I_MAX - GPIO 的最大电流12mA
深度睡眠功耗20µA
活动模式的功耗120mA

来源：ESP8266EX 数据手册

内部上拉/下拉电阻的阻值为 30kΩ 至 100kΩ （来源）。

另请参见

Section titled “另请参见”