Synchronizing with the Backend

Basic sync loop

Property changes are buffered locally. To actually exchange data with the Coldwave Backend you need to call service->sync(timeout_ms) regularly.

Typical pattern (simplified):

void app_main_loop()
{
    bool initial_sync = true;

    while (true) {
        uint32_t ts = osKernelGetTickCount();

        // Periodic status refresh (e.g. once per minute)
        if (initial_sync || (ts % 60000U) < 1000U) {
            update_status_properties();
            initial_sync = false;
        }

        // Optional: emergency sync when power is critical
        float power_v = measure_supply_voltage();
        if (power_v < VOLTAGE_THRS_LOW) {
            service->set<PWR>(power_v);
            service->sync(1000);  // flush critical state immediately
        }

        // Normal sync to send pending updates and receive commands
        service->sync(1000);

        osDelayUntil(ts + 1000U);
    }
}

In this pattern:

• Fast threads (e.g. status_thread) only call set<>() for telemetry.
• A slower loop (e.g. once per second) calls sync() to keep the backend up to date without spamming the connection.
• For critical events (low voltage, EMCY, …) you can trigger an extra sync().

Sync cadence and data budget

The sync cadence is determined entirely by your application: data is exchanged when — and only when — you call sync(). Calling it regularly (e.g. every 1–10 seconds) remains the recommended pattern; the backend enforces server-side rate limits.

If monthly_data_limit_bytes is non-zero, Coldwave tracks the monthly data volume (remaining_data_budget_bytes seeds the tracker, e.g. after a restart). Tracking does not throttle syncing — but you can feed it into your own heuristics via coldwave_get_remaining_budget(), for example by reducing your sync cadence when the remaining budget runs low.