Guides
  1. Getting Started

Your First Device in 15 Minutes

The fast path from "nothing" to "device on the dashboard." 15 minutes the first time, 5 minutes after.

This is the platform-level quickstart. For the ESP32-specific deep dive (complete code, partition table, log walkthrough), see Library / ESP32 / Quickstart.

Prerequisites

  • An ESP32-family board you can flash over USB (ESP32-classic or ESP32-S3 are the production-tested paths today).
  • ESP-IDF v5.1+ (idf.py --version).
  • An account on dashboard.scadable.com and a namespace.
  • A Chromium-based browser (Chrome, Edge, Brave) for the in-dashboard WebSerial flasher.

Step 1: Add libscadable to your firmware project

From your ESP-IDF project root:

idf.py add-dependency "scadable/libscadable^0.1.0"

The IDF Component Manager fetches the component on next reconfigure.

Step 2: Write scadable_user_main

In main/main.c:

#include "scadable.h"
#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_netif.h"

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

The library owns app_main (as a weak symbol). You define scadable_user_main instead — the library calls it after its own bootstrap. Your job is to bring up the network (Wi-Fi, Ethernet, whatever fits your hardware). The library handles everything once an IP appears.

Step 3: Add .scadable/config.yaml

mkdir -p .scadable
cat > .scadable/config.yaml <<'EOF'
device_type: esp32-classic
EOF

Valid values: esp32-classic, esp32-s2, esp32-s3, esp32-c2, esp32-c3, esp32-c6, esp32-h2.

Step 4: Connect your repo to SCADABLE

In the dashboard, open your namespace → Settings → GitHub → install the SCADABLE GitHub App on the firmware repo. Pushed code triggers a build. See Connect a Repository for the detailed flow.

Step 5: Provision and flash a device

Dashboard → namespace → Provision device. SCADABLE mints a per-device cert and bundles it into the NVS partition. The browser flasher writes:

  • Your firmware → ota_0 partition
  • The NVS bundle (cert + key + CA + identity) → offset 0x9000

One click. The device reboots and starts the library's boot sequence.

Step 6: Watch it come online

Hook up idf.py monitor. The boot ends with:

I (...) scadable: online bootstrap complete
I (...) scd.mqtt: connected

Within ~30 seconds, the device shows up green on the dashboard with heartbeats.

Step 7: Push an OTA update

Make a change to your firmware. Commit and push. SCADABLE builds the new artifact. In the dashboard, hit Deploy on the new build. The library's OTA agent receives the command over MQTT, downloads, restarts, and validates. Failed boots auto-rollback to the previous slot — no fleet-side coordination needed.

What you got without writing it

All of this is running the moment the library connects:

  • Certificate-based device identity with the cert minted at provisioning time.
  • TLS-encrypted MQTT from device to broker.
  • Broker discovery via edge.scadable.com/v1/route — supports region changes without re-flashing.
  • Heartbeats every 30 seconds.
  • OTA agent that listens, downloads, installs, and validates new builds.
  • Audit trail in the dashboard — every connection, every OTA, every config change.

What's NOT in v0.1.0 (yet)

  • Log forwarding from ESP_LOG_* to the dashboard — coming v0.2.0.
  • Custom event publishing helpers (scadable_publish_event) — coming v0.2.0.
  • Inbound command handlers beyond OTA — coming v0.2.0.
  • Schema-driven typed events / metrics — v0.2.0+.

If you need custom telemetry today, call scadable_mqtt_publish() directly with a topic and JSON payload. The typed helpers being added in v0.2.0 are conveniences on top of the same primitive.

Next steps

Updated 11 days ago