Guides
  1. device-onboarding

Provisioning Mode

Provisioning mode is for shipping units to a site where you don't know the WiFi credentials until install day. You flash a small bootstrap firmware (gateway-provisioning) on the bench, ship the unit, and the end-customer walks through a captive-portal flow on their phone.

What gets flashed

The web flasher writes three things to the chip in this mode:

  1. gateway-provisioning firmware into the factory partition. It stays there forever — never gets overwritten by OTAs.
  2. Per-device mTLS cert into NVS namespace scadable_certs. Minted by SCADABLE at flash time, valid 7 days.
  3. Empty ota_0 slot. Your customer firmware lands here on first OTA after WiFi joins.

The chip boots into gateway-provisioning automatically because no ota_0/ota_1 slot is valid yet.

What the dashboard operator does

  1. Open the dashboard, click Add Device.
  2. Pick Provisioning mode in the wizard.
  3. Connect the ESP32 over USB and click Flash. The web flasher (WebSerial) does the rest. Total flash time: 30 to 60 seconds depending on chip.
  4. Unplug, ship the unit. The dashboard shows the device in Awaiting Setup state.

That's the operator's part. Everything below happens in the field.

What the end-customer does

The unit arrives, the customer plugs it into power. Within 5 to 10 seconds:

  1. The chip boots gateway-provisioning, sees no WiFi creds in NVS, and starts a SoftAP named SCADABLE-Setup-XXXXXX (where XXXXXX is the last 6 hex of the chip's MAC).
  2. Customer joins that AP from their phone.
  3. The phone's captive portal detector kicks in — a setup page pops up automatically with no URL to type.
  4. Customer picks their WiFi from a scanned list, enters the password, taps Connect.
  5. Chip stores the creds in NVS, drops the AP, joins the customer's WiFi.
  6. Chip connects to the SCADABLE broker over mTLS using the cert minted at flash time.
  7. Chip pulls the latest customer firmware release for its namespace via OTA.
  8. After the OTA validates, chip reboots into the customer firmware. Provisioner stays in the factory partition for future re-provisioning.

Total time from "plug in power" to "device online with customer firmware running": about 2 minutes (mostly the OTA download).

The full step-by-step from the customer's perspective is on Captive portal experience.

Re-provisioning

If WiFi changes (customer moves the device, network password rotates), the customer holds the BOOT button for 5 seconds. The provisioner clears WiFi creds from NVS and starts the SoftAP again. The mTLS cert stays valid (until it expires — see Device cert lifecycle).

When to use this mode

  • Shipping product to a site you don't control.
  • OEM product where the end-customer is non-technical.
  • Field installs where install day is the first time WiFi creds are known.

For dev/bench, use Direct mode instead — re-walking the captive portal 50 times a day is no fun.

Limitations today

  • WPA2 personal only. WPA-Enterprise is on the roadmap.
  • 2.4 GHz only on ESP32; ESP32-S3 supports 5 GHz with the right module variant.
  • The mTLS cert is valid for 7 days. If the unit sits unplugged for more than 7 days, you'll need to re-flash to mint a fresh cert. On-device EST renewal is Phase 2.

Updated 4 days ago