Usage Guide

Project Structure

MyProject/
├── platformio.ini        # PlatformIO configuration
├── packages.json         # node.js configuration
├── src/
│   └── main.cpp          # Application entry point
├── html/
│   ├── index.html        # Custom web UI (optional)
│   ├── logo.png          # Project logo
│   ├── js/               # Custom JavaScript
│   └── css/              # Custom CSS

Basic Integration

#include <YarrboardFramework.h>

// Generated by gulp build process
#include "index.html.gz.h"
#include "logo.png.gz.h"

YarrboardApp yba;

// Define GulpedFile structures for web assets
static const GulpedFile index_file = {
  .data = index_html_gz,
  .length = index_html_gz_len,
  .sha256 = index_html_gz_sha,
  .filename = "index.html",
  .mimetype = "text/html"
};

static const GulpedFile logo_file = {
  .data = logo_png_gz,
  .length = logo_png_gz_len,
  .sha256 = logo_png_gz_sha,
  .filename = "logo.png",
  .mimetype = "image/png"
};

void setup() {
  // Set embedded web assets
  yba.http.index = &index_file;
  yba.http.logo = &logo_file;

  // Configure board metadata
  yba.board_name = "My Device";
  yba.default_hostname = "mydevice";
  yba.firmware_version = "1.0.0";
  yba.hardware_version = "REV_A";
  yba.manufacturer = "My Company";
  yba.hardware_url = "https://github.com/myuser/myproject";
  yba.project_url = "https://example.com/myproject";
  yba.project_name = "My Project";

  // Initialize framework
  yba.setup();
}

void loop() {
  yba.loop();
}

Custom Controller

class MyController : public BaseController {
public:
  MyController(YarrboardApp& app)
    : BaseController(app, "mycontroller") {}

  bool setup() override {
    // Register protocol commands
    _app.protocol.registerCommand(
      GUEST, "my_command",
      this, &MyController::handleCommand
    );
    return true;
  }

  void loop() override {
    // Controller main loop
  }

  void generateUpdateHook(JsonVariant output) override {
    // Add real-time data to WebSocket updates
    output["my_data"] = getValue();
  }

  bool loadConfigHook(JsonVariant config, char* error, size_t len) override {
    // Load configuration from JSON
    setting = config["setting"] | defaultValue;

    // Validate configuration
    if (setting < 0) {
      snprintf(error, len, "Invalid setting value: %d", setting);
      return false;
    }

    return true;
  }

  void generateConfigHook(JsonVariant config) override {
    // Serialize configuration to JSON
    config["setting"] = setting;
  }

private:
  void handleCommand(JsonVariantConst input, JsonVariant output, ProtocolContext context) {
    // Handle protocol command
    output["result"] = processCommand(input["param"]);

    // Access context information
    // context.mode - communication mode (WEBSOCKET, HTTP, SERIAL, MQTT)
    // context.role - user role (NOBODY, GUEST, ADMIN)
    // context.clientId - unique client identifier
  }

  int setting;
};

// Register in main.cpp setup()
MyController myController(yba);
yba.registerController(myController);

Custom Channel

class MyChannel : public BaseChannel {
public:
  void init(uint8_t id) override {
    BaseChannel::init(id);
    // Hardware initialization (channels are numbered 1-N)
  }

  bool loadConfig(JsonVariantConst config, char* error, size_t err_size) override {
    if (!BaseChannel::loadConfig(config, error, err_size))
      return false;

    pin = config["pin"] | -1;
    // Additional configuration

    return true;
  }

  void generateConfig(JsonVariant config) override {
    BaseChannel::generateConfig(config);
    config["pin"] = pin;
  }

  void generateUpdate(JsonVariant output) override {
    output["value"] = readValue();
  }

  void haGenerateDiscovery(JsonVariant doc, const char* uuid, MQTTController* mqtt) override {
    // Populate discovery document
    doc["name"] = name;
    doc["state_topic"] = "~/state";
    doc["device_class"] = "sensor";
    doc["unique_id"] = ha_uuid;

    // Publish to Home Assistant
    mqtt->publishDiscovery("sensor", key, uuid, doc);
  }

  void haPublishState(MQTTController* mqtt) override {
    // Publish current state to Home Assistant
    JsonDocument doc;
    doc["value"] = readValue();
    mqtt->publishHA(key, "state", doc.as<JsonObject>());
  }

private:
  int pin;
  int readValue() { /* ... */ }
};

// Use with ChannelController
using MyChannelController = ChannelController<MyChannel, 8>;
MyChannelController myChannels(yba, "mychannels");
yba.registerController(myChannels);

---

← Previous: Installation | Next: Configuration →