Hardware page

ESPEasy has some centralized hardware configuration settings, shown in this page, and divided in sections.

Wifi Status LED

To display the Wifi acitivity, a pin can be configured to light up a LED when data is transfered via Wifi. Optionally, the LED signal can be ‘inverted’.

As many ESP boards have an onboard LED connected to GPIO-2 and inverted, it is shown as a note how to configure that.

Reset pin

To provide a possible escape from a malfunctioning ESP module, a factory-reset button/feature can be configured by setting up a GPIO-pin for this.

Warning

When connecting this pin to ground for ca. 10 seconds the unit will be completely reset, and all settings/configuration irretrievably deleted!

This feature can be useful in a development/laboratory environment, for when the configuration gets corrupted in some way.

I2C Interface

When using devices that use the I2C bus (Inter-integrated circuit, also known as IIC, and mostly compatible with SM Bus) (Wikipedia: I2C) some pins have to be configured, and initialized during boot, for the SDA and SCL connections. This can be any unused pair of pins on the ESP board.

The pins can be configured here, and will have default values initially (ESP8266: SDA: GPIO-4 (D2), SCL: GPIO-5 (D3), ESP32: SDA: GPIO-22, SCL: GPIO-23). When I2C is not used, these can be set to - None -, so the pins are available for other purposes.

When having an I2C Priority task configured, the I2C GPIO pins can no longer be changed, as that could disable the hardware, thus blocking the device. The configured GPIO pins will be display-only.

The default bus clock speed can also be set here. If only devices supporting 100 kHz are connected (Old/Slow devices), then the value can be set to 100 kHz, by default 400 kHz is configured, that is supported by newer devices, though there are many devices supporting higher frequencies. ESP8266 is able to achieve ca. 400 kHz, while ESP32 allows much higher speeds.

ESPEasy has a separate setting for Slow I2C devices, and per I2C device this slow clock speed can be selected in the Device edit page. This value is by default set to 100 kHz, but can be set lower or higher if desired.

Device specific Force Slow I2C speed selection:

Added: 2023-11-23

A device flag has been added for specific devices to have Force Slow I2C speed set by default. After adding the device this option will be checked, but can still be unchecked to use (try) Fast I2C speed (400 kHz).

I2C Multiplexer

Since build 20110, there is the option of using an I2C multiplexer. This option is not available in all builds, because of the size of the code. It is usually available in the normal, testing and custom builds, but ommitted from minimal, IR and hardware-specific builds.

Possible use-cases for an I2C multiplexer are:

• Connect multiple devices that have fixed or limited I2C addresses (For example, some OLED devices have a single fixed address but you need to connect 2 or more, or connect more than 3 TLS2561 devices, that support only 3 different addresses).

• Connect different devices that have the same I2C address (For example connecting a TSL2561 light/lux sensor and an APDS9960 proximity sensor).

• Connect slow and fast devices, where the speed of the fast device prohibits proper working of the slow device.

Note

If devices with conflicting I2C addresses are to be used, then none of them can be connected to the ESP main I2C bus, but they should each be connected to a separate channel of the multiplexer.
Devices that do not conflict with other devices can be connected to the ESP main I2C bus, this might improve the performance/responsiveness of these devices.

Note

When using an I2C Multiplexer, make sure there is no address conflict with any of the devices you intend to connect, f.e. when connecting BME280 sensors, don’t set the address of the multiplexer to 0x76 or 0x77.

There are a couple of I2C multiplexer chips available, currently there is support for:

• TCA9548a (8 channels, multiple channel-connections, 8 I2C addresses, with reset)

• TCA9546a (4 channels, multiple channel-connections, 8 I2C addresses, with reset, also TCA9545a can be used, but no support for the Interrupt function though)

• TCA9543a (2 channels, multiple channel-connections, 4 I2C addresses, with reset)

• PCA9540 (2 channels, fixed I2C address, no reset, experimental support)

The TCA9548a, TCA9546a and TCA9543a support connecting multiple channels to the main I2C channel. This can be configured on the Device edit page for I2C devices, once the I2C Multiplexer configuration is enabled by selecting a multiplexer type and an I2C address for the multiplexer.

Also, the TCA9548a, TCA9546a and TCA9543a chips have a connection for a reset signal available. This allows the chip to be reset if it gets stuck by some ‘less compatible’ or ‘badly behaving’ devices. Once connected and configured, the multiplexer can be reset from the software, if desired or required. This feature is not yet used in any I2C device plugin.

A TCA9543a board has the advantage of being quite a bit smaller than either TCA9546a or TCA9548a, while being digitally compatible. (But with less channels and only 4 I2C addresses).

All these chips/boards can be found at Adafruit, Aliexpress, Banggood, EBay, etc.

Available multiplexer types:

Select the I2C Address for the multiplexer:

Device configuration

If an I2C multiplexer is configured, every Device edit page for I2C devices will show extra options to select the channel the device is connected on.

There is the default option of Single channel, or, when a TCA9548a, TCA9546a or TCA9543a is configured, Multiple channels.

Example: A multiplexer is configured, but the device is connected directly on the ESP board I2C channel:

Configure a (single) multiplexer channel the device is connected on:

NB: Only acceptable channels (0-7/0-3/0-1) will be available in the dropdown list, depending on the Multiplexer type configured.

Select Single channel or Multiple channels:

Configure multiple channels for a device, 8 channel multiplexer configured

Above configuration results in channels 0, 4, 5, 6 and 7 being connected to the ESP board I2C bus when this sensor is active via I2C.

NB: Only acceptable channel checkboxes (0-7/0-3/0-1) will be shown, depending on the Multiplexer type configured.

SPI Interface

When using devices that are connected via the SPI interface (Wikipedia: SPI), the interface must be initialized during boot. This can be enabled here. For ESP32 there is the option to select the HSPI (often called Hardware SPI) interface, the VSPI (often called Virtual SPI) interface, or select User-defined GPIO pins for the SCLK, MISO and MOSI signals.

The common SPI pins are shown here.

Other SPI pins to be used are device specific, and need to be configured from the corresponding Device edit page.

For ESP8266:

For ESP32, disabled:

For ESP32, select the desired configuration:

NB: When using the VSPI configuration and also the I2C interface is used, another pin has to be selected for I2C GPIO -> SCL, as its configuration is fixed for the VSPI setting.

When selecting the User-defined options, 3 extra input fields are displayed, where the SCLK, MISO and MOSI GPIO pins have to be selected. Nearly all pins can be used, but for the output signals SCLK and MOSI no input-only pins should be selected!

Warning

When changing the setting for Init SPI, or changing any of the User-defined GPIO pins, the ESP32 unit needs a hardware reset. This can be achieved by pressing the reset button (when available, sometimes labelled EN or RST), or by completely removing the power for ~30 seconds. Also take into account here that units with a backup battery (f.e. some LilyGo and Waveshare ESP32 models) may keep power on the unit, so specific measures may have to be taken!

NB: When selecting the User-defined option, all 3 GPIO pins should be set, or an error message will be displayed when the page is saved, and the SPI interface will not be enabled at the next boot.

SD Card

When the compile-time option for SD-card support is enabled, the CS pin for the SD-card interface can be configured here. For the SD-card interface to work, Init SPI should also be enabled.

Ethernet

On builds including _eth in their build name, it is also possible to use ethernet instead of WiFi. Currently this is only present for ESP32 builds and no plans currently exist to support it for ESP82xx.

N.B. This is still in testing phase, so not all kinds of network communications work right now.

Preferred network medium

Allows to switch between:

• WiFi (default)

• Ethernet

To activate a new configuration, a reboot is needed.

Ethernet PHY type

ESP boards can be equiped with Ethernet. This is more stable and reliable compared to WiFi and allows for better responsiveness.

Actual transfer speed (at least when using RMII) is also higher than can be achieved via WiFi, but this is less of a concern for typical use cases where ESPEasy is used.

Ethernet chips/boards for ESP32-variant boards exist with 2 types of interfaces to the ESP.

• RMII interface - Faster actual transfer speeds possible, uses more GPIO pins, only supported on ESP32-classic (and upcoming ESP32-P4).

• SPI interface - (Added: 2024/02) Supported on all ESP32-variants (not all tested) on builds based on ESP-IDF 5.1 SPI Ethernet adapters do obviously require the SPI interface to be configured.

N.B. Only ESP32-variant builds with LittleFS support SPI Ethernet. (starting February 2024)

Supported Ethernet chips:

• RMII Interface:

  • LAN8710 (LAN8720 is also supported, but none of the newer features are supported)

  • TLK110

  • RTL8201 (since ESP32 IDF 4.4)

  • JL1101 (since ESP32 IDF 4.4)

  • DP83848 (since ESP32 IDF 4.4)

  • KSZ8041 (since ESP32 IDF 4.4)

  • KSZ8081 (since ESP32 IDF 4.4)

• SPI Interface: (since ESP32 IDF 5.1)

  • DM9051

  • W5500

  • KSZ8851

Note

The LAN8710 and LAN8720 are also available with an “A” suffix. These are the same chips, only produced after the brand SMSC was taken over by Microchip Technology.

Ethernet PHY Address

The PHY address depends on the hardware and the PHY configuration. On some chips, like the LAN8720, the board designer may set this address by pulling some pins either high or low at power on. In theory, one could use multiple PHY adapters on the same RMII/SPI bus, but this is (currently) not supported by ESPEasy.

• Espressif’s Ethernet board with TLK110 PHY use PHY address 31.

• Common Waveshare LAN8720 PHY breakout board (and clones) use PHY address 1.

• Olimex ESP32 EVB REV B IoT LAN8710 PHY Board with CAN use PHY address 0.

• Other LAN8720 breakouts often use PHY address 0.

• ETH01-EVO (ESP32-C3 based board) uses PHY address 1.

If the PHY address is incorrect then the EMAC will initialise but all attempts to read/write configuration registers on the PHY will fail.

N.B. There is support for an auto detect of this PHY address, by setting it to -1, but at least on the LAN8720 this does not seem to work.

RMII Ethernet

As mentioned above, the RMII interface is only present on ESP32-classic (and is mentioned on the announced ESP32-P4).

RMII PHY SMI Wiring

Most PHY boards have documented their RMII PHY SMI Wiring pins:

• MDC Output to PHY, usually pin 23

• MDIO Bidirectional, usually pin 18

Clock sync

The PHY and the ESP need to keep a clock in sync. This can either be done via an external crystal, which is connected to a GPIO pin. Another option is to let the ESP provide the clock to the PHY.

• External crystal oscillator

• 50MHz APLL Output on GPIO0

• 50MHz APLL Output on GPIO16

• 50MHz APLL Inverted Output on GPIO17

Note

When using an external crystal oscillator, this is connected to GPIO-0. Make sure this crystal is not active, or connected to GPIO-0, during boot or else the ESP32 may boot into flash mode.

Power pin

On almost all PHY boards, or ESP boards equiped with an ethernet PHY, it is possible to turn the PHY on or off. Either to save energy, or to make sure the external clock is not affecting the ESP boot mode when it restarts.

For example the Olimex ESP32-EVB does have the external crystal oscillator connected to GPIO-0, which could boot the ESP32 randomly into UART flash mode. Most boards use a specific GPIO pin to control the power to the PHY. The Olimex ESP32-EVB does have a specific delay circuit to only allow power to the PHY after boot and therefore does not need to control the PHY power.

For other boards, the default is often GPIO-17, but this may change per board.

(Changed: 2022-01-20)

If the power pin is defined, ESPEasy will toggle the ethernet module off and on at boot. Some Ethernet modules, like the LAN8720, may sometimes get stuck and need to be reset to get it to work again.

RMII PHY Wiring

Apart from these GPIO pins, there is a number of other pins reserved on the ESP32 for RMII PHY Wiring.

Since these GPIO pin assignments cannot be changed, it is also not needed to configure them. However, they also cannot be used when RMII PHY is used.

The following PHY connections are required for RMII PHY data connections:

RMII PHY Wiring

GPIO	RMII Signal	ESP32 EMAC Function	Notes
0 / 16 / 17	REF_CLK	EMAC_TX_CLK	See desciption about the clock
18	MDIO	EMAC_MDIO	In theory user configurable, but almost always used as MDIO pin
23	MDC	EMAC_MDC	In theory user configurable, but almost always used as MDC pin
21	TX_EN	EMAC_TX_EN
19	TX0	EMAC_TXD0
22	TX1	EMAC_TXD1
25	RX0	EMAC_RXD0
26	RX1	EMAC_RXD1
27	CRS_DV	EMAC_RX_DRV

See ESP32 datasheet

RMII Ethernet ESP32 Boards

There is a number of ESP32 boards available with Ethernet connected via RMII.

However it is not always clear which configuration should be used.

Warning

Important notice: It is possible to actually damage the Ethernet chip when a wrong configuration is used.

RMII PHY Boards

Board	Ethernet Chip	Addr	MDC	MDIO	Power/RST	Clock
Olimex ESP32 PoE	LAN8720	0	23	18	12	50MHz Inv Output GPIO17
Olimex ESP32 EVB	LAN8720	0	23	18	(no power pin)	External clock
Olimex ESP32 Gateway	LAN8720	0	23	18	5	50MHz Inv Output GPIO17
wESP32	LAN8720	0	16	17	(no power pin)	External clock
WT32 ETH01	LAN8720	1	23	18	?	External clock
TTGO T-Internet-POE ESP32	LAN8720	0	23	18	5 (RST)	50MHz Inv Output GPIO17
TTGO T-ETH-POE-PRO	LAN8720	0	23	18	5 (RST)	50MHz Output GPIO0
TTGO T-INTER_COM	LAN8720	0	23	18	4 (RST)	50MHz Output GPIO0
TTGO T-EH-Lite-ESP32	RTL8201	0	23	18	12	External clock

See:

• ESP32 datasheet

• TTGO/LilyGO Ethernet boards

• Olimex ESP32-PoE

• Olimex ESP32-POE-ISO

• Olimex ESP32-EVB

• Olimex ESP32-GATEWAY

SPI Ethernet

(Added: 2024/02)

As mentioned above, these SPI based Ethernet interfaces require the SPI interface to be configured.

The SPI bus can be shared, but the SPI Ethernet chips are a bit specific about the used frequency. Currently the default SPI frequency of 20 MHz is used, so not all other SPI devices may work together with SPI Ethernet.

Some boards like the ETH01-EVO (ESP32-C3 based) do not even have the SPI bus pins made accesible.

Note

Switching to ECO mode can sometimes result in an unreachable node when using SPI Ethernet. After a reboot the node works just fine again (in ECO mode). This is currently being investigated.

GPIO Configuration

• CS pin: Just as any SPI device, it needs a CS pin to tell the device it is being addressed.

• IRQ/INT pin: Allows the Ethernet chip to signal the ESP about new data. (Optional for W5500)

• RST pin: ESP will try to reset the Ethernet adapter during boot. Not all boards may have this wired.

SPI Ethernet ESP32 Boards

There is a number of ESP32 boards available with Ethernet connected via SPI

However it is not always clear which configuration should be used.

Note

SPI Ethernet is only supported on builds based on ESP-IDF 5.1 or newer. Thus only on ESP32-builds with LittleFS support made after 2024/02.

N.B. As there is not yet support in ESPEasy for multiple SPI busses, it cannot be configured.

When later versions of ESPEasy will support multiple SPI busses, the SPI bus information may be needed for the configuration. Therefore it is included in the table below.

SPI Ethernet Boards

Board	ESP chip	Ethernet Chip	Addr	CS	IRQ/INT	RST	SPI Clock	SPI MISO	SPI MOSI	SPI bus
ETH01-EVO	ESP32-C3	DM9051	1	9	8	6	7	3	10	SPI2_HOST
M5Stack PoECAM	ESP32-classic	W5500		4			23	38	13	SPI2_HOST
M5Stack Atom PoE Kit (ATOM LITE)	ESP32-classic	W5500		19			22	23	33	SPI2_HOST
M5Stack Atom PoE Kit (AtomS3)	ESP32-S3	W5500		6			5	7	8	SPI2_HOST
M5Stack Base LAN (End-of-life)	M5Core	W5500		26	34	13	18	19	23	SPI2_HOST
M5Stack LAN (PoE) BASE V12	M5Core	W5500		26	34	13	18	19	23	SPI2_HOST
M5Stack LAN Module 13.2	M5Core	W5500		5/15	35/34	0/13	18	19	23	SPI2_HOST
M5Stack LAN Module 13.2	M5Core2	W5500		33/2	35/34	0/19	18	38	23	SPI2_HOST
M5Stack LAN Module 13.2	M5CoreS3	W5500		1/13	10/14	0/7	36	35	37	SPI2_HOST
T-ETH-Lite-ESP32S3	ESP32-S3	W5500	1	9	13	14	10	11	12	SPI2_HOST

See:

• M5 Stack Base LAN

• M5 Stack LAN Base V12

• M5 Stack PoECAM

• M5 Stack LAN PoE Base V12

• M5 Stack LAN Module V13.2

• M5 Stack ATOM PoE ATOM Lite AtomS3

• M5 Stack Base PoE

• TTGO/LilyGO Ethernet boards

Ethernet with PoE

Some ethernet boards support Power over Ethernet (PoE), so only a single (ethernet) cable to the ESP is needed, and the ESP (and any sensors) will be powered via an onboard converter.

For Olimex boards in the ESP32-POE range, the supplier has documented this warning:

Warning

Important notice: Olimex ESP32-PoE has no galvanic isolation from Ethernet’s power supply, when you program the board via the micro USB connector the Ethernet cable should be disconnected (if you have power over the Ethernet cable)!

Consider using Olimex USB-ISO to protect your computer and board from accidental short circuit. Also consider instead using Olimex ESP32-PoE-ISO board, which is insulated.

Most likely, this warning is applicable to other brands as well.

Ethernet Isolation

Most Ethernet RJ45 phy (the connector on the PCB) have isolation transformers in them. This does isolate the TX/RX pins to make sure there is no direct connection between the long cables and the Ethernet controller chip. The isolation does protect the Ethernet chip from picked up high voltage spikes and ESD surges when inserting the Ethernet cable. However not all ESP boards with Ethernet have these installed.

Apart from the isolation of the TX/RX pins the metallic enclosure of the phy should also be isolated from the rest of the circuit of the ESP board. Typically this is done by connecting the metal enclosure of the phy via a capacitor to GND of the rest of the circuit. A lot of boards with Ethernet have these directly connected to GND, which may impose a problem when connecting the ESP board to your PC.

Warning

Important notice: For ESP boards with Ethernet which need debugging, never use Ethernet cables with metal shielding on the Ethernet connector.

Using shielded Ethernet cable will connect the metal shield of the RJ45 phy to the ground of the switch and this may be connected to other appliances which may be badly grounded. This will add a significant voltage offset between the ESP board and your PC while debugging. Such a high voltage is very likely to destroy electronics.

GPIO boot states

For some GPIO pins, the boot state (initial configuration after startup) can be configured.

Some differences exist between ESP8266 and ESP32:

• ESP8266 can’t initialize GPIO’s 6, 7, 8, 9 and 11 (used for flash-chip by ESP8266 chip).

• ESP8285 can’t initialize GPIO’s 6, 7, 8 and 11 (used by flash of ESP8285 chip).

• ESP32 / ESP32-S2 can’t initialize all GPIO’s, only GPIO pins that are actually available for use are shown.

ESP8266 GPIO boot states:

ESP32 GPIO boot states:

(Besides the serial pins, also I2C and SPI are configured)

If the board supports PSRAM, it has these differences:

Overview of the GPIO pin mapping of ESP32 (link to Espressif documentation): ESP32 DevKitC

ESP32-S2 GPIO boot states:

(Only the serial port logging is enabled on this unit, no SPI or I2C)

If the board supports PSRAM, it hides GPIO-26

(GPIO-26 is missing from the range, as it can not be used if PSRAM is present)

Overview of the GPIO pin mapping of ESP32-S2 (link to Espressif documentation): ESP32-S2 Saola1