Skip to content

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.

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:

  • Ethernet PHY type is Microchip LAN8720
  • PHY address is 0
  • EMAC clock mode is GPIO0 input
  • Use PHY power pin is disabled
  • SMI MDC pin is 16, SMI MDIO pin is 17

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 was merged upstream, so 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 takes optional parameters to set the configuration, but the board support package already takes care of setting these correctly for the wESP32.

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(){
  // Start the ethernet
  ETH.begin();
  // 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, the wESP32 is supported out-of-the-box.

The following is the minimum code needed to get the wESP32 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)

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

[NOTE: Until wESP32 board support is merged upstream, use this repo.]

Lua-RTOS-ESP32 provides a rich Lua environment for the ESP32. While there are other Lua environments for the ESP32 such as NodeMCU, they seemed to be lacking Ethernet support, while Ethernet is well supported in this project.

Installation instructions are in the README.md, but please take note to change the git clone URL to the “xorbit” fork for as long as the wESP32 board support is not yet merged. You need to follow the “Method 2: build it yourself” instructions for now. When you execute the make flash command, you can choose option 21 for the wESP32.

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!