ESP-IDF firmware for ESP32. It runs a tiny patchbay on-device and conditioned output to NATS. It is the tiny counterpart to lexvicacom/monoblok - take a look for more context, or read the tinyblok intro blog post.

Status

• Connects to Wi-Fi, then NATS over TCP or TLS.
• Supports no auth, user/pass, or NATS .creds auth - works with Synadia Cloud and other operator mode clusters
• Publishes heap, RSSI, uptime, and temperature-derived subjects from patchbay.edn.
• You can configure Wi-Fi and NATS details with make menuconfig; ESP-IDF writes them to local sdkconfig.
• Run make build flash, then make monitor to try it on hardware.

Patchbay Lite

Tinyblok is a firmware-sized patchbay for telemetry. Rules are compiled ahead of time into deterministic Zig, run with fixed state, read local sensor pumps, derive new subjects, answer fixed request/reply subjects, and publish the results to NATS without allocating.

It is not trying to be a full monoblok runtime on an ESP32-C6. Runtime patch loading, dynamic graph edits, JSON/event document processing, inbound bridges, and fleet-management features are outside the current scope.

What's there and not there

Tinyblok intentionally implements a static, numeric subset of monoblok's patchbay. Supported forms include when, ->, comparisons, arithmetic pipeline ops (+, -, *, /, min, max, abs, sign), deadband, squelch, changed?, delta, moving-*, round, quantize, clamp, throttle, hold-off, edge gates, publish!, count!, bar!, sample!, debounce!, on-req, and reply!.

Not yet supported in Tinyblok: if, do, transition, on-silence, aggregate!, JSON forms, string/subject builders beyond publish-target subject-append, rate, percentile, median, stddev, variance, lvc, and bridge.

This does not mean never - some are trivial, some make no sense to even bother with (bridge, for instance is implicit). Others are tricky due to static code gen.

Soundcheck

Running bin/soundcheck builds a native host CLI from the generated patchbay. It reads newline-delimited SUBJECT|payload messages on stdin and writes emitted messages to stdout in the same shape. Top-level inputs are passed through first, followed by any patchbay emits:

printf 'tinyblok.temp|31\n' | ./soundcheck
printf 'tinyblok.temp|31\n' | ./soundcheck --label
printf 'tinyblok.rssi|-80\n' | ./soundcheck --label --linger-ms 1200

When stdin reaches EOF, soundcheck keeps pending timers alive for up to 10 s by default, so sample!, debounce!, and wall-clock bar! rules can still fire after piped input closes. Use --linger-ms N to change that window, or --linger-ms 0 to exit immediately after EOF.

See guide.md for the standalone soundcheck guide.

Drivers

A driver is just a function named from patchbay.edn:

(pump "tinyblok.temp" :from tinyblok_read_temp_c :type f32 :hz 1)

After you add the implementation and the patchbay.edn declaration, there is no other pump registration step. Codegen declares the function for Zig and adds it to the generated pump table consumed by C. main/c/drivers.c arms one esp_timer per pump, posts onto esp_event, then calls back into Zig.

Put small user-owned implementations in one of the files already wired into the build:

• C/ESP-IDF-facing code: main/c/user.c
• dependency-free Zig code: main/zig/user.zig

Then reference the exported symbol from patchbay.edn. There is no separate runtime registry; (pump ...) registers a timed source, (fn ...) registers a callable C/Zig function, and (on-req ...) registers a NATS request subject. make gen turns those declarations into generated Zig extern fn declarations and call sites in main/zig/rules.zig; you do not hand-write the externs. The linker checks that every named C/Zig symbol exists.

Pump source shapes are zero-argument reads:

Request handlers can also call registered functions:

(fn hello-c :from tinyblok_hello_c :input bytes :type bytes)

(on-req "tinyblok.req.hello-c"
  (reply! (hello-c payload)))

An on-req handler is patchbay code, not another compiled symbol. Declare any C/Zig helper it needs with (fn ...), then call that DSL name inside the handler.

Registered function :type describes the return value. Optional :input describes whether the function receives the current threaded value or request payload. Omit :input for zero-argument reads.

Function shapes:

For byte functions, codegen passes payload_ptr, payload_len, out_ptr, and out_len; the function returns the number of reply bytes written. For scalar input functions, codegen converts the current threaded f64 into the declared input type and formats the scalar return value.

Request/reply

on-req declares fixed NATS service subjects that Tinyblok subscribes to after every broker connect. The requester owns the _INBOX reply subject; Tinyblok only parses the incoming MSG reply-to field and sends reply! back to it. Replies can be inline literals, numeric rule results, the original request payload, or the result of a registered :input bytes :type bytes function.

That keeps request handling static like the rest of Patchbay Lite: no arbitrary runtime SUB, no generated inboxes, and no pending request table on-device. The generated handler dispatches by subject and uses stack buffers for payload parsing and function-backed replies.

This is useful for small control-plane actions that should not be continuous telemetry: pinging a device, reading uptime, asking it to reload published metadata, starting a sensor sweep, or triggering a one-shot diagnostic sample. It also works naturally for fleet queries. If many devices subscribe to the same request subject, one nats req-style request is effectively a broadcast: each device receives the same request and replies to the requester's inbox. Clients that expect fleet replies should wait for multiple responses rather than stopping after the first one.

(on-req "tinyblok.req.ping"
  (reply! "pong"))

(on-req "tinyblok.req.uptime"
  (-> uptime-s
      (round 3)
      (reply!)))

(on-req "tinyblok.req.hello-c"
  (reply! (hello-c payload)))

From a NATS client:

nats req tinyblok.req.ping ''
nats req tinyblok.req.uptime ''
nats req tinyblok.req.hello-c tinyhi
nats req tinyblok.req.hello-zig tinyhi

How it fits together

tools/gen.py compiles patchbay.edn into main/zig/rules.zig. The generated Zig is straight-line rule code with static state slots, which is much friendlier to a microcontroller than walking an s-expression tree at runtime.

The reusable ops live in main/zig/kernel.zig. That file is vendored from monoblok and should stay byte-identical; use make sync-kernel or make sync-kernel-remote when it changes upstream.

TX ring

main/zig/tx_ring.zig sits between rule eval and the NATS socket. publish! queues a subject/payload record; main/zig/main.zig drains it through main/c/nats.c. If Wi-Fi or the broker stalls, the ring drops the oldest samples rather than blocking rule evaluation.

Why C and Zig

main/c/stub.c, main/c/nats.c, main/c/drivers.c, and main/c/sources.c own the ESP-IDF surface: Wi-Fi, NVS, sockets, TLS, timers, events, and sensors. Zig owns the portable patchbay path: generated rules, op kernels, and the publish queue.

That split keeps IDF macros out of @cImport and keeps the Zig side small enough to host-test with make test.

make commands

Use the top-level Makefile:

make gen
make soundcheck
make test
make nats-host-smoke
make build
make flash
make monitor
make menuconfig

Run these from a shell where ESP-IDF is already exported, install ESP-IDF at $(HOME)/esp-idf-v6.0.1, or pass IDF_PATH=/path/to/esp-idf or IDF_EXPORT=/path/to/esp-idf/export.sh. For hardware commands, leave PORT unset for ESP-IDF auto-detection or pass a serial device, for example make flash PORT=/dev/cu.usbmodem101. You can also put machine-local overrides in ignored local.mk.

make nats-host-smoke exercises the host-built C NATS client against a local broker. It starts nats-server on 127.0.0.1:4223, verifies request/reply on tinyblok.req.ping, then verifies a five-message publish batch on tinyblok.host.pub.

It needs nats-server, the nats CLI, and zig cc in PATH. Override the test broker port with NATS_HOST_PORT if 4223 is already in use:

make nats-host-smoke
make nats-host-smoke NATS_HOST_PORT=4224

Checked-in defaults belong in sdkconfig.defaults; local choices live in sdkconfig. Real secrets do not: use secrets/nats.creds.example as the local .creds template.