Skip to main content

Architecture

The Blokdots C++ library runs on the Arduino and provides the same component model you use in the app. Components register themselves automatically, and the library handles initialization, per-loop updates, events, and timers for you.

#Sketch Structure

Every generated sketch follows this pattern:

C++
#include "blokdots.h"

Led led(5);        // D5 — digital output
Button button(2);  // D2 — digital input

void setup() {
  blokdots::beginAll();  // initialize all registered components
}

void loop() {
  eventBus.tick();       // run timers and dispatch events
  blokdots::tickAll();   // update component animations
}

#Component Lifecycle

Components register themselves in their constructor. You never call registration functions manually — just create a component and it's ready to use.

When blokdots::beginAll() is called in setup(), each component runs its one-time initialization (e.g., setting pin modes). When blokdots::tickAll() is called in loop(), each component updates its state (e.g., advancing blink animations).

#EventBus

eventBus is a global event system that connects components and controls timing. It supports named events, one-shot timers, and repeating intervals.

C++
// Define event IDs (generated automatically in Blokdots sketches)
enum Events { BUTTON_PRESSED, BUTTON_RELEASED };

// Subscribe to an event
eventBus.on(BUTTON_PRESSED, onButtonPressed, nullptr);

// Fire a one-shot timer after 2 seconds
eventBus.setTimeout(onTimeout, nullptr, 2000);

// Fire repeatedly every 500 ms
int id = eventBus.setInterval(onTick, nullptr, 500);
eventBus.clearTimer(id);  // cancel it later

eventBus.tick() must be called every loop() iteration. It drains the event queue, fires due timers, and dispatches all pending events to their handlers.

#ComponentBase

Every component — sensors, actuators, displays — extends ComponentBase. It provides the lifecycle hooks (begin / tick) and registers with the global beginAll / tickAll system automatically.

You never instantiate ComponentBase directly. Use a concrete class like DigitalActor, AnalogSensor, AnalogActor, or Button.

#Value Types

The library defines two types to avoid memory fragmentation on Arduino's limited heap:

  • blokdots::String — fixed-size 64-byte stack string with auto-conversion from int, float, bool, and Color
  • blokdots::Color — RGB struct used by LED strips and color-capable outputs

See the Value Types page for details.