Configuration portal HTTP API

This page documents the HTTP form fields accepted by the on-device WiFi configuration portal so that companion apps, provisioning scripts, and Home Assistant flows can integrate without reading firmware source.

The portal is implemented on top of h2zero's WiFiManager fork and the field declarations live in main/main.cpp (see setup_wifimanager).

Endpoint

POST http://<portal-ip>/wifisave
Content-Type: application/x-www-form-urlencoded

When the portal is active (no saved credentials, or trigger pressed at boot) the device exposes a soft-AP — see Portal for SSID/password rules.

Form fields

Field	Type	Source declaration	Persisted?
s	SSID	WiFiManager built-in	yes
p	WiFi PSK	WiFiManager built-in	yes
server	MQTT host (≤ 64)	custom_mqtt_server	yes, if non-empty
port	MQTT port	custom_mqtt_port	yes, if non-empty
user	MQTT username	custom_mqtt_user	yes, if non-empty
pass	MQTT password	custom_mqtt_pass	yes, if non-empty and value differs from the compile-time MQTT_PASS sentinel
secure	0 / 1	custom_mqtt_secure	yes (always)
validate	0 / 1	custom_validate_cert	yes (always)
cert	PEM (≤ 4096 B)	custom_mqtt_cert	yes, if length > MIN_CERT_LENGTH
ota_cert	PEM (≤ 4096 B)	custom_ota_server_cert	yes, if length > MIN_CERT_LENGTH
client_cert	PEM	custom_client_cert (signed-client builds only)	yes, if length > MIN_CERT_LENGTH
client_key	PEM	custom_client_key (signed-client builds only)	yes, if length > MIN_CERT_LENGTH
topic	MQTT base topic	custom_mqtt_topic	yes, if non-empty (trailing / added if missing)
name	Gateway name	custom_gateway_name	yes, if non-empty
ota	OTA / WebUI password	custom_ota_pass	yes, if non-empty

Empty-field semantics

Empty server / port / user / topic / name / ota values are ignored rather than persisted. This means a partial POST (e.g. WiFi-only) preserves any pre-flashed defaults instead of clearing them. To intentionally clear a field, this portal API does not currently support it — re-flash with new build defaults or use the WebUI.

The pass field combines the empty-check with a sentinel guard: the firmware persists the form value only when it is non-empty and differs from the compile-time MQTT_PASS sentinel. The sentinel branch prevents an unmodified form (which echoes back the default) from overwriting a stored password; the non-empty branch prevents a partial POST from wiping it.

Response and AP teardown

After processing the POST, WiFiManager returns a small success page and then tears down the soft-AP to attempt joining the configured station network. The teardown happens quickly enough that the TCP socket may be reset before the HTTP response is fully flushed to the client. Companion apps should:

• Treat a connection reset immediately after the POST as a likely-success signal, not a failure.
• Verify provisioning by checking for the device on the target network or for its first MQTT LWT message rather than relying on the HTTP response.

Example

curl -X POST \
  --data-urlencode 's=my-ssid' \
  --data-urlencode 'p=my-psk' \
  --data-urlencode 'server=192.168.1.10' \
  --data-urlencode 'port=1883' \
  --data-urlencode 'name=kitchen-omg' \
  --data-urlencode 'ota=mySecret123' \
  --data-urlencode 'topic=home/' \
  http://192.168.4.1/wifisave