WiFiManager/docs/recipes/FIELD_INSTALLER_PROVISIONING.md

Field installer provisioning

A field-installed controller or sensor often needs more time for setup than a desk-bound demo, but should not host an unattended configuration portal forever. Existing consuming device sketches solve this by choosing a deliberate 15-minute configuration window and exposing clear local feedback while setup is active.

Flow

1. Boot with the product's normal configuration.
2. Try the stored primary/fallback profile set.
3. If Wi-Fi is unavailable, start the local setup AP and portal.
4. Keep the portal available for the installation window.
5. On a successful connection, let the application start services or reboot according to its own policy.
6. On timeout, return to the product's recovery policy rather than assuming the installer finished.

constexpr unsigned long kInstallerWindowSeconds = 15 * 60;
MyProfileStore profileStore;

void setup() {
    configureProductPortal();
    wifi.setStationProfileStore(&profileStore);
    wifi.setStationRecoveryInterval(30000);
    wifi.setConfigPortalTimeout(kInstallerWindowSeconds);

    wifi.setAPCallback([](WiFiManager*) {
        setIndicator(IndicatorState::Setup);
        showInstallerInstructions();
    });

    wifi.setConfigPortalTimeoutCallback([] {
        setIndicator(IndicatorState::Offline);
        recordSetupTimeout();
    });

    wifi.startStationConnection(deviceSetupName(), deviceSetupPassword());
}

void loop() {
    wifi.process();
    // Do not start or recreate an application server while the portal owns its port.
}

The timeout is a product decision. A short interval is appropriate for a user-facing appliance; a longer maintenance window may be justified for a device installed in a cabinet or plant room. Set 0 only when an always-open setup portal is an explicit operational choice.

What to show an installer

Keep feedback independent of a browser redirect:

• the setup SSID and any required password;
• the device's portal address and non-default port, if configured;
• a distinct setup indicator while the portal is active;
• a distinct failure/offline indication after timeout;
• confirmation only after Wi-Fi has actually connected.

Use getConfigPortalActive(), didConfigPortalConnectSucceed(), and getConfigPortalConnectMessage() for this state. See Observability.

Product boundary

WiFiManager supplies the local portal and timer. The product decides what happens after timeout: keep retrying profiles, sleep, wait for a physical action, or operate in an offline mode. If startStationConnection() returns false because no usable stored profile exists, the portal may be the intended next state rather than a reason to reboot immediately.

For a product that deliberately uses one platform-saved network rather than primary/fallback profiles, the smaller legacy equivalent is wifi.autoConnect(deviceSetupName(), deviceSetupPassword()). It has the same local portal fallback, but no application-owned profile store, candidate verification, or fallback network.

Continue with Provisioning lifecycle or Provisioning state feedback.