provisioning_service.h File Reference

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

#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	ProvNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Functions
	PROTOCORE_NS_LAYOUT (ProvNs, form_field, load, begin, clear)
proto_bool	protocore_prov_form_field (uint8_t *work, const char *body, const char *key, char *out, size_t cap)
	Extract and URL-decode a field from an x-www-form-urlencoded body. .
proto_bool	protocore_prov_load (uint8_t *work, char *ssid, size_t ssid_cap, char *psk, size_t psk_cap)
	Load stored WiFi credentials from NVS.
void	protocore_prov_begin (uint8_t *work, const char *ap_ssid)
	Start the captive portal: softAP ap_ssid + catch-all DNS + form .
void	protocore_prov_clear (uint8_t *work)
	Erase stored credentials (forces re-provisioning on next boot).
uint8_t *	protocore_provisioning_service_span (void)
	The PROTOCORE_PROVISIONING_BORROW bytes this module's state lives in.

Variables
PROTOCORE_NS ProvNs Prov	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

First-boot WiFi provisioning via a captive portal (PROTOCORE_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 Physical.wifi_ap_init, the library UDP transport, and the platform's key/value store; compiled to stubs when disabled or when the platform carries no such store.

The form-field parser (Prov.form_field) is the pure half of this module and is the only non-trivial logic, so it is unit-tested off-target.

work is PROTOCORE_PROVISIONING_BORROW bytes the CALLER took, at an address it knows. It is not held past the call, so nothing here aliases it. How those bytes are carved is this module's and is never named here.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file provisioning_service.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	ProvNs	,
		form_field	,
		load	,
		begin	,
		clear
	)

protocore_prov_form_field()

proto_bool protocore_prov_form_field	(	uint8_t *	work,
		const char *	body,
		const char *	key,
		char *	out,
		size_t	cap
	)

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

Parameters

work	PROTOCORE_PROV_BORROW bytes the caller took. Not held past the call.
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

PROTO_TRUE on success.

protocore_prov_load()

proto_bool protocore_prov_load	(	uint8_t *	work,
		char *	ssid,
		size_t	ssid_cap,
		char *	psk,
		size_t	psk_cap
	)

Load stored WiFi credentials from NVS.

Parameters

work	PROTOCORE_PROV_BORROW bytes the caller took. Not held past the call.
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

PROTO_TRUE on success.

protocore_prov_begin()

void protocore_prov_begin	(	uint8_t *	work,
		const char *	ap_ssid
	)

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

Parameters

work	PROTOCORE_PROV_BORROW bytes the caller took. Not held past the call.
ap_ssid	Ap ssid

protocore_prov_clear()

void protocore_prov_clear

(

uint8_t *

work

)

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

Parameters

work	PROTOCORE_PROV_BORROW bytes the caller took. Not held past the call.

protocore_provisioning_service_span()

uint8_t * protocore_provisioning_service_span

(

void

)

The PROTOCORE_PROVISIONING_BORROW bytes this module's state lives in.

Stated beside the namespace rather than on it: an entry takes a borrow, and this is where that borrow comes from. Taken once from the end of the pool, which no mark and no release walks, so the state lasts the life of the program.

Returns

the span.

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS ProvNs Prov PROTOCORE_UNUSED

Initial value:

= {.form_field = protocore_prov_form_field,
                                             .load = protocore_prov_load,
                                             .begin = protocore_prov_begin,
                                             .clear = protocore_prov_clear}

Module namespace.

Definition at line 86 of file provisioning_service.h.