ESP32 and ESP8266 boards for ESPHome

Notes on various boards and their idiosyncrasies.

Most (but not all) ESP321 have Bluetooth (most of those have BLE only), and is the successor of ESP82662. The chips are made by Espressif, and they publish the datahseets online3.

ESPHome uses/wraps PlatformIO, and thus uses their naming4 for the chips, boards and their variants.

There are a lot of different chips, boards, devkits and variants there of available5. Almost all of them are cheap, eBay is a is a good source for buying them but expect them to be shipped from China and delivery time to reflect that.

Tip: the FCC ID's (often printed on the metal cover) are useful for identifying boards as they are listed in the Wikipedia articles.

NodeMCU ESP32

ManufacturerVarious, ESP32 is made by Espressif Systems
Datasheetesp32_datasheet_en.pdf
Reference manualesp32_technical_reference_manual_en.pdf
Pinoutnodemcu_esp32_pinout.jpg
PlatformIONodeMCU-32S
ESPHome deviceNodeMCU ESP32
ESPHome platformESP32 Platform
Recomended frameworkarduino6
ESPHome configpackages/boards/esp32nodemcu.yaml7

NodeMCU ESP32 board with Micro-USB connector (USB-C is also available)

ESPHome support

Board config:

esp32:
  board: nodemcu-32s
  framework:
    type: arduino

Config for status_led:

light:
  - platform: status_led
    name: "Status LED"
    id: esp_status_led
    icon: "mdi:alarm-light"
    restore_mode: ALWAYS_OFF
    pin: GPIO02

Pinout

NodeMCU ESP32 pinout

Pins

InterfacePinsNotes
ADCGPIO32-GPIO39

Some notes about the pins NodeMCU8 ESP329:

  • GPIO0: Boot mode, will boot into flash mode if pulled LOW on startup. Can be used as output pin.
  • GPIO2: Blue status_led. Supports touch pad binary_sensor (like other pins).
  • GPIO34-GPIO39: Can not be used as outputs.
  • GPIO32-GPIO39: ADC pins
  • 5V: Connected to the 5\(V\) railfrom the USB bus, can power another board8.

ESP32 WROOM

Manufacturer
Board docs
Datasheet
Schematic
Pinoutesp32_wroom_pinout.png
PlatformIODOIT ESP32 DEVKIT V1
ESPHome platformESP32 Platform
Recomended frameworkarduino6
ESPHome configpackages/boards/esp32wroom.yaml7

This is a bit of an oddball board10 that I have a few of. It is basically the same as a regular ESP32, with more pins.

ESPHome support

esp32:
  board: esp32doit-devkit-v1
  framework:
    type: arduino

Pinout

ESP32 Wroom

ESP32 S2 mini

ManufacturerWemos
Board docsS2 mini
Datasheetesp32_s2_mini_v1.0.0_datasheet.pdf
Dimensionsesp32_s2_mini_v1.0.0_dimensions.pdf
Schematicesp32_s2_mini_v1.0.0_schematic.pdf
PinoutESP32_S2_mini_pinout.jpg
Pinout (simple)s2_mini_v1.0.0_4_16x9.jpg
PlatformIOWEMOS LOLIN S2 Mini
ESPHome platformESP32 Platform
Recomended frameworkesp-idf11
ESPHome configpackages/boards/esp32s2mini.yaml7
arduino-esp32 pinspins_arduino.h

ESP32 S2 Mini ESP32 S2 Mini underside

ESPHome support

Board config:

esp32:
  board: lolin_s2_mini
  variant: ESP32S2
  framework:
    type: esp-idf
    # for Python 3.8 (unsure if works on defaults on up-to-date Python)
    # This can be removed after initial USB flash (if it was used)
    version: 4.4.3
    platform_version: 5.3.0

Config for status_led:

light:
  - platform: status_led
    name: "Status LED"
    id: esp_status_led
    icon: "mdi:alarm-light"
    restore_mode: ALWAYS_OFF
    pin:
      number: GPIO15
      inverted: false

Pinout

ESP32 S2 mini pinout

Pins

The ESP32 S2 Mini board has 2x ADCs, and 2x UART channels12.

InterfacePinsNotes
ADC1GPIO01-GPIO10
ADC2GPIO11-GPIO14, GPIO19-GPIO20, DAC_1, DAC_2Not usable when Wi-Fi is enabled
UARTAny GPIO pins
LED PWMAny GPIO pins (maybe not GPIO15)
I²CAny GPIO pinsSchematic shows SDA on GPIO33 and SCL on GPIO35 (see below)
SPIGPIO09-GPIO14 and GPIO33-GPIO374x SPI interfaces (SPI0-SPI3)

Unsafe pins (strapping pins, trigger bootloader modes if pulled up/down):

  • GPIO0 (Button 0): SPI boot mode, pull-up
  • GPIO45: VDD_SPI voltage, defaults as pull-down 0V
  • GPIO46: SPI boot mode, pull-down

Other notes about pins

  • GPIO33: I²C SCL (schematic)
  • GPIO35: I²C SDA (schematic)
  • GPIO11-GPIO20 (ADC2): Not usable when Wi-Fi is enabled.
  • Power supply for GPIO33, GPIO34, GPIO35, GPIO36 and GPIO37 is configurable to be either VDD3P3_CPU (default) or VDD_SPI.
  • GPIO10, GPIO34: FSPI/SPI CS0 (Chip select).
  • GPIO12, GPIO36: FSPI/SPI CLK (Clock).
  • Supports LEDC PWM from esp-idf13.
  • The ESPHome ledc component only supports using GPIO00-GPIO3314.
  • For pin mappings used by the arduino framework, see pins_arduino.h. Currently unsure if the mappings are different in esp-idf.

Notes on I²C on the S2 Mini

According to the datasheet any GPIO pins can be used for the I²C bus. But then the schematic shows:

  • GPIO33: SDA
  • GPIO35: SCL

It seems that the datasheet is "more correct", and that it is in fact possible to use any GPIO pins for I²C (though GPIO33 and GPIO35 might be handling I²C on the hardware level, other pins might be using them on the software level?).

Using I²C with the esp-idf framework, you might see errors like:

[C][i2c.idf:061]: I2C Bus:
[C][i2c.idf:062]:   SDA Pin: GPIO16
[C][i2c.idf:063]:   SCL Pin: GPIO18
[C][i2c.idf:064]:   Frequency: 50000 Hz
[C][i2c.idf:073]:   Recovery: failed, SDA is held low on the bus

The i2c component in esp-idf has two undocumented15 parameters, sda_pullup_enabled and scl_pullup_enabled, that can be used to enable or disable the internal \(10kΩ\) pullup resistors. By default, they are enabled on GPIO33 and GPIO35, and according to the datasheet from Espressif, the S2 Mini has both internal pullup and pulldown resistors on all GPIO pins.

To use pins other than GPIO33 and GPIO35, you need to disable or enable these internal pullup resistors. Wether you need to enable or disable them seem to depend on what device you are connecting. For an PN532 RFID/NFC reader, you need to disable them:

i2c:
  sda_pullup_enabled: false
  scl_pullup_enabled: false

Then you can configure any GPIO pins for I²C:

i2c:
  sda: GPIO33
  scl: GPIO35
  sda_pullup_enabled: false
  scl_pullup_enabled: false
Note that this only works on the esp-idf framework. Using the arduino framework, these options are not avilable, and I²C seems to work better with it in general.

There are some reports the arduino framework working better for I²C. This seems to be true, as I have only managed to get SSD1306 OLED displays working using the arduino framework so far.

Found someone on reddit saying that the S2 Mini doesn't have internal pull-up resistors on GPIO33 and GPIO35. But i don't think that is true since disabling them (by setting sda_pullup_enabled and scl_pullup_enabled on esp-idf) is what got a PN532 to start working.

This also works well with YAML anchors and the ESPHome !include syntax if you use packages. You can specify defaults for the i2c components, and then using the above you can override them in the file importing it.

I'm unsure why datasheet says that any pins can be used for I²C when the schematic shows GPIO33 and GPIO35 being wired as SDA and SCL, maybe it's done in software or software/firmware can bridge other GPIO pins to the internal system pins for I²C on the chip.

Sidenote: Sometimes, for some components, it can help to set the frequency to \( 400 kHz \) for the I²C bus.

Enter bootloader mode to program over USB

To put the ESP32 S2 Mini into bootloader mode:

  1. Unplug USB/power
  2. Hold both buttons (Marked RST and 0)
  3. Plug in USB
  4. Release RST ("reset")
  5. Release 0 ("boot")

This puts the device into boot loader mode where it can be flashed. On Linux it appears as /dev/ttyACM0 (or higher number if 0 already exists). On Mac OS it shows up as /dev/tty.usbmodem01 anid /dev/cu.usbmodem01.

Sometimes you can press the buttons after you plug in USB.

Issues:

  • apparmor gets in the way and disrupts the access ("protocol error")

Useful tool: Adafruit ESPTool only works on Chrome. Can be used to erease memory.

Erease memory:

# its unclear what argument to pass to --port
esptool.py --port COM13 erase_flash

Flashing my bootstrap config on Mac OS:

# with esph.py wrapper
./esph.py run esp32-s2-mini --name study-VINDRUTA --user --domain s21.sudo.is --device /dev/tty.usbmodem01

# without wrapper, using esphome directly
esphome -s node_name $namee -s lower_node_name $hostname -s domain $domain run esp32-s2-mini.yaml --device /dev/tty.usbmodem0

Some incomplete answers online that I stitched this together from:

press both buttons and release programming button, s2 mini set for programming16

hold 0, press reset, release 017

ESP32 C3 Super Mini

ManufacturerWemos
Board docs (C3 mini)C3 Mini
Datasheet (C3)esp32_c3_datasheet.pdf
Dimensions (C3 mini)esp32_c3_mini_dimensions.pdf
Schematic (C3 mini)esp32_c3_schematic.pdf
Pinoutesp32_c3_supermini_pinout.jpg
MicrosoftESP32-C3 SuperMini
PlatformIOEspressif ESP32-C3-DevKitM-1
AnnouncementIntroducing ESP32-C3
ESPHome platformESP32 Platform
Recomended frameworkesp-idf11
ESPHome configpackages/boards/esp32c3supermini.yaml7

ESP32 C3 Super mini

ESPHome support

Board config:

esphome:
  platformio_options:
    board_build.f_flash: 40000000L
    board_build.flash_mode: dio
    board_build.flash_size: 4MB

esp32:
  board: esp32-c3-devkitm-1
  variant: esp32c3
  framework:
    type: esp-idf

Config for status_led:

light:
  - platform: status_led
    name: "Status LED"
    id: esp_status_led
    icon: "mdi:alarm-light"
    pin:
      number: GPIO8
      inverted: true
    restore_mode: ALWAYS_OFF

Pinout

ESP32 C3 super mini pinout

Pins

On the C3 SuperMini the pins are as follows18:

Silkscreen pinInternal pinInterfaces
0GPIO0Analog, GPIO
1GPIO1Analog, GPIO
2GPIO2Analog, GPIO, boot
3GPIO3Analog, GPIO
4GPIO4Analog, GPIO, debug
5GPIO5GPIO, Debug
6GPIO6I²C SDA, GPIO, debug
7GPIO7I²C SCL, GPIO, debug
8GPIO8status_led (inverted), GPIO, boot
9GPIO9Boot button, boot mode, GBPIO
10GPIO10GPIO
20GPIO20UART RX, GPIO
21GPIO21UART TX, GPIO

The blue status_led is on GPIO8 and is inverted. Additionally the Wemos C3 Mini documentation shows a RGB led on GPIO7, but that might be on the C3 Mini only (and not SuperMini). This will be checked experimentally.

Enter bootloader mode to program over USB

If the ESP C3 SuperMini is unprogrammed, it seems to enter bootloader mode by default when plugged in with USB. If it has been programmed, it will connect and disconnected. To put the ESP32 C3 SuperMini into bootloader mode (if it is connecting/disconnected, or has been programmed):

  1. Plug in USB
  2. Hold both buttons
  3. Release both buttons at the same time

Before you press the buttons it will connect and disconnect.

Watching dmesg while you do this is helpful:

$ sudo dmesg -w

usb 3-2: Product: USB JTAG/serial debug unit
usb 3-2: Manufacturer: Espressif
cdc_acm 3-2:1.0: ttyACM0: USB ACM device

usb 3-2: USB disconnect, device number 89

On Linux (Fedora) it show up as /dev/ttyACM0 (or ttyACM1 etc).

ESP32 WT32-ETH01

ESP32 WROVER

Freenove ESP32-WROVBER CAM board

ESPHome support

esp32:
  board: esp-wrover-kit
  framework:
    type: arduino

Pinout

ESP32 WROVER pinout

Pins

Camera pins:

Pin
GPIO4Y2 data
GPIO5Y3 data
GPIO18Y4 data
GPIO19Y5 data
GPIO21XCLK / external clock
GPIO22PCLK / pixel clock
GPIO23HREF
GPIO25VSYNC
GPIO26SIOD / I²C SDA
GPIO27SIOC / I²C SCL
GPIO36 / VPY6 data
GPIO39 / VNY7 data
GPIO34Y8 data
GPIO35Y9 data

NodeMCU ESP8266

ManufacturerVarious, ESP8266 is made by Espressif Systems
DatasheetESP8266-NodeMCU-Datasheet.pdf
Pinoutnodemcu_esp8266_pinout.jpg
Arduino pinsnodemcu/pins_arduino.h
ESPHome deviceNodeMCU ESP8266
ESPHome platformESP8266 Platform
Recomended frameworkarduino19
ESPHome configpackages/boards/esp8266nodemcu.yaml7

NodeMCU ESP8266 board with micro-USB connector (USB-C variants are also available)

ESPHome support

Board config:

esp8266:
  board: nodemcuv2

Config for status_led (on some boards):

light:

  # this is the built-in blue stauts LED
  - platform: status_led
    name: "Status LED"
    id: esp_status_led
    icon: "mdi:alarm-light"
    entity_category: "config"
    restore_mode: ALWAYS_OFF
    pin:
      number: D4
      inverted: true

  # only on some boards, this is the built in AUX led, next to the UART chip
  - platform: status_led
    name: "AUX LED"
    id: esp_aux_led
    icon: "mdi:alarm-light"
    entity_category: "config"
    restore_mode: ALWAYS_OFF
    pin:
      number: D0
      inverted: true

Pinout

NodeMCU ESP8266 pinout

Pins

The NodeMCU pin numbering on the silkscreen (e.g. D0, A0) is different from the internal pin numbering. ESPHome knows how to map the silkscreen pins numbers to internal pin numbers20.

Silkscreen pinInternal pinInterfaceNotes
A0GPIO17ADC
D0GPIO16Deep-sleep wakeup, AUX LED (inverted)Can be accessed from RTC, weak pull-down
D1GPIO5I²C SCLHigh impedence
D2GPIO4I²C SDAHigh impedence
D3GPIO0Controls boot mode (strapping pin), weak pull-up
D4GPIO2Blue LED (inverted)Controls boot mode (strapping pin), weak pull-up
D5GPIO14SPI CLK/SCKWeak pull-up
D6GPIO12SPI MISOWeak pull-up
D7GPIO13SPI MOSIWeak pull-up
D8GPIO15SPI CS/SSControls boot mode (strapping pin), weak-pull-up
RX / D9GPIO3UART Serial RX
TX / D10GPIO1UART Serial TX

The ESP8266 can only use the designed pins for each interface (SPI, UART, I²C, etc), other pins can't be used for them.

InterfacePins
status_ledD4 / GPIO2
UART RXRX / D9 / GPIO03
UART TXTX / D10 / GPIO01
SPI MISOD6 / GPIO12
SPI MOSID7 /GPIO13
SPI CLK/SCKD5/ GPIO14
SPI CS/SSD8 / GPIO15
ADCA0 / GPIO17
I²C SCLD1 / GPIO5
I²C SDAD2 / GPIO4

Some notes about pins on NodeMCU ESP826619:

  • The inernal pull-up/-down resistors have values of \( 30 kΩ \) to \( 100 kΩ \)21.
  • In some cases pins marked as INTERNAL on the pinout can be used.
  • D0 can be ued to wake the device up from deep sleep if the pin is connected to the RESET pin.
  • D3, D4, D8: Strapping pins that control boot mode. If these are used as general purpose GPIO pins they should be in the default states to boot from flash:
    • D3 (GPIO0): HIGH
    • D4 (GPIO2): HIGH (blue status led)
    • D8 (GPIO15): LOW
  • D4 (GPIO2): connected to blue status_led, in inverted mode.
  • D0 (GPIO16, only on some boards): AUX LED next to the UART chip, in inverted mode.
  • A0 (GPIO17): ADC pin, measures voltages from \(1 0 \) to \( 1 V \). Can be used as a normal GPIO pin.
  • VIN: Voltage input, board can be powered by external power supply on this pin. Some boards support up to \(12 V\), other \(5 V\).
  • ENABLE/RESET: Board resets when these pins are triggered. Difference is how they handle voltages above \(3.3 V\).

When the ESP8266 boots, the three strapping pins are checked to determins which boot mode to enter19:

ModeUART codeGPIO0 (D3)GPIO2 (D4)GPIO15 (D8)
Boot from flash (normal)3HIGHHIGHLOW
Program from UART1LOWHIGHLOW
Boot from SD-card4-7AnyAnyHIGH

The reset causes are documeted in the datasheet and are as follows:

UART codeReset cause
0Undefined
1Power on reboot
2Deep-sleep wake-up or external reset
4Hardware WDT reset

On boot, the first line in the UART output tells you which boot mode was used and the reset cause:

rst cause:4, boot mode:(3,6)

Here the reset cause was 4 and the boot mode was 3.

ESP8266 D1 Mini

ESP8266 D1 Mini ESP8266 D1 Mini underside

ESPHome support

Board config:

esp8266:
  board: d1_mini

Config for status_led:

light:
  - platform: status_led
    name: "Status LED"
    id: esp_status_led
    icon: "mdi:alarm-light"
    restore_mode: ALWAYS_OFF
    pin:
      number: D4
      inverted: true

Pinout

ESP32 D1 mini pinout

This pinout diagram displays the internal pin numbers, not what's printed on the silkscreen

Pins

Silkscreen pinInternal pinInterfaceNotes
A0GPIO17ADC
D0GPIO16Deep-sleep wakeupCan be accessed from RTC, weak pull-down
D1GPIO5I²C SCLHigh impedence
D2GPIO4I²C SDAHigh impedence
D3GPIO0Controls boot mode (strapping pin), weak pull-up
D4GPIO2Blue LED (inverted)Controls boot mode (strapping pin), weak pull-up
D5GPIO14SPI CLK/SCKWeak pull-up
D6GPIO12SPI MISOWeak pull-up
D7GPIO13SPI MOSIWeak pull-up
D8GPIO15SPI CS/SSControls boot mode (strapping pin), weak-pull-up
RXGPIO3UART Serial RX
TXGPIO1UART Serial TX

The pin number mappings are similar to NodeMCU ESP8266, but the D1 mini has fewer pins, all of which map to intenral pin numbers. Has no AUX LED on any boards.

Largely the pin notes from NodeMCU 8266 apply to D1 mini, the boot modes and reset causes are the same.


References

22

Components 101 NodeMCU ESP8266