.. _esp32_quickref: Quick reference for the ESP32 ============================= .. image:: img/esp32.jpg :alt: ESP32 board :width: 640px The Espressif ESP32 Development Board (image attribution: Adafruit). Below is a quick reference for ESP32-based boards. If it is your first time working with this board it may be useful to get an overview of the microcontroller: .. toctree:: :maxdepth: 1 general.rst tutorial/index.rst Note that there are several varieties of ESP32 -- ESP32, ESP32C3, ESP32C6, ESP32S2, ESP32S3 -- supported by MicroPython, with some differences in functionality between them. Installing MicroPython ---------------------- See the corresponding section of tutorial: :ref:`esp32_intro`. It also includes a troubleshooting subsection. General board control --------------------- The MicroPython REPL is on UART0 (GPIO1=TX, GPIO3=RX) at baudrate 115200. Tab-completion is useful to find out what methods an object has. Paste mode (ctrl-E) is useful to paste a large slab of Python code into the REPL. The :mod:`machine` module:: import machine machine.freq() # get the current frequency of the CPU machine.freq(240000000) # set the CPU frequency to 240 MHz The :mod:`esp` module:: import esp esp.osdebug(None) # turn off vendor O/S debugging messages esp.osdebug(0) # redirect vendor O/S debugging messages to UART(0) # low level methods to interact with flash storage esp.flash_size() esp.flash_user_start() esp.flash_erase(sector_no) esp.flash_write(byte_offset, buffer) esp.flash_read(byte_offset, buffer) The :mod:`esp32` module:: import esp32 esp32.raw_temperature() # read the internal temperature of the MCU, in Fahrenheit esp32.ULP() # access to the Ultra-Low-Power Co-processor, not on ESP32C3/C6 Note that the temperature sensor in the ESP32 will typically read higher than ambient due to the IC getting warm while it runs. This effect can be minimised by reading the temperature sensor immediately after waking up from sleep. ESP32C3, ESP32C6, ESP32S2, and ESP32S3 also have an internal temperature sensor available. It is implemented a bit differently to the ESP32 and returns the temperature in Celsius:: esp32.mcu_temperature() # read the internal temperature of the MCU, in Celsius Networking ---------- WLAN ^^^^ The :class:`network.WLAN` class in the :mod:`network` module:: import network wlan = network.WLAN() # create station interface (the default, see below for an access point interface) wlan.active(True) # activate the interface wlan.scan() # scan for access points wlan.isconnected() # check if the station is connected to an AP wlan.connect('ssid', 'key') # connect to an AP wlan.config('mac') # get the interface's MAC address wlan.ipconfig('addr4') # get the interface's IPv4 addresses ap = network.WLAN(network.WLAN.IF_AP) # create access-point interface ap.config(ssid='ESP-AP') # set the SSID of the access point ap.config(max_clients=10) # set how many clients can connect to the network ap.active(True) # activate the interface A useful function for connecting to your local WiFi network is:: def do_connect(): import machine, network wlan = network.WLAN() wlan.active(True) if not wlan.isconnected(): print('connecting to network...') wlan.connect('ssid', 'key') while not wlan.isconnected(): machine.idle() print('network config:', wlan.ipconfig('addr4')) Once the network is established the :mod:`socket ` module can be used to create and use TCP/UDP sockets as usual, and the ``requests`` module for convenient HTTP requests. After a call to ``wlan.connect()``, the device will by default retry to connect **forever**, even when the authentication failed or no AP is in range. ``wlan.status()`` will return ``network.STAT_CONNECTING`` in this state until a connection succeeds or the interface gets disabled. This can be changed by calling ``wlan.config(reconnects=n)``, where n are the number of desired reconnect attempts (0 means it won't retry, -1 will restore the default behaviour of trying to reconnect forever). .. _esp32_network_lan: LAN ^^^ 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 lan = network.LAN(mdc=PIN_MDC, ...) # 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: - ``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_GENERIC``, ``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: - ``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) 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) # Wireless-Tag's WT32-ETH01 v1.4 lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), phy_type=network.PHY_LAN8720, phy_addr=1, power=machine.Pin(16)) # 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) .. _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 `. Delay and timing ---------------- Use the :mod:`time