Anniversary Sale · up to 80% off all librariesEnds Nov 9Shop now
SOFTTDocs

Example

A complete NetWizard sketch with a synchronous web server, status callbacks and configuration parameters.

The sketch below is based on the Demo example that ships with the library. It starts NetWizard with the blocking strategy, logs connection and portal changes, adds two configuration parameters and serves an additional route from the same web server. More examples are available in the repository.

Demo sketch

Demo.ino
#include <WebServer.h>
#include <NetWizard.h>  // NetWizard Pro: #include <NetWizardPro.h>

WebServer server(80);

// Initialize NetWizard
NetWizard NW(&server);

// Configuration parameters shown in the captive portal
NetWizardParameter nw_header(&NW, NW_HEADER, "MQTT");
NetWizardParameter nw_divider1(&NW, NW_DIVIDER);
NetWizardParameter nw_mqtt_host(&NW, NW_INPUT, "Host", "", "mqtt.example.com");
NetWizardParameter nw_mqtt_port(&NW, NW_INPUT, "Port", "", "1883");

void setup(void) {
  delay(3000);
  Serial.begin(115200);
  Serial.println("");

  // BLOCKING: autoConnect() returns only after the captive portal has closed.
  // NON_BLOCKING: autoConnect() returns immediately; the portal runs in the background.
  NW.setStrategy(NetWizardStrategy::BLOCKING);

  // Called whenever the connection status changes
  NW.onConnectionStatus([](NetWizardConnectionStatus status) {
    String status_str = "";

    switch (status) {
      case NetWizardConnectionStatus::DISCONNECTED:
        status_str = "Disconnected";
        break;
      case NetWizardConnectionStatus::CONNECTING:
        status_str = "Connecting";
        break;
      case NetWizardConnectionStatus::CONNECTED:
        status_str = "Connected";
        break;
      case NetWizardConnectionStatus::CONNECTION_FAILED:
        status_str = "Connection Failed";
        break;
      case NetWizardConnectionStatus::CONNECTION_LOST:
        status_str = "Connection Lost";
        break;
      case NetWizardConnectionStatus::NOT_FOUND:
        status_str = "Not Found";
        break;
      default:
        status_str = "Unknown";
    }

    Serial.printf("NW connection status changed: %s\n", status_str.c_str());
  });

  // Called whenever the captive portal state changes
  NW.onPortalState([](NetWizardPortalState state) {
    String state_str = "";

    switch (state) {
      case NetWizardPortalState::IDLE:
        state_str = "Idle";
        break;
      case NetWizardPortalState::CONNECTING_WIFI:
        state_str = "Connecting to WiFi";
        break;
      case NetWizardPortalState::WAITING_FOR_CONNECTION:
        state_str = "Waiting for Connection";
        break;
      case NetWizardPortalState::SUCCESS:
        state_str = "Success";
        break;
      case NetWizardPortalState::FAILED:
        state_str = "Failed";
        break;
      case NetWizardPortalState::TIMEOUT:
        state_str = "Timeout";
        break;
      default:
        state_str = "Unknown";
    }

    Serial.printf("NW portal state changed: %s\n", state_str.c_str());
  });

  // Called when the user submits the configuration parameters
  NW.onConfig([&]() {
    Serial.printf("Host: %s\n", nw_mqtt_host.getValueStr().c_str());
    Serial.printf("Port: %s\n", nw_mqtt_port.getValueStr().c_str());
    return true;  // accept the submitted values
  });

  // Connect to the saved network, or start the captive portal
  NW.autoConnect("NetWizard Demo", "");

  if (NW.isConfigured()) {
    Serial.println("Device is configured");
    if (NW.getConnectionStatus() == NetWizardConnectionStatus::CONNECTED) {
      Serial.print("Connected to ");
      Serial.println(NW.getSSID());
      Serial.print("IP address: ");
      Serial.println(NW.localIP());
    } else {
      Serial.println("Not connected to any WiFi");
    }
  } else {
    Serial.println("Device is not configured");
  }

  // Application route
  server.on("/demo", HTTP_GET, []() {
    server.send(200, "text/plain", "Hi! This is NetWizard Demo.");
  });

  server.begin();
}

void loop(void) {
  server.handleClient();

  // NetWizard loop task
  NW.loop();
}

What the sketch does

  • NetWizard NW(&server) attaches NetWizard to the web server. NetWizard registers the portal routes on this server only while the portal is active.
  • The four NetWizardParameter objects build the configuration page. See Parameters.
  • autoConnect("NetWizard Demo", "") connects to the saved network. If none is saved or the connection fails, it starts an open access point named NetWizard Demo. With the blocking strategy, the call returns after the portal closes.
  • NW.loop() must run continuously. With the synchronous WebServer, it also calls server.handleClient(), so the explicit call in loop() is optional.

Notes

  • On RP2040 and RP2350, a LittleFS partition is required to persist credentials. See Installation.
  • For an ESPAsyncWebServer version of this sketch, see the AsyncDemo example and Async Mode.

On this page