Skip the boilerplate. Ship the sketch.

The whole program

Hand-written, driving one LED from the cloud is about ninety lines of WiFi, TLS, JSON parsing, acking, and reconnect handling. With the library it's this — bind a dashboard toggle to led and it works end to end:

#include <Nodrix.h>
#include "secret.h"

const int LED_PIN = 2;

NODRIX_WRITE("led") {                 // cloud writes "led" -> this runs
  digitalWrite(LED_PIN, value.asBool() ? HIGH : LOW);
  Nodrix.send("led", value.asBool()); // report real state back
}

void setup() {
  pinMode(LED_PIN, OUTPUT);
  Nodrix.begin(WIFI_SSID, WIFI_PASS, HOST, TOKEN);
}

void loop() {
  Nodrix.run();
}

Everything below is what the library does underneath.

Receiving control

NODRIX_WRITE("var") { … } registers a handler for a variable. When a dashboard widget, an automation, or the API writes it, the block runs with a value in scope. Registration happens before setup(), so a handler is a single self-contained block anywhere in the sketch — no dispatch table.

The value is a NodrixValue that coerces the wire type, so a toggle sending true, a slider sending 42, and a select sending "on" all just work:

Acknowledgements are automatic — the library acks every write it delivers, so the cloud stops re-sending it. Because delivery is at-least-once, a handler can run more than once for the same command across a reconnect, so keep it idempotent. Setting a pin to a definite state is naturally safe.

Two transports, same handlers

A device lives one of two ways, and the library matches both without changing your handlers — a one-line switch between begin() and beginHTTP().

HTTP wake cycle

void setup() {
  Nodrix.beginHTTP(WIFI_SSID, WIFI_PASS, HOST, TOKEN);
  Nodrix.send("soil", analogRead(34));
  Nodrix.flush();   // POST telemetry
  Nodrix.poll();    // fetch + apply queued control, then ack
  // ... then esp_deep_sleep_start()
}

TLS pinning

By default the library connects encrypted but unverified — the shortest path to a first working device. To pin, call setCACert(pem) (ESP32, WebSocket and HTTP) or setFingerprint(fp) (ESP8266, HTTP) before begin(). Pin the root CA, not the leaf — the leaf rotates every ~90 days, the root does not. Your host serves its root as the last block of the chain:

openssl s_client -showcerts -servername yourproject.workers.dev \
  -connect yourproject.workers.dev:443 </dev/null 2>/dev/null \
| awk '/BEGIN CERTIFICATE/{c++; b=""} {b=b $0 ORS} /END CERTIFICATE/{last=b} END{printf "\n%s", last}'

For Cloudflare *.workers.dev that returns GTS Root R4. One limitation: on ESP8266 the WebSocket transport is always unvalidated — use an ESP32, or ESP8266 in HTTP mode with a fingerprint.

Worked examples

Five runnable sketches ship with the repository. The two DHT11 examples also need the DHT sensor library by Adafruit.