Skip to content

Compile-time options ​

Define these as build flags (-DNAME=value in PlatformIO build_flags) or before including espFace.h.

OptionDefaultMeaning
ESPFACE_MAX_CLIENTS4Maximum concurrent sessions across all transports; the next client gets err 9
ESPFACE_LOG_HISTORY0Number of log lines kept on the device and replayed to a client that connects later
ESPFACE_PERSIST_MS2000Persisted inputs are written to NVS at most once per this interval (ms); a slider drag costs one or two flash writes, not one per step
ESPFACE_FRAME_SIZE1024Size of the frames the ui message is streamed in
ESPFACE_MAX_MSG2048Largest accepted client-to-device message and stream line, in bytes
ESPFACE_NO_TLSoffDrop TLS: OTA and ntfy are http-only, https URLs fail with a log line
ESPFACE_BLEoffEnable the NimBLE transport; needs h2zero/NimBLE-Arduino@^2.5.1
ESPFACE_BLE_MTU512MTU the device accepts
ESPFACE_BLE_MAX_CONN2Maximum BLE centrals
ESPFACE_BT_CLASSICoffEnable Bluetooth Classic SPP (Bluedroid, classic ESP32 only); excludes ESPFACE_BLE

Runtime setters ​

CallEffect
face.setPort(port)HTTP and WebSocket port (default 80, falls back to 8080 if the bind fails)
face.enableWs(false)Skip the http and WebSocket server; call before begin()
face.logTo(Print*)Where library log lines go; nullptr silences them
face.setOtaCaCert(pem)CA certificate for https downloads and ntfy
face.ntfyRateLimit(ms)Minimum time between ntfy messages (default 10000)
face.serial(stream).setIdleTimeout(ms)Close a stream session after silence (default off)

Examples ​

Each example lives in firmware/examples/<Name>. An example directory may carry build_flags, lib_deps, boards and project_options files that tools/ci-build.sh applies.

ExampleWhat it showsSpecial build needs
MinimalGauge and switchnone
FullDemoEvery widget, PIN, OTA, NTP, ntfynone
Notifyntfy alertsnone
SerialOnlyUI on USB serial, no WiFinone
BleOnlyUI over BLE, no WiFi-DESPFACE_BLE, NimBLE-Arduino
ProvisioningMain UI on WiFi, open setup UI on BLE via addUi-DESPFACE_BLE, NimBLE-Arduino
BtClassicUI over Bluetooth SPP-DESPFACE_BT_CLASSIC, esp32dev only, larger partition

MIT licensed. Firmware, web renderer and apps.