Starter Templates

The fastest way to ship your first SCADABLE firmware is to fork a starter template. Each starter has libscadable linked, a minimal .scadable/ folder, and a main.c (or main.cpp) that publishes a heartbeat. Push a tag and you have a release.

Available templates

Pick whichever matches your existing toolchain. They produce equivalent artifacts — the cloud doesn't care which one built it.

What's in the box

Both templates ship with:

• main/main.c (or src/main.cpp for PlatformIO) — minimal wifi_up + scadable_init + scadable_connect + a 30s heartbeat publish.
• .scadable/config.toml — target = "esp32-s3" plus the always_on connectivity preset.
• .scadable/digital-twin/heartbeat.toml — one register (uptime_seconds) so the dashboard has something to plot from minute one.
• .github/CODEOWNERS and .gitignore — sensible defaults.
• README.md — a "what to change first" checklist.

The IDF starter additionally includes main/idf_component.yml with the libscadable dependency pinned. The PlatformIO starter has the equivalent in platformio.ini.

Use it

# Fork via GitHub UI (preserves the template's commit history) OR clone:
git clone https://github.com/scadable/esp-idf-starter my-firmware
cd my-firmware
rm -rf .git && git init && git remote add origin [email protected]:you/my-firmware
git add . && git commit -m "Bootstrap from scadable/esp-idf-starter"
git push -u origin main

Then Connect a Repository — install the SCADABLE GitHub App on you/my-firmware and link it to a namespace.

First release:

git tag v0.1.0
git push --tags

The dashboard's Releases view shows the build progressing. Two to four minutes later, you have a flashable artifact.

Customizing from the starter

The README in each starter has a checklist of the first three changes you'll likely make. Roughly:

1. Change target in .scadable/config.toml to your actual chip (esp32, esp32-s3).
2. Add your own digital-twin registers in .scadable/digital-twin/. See the folder spec.
3. Replace the heartbeat in main.c with your real sensor read or actuator drive logic. The scadable_* API surface (publish, metric set, log) is the same — see the API reference.

When NOT to use a starter

• You already have an ESP-IDF or Arduino project you want to add SCADABLE to. Don't rip it out and start from a starter — drop libscadable into your existing repo following Custom firmware.
• You're using a non-IDF non-Arduino toolchain (ESP-HAL on Rust, custom build). The starters won't help directly; talk to us about your build setup.

Versioning

Templates are versioned independently from libscadable. The starters track the latest stable libscadable major. We tag the starter repos when we cut new template revisions; existing forks don't auto-update.

If a critical change lands in a starter (security fix in the heartbeat example, build flag fix), we open a GitHub issue on the template that explains the diff so existing forks can cherry-pick.