First-boot WiFi provisioning via a captive portal (DETWS_ENABLE_PROVISIONING). More...

#include "ServerConfig.h"
#include <stddef.h>

Functions
bool	detws_prov_form_field (const char body, const char key, char *out, size_t cap)
	Extract and URL-decode a field from an x-www-form-urlencoded body.

bool	detws_provisioning_load (char ssid, size_t ssid_cap, char psk, size_t psk_cap)
	Load stored WiFi credentials from NVS.

void	detws_provisioning_begin (DetWebServer &server, const char *ap_ssid)
	Start the captive portal: softAP `ap_ssid` + catch-all DNS + form routes.

void	detws_provisioning_clear ()
	Erase stored credentials (forces re-provisioning on next boot).

Detailed Description

First-boot WiFi provisioning via a captive portal (DETWS_ENABLE_PROVISIONING).

When no WiFi credentials are stored, the device starts a softAP and a catch-all DNS responder (via the transport-layer UDP service - no add-on library) so any connected client is funneled to a credentials form. Submitted SSID/passphrase are persisted to NVS and the device reboots into station mode. Uses only WiFi.softAP, lwIP UDP, and Preferences; compiled to stubs when disabled or off-Arduino.

The form-field parser (detws_prov_form_field) is always compiled and is the only non-trivial logic, so it is unit-tested off-target.

Author: Douglas Quigg (dstroy0)

Date: 2026

Definition in file provisioning_service.h.

Function Documentation

◆ detws_prov_form_field()

bool detws_prov_form_field	(	const char *	body,
		const char *	key,
		char *	out,
		size_t	cap
	)

Extract and URL-decode a field from an x-www-form-urlencoded body.

Finds @p key= in body (matching only whole field names, i.e. at the start or just after &), copies its value up to the next & or end into out, decoding + to space and XX hex escapes. Always null-terminates.

Parameters

body	Form body (e.g. "ssid=My+AP&psk=p%40ss").
key	Field name (e.g. "ssid").
out	Destination buffer.
cap	Capacity of `out` (>= 1).

Returns: true if the field was found, false otherwise (out set to "").

Definition at line 21 of file provisioning_service.cpp.

References det_hex_val().

◆ detws_provisioning_load()

bool detws_provisioning_load	(	char *	ssid,
		size_t	ssid_cap,
		char *	psk,
		size_t	psk_cap
	)

Load stored WiFi credentials from NVS.

Parameters

ssid	Destination for the stored SSID (always null-terminated).
ssid_cap	Capacity of `ssid`.
psk	Destination for the stored passphrase (always null-terminated).
psk_cap	Capacity of `psk`.

Returns: true if a non-empty SSID is stored (the app should connect in STA mode).

Definition at line 222 of file provisioning_service.cpp.

◆ detws_provisioning_begin()

void detws_provisioning_begin	(	DetWebServer &	server,
		const char *	ap_ssid
	)

Start the captive portal: softAP ap_ssid + catch-all DNS + form routes.

Registers GET /* (the credentials form) and POST /save (persist + reboot) on server. The catch-all DNS responder runs from a transport-layer UDP callback, so no per-loop servicing is required. Call after server.begin().

Definition at line 230 of file provisioning_service.cpp.

◆ detws_provisioning_clear()

void detws_provisioning_clear ( )

Erase stored credentials (forces re-provisioning on next boot).