Coldwave Documentation

Appearance

Exposing Telemetry as Properties ​

Property tags ​

Your data model is defined as a set of Flake properties. Each property has a tag (a compile-time constant such as PWR, HEAP, DI1, DO1, STATE, RTC, REMAINING_DATA_MTH, …). These tags are generated from your Flake model and included via a header in your firmware.

On the device, you use those tags with flake::Service:

  • Read-only telemetry properties: you only write them from firmware and the backend treats them as telemetry (e.g. power supply voltage, free heap, digital inputs).
  • Writable properties: the backend can write them to control actuators or configure the device (e.g. digital outputs, feature flags).

Setting telemetry properties ​

The simplest way to publish telemetry is to call service->set<PropTag>(value) whenever a value changes or when you want to refresh it.

Example (simplified from the reference app):

cpp
void update_status_properties()
{
    float power_v = measure_supply_voltage();
    uint32_t free_heap = xPortGetFreeHeapSize();
    time_t now = time(nullptr);

    // Remaining data (percentage of MONTHLY_BUDGET)
    double remaining = static_cast<double>(coldwave_get_remaining_budget()) / MONTHLY_BUDGET * 100.0;

    service->set<REMAINING_DATA_MTH>(remaining);
    service->set<RTC>(now);
    service->set<PWR>(power_v);
    service->set<HEAP>(free_heap);
}

Digital inputs updated in a fast status thread:

cpp
void status_thread(void*)
{
    while (true) {
        bool di1 = read_di1();
        bool di2 = read_di2();
        bool di3 = read_di3();
        bool di4 = read_di4();

        service->set<DI1>(di1);
        service->set<DI2>(di2);
        service->set<DI3>(di3);
        service->set<DI4>(di4);

        osDelay(25);
    }
}

Error handling ​

set<PropTag>(value) returns an integer error code:

  • E_OK on success
  • E_REFUSED if the value cannot be safely cast to the property’s type or if called from within a forbidden callback context

In typical telemetry code you either assert on errors (during development) or record them in a diagnostics log.