ESP32 and ESP8266 boards for ESPHome

Notes on various boards and their idiosyncrasies.

• NodeMCU ESP32
  • ESPHome support
  • Pinout
  • Pins
• ESP32 WROOM
  • ESPHome support
  • Pinout
• ESP32 S2 mini
  • ESPHome support
  • Pinout
  • Pins
  • Notes on I²C on the S2 Mini
  • Enter bootloader mode to program over USB
• ESP32 C3 Super Mini
  • ESPHome support
  • Pinout
  • Pins
  • Enter bootloader mode to program over USB
• ESP32 WT32-ETH01
• ESP32 WROVER
  • ESPHome support
  • Pinout
  • Pins
• NodeMCU ESP8266
  • ESPHome support
  • Pinout
  • Pins
• ESP8266 D1 Mini
  • ESPHome support
  • Pinout
  • Pins
• References

Most (but not all) ESP32¹ have Bluetooth (most of those have BLE only), and is the successor of ESP8266². The chips are made by Espressif, and they publish the datahseets online³.

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

There are a lot of different chips, boards, devkits and variants there of available⁵. 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

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

Pins

Some notes about the pins NodeMCU⁸ ESP32⁹:

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

ESP32 WROOM

This is a bit of an oddball board¹⁰ 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 S2 mini

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

• Support requested: esphome/feature-requests#996
• Support added: esphome/esphome#3264
• Support added in PlatformIO: platformio/platform-espressif32#736

Pinout

Pins

The ESP32 S2 Mini board has 2x ADCs, and 2x UART channels¹².

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-idf¹³.
• The ESPHome ledc component only supports using GPIO00-GPIO33¹⁴.
• 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 undocumented¹⁵ 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

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 programming¹⁶

hold 0, press reset, release 0¹⁷

ESP32 C3 Super Mini

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

Pins

On the C3 SuperMini the pins are as follows¹⁸:

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

Pins

Camera pins:

NodeMCU ESP8266

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

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 numbers²⁰.

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

Some notes about pins on NodeMCU ESP8266¹⁹:

• The inernal pull-up/-down resistors have values of \( 30 kΩ \) to \( 100 kΩ \)²¹.
• 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 enter¹⁹:

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

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

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

Pins

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