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

    • 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.

    • platform_version (Optional, string): The version of the platformio/espressif8266 package to use.

  • 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.

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 Analog To Digital Sensor 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.

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).

See Also