API Reference (Telemetry-Relevant Subset)

This section summarizes the parts of the Coldwave and flake::Service APIs that are most relevant for telemetry.

Coldwave C API (excerpt)

All functions are declared in <coldwave/coldwave.h>.

Function	Description
int coldwave_init(const coldwave_init_t* init, const char* srv_uuid, flake::Service** srv)	Initialize Coldwave. Fills *srv with a flake::Service instance on success (E_OK).
int coldwave_register_service(const char* srv_uuid, flake::Service** srv)	Register an additional service instance (secondary object).
int coldwave_backend_attach(const char* cbe_fqdn, unsigned char* cbe_ca_cert, unsigned cbe_ca_cert_len)	Attach to the Coldwave Backend (CBE) using the given FQDN and CA certificate.
int coldwave_backend_detach(void)	Detach from the backend.
bool coldwave_backend_attached(void)	Returns true if the backend is currently attached.
unsigned coldwave_get_remaining_budget(void)	Remaining monthly data budget in bytes for the client; returns 0 if not initialized or not a client node.
void coldwave_reset_budget(void)	Reset the monthly budget manager.
int coldwave_suspend(void) / int coldwave_resume(void)	Suspend / resume Coldwave activity (e.g. for low-power modes).

Relevant fields in coldwave_init_t / coldwave_client_options_t:

Field	Type	Description
node_type	coldwave_node_t	Node role (cwClient or cwRouter). Telemetry devices typically use cwClient.
app_semver	const char*	Firmware SemVer string.
device_id	const char*	Unique device ID (IMEI or similar).
product_id	const char*	4-character product ID.
hw_id	const char*	Hardware identifier (SoC family, board variant).
opt.client.monthly_data_limit_bytes	unsigned	Monthly data budget in bytes.
opt.client.remaining_data_budget_bytes	unsigned	Remaining monthly budget at startup (optional).
opt.client.dasired_sync_interval_s	int	Target sync interval in seconds.

flake::Service (excerpt)

All methods are declared in <flake/Service.h>.

Core methods for telemetry:

Member	Description
template<uint32_t PropTag, typename T> int set(T value)	Set the value of a property identified by PropTag. Returns E_OK on success, E_REFUSED if the value cannot be converted or if called from within a forbidden callback context.
template<uint32_t PropTag> PropType<PropTag> get(PropType<PropTag> defval = ...)	Get the value of a property, or defval if not available.
template<uint32_t PropTag> int on(PropCallback<PropTag> cb)	Register a property callback for a tag (called when the property is written by the backend).
template<uint32_t PropTag> int on(PropCallback<PropTag & ~TAG_ACTIONABLE> cb, PropType<PropTag> min, PropType<PropTag> max)	Register a property callback with range validation for non-actionable properties.
template<uint32_t PropTag> int onRead(PropCallBackStreamRead cb)	Register stream read callback for a stream property.
template<uint32_t PropTag> int onWrite(PropCallBackStreamWrite cb)	Register stream write callback for a stream property.
template<uint32_t PropTag> int onOpenClose(PropCallBackStreamOpenClose cb)	Register stream open/close callback.
int openProperty(const uint32_t propTag, Stream** stream)	Open a stream for the given property tag (for large or streaming telemetry).
int sync(int timeout_ms = FLAKE_DEFAULT_TIMEOUT_MS)	Exchange pending property updates and messages with the backend.
void defer() / int syncDeferred(unsigned timeout_ms, bool block) / bool hasDeferred()	Low-level control of deferred sync batches.
unsigned pendingBytes()	Get the number of pending bytes waiting to be sent.
void reset()	Reset the service state.