Software¶
The wESP32™ by default ships with MicroPython preloaded, but it can be made to work with pretty much all ESP32 compatible software development tools that exist. However, some work out-of-the-box while others would require quite a bit of hacking. This section lists software of which compatibility has been checked.
WARNING: GPIO pin configuration¶
By default, the wESP32 ships with MicroPython and a boot.py script that automatically configures the GPIO pins correctly to communicate with the Ethernet PHY and enables the Ethernet subsystem. Plugging in an Ethernet cable should automatically connect the board to the network with DHCP.
If the user wants to use a different software environment, it is the user's responsibility to ensure that the software loaded on the ESP32 configures the GPIO pins that are connected to the Ethernet PHY correctly. Many of the signals between the ESP32 and the LAN8720 Ethernet PHY are part of the high speed RMII bus, and they are directly connected together without any protection. Pins involved in connectivity between the ESP32 and PHY are IO0, IO16, IO17, IO19, IO21, IO22, IO25, IO26, IO27.
If the user loads software on the ESP32 that does not configure the RMII pins correctly, it is possible the software will configure the pins in such a way that physical damage may result, for instance connecting an output from the PHY to an output of the ESP32, resulting in a short circuit through the chip’s output drivers. This may cause damage, at least to board revisions using the LAN8720. The new RTL8201 has never been damaged during our testing.
It is recommended the wESP32 is first tested with the default MicroPython software to confirm
network functionality, before other software is loaded. Basic network functionality can be confirmed
by running lan.ifconfig() and checking that the wESP32 received an IP address from DHCP.
No defective units will be replaced once they have been flashed with different software.
ESP-IDF¶
ESP-IDF is the official Espressif development framework for the ESP32. Since the ESP-IDF provides the ultimate flexibility, it is out-of-the-box compatible with the wESP32. The only thing the user needs to do to make it work with the wESP32 is set the right configuration for how the PHY is connected and configured (either in the menuconfig if using example projects, or in code):
- Ethernet PHY type is RTL8201 from revision 7 boards onward and LAN8720 before that
- PHY interface is RMII
- PHY address is 0
- Clock mode is GPIO0 external input
- PHY power/reset pin is disabled (set to -1)
- SMI MDC pin is 16, SMI MDIO pin is 17
In code, this can be done with the following code snippet to configure and start Ethernet:
#include "esp_event.h"
#include "esp_netif.h"
#include "esp_eth.h"
void init_wesp32_eth()
{
eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG();
eth_esp32_emac_config_t emac_config = ETH_ESP32_EMAC_DEFAULT_CONFIG();
emac_config.smi_mdc_gpio_num = 16;
emac_config.smi_mdio_gpio_num = 17;
esp_eth_mac_t *mac = esp_eth_mac_new_esp32(&emac_config, &mac_config);
eth_phy_config_t phy_config = ETH_PHY_DEFAULT_CONFIG();
phy_config.phy_addr = 0;
phy_config.reset_gpio_num = -1;
// For boards revision 7 and onward, use RTL8201
esp_eth_phy_t *phy = esp_eth_phy_new_rtl8201(&phy_config);
// For boards before revision 7, use LAN8720
// esp_eth_phy_t *phy = esp_eth_phy_new_lan8720(&phy_config);
ESP_ERROR_CHECK(esp_netif_init());
ESP_ERROR_CHECK(esp_event_loop_create_default());
esp_netif_config_t netif_config = ESP_NETIF_DEFAULT_ETH();
esp_netif_t* eth_netif = esp_netif_new(&netif_config);
esp_eth_handle_t eth_handle = NULL;
esp_eth_config_t eth_config = ETH_DEFAULT_CONFIG(mac, phy);
ESP_ERROR_CHECK(esp_eth_driver_install(ð_config, ð_handle));
esp_eth_netif_glue_handle_t eth_driver_handle =
esp_eth_new_netif_glue(eth_handle);
ESP_ERROR_CHECK(esp_netif_attach(eth_netif, eth_driver_handle));
ESP_ERROR_CHECK(esp_eth_start(eth_handle));
}
Full details can be found in the ESP-IDF Programming Guide.
Arduino-ESP32¶
The Arduino-ESP32 project allows you to program the wESP32 from the popular Arduino IDE. Installation instructions are in the repo's README.md, support for the wESP32 is now fully integrated into the stable release so you can use the Adruino Boards Manager installation instructions. Support for the RTL8201 used in revision 7 boards and onward requires version 2.0.0 or higher.
Once the ESP32 support is installed, you can select the wESP32 from the Arduino IDE menu:
Tools → Board → Silicognition wESP32
To use the Ethernet connection in your sketch, you need to #include <ETH.h> and call ETH.begin() to start the Ethernet peripheral. This function can take optional parameters to set the configuration, the defaults are currently set for the wESP32 before revision 7, for revision 7 you need to add parameters to select the RTL8201 PHY. It is likely that in the future, the default will be changed to work for the RTL8201 and extra parameters have to be specified for older LAN8720 boards.
Below is a minimal web server with mDNS example sketch:
#include <ETH.h>
#include <WebServer.h>
#include <ESPmDNS.h>
// Web server
WebServer server(80);
// HTTP handlers
void handleRoot() {
server.send(200, "text/plain", "Hello from wESP32!\n");
}
void handleNotFound() {
server.send(404, "text/plain", String("No ") + server.uri() + " here!\n");
}
void setup(){
Serial.begin(115200);
Serial.println("wESP32 web server test!");
// Start the Ethernet (Arduino-ESP32 3.x on rev 7 hardware)
ETH.begin(ETH_PHY_RTL8201, 0, 16, 17, -1, ETH_CLOCK_GPIO0_IN);
// Order of parameters in Arduino-ESP32 2.x was different:
// ETH.begin(0, -1, 16, 17, ETH_PHY_RTL8201, ETH_CLOCK_GPIO0_IN);
// For wESP32 hardware revisions before rev 7, use ETH_PHY_LAN8720
// as PHY type parameter
// You can browse to wesp32demo.local with this
MDNS.begin("wesp32demo");
// Bind HTTP handler
server.on("/", handleRoot);
server.onNotFound(handleNotFound);
// Start the Ethernet web server
server.begin();
// Add service to MDNS-SD
MDNS.addService("http", "tcp", 80);
}
void loop(){
server.handleClient();
}
MicroPython¶
The MicroPython project provides a very rich Python 3 environment for small microcontrollers. The ESP32 and Ethernet are well supported, and due to its flexible nature, MicroPython is the default out-of-the-box software preinstalled on the wESP32.
The following is the minimum code needed to get a wESP32 before revision 7 that used the LAN8720 PHY connected to Ethernet with MicroPython:
import machine
import network
lan = network.LAN(mdc = machine.Pin(16), mdio = machine.Pin(17), power = None, phy_type = network.PHY_LAN8720, phy_addr = 0)
lan.active(1)
This works with ESP-IDF v3.x based MicroPython releases and with ESP-IDF v4.x based MicroPython releases from version v1.16 onward. For revision 7 and above wESP32 boards, MicroPython v1.16 or newer based on ESP-IDF v4.x is required to support the RTL8201. The following is the minimum code needed when using this PHY:
import machine
import network
lan = network.LAN(mdc = machine.Pin(16), mdio = machine.Pin(17), power = None, phy_type = network.PHY_RTL8201, phy_addr = 0)
lan.active(1)
From MicroPython version 1.17 on, there is a custom build of MicroPython for the wESP32 revision 7 to make use of the full 16 MB of flash available on the board. The “Generic ESP32 module” binaries will still work, but only provide access to 4 MB of flash. The MicroPython website has a download page specific to the wESP32 revision 7 and higher.
Once connected, all networking functionality will occur over Ethernet.
The wESP32 by default ships with MicroPython and a pre-installed boot.py script that contains
the code shown above, configured for the correct PHY populated on a particular board revision.
This means that out-of-the-box, the wESP32 will connect to the network when the Ethernet jack is connected without any code needing to be supplied by the user.
Lua-RTOS-ESP32¶
Lua-RTOS-ESP32 provides a rich Lua environment for the ESP32. Installation instructions are in the README.md, when prompted to enter a board type choose the option for the "Silicognition wESP32" with or without OTA. As of the time of writing, this project is built on IDF 3.x and only supports old board revisions before revision 7 that use the LAN8720 Ethernet PHY.
Once built and flashed, the minimum code to get connected over Ethernet is:
net.en.setup()
net.en.start()
Once connected, all networking functionality will occur over Ethernet. Since this runtime has dropbear on board, you can even remotely log in to the Lua REPL over SSH!
NodeMCU¶
Fans of Lua have a second option to run Lua on the wESP32, and this one works with revision 7 and newer. The dev-esp32-idf4 branch of NodeMCU supports both the LAN8720 on older revisions and the RTL8201 on revision 7. They provide quite a nice implementation with events that allow the user to respond to various states of the Ethernet connection such as cable connect / disconnect and acquiring an IP address.
NodeMCU does not seem to provide ready-made images, you have to check out the dev-esp32-idf4 branch from Github and follow the build instructions found in the project's documentation. To be able to use the Ethernet port, you have to ensure you turn on the Ethernet module when you run make menuconfig to configure your build options:
Component config → NodeMCU modules → Ethernet module
Once built and flashed, the minimum code to get connected over Ethernet when using a board before revision 7 is:
eth.init({phy = eth.PHY_LAN8720, addr = 0, mdc = 16, mdio = 17})
For revision 7 and later boards using the RTL8201, instead use:
eth.init({phy = eth.PHY_RTL8201, addr = 0, mdc = 16, mdio = 17})
Mongoose OS¶
Mongoose OS is a development framework for IoT firmware, with good support for the ESP32. It comes with a lot of back end functionality to take care of device management, such as a device dashboard and OTA updates.
Ethernet on the ESP32 is supported, but at the time of writing, the project does not seem to tie it in to the network stack in any way to make it useful. See this issue on Github.
Hoping that this is a temporary problem, below is an example mos.yml file that contains the right bits to configure a project to make use of the wESP32 hardware:
author: mongoose-os
description: A JS-enabled demo Mongoose OS firmware
platform: esp32
version: 1.0
manifest_version: 2017-05-18
libs_version: ${mos.version}
modules_version: ${mos.version}
mongoose_os_version: ${mos.version}
config_schema:
- ["mqtt.server", "iot.eclipse.org:1883"]
- ["i2c.enable", true]
tags:
- js
filesystem:
- fs
config_schema:
- ["eth.clk_mode", 0]
- ["eth.mdc_gpio", 16]
- ["eth.mdio_gpio", 17]
- ["eth.phy_addr", 0]
- ["eth.enable", true]
libs:
- location: https://github.com/mongoose-os-libs/ethernet
- location: https://github.com/mongoose-os-libs/js-demo-bundle
Note in particular the config_schema section that configures the Ethernet subsystem and the ethernet library in the libs section. This is sufficient for wESP32 revisions prior to 7 using the LAN8720, from revision 7 onward, the following part needs to be added to configure the Ethernet driver to use the RTL8201 PHY:
conds:
- when: mos.platform == "esp32"
apply:
cdefs:
MGOS_ETH_PHY_LAN87x0: 0
MGOS_ETH_PHY_RTL8201: 1