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
EspFace()Constructs the facade; nothing starts until begin().
EspFace face;begin
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().
| Argument | Type | Default | Meaning |
|---|---|---|---|
name | const char* | – | display name shown by the clients and used for the mDNS host and the AP SSID |
void setup() {
face.begin("Boiler");
face.wifi().autoConnect();
}loop
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.
void loop() {
face.loop();
face.set("temp", readTemp());
}beginTask
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.
| Argument | Type | Default | Meaning |
|---|---|---|---|
stack | uint32_t | 8192 | task stack in bytes |
prio | uint8_t | 1 | task priority |
core | int | -1 | CPU core, -1 = any |
face.beginTask(); // defaults: 8 KB stack, priority 1, any core
face.beginTask(12288, 2, 1);delay
void delay(uint32_t ms)Like delay(ms) but keeps calling loop() so clients stay served while the sketch waits.
face.delay(500);Identity
setProject
EspFace& setProject(const char* p)Project/group name shown in the device list of the clients (proj in hello and mDNS TXT).
face.setProject("Home");setIcon
EspFace& setIcon(const char* i)Icon name from the shared set for the device list.
face.setIcon("thermostat");setVersion
EspFace& setVersion(const char* v)Firmware version string (fw in hello and info; compared with GitHub releases when setRepo is set).
face.setVersion("1.2.0");setRepo
EspFace& setRepo(const char* r)GitHub owner/repo; lets clients offer a user-triggered release check and ota.url install.
face.setRepo("manzari/espFace");setAbout
EspFace& setAbout(const char* a)Free text shown on the info page.
face.setAbout("Boiler controller, rev B");id
const char* id() constDevice id (6 to 12 lowercase hex from the MAC).
Serial.println(face.id());Security
setPin
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.
| Argument | Type | Default | Meaning |
|---|---|---|---|
pin | const char* | – | 4 to 32 characters, or nullptr |
force | bool | false | overwrite a PIN a client set at runtime |
face.setPin("1234");
face.setPin(nullptr); // open device
face.setPin("4321", true); // reset a client-changed PINTransports
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
EspFace& setPort(uint16_t port)HTTP/WebSocket port (default 80; falls back to 8080 when the bind fails and logs it). Call before begin().
face.setPort(8080);enableWs
EspFace& enableWs(bool on)false before begin() skips the http/WebSocket server entirely (BLE-only or serial-only devices).
face.enableWs(false);wifi
WifiMgr& wifi()The WiFi manager: autoConnect(), connect(ssid, pass), startAp(), setApPassword(), connected(), ip().
face.wifi().autoConnect(); // stored credentials, else captive AP espFace-<id>
face.wifi().setApPassword("setup123");ws
WsTransport& ws()The WebSocket/http transport object (port, renderer host, running()).
if (face.ws().running()) { /* ... */ }serial
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).
| Argument | Type | Default | Meaning |
|---|---|---|---|
s | Stream& | – | |
name | const char* | "serial" |
face.serial(Serial);
face.serial(Serial1, "uart").setIdleTimeout(30000);ble
BleTransport& ble()Enables the NimBLE transport (build with -DESPFACE_BLE); returns it for setName() / use(ui).
#define ESPFACE_BLE
face.ble().setName("Boiler");btClassic
BtSerialTransport& btClassic(const char* name = nullptr)Enables Bluetooth Classic SPP (build with -DESPFACE_BT_CLASSIC, classic ESP32 only, exclusive with BLE).
| Argument | Type | Default | Meaning |
|---|---|---|---|
name | const char* | nullptr |
face.btClassic("Boiler");System features
enableOta
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.
face.enableOta(true);setOtaCaCert
EspFace& setOtaCaCert(const char* pem)PEM CA certificate used to verify https for ota.url downloads and ntfy. Without it https is used unverified.
static const char CA_CERT[] PROGMEM = "-----BEGIN CERTIFICATE-----\n...";
face.setOtaCaCert(CA_CERT);enableNtp
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.
| Argument | Type | Default | Meaning |
|---|---|---|---|
on | bool | – | start/stop SNTP |
server | const char* | "pool.ntp.org" | NTP server |
tz | const char* | nullptr | POSIX TZ string |
face.enableNtp(true, "pool.ntp.org", "CET-1CEST,M3.5.0,M10.5.0/3");ntfy
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.
| Argument | Type | Default | Meaning |
|---|---|---|---|
server | const char* | – | |
topic | const char* | – | |
token | const char* | nullptr |
face.ntfy("https://ntfy.sh", "boiler-alerts");
face.ntfy("https://ntfy.example.com", "alerts", "tk_secret");ntfyRateLimit
EspFace& ntfyRateLimit(uint32_t ms)Minimum interval between notifications (default 10 000 ms); extra messages queue (4 slots) or are dropped.
face.ntfyRateLimit(60000); // at most one per minutenotify
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.
| Argument | Type | Default | Meaning |
|---|---|---|---|
title | const char* | – | |
msg | const char* | – | |
prio | Ntfy | Ntfy::Default |
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
Ui& ui()The default UI builder (see Ui).
auto& ui = face.ui();
ui.gauge("temp", "Temperature", 0, 120, "°C");addUi
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).
auto& setupUi = face.addUi("setup");
setupUi.pin(""); // no PIN for this UI
setupUi.header("WiFi setup");
face.ble().use(setupUi);set
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.
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
bool setRows(const char* id, const char* rowsJson)Table rows as a raw JSON array of rows.
face.setRows("tbl", "[[\"Kitchen\",21.5],[\"Bath\",23]]");setPoints
bool setPoints(const char* id, const char* pointsJson)Map points as a raw JSON array of [lat, lon, label].
face.setPoints("pos", "[[52.52,13.405,\"Boiler\"]]");push
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).
face.push("tchart", "temp", t);log
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).
| Argument | Type | Default | Meaning |
|---|---|---|---|
msg | const char* | – | |
color | const char* | nullptr |
face.log("boot ok");
face.log("term", "overheat", "#f00");toast
void toast(const char* lvl, const char* msg)Transient message on all clients; lvl is info, warn or err.
face.toast("warn", "Overheating");Callbacks and time
clients
uint8_t clients() constNumber of authenticated clients.
if (face.clients() == 0) sleepSoon();time
uint32_t time() constUnix seconds from NTP, else from the last client time message, else 0.
uint32_t now = face.time();setTime
void setTime(uint32_t unix)Feeds an authoritative time (e.g. from an RTC).
face.setTime(rtc.now().unixtime());onConnect
void onConnect(std::function<void(const ClientInfo&)> fn)Called when a client finished the handshake (ClientInfo: slot, transport name, isWeb).
face.onConnect([](const ClientInfo& c) { Serial.printf("client on %s\n", c.transport); });onDisconnect
void onDisconnect(std::function<void(const ClientInfo&)> fn)Called when a client left.
face.onDisconnect([](const ClientInfo& c) { /* ... */ });onReboot
void onReboot(std::function<void(RebootReason)> fn)Called right before a client-, OTA- or sketch-triggered reboot (RebootReason::Client, Ota, Sketch).
face.onReboot([](RebootReason r) { saveState(); });reboot
void reboot(uint32_t delayMs = 500)Reboots after delayMs (clients are told first, onReboot runs).
| Argument | Type | Default | Meaning |
|---|---|---|---|
delayMs | uint32_t | 500 |
face.reboot();flushPersist
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().
face.flushPersist();
esp_deep_sleep_start();resetReason
const char* resetReason() constLast reset reason as ota|button|panic|power|wdt|sw|brownout|other.
Serial.println(face.resetReason());Internals
logTo
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.
face.logTo(nullptr);
face.logTo(&Serial1);core
Core& core()The protocol core (sessions, caps, hooks). Rarely needed by sketches.
face.core();ota
Ota& ota()The OTA state machine (progress, abort).
face.ota();notifier
Notifier& notifier()The ntfy queue (queued(), sent()).
face.notifier();