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

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 settings fields 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);

// Settings fields shown on the portal's settings step
NetWizardHeader nw_header(&NW, "MQTT");
NetWizardDivider nw_divider1(&NW);
NetWizardInput nw_mqtt_host(&NW, "Host", "", "mqtt.example.com");  // String
NetWizardInput nw_mqtt_port(&NW, "Port", 1883);                     // int

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 settings page
  NW.onConfig([&]() {
    Serial.printf("Host: %s\n", nw_mqtt_host.getValue().c_str());
    Serial.printf("Port: %d\n", nw_mqtt_port.getValue());
    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 settings fields build the portal's settings page, and nw_mqtt_port.getValue() returns an int. See Settings Fields.
  • 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