Documentation: ESP32 + Ethernet LAN8720A with External Crystal Clock?

[Arcitec]

Board

ESP32

Device Description

LAN8720A

Hardware Configuration

No.

Version

v3.2.0

IDE Name

VSCode with PlatformIO

Operating System

Linux

Flash frequency

80MHz

PSRAM enabled

yes

Upload speed

921600

Description

Hi! :) Because of the ESP32 hardware PLL bug, I need to stop using the ESP32 PLL, and will instead connect an external 25 MHz crystal directly to the LAN8720A, as described on Page 29 of their datasheet under "3.7.4.2 REF_CLK Out Mode".

Now I need to tell ESP32 SDK's ETH.begin() call how to talk to the LAN8720A chip in that configuration.

Can you please provide an example with all the correct values for "ETH.begin" when the ESP32 is connected to a LAN8720A that uses an external 25 MHz crystal on its XTAL1/XTAL2 pins?

PS: It would also be greatly appreciated if someone knows how the ESP32 is able to control/synchronize with the LAN8720A when the crystal is external? Do I need to do something special? Keep in mind that my crystal is only wired to the LAN8720A. It isn't wired to the ESP32. So they are not sharing the same clock. Does anyone know if I need to do something special to turn on/off the crystal via the ESP32 in this configuration, or if the LAN8720A handles it?

What I've researched...

The Ethernet API for the ESP32 SDK is not documented. It only pulls in some example source code, but it doesn't actually explain the APIs or the available constant values:

• https://github.com/espressif/arduino-esp32/blob/release/v3.3.x/docs/en/api/ethernet.rst

So I am looking directly at the source code to try to figure out the APIs here:

• https://github.com/espressif/arduino-esp32/blob/release/v3.3.x/libraries/Ethernet/src/ETH.cpp
• https://github.com/espressif/arduino-esp32/blob/release/v3.3.x/libraries/Ethernet/src/ETH.h

But I don't understand what I should do.

The ETH.h contains the following values in an enum:

arduino-esp32/libraries/Ethernet/src/ETH.h

Lines 83 to 88 in a6bba43

	typedef enum {
	ETH_CLOCK_GPIO0_IN,
	ETH_CLOCK_GPIO0_OUT,
	ETH_CLOCK_GPIO16_OUT,
	ETH_CLOCK_GPIO17_OUT
	} eth_clock_mode_t;

I can't find any file where those values (such as ETH_CLOCK_GPIO0_IN) are defined.

But more importantly, I don't see any way to define an external clock? All those "modes" are only about using GPIO 0/16/17 for PLL clock outputs, which I don't want to do...

I need a way to tell "ETH.begin" that my clock is external.

Then I found this file:

arduino-esp32/libraries/Ethernet/src/ETH.cpp

Lines 222 to 226 in a6bba43

	mac_config.clock_config.rmii.clock_mode = (clock_mode) ? EMAC_CLK_OUT : EMAC_CLK_EXT_IN;
	mac_config.clock_config.rmii.clock_gpio = (1 == clock_mode) ? EMAC_APPL_CLK_OUT_GPIO
	: (2 == clock_mode) ? EMAC_CLK_OUT_GPIO
	: (3 == clock_mode) ? EMAC_CLK_OUT_180_GPIO
	: EMAC_CLK_IN_GPIO;

It reveals that there's two secret values: EMAC_CLK_OUT : EMAC_CLK_EXT_IN;

But which value is correct? Why is there an "OUT" and "EXT IN"? None of this seems to be documented anywhere.

Sketch

...

Debug Message

...

Other Steps to Reproduce

No response

I have checked existing issues, online documentation and the Troubleshooting Guide

• I confirm I have checked existing issues, online documentation and Troubleshooting guide.

[me-no-dev]

I will suggest that you try to get this going with the IDF team first. Once you have a confirmed working config, we can try and get this working in Arduino as well. Since we do not have boards with your hardware configuration, we have no way of confirming what changes are necessary and if they will indeed work.

[Jason2866]

It does work, see this code snipplet https://github.com/arendst/Tasmota/blob/development/tasmota/tasmota_xdrv_driver/xdrv_82_esp32_ethernet.ino
The mentioned WT32-ETH01 does use an external 50Mhz Oscillator and is verified working.

[Arcitec]

@Jason2866 Thank you. That's fascinating:

https://github.com/arendst/Tasmota/blob/f3d4b5275d55095f6652f3849f67732b7cc71adf/tasmota/tasmota_xdrv_driver/xdrv_82_esp32_ethernet.ino#L232-L238

#if CONFIG_ETH_USE_ESP32_EMAC
  if (WT32_ETH01 == TasmotaGlobal.module_type) {
    Settings->eth_address = 1;                    // EthAddress
    Settings->eth_type = ETH_PHY_LAN8720;         // EthType 0 = LAN8720
    Settings->eth_clk_mode = 0;                   // EthClockMode 0 = ETH_CLOCK_GPIO0_IN
  }
#endif  // CONFIG_ETH_USE_ESP32_EMAC

If I am reading that correctly:

1. It sets the ESP32 SDK clock mode to ETH_CLOCK_GPIO0_IN. So apparently, the ESP32 chip must also receive the same clock from the same crystal that the Ethernet LAN8720A chip uses, and receives it on GPIO 0? Is that really true?
2. That sounds a bit problematic since GPIO0 has some special meaning at startup for the ESP32 and can force it into bootloader mode unless some extra circuit is used to prevent that.

Is there any mode where the ESP32 is unconnected to the Ethernet clock crystal? I found those weird, undocumented EMAC_CLK_OUT : EMAC_CLK_EXT_IN modes that sound like "it has its own external clock and we aren't bothered with it", but I can't see if that would work.

[Arcitec]

Okay I found their design and started analyzing it:

https://github.com/TDLOGY/WT32-ETH01-Docs/blob/main/WT32_ETH01_V2.schematic.pdf

• Yes. The external crystal clock signal must also go to ESP32's GPIO 0 in "input" mode.
• But the signal doesn't come directly from the crystal, it comes from the "REFCLKO" pin on the LAN8720A. I'll have to double-check the datasheet but seems that's actually a clock output pin when an external crystal is used. Great!

Potential issues. Does anyone know the answer?

1. Would it work to use a 25 MHz crystal? The LAN8720A allows that in its datasheet. Hopefully it generates a 50 MHz signal from REFCLKO when feeding it to the ESP32.
2. I noticed that they use GPIO 16 as the crystal "enable" pin... (Seen at the bottom of schematic, as IO16_OSC_EN). I am guessing that it's their own homebrew solution with a custom code patch. Is there a way to avoid this or combine it with another ESP32 GPIO to avoid having to use an extra GPIO just to enable the crystal?

[Arcitec]

Interesting. I'll have to see what Olimex did here, but it seems to be my ideal setup that I just mentioned. I only had a quick look so far, but it seems like they don't waste any extra GPIOs for the crystal's enable pin.

They use a 50 MHz external crystal that seems to always be on by default (power + enable pin are both hooked to the 3.3V line):

https://github.com/OLIMEX/ESP32-EVB/blob/master/HARDWARE/REV-K1/ESP32-EVB_Rev_K1.pdf

They also use some kind of crystal enable/disable circuitry that's wired to the ESP32's EN pin. Hmm? Looks strange, since EN is held high during both flashing and regular boot modes. And the crystal should only be turned on in regular boot mode. Maybe their schematic is suboptimal.

And then they route that clock signal to both GPIO 0 and to the LAN8710A XTAL1/CLKIN pin.

But the newer 8720A has the "REFCLKO" pin, so that simplifies routing by just taking it directly from the ethernet chip to GPIO 0 instead. And the 8720A has the ability to use a 25 MHz crystal, and I seem to have found confirmation that it will output 50 MHz on that pin when you do that. So that's a better choice than wiring a 50 MHz crystal directly to the ESP32 GPIO0.

They also have a CH340 and are wiring it directly to GPIO 0 too, which is how the flash/regular boot modes are signaled at startup by the CH340.

So far I haven't seen exactly how they're solving the issue that ESP32 would go into programming mode at startup if the crystal is running. Their crystal seems to always be running and always going into GPIO 0. It looks like they're doing something with the ESP32 "EN" signal to start the crystal at the same time the ESP32 is being started. But it makes no sense to me because that would mean the crystal starts even in bootloader mode, since "EN" is always high in both Flash and Boot modes. So I have probably missed something.

[Arcitec]

So to sum it up so far:

• With LAN8720A you can use a 25 MHz crystal. It will internally generate a 50 MHz signal from it.
• Wire the crystal to always be on (put 3.3V on both its VCC and ENABLE pins).
• Wire something to enable/disable the crystal based on the ESP32 state: It needs to only turn on the crystal when the ESP32 is being booted in regular (non flashing) mode. And it needs to be turned on early enough that the crystal will have fully started up by the time the ESP32 tries to talk to Ethernet.
• Wire the crystal to XTAL1/CLKIN of the LAN8720A. Don't connect XTAL2 to anything.
• Use the LAN8720A's REFCLKO output to go into GPIO 0 of the ESP32. This forwards the 50 MHz clock signal.
• Set the ESP32 to ETH_CLOCK_GPIO0_IN mode in ETH.begin() to tell it to sync to the same clock frequency as the LAN8720A.
• Wire the REFCLKO + the CH340 pins with both going into GPIO 0. Not sure yet if I can just join the traces or if I need a mux or diode to do it safely.
• I'll have to triple-check the datasheets again to make sure this plan will work.

[Arcitec]

Alright after 5 hours of grueling research, here is a summary of the solutions to implement external crystals elegantly:

First of all, the LAN8720A startup sequence:

• It can be powered without any running crystal, as far as I can see (the datasheet doesn't seem to warn against it). See "Hardware Reset" on page 33 of https://eu.mouser.com/datasheet/2/268/LAN8720A_LAN8720Ai_Data_Sheet_DS00002165-3444713.pdf
• When you finally want to use it, you must first start a crystal (and ensure you wait long enough so it's reached its full, stable rate), and then trigger the nRST pin to reset the chip to actually boot it.
• If you nRST without a crystal, it will hang.

Useful LAN8720A features:

• You can use a 25 MHz crystal. It will internally generate a 50 MHz signal from it.
• It will output the generated 50 MHz synchronization signal from its own REFCLKO pin.

The ESP32 ethernet design law:

• It must receive the same clock as the LAN8720A. The only ESP32 pin that can receive a clock is GPIO 0 (ETH_CLOCK_GPIO0_IN).

How to wire all of this up:

• LAN8720A:
  • Strapping pins set to external clock 25 MHz mode.
  • XTAL1/CLKIN1: Connect to the 25 MHz crystal output.
  • XTAL2: Not connected.
  • REFCLKO: Outputs 50 MHz. Connected to ESP32's GPIO0.
• CH340:
  • Connect to ESP32's GPIO0 too as usual, but through a schottky diode to block crystal going into the CH340's output pin.
• Now we need to delay the startup of the Crystal's ENABLE pin so that it doesn't interfere with GPIO0's startup mode selection (flash vs regular boot selector). There are two ways to delay it:
  • "I want to save a GPIO pin": The ESP32 must receive a permanent "EN" signal to stay powered, so you can just route the same "EN" signal to a time-delay startup chip (~500ms is very safe) which drains away a 3.3v power rail from the Crystal's ENABLE pin until "EN" has stayed high for long enough. This delays the crystal startup.
  • Alternatively, use a GPIO and connect it to the crystal's ENABLE pin. Then you don't need time-delay startup circuitry and extra complexity.

Finally, code:

The code running on the ESP32 must then do this startup sequence before talking to Ethernet:

• If you used a GPIO for the crystal's ENABLE pin: Enable and wait for the Crystal to fully start.
• Send the LAN8720A nRST signal and wait for that chip to restart/boot.
• Then talk to the Ethernet chip.

There's just one problem remaining: If I use a GPIO for the Crystal enable, I'll have to patch WLED to add support for a separate "crystal enable" GPIO - unless I can somehow combine crystal enable and something else into one GPIO.

Most likely I'll have to rename WLED's eth_power -> eth_reset and add a new eth_crystal pin feature. Since I don't think both actions can be combined to one pin (because WLED only briefly pulses the nRST GPIO signal, which won't keep a crystal active).

So the upside of using a GPIO for crystal ENABLE is that you save cost. The downside is that ESP32 software must be rewritten to handle it. Therefore, the most universal solution (which can run everyone's software unmodified) is to use a startup time-delay circuit for the crystal instead of a GPIO.