Provisioning

The Provisioning component provides WiFi provisioning via a web interface hosted on a temporary access point. Users can scan for networks, select or manually enter credentials, test the connection, and save multiple network configurations for easy switching.

Provisioning Example

API Reference

Header File

components/provisioning/include/provisioning.hpp

Classes

class Provisioning : public espp::BaseComponent 

WiFi Provisioning Component.

Provides a web-based WiFi provisioning interface. Creates a WiFi access point with an embedded web server that allows users to scan for and connect to WiFi networks.

Features:

Automatic AP creation with customizable SSID/password
HTML web interface for WiFi scanning and configuration
Network scanning and signal strength display
Credential validation before saving
Callback notification on successful provisioning
Automatic AP shutdown after provisioning (optional)

Provisioning Example

  espp::Logger logger({.tag = "Provisioning Example", .level = espp::Logger::Verbosity::INFO});

  logger.info("Starting WiFi Provisioning Example");

  // Initialize NVS (required for WiFi)
  logger.info("Initializing NVS...");
  std::error_code ec;
  espp::Nvs nvs;
  nvs.init(ec);
  if (ec) {
    logger.error("Failed to initialize NVS: {}", ec.message());
    return;
  }

  // Create provisioning configuration
  espp::Provisioning::Config config{
      .ap_ssid = "ESP-Prov",
      .append_mac_to_ssid = true, // Will append MAC to make unique
      .ap_password = "",          // Open network for simplicity
      .device_name = "Provisioning Example",
      .server_port = 80,
      .auto_shutdown_ap = false, // Keep AP running for this example
      .on_provisioned =
          [&logger](const std::string &ssid, const std::string &password) {
            logger.info("Provisioned successfully!");
            logger.info("  SSID: {}", ssid);
            logger.info("  Password: {}", password.empty() ? "(none)" : "********");

            // Save credentials to NVS
            std::error_code ec;
            espp::NvsHandle handle("wifi_config", ec);
            if (!ec) {
              handle.set("ssid", ssid, ec);
              handle.set("password", password, ec);
              if (!ec) {
                logger.info("Credentials saved to NVS");
              } else {
                logger.error("Failed to save credentials: {}", ec.message());
              }
            }
          },
      .log_level = espp::Logger::Verbosity::INFO};

  // Create provisioning
  espp::Provisioning provisioning(config);

  // print any existing network ssids that have been provisioned
  {
    espp::NvsHandle handle("wifi_config", ec);
    if (!ec) {
      std::string saved_ssid;
      handle.get("ssid", saved_ssid, ec);
      if (!ec) {
        logger.info("Existing provisioned network SSID: {}", saved_ssid);
      } else {
        logger.info("No existing provisioned network found in NVS");
      }
    }
  }

  // Start provisioning
  if (!provisioning.start()) {
    logger.error("Failed to start provisioning");
    return;
  }

  logger.info("Provisioning started");
  logger.info("Connect to WiFi network: {}", provisioning.get_ap_ssid());
  logger.info("Open browser to: http://192.168.4.1");

  // Keep running until user completes provisioning
  while (!provisioning.is_completed()) {
    std::this_thread::sleep_for(1s);
  }

  logger.info("Provisioning completed by user, stopping service");
  provisioning.stop();

  logger.info("Provisioning example finished");

Public Types

typedef std::function<void(const std::string &ssid, const std::string &password)> provisioned_callback

Callback when provisioning completes successfully.

Param ssid:: The SSID that was provisioned
Param password:: The password that was configured

Public Functions

explicit Provisioning(const Config &config)

Construct provisioning component.

Parameters:: config – Configuration structure

~Provisioning(): Destructor - stops server and AP.

bool start()

Start the provisioning process.

Returns:: true if started successfully

void stop(): Stop the provisioning process.

inline bool is_active() const

Check if provisioning is active.

Returns:: true if the AP and server are running

inline bool is_provisioned() const

Check if device has been provisioned.

Returns:: true if provisioning callback has been called

inline bool is_completed() const

Check if user has completed provisioning.

Returns:: true if user clicked “Complete Setup” button

std::string get_ip_address() const

Get the IP address of the provisioning AP.

Returns:: IP address string (e.g., “192.168.4.1”)

inline const std::string &get_ap_ssid() const

Get the actual AP SSID (after MAC appending)

Returns:: The SSID of the provisioning AP

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns:: A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters:: tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns:: The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters:: level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters:: level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns:: The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters:: rate_limit – The rate limit to use for the logger

struct Config

Configuration for the provisioning component.

Public Members

std::string ap_ssid = {"ESP-Prov"}: Base SSID for the provisioning AP.

bool append_mac_to_ssid = {true}: Append MAC address to AP SSID.

std::string ap_password = {""}: Password for AP (empty = open)

std::string device_name = {"ESP32 Device"}: Device name shown in UI.

uint16_t server_port = {80}: HTTP server port.

bool auto_shutdown_ap = {true}: Shutdown AP after provisioning.

provisioned_callback on_provisioned = {nullptr}: Called on successful provisioning.

Logger::Verbosity log_level = {Logger::Verbosity::WARN}: Log verbosity.