Documentation home · All topics · Source

ArdPortal is a standalone Arduino library. Its complete distribution contains library.properties, src, examples, media, this README and the MIT license. The external ArdUI.ino demo is not part of the library.

Install ArdPortal through the Arduino Library Manager when the release is available there, or download a release ZIP and use Sketch → Include Library → Add .ZIP Library. A manual installation places ArdPortal in the sketchbook's libraries directory. Avoid duplicate installed copies; Arduino's compilation output identifies the actual library path. For your first connection, open File → Examples → ArdPortal → BasicPortal (examples/BasicPortal/BasicPortal.ino), then select the board, physical flash size and partition layout with space for ArdFS and OTA.

#include <ArdPortal.h>

ArdPortal portal;

void setup() {
  Serial.begin(115200);
  if (!portal.begin()) Serial.println("Invalid portal options");
}

void loop() {
  portal.loop();
  // Keep doing application work; do not wait for network or storage completion.
}

On a new board, ArdFS is mounted and automatically formatted if mounting fails. With no saved Wi-Fi credentials, the device starts an AP named ArdUI-<chip ID> with password 1234567890. Connect to it and open http://192.168.4.1/. Operating systems supporting captive portal detection may open a configuration window automatically.

begin() starts initialization and returns immediately after validating options; storage initialization and configuration loading continue through loop(). Use portalAndAppConfigReady() or onPortalAndAppConfigReady before accessing saved settings. Call loop() frequently. Methods and callbacks run in the Arduino task: do not call loop() recursively or access the portal concurrently from other tasks.

Examples are in examples:

The main the external ArdUI.ino demo additionally demonstrates MQTT subscriptions to device commands/queries, publishing status and reacting to portal changes.

Progress and successful actions appear in green notification boxes. Failed requests and connection attempts appear in red. Empty notifications are hidden; the scan progress notification disappears after scanning completes. The Wi-Fi connection progress notification disappears when the requested connection obtains an IP address. Submitting unchanged Wi-Fi credentials starts a fresh attempt.

examples/DHT/DHT.ino uses Adafruit's DHT library and Unified Sensor dependency, with a DHT22 on GPIO2, OTA, MQTT, HA and Console enabled. TLS, dependencies and unused controls are excluded; slider, text and select are enabled. Use a pull-up from DATA to 3.3 V and ensure GPIO2 is high during ESP8266 boot.

Home shows temperature and humidity; Settings contains C/F units, two calibration offsets and a persisted MQTT rate selector: on displayed-reading change, every 10 seconds, minute, 10 minutes or hour. Corrected values use one decimal place. Changing calibration or C/F units immediately recalculates the last sensor sample and queues updated temperature/humidity for MQTT, bypassing the normal publishing interval. It does not trigger an extra DHT transaction. Temperature calibration is applied in Celsius before display conversion; humidity is clamped to 0–100%. HA's temperature template converts the selected unit back to Celsius. Live readings use RAM-only setters and their own MQTT schedule; settings use ArdFS. Reconnect/get snapshots and HA discovery remain independent of that schedule.

Samples are scheduled every two seconds, starting two seconds after configuration readiness, and skipped during OTA. The DHT transaction itself is synchronous. Three failed readings reinitialize the sensor with a two-second retry delay; Serial diagnostics distinguish sensor failures from rejected portal values. On-change mode publishes when the rounded displayed value changes, so changes smaller than the displayed resolution do not necessarily send another packet.

Back to documentation home