Initializing Coldwave and the Service

Fill coldwave_init_t

Use the Coldwave init structure to configure your device identity and client options:

#include <coldwave/coldwave.h>
#include <Service.h>

static flake::Service* service = nullptr;

// Example: ~6.5 MB per month for telemetry
#define MONTHLY_BUDGET static_cast<unsigned>(6.5 * 1024 * 1024)

void coldwave_init_app(const char* device_id_imei)
{
    coldwave_init_t cw_init = COLDWAVE_INIT_DEFAULT;  // default initializer

    cw_init.app_semver = APP_VERSION_STR;     // your firmware SemVer
    cw_init.device_id  = device_id_imei;      // globally unique device ID (e.g. IMEI)
    cw_init.product_id = "YD42";              // optional: product identifier
    cw_init.hw_id      = "default";           // SoC / hardware ID for updates

    // Backend is mandatory for cwClient and must be set BEFORE coldwave_init():
    cw_init.backend.fqdn        = COLDWAVE_BACKEND_URL;
    cw_init.backend.ca_cert     = backend_ca;       // DER bytes
    cw_init.backend.ca_cert_len = backend_ca_len;

    // Primary network interface used to reach the backend:
    cw_init.net_device_handle = modem_fd;           // open("modem0", ...)
    cw_init.net_device_type   = cwNetLte;           // drives MAC + LTE pull-path

    cw_init.opt.client.monthly_data_limit_bytes     = MONTHLY_BUDGET;
    cw_init.opt.client.remaining_data_budget_bytes  = MONTHLY_BUDGET;

    // UUID of your generated service (from your Flake data model)
    const char* SERVICE_UUID = YD42_SRV_UUID;

    int rc = coldwave_init(&cw_init, SERVICE_UUID, &service);
    if (rc != CW_OK) {
        // handle error
    }
}

Key points:

• device_id must be unique per device (IMEI or similar).
• app_semver, product_id and hw_id are used for version tracking and OTA.
• backend.fqdn is mandatory for cwClient: the wire is created and flakeInitialize() is called inside coldwave_init(). No network traffic happens yet — it is triggered by coldwave_backend_attach().
• monthly_data_limit_bytes and remaining_data_budget_bytes track your monthly data usage for reporting and coldwave_get_remaining_budget(); they do not change sync behavior — rate limits are enforced by the backend.
• service will point to your device’s flake::Service instance after coldwave_init() succeeds.

Persisting and restoring the data budget (optional)

You can persist the remaining data budget across reboots (e.g. in RTC RAM or flash) and feed it back into Coldwave before calling coldwave_init():

uint32_t remaining_budget = MONTHLY_BUDGET;

// Load last remaining budget from non-volatile memory:
uint32_t persisted = load_remaining_budget_from_nv();
if (persisted > 0U && persisted < MONTHLY_BUDGET) {
    remaining_budget = persisted;
}

cw_init.opt.client.remaining_data_budget_bytes = remaining_budget;

Later, while attached, you can periodically refresh and persist the budget using coldwave_get_remaining_budget():

if (coldwave_backend_attached()) {
    remaining_budget = coldwave_get_remaining_budget();
    save_remaining_budget_to_nv(remaining_budget);
}

This pattern keeps your usage accounting consistent across device restarts.