ESP8266 Platform

This component contains platform-specific options for the ESP8266 platform.

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

Configuration variables

board (Required, string): The PlatformIO board ID that should be used. Choose the appropriate board from this list (the icon next to the name can be used to copy the board ID). This only affects pin aliases, flash size and some internal settings, if unsure choose a generic board from Espressif such as esp01_1m.
framework (Optional): Options for the underlying framework used by ESPHome.
- version (Optional, string): The base framework version number to use, from esp8266 arduino releases. Defaults to recommended. Additional values
  - dev : Use the latest commit from https://github.com/esp8266/Arduino, note this may break at any time. Only with the platformio toolchain.
  - latest : Use the latest release from https://github.com/esp8266/Arduino/releases, even if it hasn’t been recommended yet. With the arduino toolchain, the newest version ESPHome publishes (see Toolchain).
  - recommended : Use the recommended framework version.
- source (Optional, string): The PlatformIO package or repository to use for the framework. This can be used to use a custom or patched version of the framework. Only with the platformio toolchain.
- platform_version (Optional, string): The version of the platformio/espressif8266 package to use. Only used by the platformio toolchain.
restore_from_flash (Optional, boolean): Whether to store some persistent preferences in flash memory. Defaults to false.
board_flash_mode (Optional, string): The SPI mode of the flash chip. One of qio, qout, dio and dout. Defaults to dout for compatibility with all chips. Note: on the next OTA update the actual flash mode is automatically detected and changed to the appropriate one.
early_pin_init (Optional, boolean): Specifies whether pins should be initialised as early as possible to known values. Recommended value is false where switches are involved, as these will toggle when updating the firmware or when restarting the device. Defaults to true.
enable_serial (Optional, boolean): Force-enable the Arduino Serial object (UART0) for use in lambdas or external libraries. Most users will never need this option, as the logger and uart components automatically enable the required Serial objects. Only use this if you directly access Serial in a lambda and get a compilation error. Use the UART component instead when possible, as it works across all platforms. Defaults to automatic detection.
enable_serial1 (Optional, boolean): Force-enable the Arduino Serial1 object (UART1) for use in lambdas or external libraries. Most users will never need this option, as the logger and uart components automatically enable the required Serial objects. Only use this if you directly access Serial1 in a lambda and get a compilation error. Use the UART component instead when possible, as it works across all platforms. Defaults to automatic detection.
enable_full_printf (Optional, boolean): Enable full FILE*-based printf support. By default, ESPHome wraps printf(), vprintf(), and fprintf() with lightweight stubs that use vsnprintf() + fwrite(), saving ~1.6 KB of flash. ESPHome logging writes directly to the UART via Arduino’s Serial, not libc printf, so these functions are typically unused unless an external component calls them. Set to true only if an external component needs full FILE*-based printf. Defaults to false.
enable_scanf_float (Optional, boolean): Enable float support for scanf()/sscanf(). By default, ESPHome removes the -u _scanf_float linker flag to save ~8 KB of flash. This means sscanf() with %f will silently fail to parse floating-point numbers. Nothing in ESPHome itself uses scanf; set to true only if you use sscanf() with %f in lambdas. Defaults to false.
toolchain (Optional, Toolchain): Toolchain used to build the firmware. Defaults to arduino. The platformio toolchain is deprecated and will be removed in 2027.4.0.

Toolchain Configuration

ESPHome supports two toolchains for building ESP8266 firmware. The toolchain determines how the firmware is compiled and which build system is used.

arduino (default): builds the Arduino core directly. ESPHome downloads the framework and the compiler itself and drives the build natively, the same way the ESP32 platform builds ESP-IDF. The resulting firmware is functionally identical to a PlatformIO build.
platformio (deprecated): builds through PlatformIO.

WARNING

The platformio toolchain is deprecated and will be removed in 2027.4.0. Configurations that only select it can drop toolchain: platformio now; configurations that need it (a custom framework source, a framework version other than the ones ESPHome publishes, a board outside the board list) must add it when upgrading, and stop building with that release.

The arduino toolchain builds the framework versions ESPHome publishes, currently 3.1.2, which recommended and latest both select. It does not support a custom framework source, ignores platform_version, and only supports the named boards from the board list; use platformio for other framework versions or custom boards. Under esphome: platformio_options: it honors build_flags, build_unflags, lib_deps, lib_ignore, board_build.f_cpu and board_build.ldscript; other options are ignored with a warning.

The arduino toolchain uses compiler builds from esphome-libs/xtensa-lx106-elf-toolchain, which are available for Linux (x86_64 and arm64), macOS (Apple Silicon and Intel) and Windows (x86_64). On other host systems, use the platformio toolchain.

NOTE

On Apple Silicon Macs the platformio toolchain needs Rosetta 2, because its compiler is only built for Intel Macs. The arduino toolchain runs natively and does not need it.

Example for using the PlatformIO toolchain until it is removed:

esp8266:
  board: nodemcuv2
  toolchain: platformio

GPIO Pin Numbering

Many boards have a pin numbering for the exposed pins that is different from the internally used ones. ESPHome tries to map the silk-screen pin numbers into the internal pin numbers with a few boards, but for generic ESP8266 boards it is often required to just use the internal pin numbers. To do this, just prefix all pins with GPIO, for example GPIO0 for the pin with the internal pin number 0.

Some notes on the pins:

GPIO6 - GPIO11, GPIO0, GPIO2 and GPIO15 are often already used by the internal flash interface and boot mode detection. So it’s best to avoid using these pins.
GPIO17 additionally has an ADC connected to it. See the Adc to read voltages (in the range from 0 to 1.0V) on this pin.

# Example configuration entry
esphome:
  name: livingroom

esp8266:
  board: nodemcuv2

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

Special Pins

`GPIO0`	Controls Boot Mode
`GPIO1`	UART TX pin
`GPIO2`	Controls Boot Mode
`GPIO3`	UART RX pin
`GPIO6`	SDIO/Flash CLK pin
`GPIO7`	SDIO/Flash Data 0 pin
`GPIO8`	SDIO/Flash Data 1 pin
`GPIO9`	SDIO/Flash Data 2 pin (qio/qout only)
`GPIO10`	SDIO/Flash Data 3 pin (qio/qout only)
`GPIO11`	SDIO/Flash CMD pin
`GPIO12`	Attached to Hardware SPI controller MISO
`GPIO13`	Attached to Hardware SPI controller MOSI
`GPIO14`	Attached to Hardware SPI controller CLK
`GPIO15`	Controls Boot Mode; Attached to Hardware SPI controller CS
`GPIO16`	Special pin that can be accessed from RTC, and is Deep-Sleep wakeup pin
TOUT aka `GPIO17`	ADC pin for measuring voltages, can only be used as analog input pin

This means effectively only the following pins can be used as general purpose GPIO:

Pin	Restrictions	State after Reset
`GPIO0`	If HIGH on boot	Weak Pull Up
`GPIO2`	If HIGH on boot	Weak Pull Up
`GPIO4`		High Impedance
`GPIO5`		High Impedance
`GPIO6`		Weak Pull Up
`GPIO12`		Weak Pull Up
`GPIO13`		Weak Pull Up
`GPIO14`		Weak Pull Up
`GPIO15`	If LOW on boot	Weak Pull Up
`GPIO16`	Has pull-down (but no pull-up) resistor	Weak Pull Down

Boot Modes

On each boot, the ESP8266 will check three pins to determine in which boot mode to enter. There are three boot modes:

Mode	`GPIO0`	`GPIO2`	`GPIO15`	`boot mode:`
Boot from Flash (normal)	HIGH	HIGH	LOW	3
Download Code from UART	LOW	HIGH	LOW	1
Boot from SD-Card	ANY	ANY	HIGH	4-7

You can identify these on boot-up by looking at the UART output, the first number in the boot mode: line tells you what mode was selected

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

The first lines when viewing the UART logs might have unrecognized characters. This is because the effective baudrate of the ESP8266 bootloader is 74800, whereas the program uses 115200.

Reset Causes

Additionally, the first line also contains the reset cause. These reset causes are documented:

0	Undefined
1	Power On Reboot
2	External reset or deep-sleep wakeup
4	Hardware WDT reset

After a software reset, the reset cause will not change.

Crash Handler

ESPHome automatically captures crash data from the previous boot and logs it on startup. This works for all crash types: exceptions (null pointer dereference, illegal instruction), software watchdog resets, and hardware watchdog resets.

When a crash occurs, the exception cause, fault PC, and up to 16 stack-scanned return addresses are preserved across the reboot and logged at the ERROR level. The ESPHome CLI automatically decodes the addresses to function names.

[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

No configuration is needed — the crash handler is always enabled.

Electrical Characteristics

Parameter	Min.	Typical	Max.	Unit
Operating Temperature	-40		125	°C
Working Voltage `V_IO`	2.5	3.3	3.6	V
`V_IL` - INPUT voltage level to be considered LOW	-0.3		0.25*V_IO	V
`V_IH` - INPUT voltage level to be considered HIGH	0.75*V_IO		3.6	V
`V_OL` - OUTPUT voltage level for LOW			0.1*V_IO	V
`V_OH` - OUTPUT voltage level for HIGH	0.8*V_IO			V
`I_MAX` - Maximum current for GPIO			12	mA
Power Consumption in Deep Sleep		20		µA
Power Consumption in Active Mode		120		mA

Source: ESP8266EX datasheet

The internal pull up/down resistors have values of 30kΩ to 100kΩ (source).