The Case for Ethernet

Over the past few months, Moddable has developed products for clients in the manufacturing and automotive industries. One client is building a monitoring system for factories; the other, a system to detect maintenance issues in cars. To my surprise, both clients asked us to support Ethernet in these projects. As it turns out, people still use Ethernet, actually quite often. And, even more surprising, it's great.

This article explains the benefits of using Ethernet instead of Wi-Fi. It also walks you through the steps you need to take to incorporate Ethernet into your projects built with the Moddable SDK.

Why Use Ethernet?

Ethernet was invented in 1973 and first commercialized in 1980. Decades later, it remains relevant. Here are just a few reasons why.

Reliability

Wi-Fi is great...except when it's not. Even in a controlled environment like a house, it can be difficult to maintain a reliable Wi-Fi connection for an extended period of time. In less controlled environments, it is basically impossible. On a factory floor, for example, electrical noise from generators and manufacturing equipment can interfere with Wi-Fi signal. Or consider a trade show with thousands of smartphones and connected devices competing to communicate wirelessly. Wi-Fi signals are broadcast in the 2.4 or 5 GHz frequency bands, and when you have hundreds or thousands of devices transmitting and receiving data over the same radio frequency, signal interference is inevitable. To make the situation even worse, BLE signals are also broadcast in the 2.4 GHz frequency band, which only adds to the chaos.

Ethernet connections are wired, which means you don't have to worry about wireless signal interference. This makes Ethernet connections much more reliable than Wi-Fi. They're even reliable enough for trade shows, as experienced by our automotive client. They demonstrated a product prototype that had four devices broadcasting sensor readings in mDNS packets and another device collecting that data to visualize on a display. This would have been a disaster if the devices were connected via Wi-Fi or BLE. But using Ethernet, there were no connectivity issues. If you've ever used Wi-Fi or BLE in a trade show demo, you know what a miracle that is.

Security

In addition to being more reliable, Ethernet is more secure than Wi-Fi. Wi-Fi packets travel through air, making it possible to intercept them. Properly securing a Wi-Fi network takes real effort. Ethernet, on the other hand, is wired, which means you have to physically attach devices to an Ethernet network to access Ethernet packets. This is much more secure.

The first prototype of the factory monitoring product communicated with the cloud using Wi-Fi. For many potential customers, Wi-Fi was acceptable. For others, a secure, physical network connection was a must-have requirement. Our client asked us to investigate options, which led to the Moddable SDK adding support for Ethernet. Now their product supports both Ethernet and Wi-Fi, and their customers can select the one that best fits their needs.

Speed

If reliability and security aren't enough reason to use Ethernet, there's also speed: the connection time for Ethernet is basically zero, compared to at least several seconds for Wi-Fi. And once connected, Ethernet is typically faster than Wi-Fi. Of course, Wi-Fi can be plenty fast, with speeds that are perfectly acceptable for many projects. And sometimes the benefits of having a wireless connection outweigh the speed benefits you might get from Ethernet. But the extra speed you get from using Ethernet never hurts, and the faster connection time speeds up the debug cycles during product development.

Ethernet Support in the Moddable SDK

The Moddable SDK now supports Ethernet for the ESP32. Incorporating Ethernet into your projects is a straightforward process. A summary of the process is provided in this section. Full documentation for Ethernet support in the Moddable SDK is available in the Moddable SDK repository on GitHub.

Hardware Set-up

Most ESP32 hardware modules have a built-in antenna that supports Wi-Fi and BLE. To use Ethernet with the ESP32, you have to add some hardware. The Moddable SDK supports the use of any Ethernet module you can wire into the hardware and integrate with the ESP-IDF. In our work, we use the ENC28J60 breakout boards pictured below. Wiring instructions are in the Wiring section of the Ethernet documentation.

Verifying Hardware Connections

The Moddable SDK includes two example applications you can run to confirm that your Ethernet module is wired correctly to the ESP32. The best place to start is the ethernet-test example because it works with any ESP32 board.

cd $MODDABLE/examples/network/ethernet/ethernet-test
mcconfig -d -m -p esp32

When ethernet-test starts up, it checks for a connection to an Ethernet module. If it cannot find one, it throws an error that you can see in the console pane of the xsbug debugger.

If you see that error, it is time to go back and check all the electrical connections between the ESP32 and the Ethernet module.

Once the board is wired up properly, the example traces the state of the Ethernet connection to the debugger's console. The state changes when you plug or unplug the Ethernet module from a working Ethernet port.

If your ESP32 is connected to a display (for example, a Moddable Two), you can also run the ethernet-test-graphic example.

cd $MODDABLE/examples/network/ethernet/ethernet-test-graphic
mcconfig -d -m -p esp32/moddable_two

The ethernet-test-graphic example displays the status of the Ethernet connection on screen. This eliminates the need to have the ESP32 connected to xsbug to see the status of the Ethernet connection.

Once your Ethernet board is hooked up and working properly, you're ready to start using Ethernet in your applications.

Using Ethernet in Applications

For developers, working with Ethernet is almost exactly the same as working with Wi-Fi. The main differences are how you set up the connection to Ethernet and how you monitor the status of the connection. But once you're connected, you use all the same networking modules and APIs for operations including making HTTP/HTTPS requests, establishing MQTT connections, and broadcasting service data via mDNS.

Before diving into how to use Ethernet, it is helpful to first review how Wi-Fi works in the Moddable SDK.

Wi-Fi Refresher

If you've read through the source code of the network examples in the Moddable SDK, you've probably noticed that their manifests all include manifest_net.json.

"include": [
    /* other included manifests here */
    "$(MODDABLE)/examples/manifest_net.json"
],

For ESP32 device targets, this manifest adds the modules needed to work with Wi-Fi. That includes the setup/network module to establish a Wi-Fi connection when the application starts. When you build examples to work with Wi-Fi, you include the Wi-Fi credentials (SSID and password) in your mcconfig build command. For example:

cd $MODDABLE/examples/network/http/httpgetjson
mcconfig -d -m -p esp32/moddable_two ssid=Moddable password=verySecurePassword123

When the ESP32 starts-up, the setup/network module executes before the project's main module. It connects to Wi-Fi using the credentials provided. Once connected, the main module of the application runs.

Updating Manifest for Ethernet

The first step in using Ethernet in your project is to update your project's manifest. To use Ethernet instead of Wi-Fi with these same examples, simply replace manifest_net.json with manifest_net_ethernet.json. This manifest adds the modules needed to work with Ethernet. That includes a different implementation of the setup/network module, one that establishes an Ethernet connection (instead of Wi-Fi) when the ESP32 starts-up.

"include": [
    /* other included manifests here */,
    "$(MODDABLE)/examples/manifest_net_ethernet.json"
],

Note: You should not include both manifest_net.json and manifest_net_ethernet.json; include only one or the other.

Then you just build and run the example with mcconfig. There's no need to include network credentials in the build command when you're using Ethernet.

cd $MODDABLE/examples/network/http/httpgetjson
mcconfig -d -m -p esp32/moddable_two

When the ESP32 starts-up, the setup/network module is executed and the ESP32 connects to Ethernet. Once connected, the main module of the application runs.

Connection Unavailable

A careful reader may be asking: what happens if the device isn't able to connect to Wi-Fi or Ethernet? The answer is that the main module never runs. That may seem odd, but it's really not a problem when you are exploring the examples: if the connection cannot be established, there's no point in running the example.

However, it certainly is a problem if you're building projects that you intend to have running for long periods of time or production systems. An Ethernet connection is reliable, but it's not invincible. There may be times where the connection drops. When that happens, you don't want your application to crash or fail to run at all. So when you're building production systems, you should:

  • Remove the setup/network module from the build
  • Add your own module to set up and monitor the Ethernet connection
  • Write code to account for times when no connection can be established or the connection drops in and out

The next section explains how to do this in more detail.

Advanced Ethernet Use

In this section, you'll learn the basics of making a production-ready Ethernet application. You'll be looking at the ethernet-monitor example which demonstrates a simple but effective way to monitor an Ethernet connection and handle dropped connections.

The operation of this example is straightforward.

  1. It installs a callback on the Ethernet class to receive notifications when the connection is available.
  2. When the callback is invoked, it stores the current connection state in a variable.
  3. Every five seconds, it checks that variable to see if the connection is active and, if so, it makes an HTTP request to the JSON Test Date & Time API.

The following sections take walk through the details of how that's done.

Manifest

To start, take a look at the manifest. It includes manifest_net_ethernet.json, as all ESP32 Ethernet applications do.

"include": [
    /* other included manifests here */,
    "$(MODDABLE)/modules/network/ethernet/manifest_net_ethernet.json"
],

As described above, the first step to making a production-ready Ethernet application is to remove the setup/network module so that your application can manage the Ethernet connection over the lifetime of execution, rather than having setup/network connect once at start-up. To omit modules, use the "~" property in the modules object. Here's the relevant section of the ethernet-monitor manifest:

"modules": {
    "~": [
        "$(MODDABLE)/modules/network/ethernet/esp32/setup/ethernet.js"
    ],
    ...
},

Note: The setup/network module for Ethernet is implemented in the $MODDABLE/modules/netwwork/ethernet/esp32/setup/ethernet.js source file, which is aliased to the module specifier setup/network by manifest_net_ethernet.json. The "~" property used to remove a module requires the path to the module's source code.

Establishing and Monitoring the Ethernet Connection

Instead of relying on the setup/network module to establish the Ethernet connection, the application establishes the connection in its ethernetconnection module. It continuously monitors the state of the connection, storing the state in the ethernet global object. This allows code throughout the rest of the application to check the connection status using the global.

First, the application imports the Ethernet class from the ethernet module:

import Ethernet from "ethernet";

Then it initializes the global ethernet variable. Because the device is not yet connected to Ethernet, the connected property is set to false.

globalThis.ethernet = { connected: false };

Calling Ethernet.start() begins the process of establishing an Ethernet connection.

Ethernet.start();

To monitor the state of the Ethernet connection, the application creates an instance of the Ethernet class. The callback passed into the constructor is called when the connection state changes. In this application, the callback simply updates the ethernet.connected property to reflect the status of the Ethernet connection.

new Ethernet((msg, code) => {
    switch (msg) {
        case Ethernet.gotIP:
            ethernet.connected = true;
            break;

        case Ethernet.disconnected:
            ethernet.connected = false;
            break;
    }
});

The Ethernet documentation explains the APIs used here in more detail.

Handling Dropped Connections

The getTime function in the main module makes an HTTP request to the JSON Test Date & Time API and traces the time.

function getTime() {
    let request = new Request({ host: "time.jsontest.com", path: "/", response: String});
    request.callback = function(message, value) {
        if (Request.responseComplete === message) {
            value = JSON.parse(value, ["time"]);
            trace(`The time is ${value.time} GMT\n`);
        }
    }
}

If the getTime function is called when Ethernet is disconnected, it throws an exception. If the exception is unhandled, the Moddable SDK automatically restarts the ESP32.

But, good news: the application only calls this function when the ESP32 is connected to Ethernet. That's because it checks that the ethernet.connected property is true before calling getTime.

Timer.repeat(() => {
    if (ethernet.connected) {
        getTime();
    }
}, 5000);

And that's all that needs to be done to ensure that dropped connections don't lead to this application crashing! You can use the same logic in your own applications. You can even just reuse the ethernetmonitor module from the ethernet-monitor example.

Ethernet or Wi-Fi? You Decide!

You now know all you need to do to run our networking examples using Ethernet instead of Wi-Fi. You can experiment with our examples to make HTTP requests, connect to MQTT or WebSocket servers, advertise services via mDNS and more.

You also know how to start developing production-ready Ethernet applications that monitor the state of the Ethernet connection and account for unreliable connections.

Wi-Fi is great. We use it all the time and sometimes a wireless connection is exactly what a project needs. That said, Ethernet is faster, more reliable, and more secure than Wi-Fi. Sometimes that's necessary for production systems. The Moddable SDK supports both so customers can decide what's best for their products, and developers creating their own hobby projects can too.