ESP32 and ESP8266 boards for ESPHome
Notes on various boards and their idiosyncrasies.
- NodeMCU ESP32
- ESP32 WROOM
- ESP32 S2 mini
- ESP32 C3 Super Mini
- ESP32 WT32-ETH01
- ESP32 WROVER
- NodeMCU ESP8266
- ESP8266 D1 Mini
- References
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
Manufacturer | Various, ESP32 is made by Espressif Systems |
---|---|
Datasheet | esp32_datasheet_en.pdf |
Reference manual | esp32_technical_reference_manual_en.pdf |
Pinout | nodemcu_esp32_pinout.jpg |
PlatformIO | NodeMCU-32S |
ESPHome device | NodeMCU ESP32 |
ESPHome platform | ESP32 Platform |
Recomended framework | arduino 6 |
ESPHome config | packages/boards/esp32nodemcu.yaml 7 |
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
Interface | Pins | Notes |
---|---|---|
ADC | GPIO32 -GPIO39 |
Some notes about the pins NodeMCU8 ESP329:
GPIO0
: Boot mode, will boot into flash mode if pulledLOW
on startup. Can be used as output pin.GPIO2
: Bluestatus_led
. Supports touch padbinary_sensor
(like other pins).GPIO34
-GPIO39
: Can not be used as outputs.GPIO32
-GPIO39
: ADC pins5V
: Connected to the 5\(V\) railfrom the USB bus, can power another board8.
ESP32 WROOM
Manufacturer | |
---|---|
Board docs | |
Datasheet | |
Schematic | |
Pinout | esp32_wroom_pinout.png |
PlatformIO | DOIT ESP32 DEVKIT V1 |
ESPHome platform | ESP32 Platform |
Recomended framework | arduino 6 |
ESPHome config | packages/boards/esp32wroom.yaml 7 |
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 S2 mini
Manufacturer | Wemos |
---|---|
Board docs | S2 mini |
Datasheet | esp32_s2_mini_v1.0.0_datasheet.pdf |
Dimensions | esp32_s2_mini_v1.0.0_dimensions.pdf |
Schematic | esp32_s2_mini_v1.0.0_schematic.pdf |
Pinout | ESP32_S2_mini_pinout.jpg |
Pinout (simple) | s2_mini_v1.0.0_4_16x9.jpg |
PlatformIO | WEMOS LOLIN S2 Mini |
ESPHome platform | ESP32 Platform |
Recomended framework | esp-idf 11 |
ESPHome config | packages/boards/esp32s2mini.yaml 7 |
arduino-esp32 pins | pins_arduino.h |
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 channels12.
Interface | Pins | Notes |
---|---|---|
ADC1 | GPIO01 -GPIO10 | |
ADC2 | GPIO11 -GPIO14 , GPIO19 -GPIO20 , DAC_1 , DAC_2 | Not usable when Wi-Fi is enabled |
UART | Any GPIO pins | |
LED PWM | Any GPIO pins (maybe not GPIO15) | |
I²C | Any GPIO pins | Schematic shows SDA on GPIO33 and SCL on GPIO35 (see below) |
SPI | GPIO09 -GPIO14 and GPIO33 -GPIO37 | 4x SPI interfaces (SPI0 -SPI3 ) |
Unsafe pins (strapping pins, trigger bootloader modes if pulled up/down):
GPIO0
(Button 0): SPI boot mode, pull-upGPIO45
: VDD_SPI voltage, defaults as pull-down 0VGPIO46
: 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
andGPIO37
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 usingGPIO00
-GPIO33
14. - For pin mappings used by the
arduino
framework, seepins_arduino.h
. Currently unsure if the mappings are different inesp-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
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:
- Unplug USB/power
- Hold both buttons (Marked
RST
and0
) - Plug in USB
- Release
RST
("reset") - 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
Manufacturer | Wemos |
---|---|
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 |
Pinout | esp32_c3_supermini_pinout.jpg |
Microsoft | ESP32-C3 SuperMini |
PlatformIO | Espressif ESP32-C3-DevKitM-1 |
Announcement | Introducing ESP32-C3 |
ESPHome platform | ESP32 Platform |
Recomended framework | esp-idf 11 |
ESPHome config | packages/boards/esp32c3supermini.yaml 7 |
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 follows18:
Silkscreen pin | Internal pin | Interfaces |
---|---|---|
0 | GPIO0 | Analog, GPIO |
1 | GPIO1 | Analog, GPIO |
2 | GPIO2 | Analog, GPIO, boot |
3 | GPIO3 | Analog, GPIO |
4 | GPIO4 | Analog, GPIO, debug |
5 | GPIO5 | GPIO, Debug |
6 | GPIO6 | I²C SDA, GPIO, debug |
7 | GPIO7 | I²C SCL, GPIO, debug |
8 | GPIO8 | status_led (inverted), GPIO, boot |
9 | GPIO9 | Boot button, boot mode, GBPIO |
10 | GPIO10 | GPIO |
20 | GPIO20 | UART RX, GPIO |
21 | GPIO21 | UART 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):
- Plug in USB
- Hold both buttons
- 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
Manufacturer | Wireless-Tag |
---|---|
Datasheet | WT32_ETH01_V1.1_datasheet.pdf |
PlatformIO | Wireless-Tag WT32-ETH01 Ethernet Module |
ESP32 WROVER
Manufacturer | Espressif |
---|---|
Board docs | ESP-WROVER-KIT V4.1 Getting Started Guide |
Datasheet | esp32_wrover_datasheet_en.pdf |
PlatformIO | Espressif ESP-WROVER-KIT |
ESPHome config | packages/boards/esp32wrover.yaml 7 |
ESPHome support
esp32:
board: esp-wrover-kit
framework:
type: arduino
Pinout
Pins
Camera pins:
Pin | |
---|---|
GPIO4 | Y2 data |
GPIO5 | Y3 data |
GPIO18 | Y4 data |
GPIO19 | Y5 data |
GPIO21 | XCLK / external clock |
GPIO22 | PCLK / pixel clock |
GPIO23 | HREF |
GPIO25 | VSYNC |
GPIO26 | SIOD / I²C SDA |
GPIO27 | SIOC / I²C SCL |
GPIO36 / VP | Y6 data |
GPIO39 / VN | Y7 data |
GPIO34 | Y8 data |
GPIO35 | Y9 data |
NodeMCU ESP8266
Manufacturer | Various, ESP8266 is made by Espressif Systems |
---|---|
Datasheet | ESP8266-NodeMCU-Datasheet.pdf |
Pinout | nodemcu_esp8266_pinout.jpg |
Arduino pins | nodemcu/pins_arduino.h |
ESPHome device | NodeMCU ESP8266 |
ESPHome platform | ESP8266 Platform |
Recomended framework | arduino 19 |
ESPHome config | packages/boards/esp8266nodemcu.yaml 7 |
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 numbers20.
Silkscreen pin | Internal pin | Interface | Notes |
---|---|---|---|
A0 | GPIO17 | ADC | |
D0 | GPIO16 | Deep-sleep wakeup, AUX LED (inverted) | Can be accessed from RTC, weak pull-down |
D1 | GPIO5 | I²C SCL | High impedence |
D2 | GPIO4 | I²C SDA | High impedence |
D3 | GPIO0 | Controls boot mode (strapping pin), weak pull-up | |
D4 | GPIO2 | Blue LED (inverted) | Controls boot mode (strapping pin), weak pull-up |
D5 | GPIO14 | SPI CLK /SCK | Weak pull-up |
D6 | GPIO12 | SPI MISO | Weak pull-up |
D7 | GPIO13 | SPI MOSI | Weak pull-up |
D8 | GPIO15 | SPI CS /SS | Controls boot mode (strapping pin), weak-pull-up |
RX / D9 | GPIO3 | UART Serial RX | |
TX / D10 | GPIO1 | UART 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.
Interface | Pins |
---|---|
status_led | D4 / GPIO2 |
UART RX | RX / D9 / GPIO03 |
UART TX | TX / D10 / GPIO01 |
SPI MISO | D6 / GPIO12 |
SPI MOSI | D7 /GPIO13 |
SPI CLK /SCK | D5 / GPIO14 |
SPI CS /SS | D8 / GPIO15 |
ADC | A0 / GPIO17 |
I²C SCL | D1 / GPIO5 |
I²C SDA | D2 / 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 theRESET
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 bluestatus_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:
Mode | UART code | GPIO0 (D3 ) | GPIO2 (D4 ) | GPIO15 (D8 ) |
---|---|---|---|---|
Boot from flash (normal) | 3 | HIGH | HIGH | LOW |
Program from UART | 1 | LOW | HIGH | LOW |
Boot from SD-card | 4 -7 | Any | Any | HIGH |
The reset causes are documeted in the datasheet and are as follows:
UART code | Reset cause |
---|---|
0 | Undefined |
1 | Power on reboot |
2 | Deep-sleep wake-up or external reset |
4 | Hardware 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
Manufacturer | Wemos |
---|---|
Board docs | D1 mini |
Schematic | esp8266_d1_mini_v4.0.0_schematic.pdf |
PlatformIO | WEMOS d1 MINI ESP32 |
Arduino pins | d1_mini/pins_arduino.h |
ESPHome config | packages/boards/esp8266d1.yaml 7 |
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
Silkscreen pin | Internal pin | Interface | Notes |
---|---|---|---|
A0 | GPIO17 | ADC | |
D0 | GPIO16 | Deep-sleep wakeup | Can be accessed from RTC, weak pull-down |
D1 | GPIO5 | I²C SCL | High impedence |
D2 | GPIO4 | I²C SDA | High impedence |
D3 | GPIO0 | Controls boot mode (strapping pin), weak pull-up | |
D4 | GPIO2 | Blue LED (inverted) | Controls boot mode (strapping pin), weak pull-up |
D5 | GPIO14 | SPI CLK /SCK | Weak pull-up |
D6 | GPIO12 | SPI MISO | Weak pull-up |
D7 | GPIO13 | SPI MOSI | Weak pull-up |
D8 | GPIO15 | SPI CS /SS | Controls boot mode (strapping pin), weak-pull-up |
RX | GPIO3 | UART Serial RX | |
TX | GPIO1 | UART 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
Components 101 NodeMCU ESP8266