feat(backend): add ethernet support

Author: JuergenLeber

docs/buildprocess.md

@@ -40,6 +40,7 @@ Customize the settings as you see fit. A value of 0 will disable the specified f
   -D FT_DOWNLOAD_FIRMWARE=1
   -D FT_SLEEP=1
   -D FT_BATTERY=1
+  -D FT_ETHERNET=1
 ```
 
 | Flag                 | Description                                                                                                                                                                                                              |
@@ -51,6 +52,7 @@ Customize the settings as you see fit. A value of 0 will disable the specified f
 | FT_DOWNLOAD_FIRMWARE | Controls whether the firmware download feature is enabled. Disable this if you won't firmware pulled from a server.                                                                                                      |
 | FT_SLEEP             | Controls whether the deep sleep feature is enabled. Disable this if your device is not battery operated or you don't need to place it in deep sleep to save energy.                                                      |
 | FT_BATTERY           | Controls whether the battery state of charge shall be reported to the clients. Disable this if your device is not battery operated.                                                                                      |
+| FT_ETHERNET          | Controls whether an ethernet interface will be used. Disable this if your device has no ethernet interface connected.                                                                                      |
 
 In addition custom features might be added or removed at runtime. See [Custom Features](statefulservice.md#custom-features) on how to use this in your application.
 

features.ini

@@ -9,3 +9,4 @@ build_flags =
   -D FT_BATTERY=0
   -D FT_ANALYTICS=1
   -D FT_COREDUMP=1
+;  -D FT_ETHERNET=1 ; ethernet feature should be enabled in the board config as not every board supports ethernet

lib/framework/ESP32SvelteKit.cpp

@@ -23,6 +23,10 @@ ESP32SvelteKit::ESP32SvelteKit(PsychicHttpServer *server, unsigned int numberEnd
                                                                                           _wifiStatus(server, &_securitySettingsService),
                                                                                           _apSettingsService(server, &ESPFS, &_securitySettingsService),
                                                                                           _apStatus(server, &_securitySettingsService, &_apSettingsService),
+#if FT_ENABLED(FT_ETHERNET)
+                                                                                          _ethernetSettingsService(server, &ESPFS, &_securitySettingsService, &_socket),
+                                                                                          _ethernetStatus(server, &_securitySettingsService),
+#endif
                                                                                           _socket(server, &_securitySettingsService, AuthenticationPredicates::IS_AUTHENTICATED),
                                                                                           _notificationService(&_socket),
 #if FT_ENABLED(FT_NTP)
@@ -65,6 +69,10 @@ void ESP32SvelteKit::begin()
     ESP_LOGV(SVK_TAG, "Loading settings from files system");
     ESPFS.begin(true);
 
+#if FT_ENABLED(FT_ETHERNET)
+    _ethernetSettingsService.initEthernet();
+#endif
+
     _wifiSettingsService.initWiFi();
 
     // SvelteKit uses a lot of handlers, so we need to increase the max_uri_handlers
@@ -150,6 +158,11 @@ void ESP32SvelteKit::begin()
     _wifiSettingsService.begin();
     _wifiScanner.begin();
     _wifiStatus.begin();
+#if FT_ENABLED(FT_ETHERNET)
+    _ethernetSettingsService.begin();
+    _ethernetStatus.begin();
+#endif
+
 
 #if FT_ENABLED(FT_COREDUMP)
     _coreDump.begin();
@@ -223,6 +236,10 @@ void ESP32SvelteKit::_loop()
     bool ap = false;
     bool event = false;
     bool mqtt = false;
+#if FT_ENABLED(FT_ETHERNET)
+    bool eth = false;
+#endif
+    bool wifi_eth_combined = false;
 
     while (1)
     {
@@ -234,21 +251,27 @@ void ESP32SvelteKit::_loop()
 #if FT_ENABLED(FT_ANALYTICS)
         _analyticsService.loop();
 #endif
+#if FT_ENABLED(FT_ETHERNET)
+        _ethernetSettingsService.loop();
+        eth = _ethernetStatus.isConnected();
+        if (eth) { wifi_eth_combined = true; }
+#endif
 
         // Query the connectivity status
         wifi = _wifiStatus.isConnected();
+        if (wifi) { wifi_eth_combined = true; }
         ap = _apStatus.isActive();
         event = _socket.getConnectedClients() > 0;
 #if FT_ENABLED(FT_MQTT)
         mqtt = _mqttStatus.isConnected();
 #endif
 
         // Update the system status
-        if (wifi && mqtt)
+        if (wifi_eth_combined && mqtt)
         {
             _connectionStatus = ConnectionStatus::STA_MQTT;
         }
-        else if (wifi)
+        else if (wifi_eth_combined)
         {
             _connectionStatus = event ? ConnectionStatus::STA_CONNECTED : ConnectionStatus::STA;
         }

lib/framework/ESP32SvelteKit.h

@@ -42,6 +42,8 @@
 #include <WiFiScanner.h>
 #include <WiFiSettingsService.h>
 #include <WiFiStatus.h>
+#include <EthernetSettingsService.h>
+#include <EthernetStatus.h>
 #include <ESPFS.h>
 #include <PsychicHttp.h>
 #include <vector>
@@ -212,6 +214,10 @@ class ESP32SvelteKit
     WiFiStatus _wifiStatus;
     APSettingsService _apSettingsService;
     APStatus _apStatus;
+#if FT_ENABLED(FT_ETHERNET)
+    EthernetSettingsService _ethernetSettingsService;
+    EthernetStatus _ethernetStatus;
+#endif
     EventSocket _socket;
     NotificationService _notificationService;
 #if FT_ENABLED(FT_NTP)

lib/framework/EthernetSettingsService.cpp

@@ -0,0 +1,103 @@
+/**
+ *   ESP32 SvelteKit
+ *
+ *   A simple, secure and extensible framework for IoT projects for ESP32 platforms
+ *   with responsive Sveltekit front-end built with TailwindCSS and DaisyUI.
+ *   https://github.com/theelims/ESP32-sveltekit
+ *
+ *   Copyright (C) 2018 - 2023 rjwats
+ *   Copyright (C) 2023 - 2025 theelims
+ *
+ *   All Rights Reserved. This software may be modified and distributed under
+ *   the terms of the LGPL v3 license. See the LICENSE file for details.
+ **/
+
+#include <EthernetSettingsService.h>
+
+EthernetSettingsService::EthernetSettingsService(PsychicHttpServer *server,
+                                                 FS *fs,
+                                                 SecurityManager *securityManager,
+                                                 EventSocket *socket) : _server(server),
+                                                 _securityManager(securityManager),
+                                                 _httpEndpoint(EthernetSettings::read, EthernetSettings::update, this, server, ETHERNET_SETTINGS_SERVICE_PATH, securityManager,
+                                                               AuthenticationPredicates::IS_ADMIN),
+                                                 _fsPersistence(EthernetSettings::read, EthernetSettings::update, this, fs, ETHERNET_SETTINGS_FILE),
+                                                 _socket(socket)
+{
+    addUpdateHandler([&](const String &originId)
+                     { reconfigureEthernet(); },
+                     false);
+}
+
+void EthernetSettingsService::initEthernet()
+{
+    // make sure the interface is stopped before continuing and initializing
+    ETH.end();
+    _fsPersistence.readFromFS();
+    configureNetwork(_state.ethernetSettings);
+}
+
+void EthernetSettingsService::begin()
+{
+    _socket->registerEvent(EVENT_ETHERNET);
+    _httpEndpoint.begin();
+}
+
+void EthernetSettingsService::loop()
+{
+    unsigned long currentMillis = millis();
+
+    if (!_lastEthernetUpdate || (unsigned long)(currentMillis - _lastEthernetUpdate) >= ETHERNET_EVENT_DELAY)
+    {
+        _lastEthernetUpdate = currentMillis;
+        updateEthernet();
+    }
+}
+
+String EthernetSettingsService::getHostname()
+{
+    return _state.hostname;
+}
+
+String EthernetSettingsService::getIP()
+{
+    if (ETH.connected())
+    {
+        return ETH.localIP().toString();
+    }
+    return "Not connected";
+}
+
+void EthernetSettingsService::configureNetwork(ethernet_settings_t &network)
+{
+    // set hostname before IP configuration starts
+    ETH.setHostname(_state.hostname.c_str());
+    if (network.staticIPConfig)
+    {
+        // configure for static IP
+        ETH.config(network.localIP, network.gatewayIP, network.subnetMask, network.dnsIP1, network.dnsIP2);
+    }
+    else
+    {
+        // configure for DHCP
+        ETH.config(INADDR_NONE, INADDR_NONE, INADDR_NONE);
+    }
+    // (re)start ethernet
+    ETH.begin();
+    // set hostname (again) after (re)starting ethernet due to a bug in the ESP-IDF implementation
+    ETH.setHostname(_state.hostname.c_str());
+
+}
+
+void EthernetSettingsService::reconfigureEthernet()
+{
+    configureNetwork(_state.ethernetSettings);
+}
+
+void EthernetSettingsService::updateEthernet()
+{
+    JsonDocument doc;
+    doc["connected"] = ETH.connected();
+    JsonObject jsonObject = doc.as<JsonObject>();
+    _socket->emitEvent(EVENT_ETHERNET, jsonObject);
+}

lib/framework/EthernetSettingsService.h

@@ -0,0 +1,127 @@
+#ifndef EthernetSettingsService_h
+#define EthernetSettingsService_h
+
+/**
+ *   ESP32 SvelteKit
+ *
+ *   A simple, secure and extensible framework for IoT projects for ESP32 platforms
+ *   with responsive Sveltekit front-end built with TailwindCSS and DaisyUI.
+ *   https://github.com/theelims/ESP32-sveltekit
+ *
+ *   Copyright (C) 2018 - 2023 rjwats
+ *   Copyright (C) 2023 - 2025 theelims
+ *
+ *   All Rights Reserved. This software may be modified and distributed under
+ *   the terms of the LGPL v3 license. See the LICENSE file for details.
+ **/
+
+#include <WiFi.h>
+#include <ETH.h>
+#include <SettingValue.h>
+#include <StatefulService.h>
+#include <EventSocket.h>
+#include <FSPersistence.h>
+#include <HttpEndpoint.h>
+#include <JsonUtils.h>
+#include <SecurityManager.h>
+#include <PsychicHttp.h>
+#include <vector>
+
+#ifndef FACTORY_ETHERNET_HOSTNAME
+#define FACTORY_ETHERNET_HOSTNAME "#{platform}-#{unique_id}"
+#endif
+
+#define ETHERNET_EVENT_DELAY 500
+
+#define ETHERNET_SETTINGS_FILE "/config/ethernetSettings.json"
+#define ETHERNET_SETTINGS_SERVICE_PATH "/rest/ethernetSettings"
+
+#define EVENT_ETHERNET "ethernet"
+
+// Struct defining the ethernet settings
+typedef struct
+{
+    bool staticIPConfig;
+    IPAddress localIP;
+    IPAddress gatewayIP;
+    IPAddress subnetMask;
+    IPAddress dnsIP1;
+    IPAddress dnsIP2;
+    bool available;
+} ethernet_settings_t;
+
+class EthernetSettings
+{
+public:
+    // core ethernet configuration
+    String hostname;
+    ethernet_settings_t ethernetSettings;
+
+    static void read(EthernetSettings &settings, JsonObject &root)
+    {
+        root["hostname"] = settings.hostname;
+        root["static_ip_config"] = settings.ethernetSettings.staticIPConfig;
+        JsonUtils::writeIP(root, "local_ip", settings.ethernetSettings.localIP);
+        JsonUtils::writeIP(root, "gateway_ip", settings.ethernetSettings.gatewayIP);
+        JsonUtils::writeIP(root, "subnet_mask", settings.ethernetSettings.subnetMask);
+        JsonUtils::writeIP(root, "dns_ip_1", settings.ethernetSettings.dnsIP1);
+        JsonUtils::writeIP(root, "dns_ip_2", settings.ethernetSettings.dnsIP2);
+        ESP_LOGV(SVK_TAG, "Ethernet Settings read");
+    }
+
+    static StateUpdateResult update(JsonObject &root, EthernetSettings &settings)
+    {
+        settings.hostname = root["hostname"] | SettingValue::format(FACTORY_ETHERNET_HOSTNAME);
+        settings.ethernetSettings.staticIPConfig = root["static_ip_config"] | false;
+        JsonUtils::readIP(root, "local_ip", settings.ethernetSettings.localIP);
+        JsonUtils::readIP(root, "gateway_ip", settings.ethernetSettings.gatewayIP);
+        JsonUtils::readIP(root, "subnet_mask", settings.ethernetSettings.subnetMask);
+        JsonUtils::readIP(root, "dns_ip_1", settings.ethernetSettings.dnsIP1);
+        JsonUtils::readIP(root, "dns_ip_2", settings.ethernetSettings.dnsIP2);
+
+        // Swap around the dns servers if 2 is populated but 1 is not
+        if (IPUtils::isNotSet(settings.ethernetSettings.dnsIP1) && IPUtils::isSet(settings.ethernetSettings.dnsIP2))
+        {
+            settings.ethernetSettings.dnsIP1 = settings.ethernetSettings.dnsIP2;
+            settings.ethernetSettings.dnsIP2 = INADDR_NONE;
+        }
+
+        // Turning off static ip config if we don't meet the minimum requirements
+        // of ipAddress and subnet. This may change to static ip only
+        // as sensible defaults can be assumed for gateway and subnet
+        if (settings.ethernetSettings.staticIPConfig && (IPUtils::isNotSet(settings.ethernetSettings.localIP) || IPUtils::isNotSet(settings.ethernetSettings.subnetMask)))
+        {
+            settings.ethernetSettings.staticIPConfig = false;
+        }
+        ESP_LOGV(SVK_TAG, "Ethernet Settings updated");
+
+        return StateUpdateResult::CHANGED;
+    };
+};
+
+class EthernetSettingsService : public StatefulService<EthernetSettings>
+{
+public:
+    EthernetSettingsService(PsychicHttpServer *server, FS *fs, SecurityManager *securityManager, EventSocket *socket);
+
+    void initEthernet();
+    void begin();
+    void loop();
+    String getHostname();
+    String getIP();
+
+private:
+    PsychicHttpServer *_server;
+    SecurityManager *_securityManager;
+    HttpEndpoint<EthernetSettings> _httpEndpoint;
+    FSPersistence<EthernetSettings> _fsPersistence;
+    EventSocket *_socket;
+    unsigned long _lastEthernetUpdate;
+
+    void configureNetwork(ethernet_settings_t &network);
+    void reconfigureEthernet();
+    void updateEthernet();
+
+};
+
+#endif // end EthernetSettingsService_h