Documentation home · All topics · Source

• Integrated configuration API
• Options and remaining blocking operations
• Registration status accessors
• Callback distinction

Names explicitly identify the domain: PortalConfig covers Wi-Fi, MQTT and device settings; AppConfig covers custom JSON values, dynamic pages, commands, state and events. PortalAndAppConfig denotes shared loading/storage operations: both domains are persisted in one document.

The portal owns storage initialization, configuration loading and saving. Application code uses the methods and notification callbacks below.

portal.onPortalAndAppConfigReady([](bool restored) {
  // Called once after initialization, including a missing file/storage failure.
  // restored means a valid saved configuration was loaded.
  ArdJSON::JSONVar value = portal.getAppConfigValue("reportInterval");
  if (!value.isUndefined()) {
    int64_t interval;
    if (value.toInteger(interval)) {
      // Validate the application-specific range before using it.
    }
  }
});

portal.onPortalConfigChanged([](const ArdPortal::PortalConfig& config,
                         ArdPortal::ChangeSource source) {
  // Called only when PortalConfig changes; AppConfig-only writes do not trigger it.
  // source: Application, Portal, Mqtt or FactoryReset.
});

portal.onPortalAndAppConfigSaved([](bool ok, const String& error) {
  // Write/readback completed, or an identical document was skipped.
  // If ok is false, the pending update was rejected; application code may retry.
});

onPortalConfigChanged and onAppConfigValueChanged each use one callback for all change sources. Filter source == ArdPortal::ChangeSource::Portal to handle only web portal changes. For persisted settings, notifications follow successful saving and application; unchanged values and failed writes do not trigger change callbacks. AppConfig RAM-only state updates and MQTT commands also notify when applied in RAM. Use onPortalAndAppConfigSaved for the storage result, including unchanged or failed writes.

Setters accept changes into RAM; true does not mean flash has already been written. onPortalAndAppConfigSaved reports completion. Once configuration is ready:

portal.setAppConfigValue("reportInterval", 5000);
portal.setAppConfigValue("enabled", true);
portal.removeAppConfigValue("obsoleteKey");

ArdPortal::PortalConfig changed = portal.getPortalConfig();
changed.deviceName = "My-Device";
portal.setPortalConfig(changed);

// Optional: bypass debounce/minimum interval; writing still happens in loop().
portal.flushPortalAndAppConfig();

Missing unregistered application keys return JSON Undefined; registered fields return their declared or type-specific default. Successive accepted application updates merge into the pending document. Setters can return false while a write, OTA, MQTT trial or another settings transaction is running; retry later. Callbacks may read settings or queue another update when the API accepts it. Change callbacks are not invoked for unchanged settings or failed writes. onPortalAndAppConfigSaved may precede applying a network change; change callbacks run after application. Register dynamic page definitions to expose selected app keys in portal forms and Home Assistant.

The configuration payload contains config and app objects. The complete payload is limited to 13376 bytes, serialized PortalConfig to 5120 bytes and serialized AppConfig to 8192 bytes and a CA certificate to 4096 bytes. Available RAM, particularly with TLS on ESP8266, can impose lower practical limits. ConfigJson.h validates the portal schema, and ArdJSON.h handles JSON parsing/serialization.

ArdPortal::PortalConfig is the complete network/device configuration. Application keys belong to the separate app object, not to this struct. Length limits below are bytes, not Unicode characters. All strings reject embedded NUL bytes.

Copy getPortalConfig(), edit the copy, then call setPortalConfig(). A change made through this API is validated and scheduled for storage; it does not run the connect-before-save trial used by the Wi-Fi/MQTT portal forms. Network changes may disconnect current clients. Device-name changes update AP/hostname/MQTT identity; do not rely on the old MQTT topics afterward.

setPortalConfigDeviceManufacturer(value) and setPortalConfigDeviceDescription(value) are dedicated persistent setters. They preserve an already pending application update and queue an ArdFS save automatically. Neither requires HA to be enabled; only their HA discovery metadata is conditional on ARDPORTAL_ENABLE_HA. Empty strings hide their Info rows. There is no dedicated setDeviceName() method: use setPortalConfig() for that change. getPortalConfig() returns the currently applied configuration, not a general mutable reference to pending edits.

// Register before begin(); apply device metadata after configuration readiness.
portal.onPortalAndAppConfigReady([](bool restored) {
  if (!restored) {
    if (!portal.setPortalConfigDeviceManufacturer("My company"))
      Serial.println("Manufacturer update rejected.");
    if (!portal.setPortalConfigDeviceDescription("Living room sensor"))
      Serial.println("Description update rejected.");
  }
});
portal.onPortalAndAppConfigSaved([](bool ok, const String& error) {
  if (!ok) Serial.println(error);
});

A ready callback with restored == false also covers storage failure, so setters can still return false. For required updates, retain the requested value and retry from a later loop() iteration when ready/not busy; do not wait in a loop. Avoid rebuilding a Config from an old snapshot for each successive edit: that can overwrite other pending portal settings. The two metadata setters explicitly merge into the pending PortalConfig.

All methods below belong to ArdPortal. Each callback registration replaces the previous callback of the same kind. Reference arguments in callbacks are valid only during the callback; copy values you need afterward. Keep callbacks short.

ChangeSource values are Application, Portal, Mqtt and FactoryReset. WifiState values are NoCredentials, Connecting, Connected and FallbackAP. MqttState values are Disabled, WaitingForWifi, WaitingRetry, Connecting, Connected and WaitingForTime. These enum values are runtime states, not error codes or elapsed-time promises.

startAppConfigPageRegistration() uses the same public lifecycle for all page sizes. true means the job was accepted; state is Pending, and the page is not yet registered. Validation success/failure is always delivered exactly once through onAppConfigPageRegistrationFinished(bool) from portal.loop(), after the start method returns. false means immediate rejection (input/busy/features/resources); no completion callback is issued for a job that was not accepted.

Definitions up to 2048 bytes with at most 8 fields are completely validated and registered in one loop pass. Larger definitions/field counts use the cooperative work budget across passes. Both modes use the same schema, limits, diagnostics, atomic commit and callback contract. Install the callback before registering, call portal.begin() and keep calling portal.loop() to advance pending jobs.

portal.onAppConfigPageRegistrationFinished([](bool success) {
  if (success) {
    // The page and its fields are now registered. Restore application hardware
    // only once portalAndAppConfigReady() is also true.
    Serial.println("Page registered");
  } else {
    const auto& error = portal.appConfigRegistrationError();
    Serial.printf("%s: %s: %s\n", error.stage, error.fieldId.c_str(),
                  error.reason.c_str());
  }
  // This callback may queue the next page with startAppConfigPageRegistration().
});
if (!portal.startAppConfigPageRegistration(FPSTR(PAGE_DEFINITION))) {
  Serial.println(portal.appConfigRegistrationError().reason);
}
portal.begin();

appConfigPageRegistrationState() returns Idle, Pending, Succeeded or Failed from ArdPortal::AppConfigPageRegistrationState. appConfigPageRegistrationBusy() reports a pending job. appConfigPageRegistrationProcessedFields() and appConfigPageRegistrationTotalFields() report index-building progress; the total becomes available after the initial scan. Discovery is checked while building the index; dependency and command-collision checks can remain after the field count reaches its total.

Only one page registration can be pending. Queue each next page from the completion callback. A failed registration does not publish a partially registered page. Wait for both registration completion and portalAndAppConfigReady() before applying saved values to hardware. Keep PROGMEM definitions immutable and alive for the portal lifetime.

startAppConfigPageRegistration() returns false only when the job cannot be accepted. Inspect the error after a rejected call and inside onAppConfigPageRegistrationFinished(false) for later validation, memory or Discovery failures:

auto reportError = []() {
  const auto& error = portal.appConfigRegistrationError();
  Serial.printf("Registration: stage=%s field=%s reason=%s\n",
                error.stage, error.fieldId.c_str(), error.reason.c_str());
};
portal.onAppConfigPageRegistrationFinished([reportError](bool success) {
  if (!success) reportError();
});
if (!portal.startAppConfigPageRegistration(FPSTR(PAGE_DEFINITION))) reportError();

The result contains stage, fieldId and reason. Stages distinguish input, JSON parsing, page/field validation, descriptor normalization, limits, registry allocation, serialization, field indexing, command collisions and HA Discovery. Parser errors include the byte offset and distinguish memory exhaustion from input/node/depth/string/container limits. Discovery overflow reports payload size and MQTT capacity. fieldId is empty when no field can be identified, for example a JSON parse error or page allocation failure. A successful page registration clears the previous error; copy the result if retaining it across another registration. The getter works even with Console diagnostics disabled. Failures are also sent to Console > Messages when ARDPORTAL_ENABLE_CONSOLE_MESSAGES is enabled. Rejected pages are rolled back and do not restart Discovery.

Use addAppConfigEntity() for telemetry or controls that belong in Home Assistant but do not need a dynamic page. Pass a single field object, not a page containing fields. All supported controls use the same validation, MQTT topic namespace, callbacks, state setters and persistence rules as panel fields. Entity IDs must be unique across the entire application. HA-only entities have their own source registry, consume no slots from the 16 panel pages, and do not appear in /api/pages or the portal menu. Their current values remain available through getAppConfigValue() and the complete /api/app values endpoint. The 1024-field and configurable source budgets cover both registries together. ARDPORTAL_ENABLE_HA and ARDPORTAL_ENABLE_DYNAMIC_PAGES must be enabled.

const char TEMPERATURE_ENTITY[] PROGMEM = R"JSON({
  "id":"air_temperature", "name":"Air temperature", "type":"text",
  "default":0, "unit_of_measurement":"°C", "device_class":"temperature",
  "state_class":"measurement"
})JSON";

// During setup; check registration failures.
if (!portal.addAppConfigEntity(FPSTR(TEMPERATURE_ENTITY)))
  Serial.println("Invalid HA entity");

// After portalAndAppConfigReady(), report sensor readings in RAM.
portal.setAppConfigStateValue("air_temperature", 22.5);

For writable entities, register onAppConfigValueChanged() or onAppConfigCommand() exactly as for panel controls. Reporting a sensor value with setAppConfigStateValue() does not write flash. See examples/HomeAssistantEntities/HomeAssistantEntities.ino for an HA sensor and switch with no dynamic panel pages.

ArdPortal::Options options;
options.haWorkBudgetMs = 2;
options.haMaxOperationsPerLoop = 1;
portal.begin(options);

haWorkBudgetMs limits how long HA may start additional work during a loop() call; haMaxOperationsPerLoop limits the number of operations. Both must be nonzero. Keep the defaults unless measurements show that your application needs a different balance between HA updates, HTTP and UART responsiveness.

The time budget is cooperative: parsing/normalizing one field, serializing a payload or a core transport call cannot be interrupted and may exceed it. Application callbacks and MQTT connection/TLS handshakes have their own timing; this budget is not a hard deadline for the entire portal loop.

Adding a page does not restart discovery of already registered entities. Broker reconnects and Home Assistant's online birth message request rediscovery; periodic discovery is disabled by default. PROGMEM definitions must remain immutable and available for the portal lifetime.

For registered scalar fields, setAppConfigValue() honors persist:false. Use setAppConfigStateValue() for explicitly RAM-only readings regardless of persistence policy. A RAM override has priority when reading/rendering/publishing a field. Do not mix a live override with persistent setters for the same key unless you intend that priority; use separate telemetry and configuration field IDs. Removing a persisted key does not remove a live override. There is no public method to remove just one RAM override; reboot clears RAM-only state.

// Register a text field with id "temperature" before using these calls.
// Invoke after portalAndAppConfigReady(), from the normal Arduino task.
if (!portal.setAppConfigStateValue("temperature", 22.5, false))
  Serial.println("Invalid or unavailable temperature field.");
// Later, on your own timer; this just marks the field for cooperative sending.
if (!portal.queueAppConfigStatePublish("temperature"))
  Serial.println("MQTT state publication is unavailable.");

For a climate-style object, read the current value, change only reported properties such as current_temperature or action, and pass the complete object back to setAppConfigStateValue(). Preserve required keys and valid modes. The library renders and publishes state; application code controls the physical actuator.

Every ArdPortal::Options member is listed here. Pass the object to begin(options); there is no runtime Options setter. Saved Config values take precedence over device/AP defaults. Time values are milliseconds unless the member explicitly ends in Seconds.

The design is cooperative, not hard real-time. It has no delay(), readString() or connection-wait loops, but the following core operations can still block:

Plain HTTP/MQTT writes on ESP32 use send(MSG_DONTWAIT) to avoid the core write retry loop. ESP8266 checks availableForWrite, uses bounded chunks and aborts interrupted clients; finishing a response uses bounded flush(1) / stop(1). These precautions do not guarantee zero interruption of the processor during flash programming or TLS.

Wi-Fi equipped ESP8266/ESP32 Arduino boards are supported; chips without a Wi-Fi radio, such as ESP32-H2/P4 without an external module, cannot provide this portal. The portal/OTA have no authentication and settings contain plaintext credentials; use a trusted AP/LAN. Verified MQTT TLS does not add HTTP authentication.

The rvalue overload startAppConfigPageRegistration(String&&) transfers the source buffer on acceptance. The const String& overload copies it. The const __FlashStringHelper* overload borrows an immutable flash source for the portal lifetime. All page sizes report completion through the same callback.

Register this callback before a reset can be requested:

portal.onBeforeFactoryReset([]() {
  // Reset application-owned hardware state or mark external data for cleanup.
  // Keep this synchronous handler short; do not wait for portal.loop() here.
});

The handler completes before ArdPortal schedules default PortalConfig and an empty AppConfig for storage. It runs once per eligible, confirmed factory-reset request, even if the values are already default. Rejected requests (missing confirmation, initialization or another operation in progress) do not invoke it. It reports reset intent, not successful persistence: a later storage error can still prevent the reset. Existing configuration-change callbacks keep their change-only behavior. Ordinary/OTA restarts and storage formatting do not invoke this handler, and factory reset still skips onBeforeRestart. Use portal.onBeforeFactoryReset(nullptr) to remove the handler.

• onPortalConfigChanged: changed network/device settings have been applied.
• onAppConfigValueChanged: one effective application value changed; this may be an immediate live update and does not prove flash completion.
• onPortalAndAppConfigSaved: the storage transaction finished or an identical document was skipped; check ok and error.
• onPortalAndAppConfigReady: startup restoration finished; restored=false includes defaults and storage failure, not just a first boot.
• onAppConfigCommand: accept/reject an explicit action; report physical results separately with a state setter.
• onAppConfigPageRegistrationFinished: an accepted registration finished once; immediately rejected jobs do not invoke it.
• onBeforeFactoryReset: a confirmed reset is about to replace configuration, independently of whether current values differ from defaults.
• onBeforeRestart: runs once for manual/OTA restart after prior saves finish; factory reset and formatting skip it. A save failure does not cancel restart.

Register callbacks before the operation they observe. Registrations replace the previous handler of that kind, and callback references are borrowed only for the invocation. Do not retain a pointer to incoming MQTT bytes.

Back to documentation home