docs/esp32/quickref: Add docs for the LAN interface constructor.

Incorporating PR #7356.

1 files changed, 64 insertions, 0 deletions

diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
index 03ca97c7a..f74926c37 100644
--- a/docs/esp32/quickref.rst
+++ b/docs/esp32/quickref.rst
@@ -68,6 +68,9 @@ by reading the temperature sensor immediately after waking up from sleep.
 Networking
 ----------
 
+WLAN
+^^^^
+
 The :mod:`network` module::
 
     import network
@@ -110,6 +113,67 @@ calling ``wlan.config(reconnects=n)``, where n are the number of desired reconne
 attempts (0 means it won't retry, -1 will restore the default behaviour of trying
 to reconnect forever).
 
+LAN
+^^^
+
+To use the wired interfaces one has to specify the pins and mode ::
+
+    import network
+
+    lan = network.LAN(mdc=PIN_MDC, ...)   # Set the pin and mode configuration
+    lan.active(True)                      # activate the interface
+    lan.ifconfig()                        # get the interface's IP/netmask/gw/DNS addresses
+
+
+The keyword arguments for the constructor defining the PHY type and interface are:
+
+- mdc=pin-object    # set the mdc and mdio pins.
+- mdio=pin-object
+- power=pin-object  # set the pin which switches the power of the PHY device.
+- phy_type=<type>   # Select the PHY device type. Supported devices are PHY_LAN8710,
+  PHY_LAN8720, PH_IP101, PHY_RTL8201, PHY_DP83848 and PHY_KSZ8041
+- phy_addr=number   # The address number of the PHY device.
+- ref_clk_mode=mode # Defines, whether the ref_clk at the ESP32 is an input
+  or output. Suitable values are Pin.IN and Pin.OUT.
+- ref_clk=pin-object  # defines the Pin used for ref_clk.
+
+The options ref_clk_mode and ref_clk require at least esp-idf version 4.4. For
+earlier esp-idf versions, these parameters must be defined by kconfig board options.
+
+These are working configurations for LAN interfaces of popular boards::
+
+    # Olimex ESP32-GATEWAY: power controlled by Pin(5)
+    # Olimex ESP32 PoE and ESP32-PoE ISO: power controlled by Pin(12)
+
+    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5),
+                      phy_type=network.PHY_LAN8720, phy_addr=0)
+
+    # or with dynamic ref_clk pin configuration
+
+    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5), 
+                      phy_type=network.PHY_LAN8720, phy_addr=0,
+                      ref_clk=machine.Pin(17), ref_clk_mode=machine.Pin.OUT)
+
+    # Wireless-Tag's WT32-ETH01
+
+    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18),
+                      phy_type=network.PHY_LAN8720, phy_addr=1, power=None)
+
+    # Espressif ESP32-Ethernet-Kit_A_V1.2
+
+    lan = network.LAN(id=0, mdc=Pin(23), mdio=Pin(18), power=Pin(5),
+                      phy_type=network.PHY_IP101, phy_addr=1)
+
+A suitable definition of the PHY interface in a sdkconfig.board file is::
+
+    CONFIG_ETH_PHY_INTERFACE_RMII=y
+    CONFIG_ETH_RMII_CLK_OUTPUT=y
+    CONFIG_ETH_RMII_CLK_OUT_GPIO=17
+    CONFIG_LWIP_LOCAL_HOSTNAME="ESP32_POE"
+
+The value assigned to CONFIG_ETH_RMII_CLK_OUT_GPIO may vary depending on the
+board's wiring.
+
 Delay and timing
 ----------------