Ethernet example: Add README, use menuconfig for all example pin assignments

examples/ethernet/ethernet/README.md

@@ -1,6 +1,56 @@
-# ethernet Example
+# Ethernet Example
 
-Init ethernet interface and enable it ,then you can ping it if it got ip address.
+Initialises the ethernet interface and enables it, then sends DHCP requests and tries to obtain a DHCP lease. If successful then you will be able to ping the device.
 
+# PHY Configuration
 
-See the README.md file in the upper level 'examples' directory for more information about examples.
+Use "make menuconfig" to set the PHY model and the PHY address, and configure the SMI I/O pins (see below). These configuration items will vary depending on the hardware configuration you are using.
+
+The default example configuration is correct for Espressif's Ethernet board with TLK110 PHY. Other hardware will require different configuration and/or changes to the example.
+
+## PHY Address
+
+The PHY address depends on the hardware and the PHY configuration. Consult the documentation/datasheet for the PHY hardware you have.
+
+* Default address 31 is correct for Espressif's Ethernet board with TLK110 PHY.
+* Address 1 is correct for the common Waveshare LAN8720 PHY breakout.
+* Other LAN8720 breakouts may take address 0.
+
+If the PHY address is incorrect then the EMAC will initialise but all attempts to read/write configuration registers on the PHY will fail.
+
+## RMII PHY Wiring
+
+The following PHY connections are required for RMII PHY data connections. These GPIO pin assignments cannot be changed.
+
+| GPIO    | RMII Signal | ESP32 EMAC Function | Notes |
+| ------- | ----------- | ------------------- | ----- |
+| 0       | REF_CLK     | EMAC_TX_CLK         | Currently this must be a 50MHz reference clock input from the PHY (ext_osc configuration). |
+| 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         | |
+
+## RMII PHY SMI Wiring
+
+The following PHY connections are required for RMII PHY SMI (aka MDIO) management interface. These GPIO pin assignments can be changed to any unused GPIO pin.
+
+For the example, these pins are configured via `make menuconfig` under the Example configuration.
+
+| Default Example GPIO | RMII Signal | Notes         |
+| -------------------- | ----------- | ------------- |
+| 23                   | MDC         | Output to PHY |
+| 18                   | MDIO        | Bidirectional |
+
+The defaults in the example are correct for Espressif's Ethernet development board.
+
+## Note about GPIO0
+
+Because GPIO0 is a strapping pin for entering UART flashing mode on reset, care must be taken when also using this pin as EMAC_TX_CLK. If the clock output from the PHY is oscillating during reset, the ESP32 may randomly enter UART flashing mode.
+
+One solution is to use an additional GPIO as a "power pin", which either powers the PHY on/off or enables/disables the PHY's own oscillator. This prevents the clock signal from being active during a system reset. For this configuration to work, GPIO0 also needs a pullup resistor and the "power pin" GPIO will need a pullup/pulldown resistor - as appropriate in order to keep the PHY clock disabled when the ESP32 is in reset.
+
+See the example source code to see how the "power pin" GPIO can be managed in software.
+
+The example defaults to using GPIO 17 for this function, but it can be overriden. On Espressif's Ethernet development board, GPIO 17 is the power pin used to enable/disable the PHY oscillator.

examples/ethernet/ethernet/main/Kconfig.projbuild

@@ -1,10 +1,10 @@
 menu "Example Configuration"
 
 choice PHY_MODEL
-    prompt "Select the device used for the ethernet PHY"
+    prompt "Ethernet PHY"
     default CONFIG_PHY_TLK110
     help
-        Select the TI TLK110 or Microchip LAN8720 PHY
+        Select the PHY driver to use for the example.
 
 config PHY_TLK110
     bool "TI TLK110 PHY"
@@ -18,10 +18,37 @@ config PHY_LAN8720
 
 endchoice
 
-config PHY_ID
-    int "Enter the PHY ID (0-31) for the selected PHY model"
+config PHY_ADDRESS
+    int "PHY Address (0-31)"
     default 31
+    range 0 31
     help
-        Select the PHY ID (0-31) for the selected PHY model
+        Select the PHY Address (0-31) for the hardware configuration and PHY model.
+
+config PHY_USE_POWER_PIN
+    bool "Use PHY Power (enable/disable) pin"
+    default y
+    help
+        Use a GPIO "power pin" to power the PHY on/off during operation.
+        Consult the example README for more details
+
+config PHY_POWER_PIN
+    int "PHY Power GPIO"
+    default 17
+    depends on PHY_USE_POWER_PIN
+    help
+        GPIO number to use for powering on/off the PHY.
+
+config PHY_SMI_MDC_PIN
+    int "SMI MDC Pin"
+    default 23
+    help
+        GPIO number to use for SMI clock output MDC to PHY.
+
+config PHY_SMI_MDIO_PIN
+    int "SMI MDIO Pin"
+    default 18
+    help
+       GPIO number to use for SMI data pin MDIO to/from PHY.
 
 endmenu

examples/ethernet/ethernet/main/ethernet_example_main.c

@@ -44,10 +44,11 @@
 
 static const char *TAG = "eth_example";
 
-#define PIN_PHY_POWER 17
-#define PIN_SMI_MDC   23
-#define PIN_SMI_MDIO  18
+#define PIN_PHY_POWER CONFIG_PHY_POWER_PIN
+#define PIN_SMI_MDC   CONFIG_PHY_SMI_MDC_PIN
+#define PIN_SMI_MDIO  CONFIG_PHY_SMI_MDIO_PIN
 
+#ifdef CONFIG_PHY_USE_POWER_PIN
 /* This replaces the default PHY power on/off function with one that
    also uses a GPIO for power on/off.
 
@@ -81,6 +82,7 @@ static void phy_device_power_enable_via_gpio(bool enable)
         DEFAULT_ETHERNET_PHY_CONFIG.phy_power_enable(true);
     }
 }
+#endif
 
 static void eth_gpio_config_rmii(void)
 {
@@ -124,13 +126,15 @@ void app_main()
 
     eth_config_t config = DEFAULT_ETHERNET_PHY_CONFIG;
     /* Set the PHY address in the example configuration */
-    config.phy_addr = CONFIG_PHY_ID;
+    config.phy_addr = CONFIG_PHY_ADDRESS;
     config.gpio_config = eth_gpio_config_rmii;
     config.tcpip_input = tcpip_adapter_eth_input;
 
+#ifdef CONFIG_PHY_USE_POWER_PIN
     /* Replace the default 'power enable' function with an example-specific
        one that toggles a power GPIO. */
     config.phy_power_enable = phy_device_power_enable_via_gpio;
+#endif
 
     ret = esp_eth_init(&config);