Captive Portal Experience

This page is what the end-customer sees when they unbox a unit you shipped them in Provisioning mode. Forward it to your install team or paste relevant snippets into your own product's setup guide.

Step 1: plug it in

Customer plugs the unit into power. Within 5 to 10 seconds the chip boots, sees no WiFi credentials in flash, and starts a SoftAP.

The status LED (if your hardware has one wired up) blinks slow blue. (Behaviour depends on which GPIO your firmware drives.)

Step 2: join the setup network

On their phone, the customer opens Settings → WiFi and looks for a network named:

SCADABLE-Setup-XXXXXX

Where XXXXXX is the last 6 hex digits of the chip's MAC address (e.g. SCADABLE-Setup-A1B2C3). The network is open (no password) and only exists during setup.

The customer taps to join it.

Step 3: captive portal pops up

Modern phones (iOS 11+, Android 5+) detect captive portals automatically. Within a second or two of joining the AP, a setup page opens by itself — no URL to type.

If the captive portal detector misfires (older Android, some Linux laptops), the customer can open any browser and go to http://4.3.2.1 to reach the same page.

Step 4: pick WiFi

The setup page shows:

• A scanned list of nearby WiFi networks, sorted by signal strength.
• A Connect button next to each.
• A Manual entry option at the bottom for hidden SSIDs.

The customer picks their WiFi from the list.

Step 5: enter password

A password field appears. Customer types the WPA2 password and taps Connect.

(For hidden SSIDs the customer also enters the SSID by hand. WPA2 personal only — WPA-Enterprise is on the roadmap.)

Step 6: wait for confirmation

The page shows a spinner with status: joining the network, connecting to SCADABLE, pulling firmware, rebooting.

If WiFi creds are wrong, the page shows "Couldn't connect to that network" and bounces back to step 4 with the password cleared. The SoftAP stays up; the customer retries without re-flashing.

If WiFi works but SCADABLE is unreachable (no internet, firewall blocking outbound 8883), the page shows "Joined WiFi but can't reach SCADABLE" with a Help link.

Step 7: device is live

On success: "Setup complete. You can close this window." The chip drops the SoftAP, joins WiFi, completes its first OTA, and reboots into the real customer firmware. Total time from "tap Connect" to online with customer firmware: about 2 minutes (mostly the OTA download).

The phone's WiFi quietly switches back to whatever network it was on before.

Re-entering setup later

If the customer ever needs to change the WiFi (move the device, password rotation), they hold the BOOT button on the chip for 5 seconds. The chip clears WiFi creds from NVS, reboots, and the SoftAP comes up again. Same captive portal, same flow.

The mTLS cert (used to talk to SCADABLE) is unaffected — see Device cert lifecycle for what happens if it expires.

What the customer never sees

No SCADABLE login (provisioning is anonymous from their side), no cert (minted at flash time before they touched the unit), no namespace or project ID. The cert binds the device to your namespace; the customer just plugs in and joins WiFi.