Library / ESP32

libscadable is the native C component you link into your ESP32 firmware. You add it as a dependency, define a single function for your application code, and the library handles everything between IP-up and the dashboard: certificate-based identity, broker discovery, TLS MQTT, periodic heartbeats, and OTA updates.

#include "scadable.h"
#include "esp_wifi.h"

void scadable_user_main(void) {
    my_wifi_connect();           // your code: bring up the network
    // ... your domain logic ...
}

That's the integration. You write scadable_user_main (the library calls it for you); the library owns app_main. Provisioning happens at flash time via the dashboard's web flasher — the certificate and identity land in NVS. On first boot, the library reads them, calls the edge router to discover its broker, opens a TLS MQTT session, starts heartbeating, and listens for OTA commands. Device shows up green on the dashboard within ~30 seconds.

What's in v0.1.0

Feature	Status
Certificate-based identity (cert pre-flashed to NVS)	✅
Broker discovery via `GET edge.scadable.com/v1/route`	✅
TLS MQTT session to the discovered broker	✅
Periodic heartbeat publish (default 30s)	✅
OTA command listener + `esp_https_ota` executor + auto-rollback	✅
Library-owned `app_main` (weak symbol)	✅
Wi-Fi / Ethernet / cellular bring-up	Customer — library is network-agnostic
Log forwarding to the dashboard	❌ v0.2.0
Customer event publishing helpers (`scadable_publish_event`)	❌ v0.2.0
Typed metrics / declarative schemas	❌ v0.2.0+
Remote diagnostics / `SCADABLE_TEST`	❌ v0.2.0+
Env vars + secrets	❌ v0.2.0+

v0.1.0 is the smallest demonstrable thing: prove the install + provision + heartbeat + OTA loop end-to-end. Everything else accretes from there.

Pages in this section

Quickstart: zero to first device, 15 minutes.
Connect a repository: install the SCADABLE GitHub App so pushed code becomes managed builds.
.scadable/ folder spec: one file, one field. That's the whole spec for v0.1.0.
API reference: every public symbol in scadable.h.
Troubleshooting: common failure modes keyed by log signature.

Compatibility

ESP-IDF ≥ 5.1. Pulled automatically via the Component Registry.
All ESP32 family chips: esp32, esp32-s2, esp32-s3, esp32-c2, esp32-c3, esp32-c6, esp32-h2. v0.1.0 targets all of them; production-tested today on esp32 classic and esp32-s3.
License: MIT.
Source: scadable/gateway-esp.
Registry: components.espressif.com/components/scadable/libscadable.

Roadmap to v0.2.0

The v0.1.0 release intentionally ships only the cert + broker + heartbeat + OTA loop. v0.2.0 adds the developer-facing publish surface, log forwarding, and the first wave of schema-driven typed event helpers. If you want to ship application telemetry today, use scadable_mqtt_publish directly — the typed helpers are a convenience layer arriving on top of the same primitive.