jepler/circuitpython
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source 
Also cross-link with the other WIZNET5K driver, to avoid confusion.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <angus@redyak.com.au>
This commit is contained in:
Angus Gratton 2025-01-29 15:18:31 +11:00 committed by Damien George
parent b11ba39c57
commit 12dd9cb745
3 changed files with 104 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

110
docs/esp32/quickref.rst
View file

@ -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=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.
- ``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``.
These are working configurations for LAN interfaces of popular boards::
All of the above keyword arguments must be present to configure the interface.
Optional keyword arguments:
- ``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 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
----------------

7
docs/library/network.LAN.rst
View file

@ -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
-------

3
docs/library/network.WIZNET5K.rst
View file

@ -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