Generic ESP8266

All ESP8266-based devices are supported by ESPHome. Simply select ESP8266 when the ESPHome wizard asks you for your platform and choose a board type from this link when the wizard asks you for the board type.

# Example configuration entry
esphome:
  name: livingroom
  platform: ESP8266
  board: <BOARD_TYPE>

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 out voltages (in the range from 0 to 1.0V) on this pin.
# Example configuration entry
esphome:
  name: livingroom
  platform: 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 ESP8266 bootloader uses a baudrate of 76800, whereas the use 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).