network_prov_mgr.h File Reference

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for network_prov_mgr.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	network_prov_event_handler
	Registration of an application event handler. More...
struct	network_prov_scheme
	Provisioning transport (scheme) vtable. More...
struct	network_prov_mgr_config
	Manager configuration passed to network_prov_mgr_init. More...

Typedefs
typedef void(*	network_prov_cb_t) (void *user_data, enum network_prov_cb_event event, void *event_data)
	Application event callback.
typedef int(*	network_prov_endpoint_handler_t) (void *user_ctx, const uint8_t *inbuf, size_t inlen, uint8_t **outbuf, size_t *outlen)
	Handler for an application-defined custom endpoint.

Enumerations
enum	network_prov_security { NETWORK_PROV_SECURITY_0 = 0 , NETWORK_PROV_SECURITY_1 = 1 }
	Security scheme used for the protocomm session. More...
enum	network_prov_cb_event {   NETWORK_PROV_INIT , NETWORK_PROV_START , NETWORK_PROV_CRED_RECV , NETWORK_PROV_CRED_FAIL ,   NETWORK_PROV_CRED_SUCCESS , NETWORK_PROV_END , NETWORK_PROV_DEINIT }
	Events emitted by the manager over the application event handler. More...
enum	network_prov_cred_fail_reason { NETWORK_PROV_WIFI_AUTH_ERROR , NETWORK_PROV_WIFI_NETWORK_NOT_FOUND }
	Reason reported alongside NETWORK_PROV_CRED_FAIL. More...

Functions
int	network_prov_mgr_init (struct network_prov_mgr_config config)
	Initialise the provisioning manager.
void	network_prov_mgr_deinit (void)
	Tear down the manager and free its resources.
int	network_prov_mgr_endpoint_create (const char *ep_name)
	Create an application-specific protocomm endpoint.
int	network_prov_mgr_endpoint_register (const char *ep_name, network_prov_endpoint_handler_t handler, void *user_ctx)
	Attach a handler to a created custom endpoint.
int	network_prov_mgr_endpoint_unregister (const char *ep_name)
	Detach a custom endpoint's handler; subsequent requests report unsupported until it is registered again.
int	network_prov_mgr_set_app_info (const char *label, const char *version, const char *const *capabilities, size_t capabilities_count)
	Advertise an application-specific section in the proto-ver capabilities JSON.
int	network_prov_mgr_is_provisioned (bool *provisioned)
	Report whether the device already has stored Wi-Fi credentials.
int	network_prov_mgr_start_provisioning (enum network_prov_security security, const char *pop, const char *service_name, const char *service_key)
	Start the provisioning service on the configured transport: BLE (register the GATT service and advertise) or SoftAP (bring up the access point, the DHCPv4 server and the HTTP endpoints).
void	network_prov_mgr_stop_provisioning (void)
	Stop advertising and tear down the transport (keeps the manager init'd).
int	network_prov_mgr_disable_auto_stop (uint32_t cleanup_delay_ms)
	Disable the automatic teardown of the provisioning service after a successful connection.
bool	network_prov_mgr_is_sm_idle (void)
	True when no provisioning session is active (state machine idle).
int	network_prov_mgr_reset_wifi_sm_state_on_failure (void)
	Reset the Wi-Fi provisioning state machine after a failed attempt so the app can supply fresh credentials without restarting the service.
int	network_prov_mgr_reset_wifi_sm_state_for_reprovision (void)
	Reset the Wi-Fi provisioning state machine to accept a new network while the service is still running (re-provision).
int	network_prov_mgr_configure_wifi_sta (const char *ssid, const char *psk)
	Apply Wi-Fi credentials programmatically, as if received from a client.
int	network_prov_mgr_get_wifi_remaining_conn_attempts (uint32_t *attempts_remaining)
	Number of Wi-Fi connection attempts left for the credentials currently being tried (wifi_conn_attempts minus completed attempts).
void	network_prov_mgr_wait (void)
	Block until provisioning completes (NETWORK_PROV_CRED_SUCCESS).
int	network_prov_mgr_reset_wifi_provisioning (void)
	Erase all stored Wi-Fi credentials; the device reverts to unprovisioned.

Typedef Documentation

network_prov_cb_t

typedef void(* network_prov_cb_t) (void *user_data, enum network_prov_cb_event event, void *event_data)

Application event callback.

Parameters

user_data	Opaque pointer supplied in network_prov_event_handler.
event	Event being delivered.
event_data	Event-specific payload (e.g. pointer to network_prov_cred_fail_reason for CRED_FAIL), or NULL.

Definition at line 55 of file network_prov_mgr.h.

network_prov_endpoint_handler_t

typedef int(* network_prov_endpoint_handler_t) (void *user_ctx, const uint8_t *inbuf, size_t inlen, uint8_t **outbuf, size_t *outlen)

Handler for an application-defined custom endpoint.

Receives the (decrypted) request and returns a response allocated with k_malloc() in outbuf / outlen (freed by the caller). Same contract as the built-in handlers.

Returns

0 on success, negative errno on failure.

Definition at line 124 of file network_prov_mgr.h.

Enumeration Type Documentation

network_prov_cb_event

enum network_prov_cb_event

Events emitted by the manager over the application event handler.

Enumerator
NETWORK_PROV_INIT	Manager initialised.
NETWORK_PROV_START	Provisioning started, transport advertising.
NETWORK_PROV_CRED_RECV	Wi-Fi credentials received from the app.
NETWORK_PROV_CRED_FAIL	Failed to connect with the received credentials.
NETWORK_PROV_CRED_SUCCESS	Connected successfully with the credentials.
NETWORK_PROV_END	Provisioning stopped.
NETWORK_PROV_DEINIT	Manager de-initialised.

Definition at line 31 of file network_prov_mgr.h.

network_prov_cred_fail_reason

enum network_prov_cred_fail_reason

Reason reported alongside NETWORK_PROV_CRED_FAIL.

Enumerator
NETWORK_PROV_WIFI_AUTH_ERROR	Authentication failed (bad passphrase).
NETWORK_PROV_WIFI_NETWORK_NOT_FOUND	Requested SSID not found.

Definition at line 42 of file network_prov_mgr.h.

network_prov_security

enum network_prov_security

Security scheme used for the protocomm session.

Enumerator
NETWORK_PROV_SECURITY_0	No security: payloads exchanged in plaintext (bring-up/testing only).
NETWORK_PROV_SECURITY_1	Curve25519 key exchange + AES-256-CTR + optional proof-of-possession.

Definition at line 23 of file network_prov_mgr.h.

Function Documentation

network_prov_mgr_configure_wifi_sta()

int network_prov_mgr_configure_wifi_sta	(	const char *	ssid,
		const char *	psk
	)

Apply Wi-Fi credentials programmatically, as if received from a client.

Runs the same staging/apply/connect/retry path (persists the credentials, emits NETWORK_PROV_CRED_RECV, then success/failure). Useful for headless provisioning. Mirrors ESP-IDF's network_prov_mgr_configure_wifi_sta().

Parameters

ssid	Network SSID (NUL-terminated, required).
psk	Passphrase (NUL-terminated), or NULL/empty for an open network.

Returns

0 on success, -EPERM if provisioning is not active, -EINVAL on bad args, or another negative errno from the apply path.

network_prov_mgr_deinit()

void network_prov_mgr_deinit

(

void

)

Tear down the manager and free its resources.

network_prov_mgr_disable_auto_stop()

int network_prov_mgr_disable_auto_stop

(

uint32_t

cleanup_delay_ms

)

Disable the automatic teardown of the provisioning service after a successful connection.

By default the manager auto-stops itself once credentials succeed, after a grace window (CONFIG_NETWORK_PROV_AUTOSTOP_TIMEOUT_MS) that lets the app read the final status. Call this (before success) to take over teardown timing; the app must then call network_prov_mgr_stop_provisioning itself. Mirrors ESP-IDF's network_prov_mgr_disable_auto_stop().

Parameters

cleanup_delay_ms

Delay applied by stop_provisioning() before the transport is torn down, so the final response can flush to the client (0 = immediate).

Returns

0 on success, -EPERM if the manager is not initialised.

network_prov_mgr_endpoint_create()

int network_prov_mgr_endpoint_create

(

const char *

ep_name

)

Create an application-specific protocomm endpoint.

Must be called after network_prov_mgr_init and before network_prov_mgr_start_provisioning so the endpoint gets a BLE characteristic / HTTP route when the transport service is built. Register its handler after provisioning starts with network_prov_mgr_endpoint_register. Mirrors ESP-IDF's network_prov_mgr_endpoint_create().

Parameters

ep_name

Endpoint name (also the BLE CUD / HTTP URI); must be unique, not a built-in name, and shorter than 16 bytes.

Returns

0 on success, -EINVAL on a bad name, -EPERM if not initialised or already started, -EALREADY on a duplicate/built-in name, -ENOSPC if the custom-endpoint table is full (CONFIG_NETWORK_PROV_MAX_CUSTOM_ENDPOINTS).

network_prov_mgr_endpoint_register()

int network_prov_mgr_endpoint_register	(	const char *	ep_name,
		network_prov_endpoint_handler_t	handler,
		void *	user_ctx
	)

Attach a handler to a created custom endpoint.

Call after provisioning has started (e.g. from the NETWORK_PROV_START event). Mirrors ESP-IDF's network_prov_mgr_endpoint_register().

Returns

0 on success, -EINVAL on bad args, -EPERM if not started, -ENOENT if the endpoint was not created.

network_prov_mgr_endpoint_unregister()

int network_prov_mgr_endpoint_unregister

(

const char *

ep_name

)

Detach a custom endpoint's handler; subsequent requests report unsupported until it is registered again.

Mirrors network_prov_mgr_endpoint_unregister().

Returns

0 on success, -EINVAL on a NULL name, -ENOENT if not created.

network_prov_mgr_get_wifi_remaining_conn_attempts()

int network_prov_mgr_get_wifi_remaining_conn_attempts

(

uint32_t *

attempts_remaining

)

Number of Wi-Fi connection attempts left for the credentials currently being tried (wifi_conn_attempts minus completed attempts).

Mirrors ESP-IDF's network_prov_mgr_get_wifi_remaining_conn_attempts().

Parameters

attempts_remaining

Set to the remaining attempt count.

Returns

0 on success, -EINVAL on NULL or if the manager is not active.

network_prov_mgr_init()

int network_prov_mgr_init

(

struct network_prov_mgr_config

config

)

Initialise the provisioning manager.

Loads the settings subsystem and the Wi-Fi credentials store, but does not start advertising. Call exactly once before any other manager API.

Returns

0 on success, negative errno otherwise.

network_prov_mgr_is_provisioned()

int network_prov_mgr_is_provisioned

(

bool *

provisioned

)

Report whether the device already has stored Wi-Fi credentials.

Parameters

provisioned

Set to true if at least one credential is stored.

Returns

0 on success, negative errno otherwise.

network_prov_mgr_is_sm_idle()

bool network_prov_mgr_is_sm_idle

(

void

)

True when no provisioning session is active (state machine idle).

network_prov_mgr_reset_wifi_provisioning()

int network_prov_mgr_reset_wifi_provisioning

(

void

)

Erase all stored Wi-Fi credentials; the device reverts to unprovisioned.

Mirrors ESP-IDF's network_prov_mgr_reset_wifi_provisioning(). Credentials are never erased automatically on connection failures — this is meant for explicit application actions such as a factory-reset button.

Returns

0 on success, negative errno otherwise.

network_prov_mgr_reset_wifi_sm_state_for_reprovision()

int network_prov_mgr_reset_wifi_sm_state_for_reprovision

(

void

)

Reset the Wi-Fi provisioning state machine to accept a new network while the service is still running (re-provision).

Mirrors ESP-IDF's network_prov_mgr_reset_wifi_sm_state_for_reprovision().

Returns

0 on success, -EPERM if provisioning is not active.

network_prov_mgr_reset_wifi_sm_state_on_failure()

int network_prov_mgr_reset_wifi_sm_state_on_failure

(

void

)

Reset the Wi-Fi provisioning state machine after a failed attempt so the app can supply fresh credentials without restarting the service.

Mirrors ESP-IDF's network_prov_mgr_reset_wifi_sm_state_on_failure().

Returns

0 on success, -EPERM if provisioning is not active.

network_prov_mgr_set_app_info()

int network_prov_mgr_set_app_info	(	const char *	label,
		const char *	version,
		const char *const *	capabilities,
		size_t	capabilities_count
	)

Advertise an application-specific section in the proto-ver capabilities JSON.

Adds a sibling object to the built-in "prov" object, keyed by label: "<label>":{"ver":"<version>","cap":[...]}. Apps use it to negotiate their own version and feature flags with the provisioning client. Mirrors ESP-IDF's network_prov_mgr_set_app_info(). Must be called after network_prov_mgr_init and before network_prov_mgr_start_provisioning (the JSON is rendered at start). Tokens must be JSON-safe.

Parameters

label	Object key (e.g. the application name).
version	Version string for the app section.
capabilities	Array of capability strings (may be NULL if count 0).
capabilities_count	Number of entries in capabilities.

Returns

0 on success, -EINVAL on bad args, -EPERM if already started, -ENOMEM if the rendered section does not fit.

network_prov_mgr_start_provisioning()

int network_prov_mgr_start_provisioning	(	enum network_prov_security	security,
		const char *	pop,
		const char *	service_name,
		const char *	service_key
	)

Start the provisioning service on the configured transport: BLE (register the GATT service and advertise) or SoftAP (bring up the access point, the DHCPv4 server and the HTTP endpoints).

Parameters

security	Security scheme to advertise and enforce.
pop	Proof-of-possession string for NETWORK_PROV_SECURITY_1, or NULL to disable PoP (advertises the "no_pop" cap). Ignored for NETWORK_PROV_SECURITY_0.
service_name	BLE device name or SoftAP SSID (e.g. "PROV_1234").
service_key	SoftAP password (8..64 characters for WPA2-PSK, or NULL/empty for an open AP). Ignored for BLE — pass NULL. Mirrors ESP-IDF's 4-argument signature.

Returns

0 on success, negative errno otherwise.

network_prov_mgr_stop_provisioning()

void network_prov_mgr_stop_provisioning

(

void

)

Stop advertising and tear down the transport (keeps the manager init'd).

network_prov_mgr_wait()

void network_prov_mgr_wait

(

void

)

Block until provisioning completes (NETWORK_PROV_CRED_SUCCESS).