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().

Budget-aware sync

The Coldwave client uses the fields in coldwave_client_options_t to respect your monthly budget and desired sync interval:

• monthly_data_limit_bytes
• remaining_data_budget_bytes
• dasired_sync_interval_s

You can keep your own application-level heuristics simple and let Coldwave throttle if you approach the budget. In most cases it is enough to:

• Call sync() regularly (e.g. every 1–10 seconds).
• Let Coldwave decide which updates to bundle and how often to actually send them to the backend based on the configured budget.