Skip to content

EspFace ​

Generated

This page is generated by docs/site/scripts/gen-api.mjs from firmware/src/Face.h; descriptions and examples live in docs/site/scripts/api-notes.json.

EspFace face; is the facade a sketch talks to: lifecycle, identity, security, transports, system features and value updates. Builder calls go through face.ui() (see Ui). Every setter returns EspFace& so calls chain.

Lifecycle ​

Call begin() once in setup() after the identity setters; then either pump loop() yourself or start the networking task.

EspFace ​

cpp
EspFace()

Constructs the facade; nothing starts until begin().

cpp
EspFace face;

begin ​

cpp
void begin(const char* name)

Starts the library: device id from the MAC, NVS namespace espface for its own settings, mDNS/AP name derived from name, restores persisted values, starts the enabled transports. Call once in setup().

ArgumentTypeDefaultMeaning
nameconst char*–display name shown by the clients and used for the mDNS host and the AP SSID
cpp
void setup() {
  face.begin("Boiler");
  face.wifi().autoConnect();
}

loop ​

cpp
void loop()

Pumps transports, sessions, the 100 ms value flush, dialogs, OTA and NTP. Call from loop() unless beginTask() runs it on its own FreeRTOS task.

cpp
void loop() {
  face.loop();
  face.set("temp", readTemp());
}

beginTask ​

cpp
void beginTask(uint32_t stack = 8192, uint8_t prio = 1, int core = -1)

Runs loop() on a dedicated FreeRTOS task so the sketch's loop() may block.

ArgumentTypeDefaultMeaning
stackuint32_t8192task stack in bytes
priouint8_t1task priority
coreint-1CPU core, -1 = any
cpp
face.beginTask();          // defaults: 8 KB stack, priority 1, any core
face.beginTask(12288, 2, 1);

delay ​

cpp
void delay(uint32_t ms)

Like delay(ms) but keeps calling loop() so clients stay served while the sketch waits.

cpp
face.delay(500);

Identity ​

setProject ​

cpp
EspFace& setProject(const char* p)

Project/group name shown in the device list of the clients (proj in hello and mDNS TXT).

cpp
face.setProject("Home");

setIcon ​

cpp
EspFace& setIcon(const char* i)

Icon name from the shared set for the device list.

cpp
face.setIcon("thermostat");

setVersion ​

cpp
EspFace& setVersion(const char* v)

Firmware version string (fw in hello and info; compared with GitHub releases when setRepo is set).

cpp
face.setVersion("1.2.0");

setRepo ​

cpp
EspFace& setRepo(const char* r)

GitHub owner/repo; lets clients offer a user-triggered release check and ota.url install.

cpp
face.setRepo("manzari/espFace");

setAbout ​

cpp
EspFace& setAbout(const char* a)

Free text shown on the info page.

cpp
face.setAbout("Boiler controller, rev B");

id ​

cpp
const char* id() const

Device id (6 to 12 lowercase hex from the MAC).

cpp
Serial.println(face.id());

Security ​

setPin ​

cpp
EspFace& setPin(const char* pin, bool force = false)

Enables PIN pairing (HMAC-SHA256 challenge-response, cap pin). The PIN is stored in NVS; a client can change it later with sys pin.set, which wins over the sketch value unless force is true. nullptr or an empty string disables the PIN.

ArgumentTypeDefaultMeaning
pinconst char*–4 to 32 characters, or nullptr
forceboolfalseoverwrite a PIN a client set at runtime
cpp
face.setPin("1234");
face.setPin(nullptr);          // open device
face.setPin("4321", true);     // reset a client-changed PIN

Transports ​

The WebSocket server is on by default; the other transports are added by one call each and share the session logic (PIN, tokens, ESPFACE_MAX_CLIENTS).

setPort ​

cpp
EspFace& setPort(uint16_t port)

HTTP/WebSocket port (default 80; falls back to 8080 when the bind fails and logs it). Call before begin().

cpp
face.setPort(8080);

enableWs ​

cpp
EspFace& enableWs(bool on)

false before begin() skips the http/WebSocket server entirely (BLE-only or serial-only devices).

cpp
face.enableWs(false);

wifi ​

cpp
WifiMgr& wifi()

The WiFi manager: autoConnect(), connect(ssid, pass), startAp(), setApPassword(), connected(), ip().

cpp
face.wifi().autoConnect();          // stored credentials, else captive AP espFace-<id>
face.wifi().setApPassword("setup123");

ws ​

cpp
WsTransport& ws()

The WebSocket/http transport object (port, renderer host, running()).

cpp
if (face.ws().running()) { /* ... */ }

serial ​

cpp
StreamTransport& serial(Stream& s, const char* name = "serial")

Adds any Arduino Stream (UART, USB CDC, BluetoothSerial) as a one-client line transport. Returns the transport for setIdleTimeout(ms) / use(ui).

ArgumentTypeDefaultMeaning
sStream&–
nameconst char*"serial"
cpp
face.serial(Serial);
face.serial(Serial1, "uart").setIdleTimeout(30000);

ble ​

cpp
BleTransport& ble()

Enables the NimBLE transport (build with -DESPFACE_BLE); returns it for setName() / use(ui).

cpp
#define ESPFACE_BLE
face.ble().setName("Boiler");

btClassic ​

cpp
BtSerialTransport& btClassic(const char* name = nullptr)

Enables Bluetooth Classic SPP (build with -DESPFACE_BT_CLASSIC, classic ESP32 only, exclusive with BLE).

ArgumentTypeDefaultMeaning
nameconst char*nullptr
cpp
face.btClassic("Boiler");

System features ​

enableOta ​

cpp
EspFace& enableOta(bool on)

Adds caps ota and otaurl: OTA push over WebSocket binary frames, ota.url download and POST /update. The Update/HTTPClient/TLS code is only linked when a sketch calls this.

cpp
face.enableOta(true);

setOtaCaCert ​

cpp
EspFace& setOtaCaCert(const char* pem)

PEM CA certificate used to verify https for ota.url downloads and ntfy. Without it https is used unverified.

cpp
static const char CA_CERT[] PROGMEM = "-----BEGIN CERTIFICATE-----\n...";
face.setOtaCaCert(CA_CERT);

enableNtp ​

cpp
EspFace& enableNtp(bool on, const char* server = "pool.ntp.org", const char* tz = nullptr)

IDF SNTP client; the system time feeds face.time() and the clock widgets (cap ntp). tz is a POSIX TZ string or nullptr for UTC.

ArgumentTypeDefaultMeaning
onbool–start/stop SNTP
serverconst char*"pool.ntp.org"NTP server
tzconst char*nullptrPOSIX TZ string
cpp
face.enableNtp(true, "pool.ntp.org", "CET-1CEST,M3.5.0,M10.5.0/3");

ntfy ​

cpp
EspFace& ntfy(const char* server, const char* topic, const char* token = nullptr)

Configures direct ntfy notifications (cap ntfy); notify() then POSTs from the device on its own task. token is an optional bearer token.

ArgumentTypeDefaultMeaning
serverconst char*–
topicconst char*–
tokenconst char*nullptr
cpp
face.ntfy("https://ntfy.sh", "boiler-alerts");
face.ntfy("https://ntfy.example.com", "alerts", "tk_secret");

ntfyRateLimit ​

cpp
EspFace& ntfyRateLimit(uint32_t ms)

Minimum interval between notifications (default 10 000 ms); extra messages queue (4 slots) or are dropped.

cpp
face.ntfyRateLimit(60000);   // at most one per minute

notify ​

cpp
bool notify(const char* title, const char* msg, Ntfy prio = Ntfy::Default)

Queues a notification; returns false when ntfy is not configured or the queue is full.

ArgumentTypeDefaultMeaning
titleconst char*–
msgconst char*–
prioNtfyNtfy::Default
cpp
if (temp > 95) face.notify("Boiler", "Overheated", Ntfy::High);

Values and events ​

Shortcuts for the most common runtime calls of the default UI (face.ui()); they return false when the id is unknown or the value is invalid.

ui ​

cpp
Ui& ui()

The default UI builder (see Ui).

cpp
auto& ui = face.ui();
ui.gauge("temp", "Temperature", 0, 120, "°C");

addUi ​

cpp
Ui& addUi(const char* name)

Creates a second, independent UI that a transport can serve with transport.use(ui); e.g. an open setup UI on BLE next to the main UI on WiFi (Provisioning example).

cpp
auto& setupUi = face.addUi("setup");
setupUi.pin("");                    // no PIN for this UI
setupUi.header("WiFi setup");
face.ble().use(setupUi);

set ​

cpp
bool set(const char* id, bool v)
bool set(const char* id, float v)
bool set(const char* id, double v)
bool set(const char* id, int v)
bool set(const char* id, const char* v)
bool set(const char* id, const String& v)
bool set(const char* id, uint32_t v)
bool set(const char* id, int x, int y)

Updates a widget value and pushes it to the clients (coalesced into one upd every 100 ms). Overloads for bool, float/double, int, uint32_t (colors, flags), strings and the joystick pair.

cpp
face.set("temp", 21.5f);
face.set("pump", true);
face.set("mode", 2);
face.set("rgb", (uint32_t)0x00ff00);
face.set("name", "Boiler");
face.set("joy", 10, -10);

setRows ​

cpp
bool setRows(const char* id, const char* rowsJson)

Table rows as a raw JSON array of rows.

cpp
face.setRows("tbl", "[[\"Kitchen\",21.5],[\"Bath\",23]]");

setPoints ​

cpp
bool setPoints(const char* id, const char* pointsJson)

Map points as a raw JSON array of [lat, lon, label].

cpp
face.setPoints("pos", "[[52.52,13.405,\"Boiler\"]]");

push ​

cpp
void push(const char* chart, const char* series, float v)

Appends a chart point (timestamp: unix ms when the time is known, else uptime ms).

cpp
face.push("tchart", "temp", t);

log ​

cpp
void log(const char* msg, const char* color = nullptr)
void log(const char* logId, const char* msg, const char* color)

Sends a log line: without a widget id to the console view of the clients, with an id to that log widget (optionally colored).

ArgumentTypeDefaultMeaning
msgconst char*–
colorconst char*nullptr
cpp
face.log("boot ok");
face.log("term", "overheat", "#f00");

toast ​

cpp
void toast(const char* lvl, const char* msg)

Transient message on all clients; lvl is info, warn or err.

cpp
face.toast("warn", "Overheating");

Callbacks and time ​

clients ​

cpp
uint8_t clients() const

Number of authenticated clients.

cpp
if (face.clients() == 0) sleepSoon();

time ​

cpp
uint32_t time() const

Unix seconds from NTP, else from the last client time message, else 0.

cpp
uint32_t now = face.time();

setTime ​

cpp
void setTime(uint32_t unix)

Feeds an authoritative time (e.g. from an RTC).

cpp
face.setTime(rtc.now().unixtime());

onConnect ​

cpp
void onConnect(std::function<void(const ClientInfo&)> fn)

Called when a client finished the handshake (ClientInfo: slot, transport name, isWeb).

cpp
face.onConnect([](const ClientInfo& c) { Serial.printf("client on %s\n", c.transport); });

onDisconnect ​

cpp
void onDisconnect(std::function<void(const ClientInfo&)> fn)

Called when a client left.

cpp
face.onDisconnect([](const ClientInfo& c) { /* ... */ });

onReboot ​

cpp
void onReboot(std::function<void(RebootReason)> fn)

Called right before a client-, OTA- or sketch-triggered reboot (RebootReason::Client, Ota, Sketch).

cpp
face.onReboot([](RebootReason r) { saveState(); });

reboot ​

cpp
void reboot(uint32_t delayMs = 500)

Reboots after delayMs (clients are told first, onReboot runs).

ArgumentTypeDefaultMeaning
delayMsuint32_t500
cpp
face.reboot();

flushPersist ​

cpp
void flushPersist()

Writes persisted values that are still waiting for the ESPFACE_PERSIST_MS interval. Library reboots (client, OTA, face.reboot()) do this on their own; call it before deep sleep or your own ESP.restart().

cpp
face.flushPersist();
esp_deep_sleep_start();

resetReason ​

cpp
const char* resetReason() const

Last reset reason as ota|button|panic|power|wdt|sw|brownout|other.

cpp
Serial.println(face.resetReason());

Internals ​

logTo ​

cpp
EspFace& logTo(Print* p)

Where library log lines go (default Serial). Pass nullptr when the UI runs over Serial so log lines stay off the wire.

cpp
face.logTo(nullptr);
face.logTo(&Serial1);

core ​

cpp
Core& core()

The protocol core (sessions, caps, hooks). Rarely needed by sketches.

cpp
face.core();

ota ​

cpp
Ota& ota()

The OTA state machine (progress, abort).

cpp
face.ota();

notifier ​

cpp
Notifier& notifier()

The ntfy queue (queued(), sent()).

cpp
face.notifier();

MIT licensed. Firmware, web renderer and apps.