docs/esp32: Add documentation for SPI Ethernet devices on esp32 port.

projectgus · dpgeorge · commit 12dd9cb74598 · 2025-02-11T12:56:42.000+11:00
Also cross-link with the other WIZNET5K driver, to avoid confusion.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton &lt;angus@redyak.com.au&gt;
diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
@@ -121,11 +121,20 @@ 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).
 
+.. _esp32_network_lan:
+
 LAN
 ^^^
 
-To use the wired interfaces via :class:`network.LAN` one has to specify the pins
-and mode ::
+Built-in MAC (original ESP32)
+"""""""""""""""""""""""""""""
+
+The original ESP32 SoC has a built-in Ethernet MAC. Using this MAC requires an
+external Ethernet PHY to be wired to the chip's EMAC pins. Most of the EMAC pin
+assignments are fixed, consult the ESP32 datasheet for details.
+
+If the PHY is connected, the internal Ethernet MAC can be configured via
+the :class:`network.LAN` constructor::
 
     import network
 
@@ -134,20 +143,33 @@ and mode ::
     lan.ipconfig('addr4')                 # get the interface's IPv4 addresses
 
 
-The keyword arguments for the constructor defining the PHY type and interface are:
+Required keyword arguments for the constructor:
+
+- ``mdc`` and ``mdio`` - :class:`machine.Pin` objects (or integers) specifying
+  the MDC and MDIO pins.
+- ``phy_type`` - Select the PHY device type. Supported devices are
+  ``PHY_LAN8710``, ``PHY_LAN8720``, ``PHY_IP101``, ``PHY_RTL8201``,
+  ``PHY_DP83848``, ``PHY_KSZ8041`` and ``PHY_KSZ8081``. These values are all
+  constants defined in the ``network`` module.
+- ``phy_addr`` - The address number of the PHY device. Must be an integer in the
+  range 0x00 to 0x1f, inclusive. Common values are ``0`` and ``1``.
+
+All of the above keyword arguments must be present to configure the interface.
+
+Optional keyword arguments:
 
-- mdc=pin-object    # set the mdc and mdio pins.
-- mdio=pin-object
-- reset=pin-object  # set the reset pin of the PHY device.
-- 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.
+- ``reset`` - :class:`machine.Pin` object (or integer) specifying the PHY reset pin.
+- ``power`` - :class:`machine.Pin` object (or integer) specifying a pin which
+  switches the power of the PHY device.
+- ``ref_clk`` - :class:`machine.Pin` object (or integer) specifying the pin used
+  for the EMAC ``ref_clk`` signal. If not specified, the board default is used
+  (typically GPIO 0, but may be different if a particular board has Ethernet.)
+- ``ref_clk_mode`` - Defines whether the EMAC ``ref_clk`` pin of the ESP32
+  should be an input or an output. Suitable values are ``machine.Pin.IN`` and
+  ``machine.Pin.OUT``. If not specified, the board default is used
+  (typically input, but may be different if a particular board has Ethernet.)
 
-These are working configurations for LAN interfaces of popular boards::
+These are working configurations for LAN interfaces of some popular ESP32 boards::
 
     # Olimex ESP32-GATEWAY: power controlled by Pin(5)
     # Olimex ESP32 PoE and ESP32-PoE ISO: power controlled by Pin(12)
@@ -172,6 +194,66 @@ These are working configurations for LAN interfaces of popular boards::
     lan = network.LAN(id=0, mdc=Pin(23), mdio=Pin(18), power=Pin(5),
                       phy_type=network.PHY_IP101, phy_addr=1)
 
+
+.. _esp32_spi_ethernet:
+
+SPI Ethernet Interface
+""""""""""""""""""""""
+
+All ESP32 SoCs support external SPI Ethernet interface chips. These are Ethernet
+interfaces that connect via a SPI bus, rather than an Ethernet RMII interface.
+
+.. note:: The only exception is the ESP32 ``d2wd`` variant, where this feature is disabled
+     to save code size.
+
+SPI Ethernet uses the same :class:`network.LAN` constructor, with a different
+set of keyword arguments::
+
+    import machine, network
+
+    spi = machine.SPI(1, sck=SCK_PIN, mosi=MOSI_PIN, miso=MISO_PIN)
+    lan = network.LAN(spi=spi, cs=CS_PIN, ...)   # Set the pin and mode configuration
+    lan.active(True)                             # activate the interface
+    lan.ipconfig('addr4')                        # get the interface's IPv4 addresses
+
+Required keyword arguments for the constructor:
+
+- ``spi`` - Should be a :class:`machine.SPI` object configured for this
+  connection. Note that any clock speed configured on the SPI object is ignored,
+  the SPI Ethernet clock speed is configured at compile time.
+- ``cs`` - :class:`machine.Pin` object (or integer) specifying the CS pin
+  connected to the interface.
+- ``int`` - :class:`machine.Pin` object (or integer) specifying the INT pin
+  connected to the interface.
+- ``phy_type`` - Select the SPI Ethernet interface type. Supported devices are
+  ``PHY_KSZ8851SNL``, ``PHY_DM9051``, ``PHY_W5500``. These values are all
+  constants defined in the ``network`` module.
+- ``phy_addr`` - The address number of the PHY device. Must be an integer in the
+  range 0x00 to 0x1f, inclusive. This is usually ``0`` for SPI Ethernet devices.
+
+All of the above keyword arguments must be present to configure the interface.
+
+Optional keyword arguments for the constructor:
+
+- ``reset`` - :class:`machine.Pin` object (or integer) specifying the SPI Ethernet
+  interface reset pin.
+- ``power`` - :class:`machine.Pin` object (or integer) specifying a pin which
+  switches the power of the SPI Ethernet interface.
+
+Here is a sample configuration for a WIZNet W5500 chip connected to pins on
+an ESP32-S3 development board::
+
+    import machine, network
+    from machine import Pin, SPI
+
+    spi = SPI(1, sck=Pin(12), mosi=Pin(13), miso=Pin(14))
+    lan = network.LAN(spi=spi, phy_type=network.PHY_W5500, phy_addr=0,
+                      cs=Pin(10), int=Pin(11))
+
+.. note:: WIZnet W5500 Ethernet is also supported on some other MicroPython
+          ports, but using a :ref:`different software interface
+          <network.WIZNET5K>`.
+
 Delay and timing
 ----------------
 
diff --git a/docs/library/network.LAN.rst b/docs/library/network.LAN.rst
@@ -6,7 +6,7 @@ class LAN -- control an Ethernet module
 
 This class allows you to control the Ethernet interface. The PHY hardware type is board-specific.
 
-Example usage::
+Example usage, for a board with built-in LAN support::
 
     import network
     nic = network.LAN(0)
@@ -32,7 +32,7 @@ Constructors
      - *phy_addr* specifies the address of the PHY interface. As with *phy_type*, the hardwired value has
        to be used for most boards and that value is the default.
      - *ref_clk_mode* specifies, whether the data clock is provided by the Ethernet controller or
-       the PYH interface.
+       the PHY interface.
        The default value is the one that matches the board. If set to ``LAN.OUT`` or ``Pin.OUT``
        or ``True``, the clock is driven by the Ethernet controller, if set to ``LAN.IN``
        or ``Pin.IN`` or ``False``, the clock is driven by the PHY interface.
@@ -41,6 +41,9 @@ Constructors
 
      nic = LAN(0, phy_type=LAN.PHY_LAN8720, phy_addr=1, ref_clk_mode=Pin.IN)
 
+   .. note:: On esp32 port the constructor requires different arguments. See
+             :ref:`esp32 port reference <esp32_network_lan>`.
+
 Methods
 -------
 
diff --git a/docs/library/network.WIZNET5K.rst b/docs/library/network.WIZNET5K.rst
@@ -9,6 +9,9 @@ the W5200 and W5500 chipsets.  The particular chipset that is supported
 by the firmware is selected at compile-time via the MICROPY_PY_NETWORK_WIZNET5K
 option.
 
+.. note:: The esp32 port also supports WIZnet W5500 chipsets, but this port
+          uses the :ref:`network.LAN interface <esp32_spi_ethernet>`.
+
 Example usage::
 
     import network
