MycilaESPConnect

License: MIT Continuous Integration PlatformIO Registry

Simple & Easy Network Manager for ESP32 with WiFi, Ethernet and Captive Portal support

This fork is based on https://github.com/ayushsharma82/ESPConnect. I highly recommend looking at all OSS projects (and products) from @ayushsharma82. He is making great Arduino libraries.

Changes

Usage

API

2 flavors of begin() methods:

  1. ESPConnect.begin(server, "hostname", "ssid", "password") / ESPConnect.begin(server, "hostname", "ssid")
  2. ESPConnect.begin(server, "hostname", "ssid", "password", ESPConnectConfig) where config is {.wifiSSID = ..., .wifiPassword = ..., .apMode = ...}

The first flavors will automatically handle the persistance of user choices and reload them at startup.

The second choice let the user handle the load/save of the configuration.

Please have a look at the self-documented API for the other methods and teh examples.

Blocking mode

  ESPConnect.listen([](__unused ESPConnectState previous, __unused ESPConnectState state) {
    // ...
  });

  ESPConnect.setAutoRestart(true);
  ESPConnect.setBlocking(true);
  ESPConnect.begin(server, "arduino", "Captive Portal SSID");
  Serial.println("ESPConnect completed!");

Non-blocking mode

void setup() {
  ESPConnect.listen([](__unused ESPConnectState previous, __unused ESPConnectState state) {
    // ...
  });

  ESPConnect.setAutoRestart(true);
  ESPConnect.setBlocking(false);
  ESPConnect.begin(server, "arduino", "Captive Portal SSID");
  Serial.println("ESPConnect started!");
}

void loop() {
  ESPConnect.loop();
}

Use an external configuration system

  ESPConnect.listen([](__unused ESPConnectState previous, __unused ESPConnectState state) {
    switch (state) {
      case ESPConnectState::PORTAL_COMPLETE:
        bool apMode = ESPConnect.hasConfiguredAPMode();
        String wifiSSID = ESPConnect.getConfiguredWiFiSSID();
        String wifiPassword = ESPConnect.getConfiguredWiFiPassword();
        if (apMode) {
          Serial.println("====> Captive Portal: Access Point configured");
        } else {
          Serial.println("====> Captive Portal: WiFi configured");
        }
        saveConfig(wifiSSID, wifiPassword, apMode);
        break;

      default:
        break;
    }
  });

  ESPConnect.setAutoRestart(true);
  ESPConnect.setBlocking(true);

  // load config from external system
  ESPConnectConfig config = {
    .wifiSSID = ...,
    .wifiPassword = ...,
    .apMode = ...
  };

  ESPConnect.begin(server, "arduino", "Captive Portal SSID", "", config);

ESP8266 Specifics

The dependency vshymanskyy/Preferences is required when using the auto-load avd auto-save feature.

Ethernet Support

Set -D ESPCONNECT_ETH_SUPPORT to add Ethernet support.

Hints:

Known compatibilities:

Board Compile Tested
OLIMEX ESP32-PoE (esp32-poe) ✅ ❌
Wireless-Tag WT32-ETH01 Ethernet Module (wt32-eth01) ✅ ✅
T-ETH-Lite ESP32 S3 (esp32s3box) ✅ ✅
USR-ES1 W5500 ✅ ✅

Example of flags for wt32-eth01:

  -D ESPCONNECT_ETH_SUPPORT
  -D ETH_PHY_ADDR=1
  -D ETH_PHY_POWER=16

Example of flags for T-ETH-Lite ESP32 S3:

  -D ESPCONNECT_ETH_SUPPORT
  -D ETH_PHY_ADDR=1
  -D ETH_PHY_CS=9
  -D ETH_PHY_IRQ=13
  -D ETH_PHY_RST=14
  -D ETH_PHY_SPI_MISO=11
  -D ETH_PHY_SPI_MOSI=12
  -D ETH_PHY_SPI_SCK=10
  ; can only be activated with ESP-IDF >= 5
  ; -D ETH_PHY_TYPE=ETH_PHY_W5500

Example of flags for USR-ES1 W5500 with esp32dev (tested by @MicSG-dev):

  -D ESPCONNECT_ETH_SUPPORT
  -D ETH_PHY_ADDR=1
  -D ETH_PHY_CS=5
  -D ETH_PHY_IRQ=4
  -D ETH_PHY_RST=14
  -D ETH_PHY_SPI_MISO=19
  -D ETH_PHY_SPI_MOSI=23
  -D ETH_PHY_SPI_SCK=18
  ; can only be activated with ESP-IDF >= 5
  ; -D ETH_PHY_TYPE=ETH_PHY_W5500

Note: this project is making use of the ETHClass library from Lewis He

You can customize the logo by providing a web handler for /logo:

  webServer.on("/logo", HTTP_GET, [](AsyncWebServerRequest* request) {
    AsyncWebServerResponse* response = request->beginResponse(200, "image/png", logo_png_gz_start, logo_png_gz_end - logo_png_gz_start);
    response->addHeader("Content-Encoding", "gzip");
    response->addHeader("Cache-Control", "public, max-age=900");
    request->send(response);
  });

If not provided, the logo won’t appear in the Captive Portal.

mDNS

mDNS takes quite a lot of space in flash (about 25KB). You can disable it by setting -D ESPCONNECT_NO_MDNS.