Coldwave API

Coldwave API Functions.

Example: initialize coldwave as a client and attach to the backend.

cpp

coldwave_init_t cw_init = COLDWAVE_INIT_DEFAULT;

cw_init.node_type      = cwClient;
cw_init.app_semver     = "1.0.0";
cw_init.device_id      = "Device123";
cw_init.product_id     = "CW01";
cw_init.hw_id          = "Hardware123";

cw_init.backend.fqdn        = "your-backend-fqdn.com";
cw_init.backend.ca_cert     = (unsigned char *) "your-ca-cert"; // DER bytes
cw_init.backend.ca_cert_len = ca_cert_len;

cw_init.opt.client.monthly_data_limit_bytes = 5u * 1024 * 1024;

flake::Service *cw_service = nullptr;
const char *cw_service_uuid = "service_uuid";

int rc = coldwave_init(&cw_init, cw_service_uuid, &cw_service);
if (rc != E_OK) {
  // init failed: bad params, allocation failure, or flake init failure.
  return rc;
}

// After init, the flake CoreWorker is running and the connection object
// exists, but no network traffic has happened yet. Trigger the connect:
coldwave_backend_attach();

Modules

Name

Name
Power & temperature push Single push entry-point for values that have no portable platform binding (battery rail, on-die temperature, ...). Integrators that sample these via ADC/sensor pass them in here whenever they have a fresh reading; libcoldwave caches the values and the connection loop publishes them on the DeviceService at the next sync.
Per-HW firmware-update tracking Hooks libcoldwave into the coldwave-os OTA target callbacks so it can publish per-slot FU-state on the device service. Slot 0 is always libcoldwave's own SW-OTA — slots 1..(COLDWAVE_HW_SLOTS_MAX-1) are subprocessor targets that the integrator wires up. If libcoldwave is not registered for a slot, the application is free to call `ota_register_target_handler` itself for that slot.

Power & temperature push
Single push entry-point for values that have no portable platform binding (battery rail, on-die temperature, ...). Integrators that sample these via ADC/sensor pass them in here whenever they have a fresh reading; libcoldwave caches the values and the connection loop publishes them on the DeviceService at the next sync.

Per-HW firmware-update tracking
Hooks libcoldwave into the coldwave-os OTA target callbacks so it can publish per-slot FU-state on the device service. Slot 0 is always libcoldwave's own SW-OTA — slots 1..(COLDWAVE_HW_SLOTS_MAX-1) are subprocessor targets that the integrator wires up. If libcoldwave is not registered for a slot, the application is free to call ota_register_target_handler itself for that slot.

Types

	Name
struct	coldwave_backend_t Backend connection parameters.
struct	coldwave_router_options_t
struct	coldwave_client_options_t
union	coldwave_options_t
struct	coldwave_init_t
struct	coldwave_status_t
struct	cw_conn_policy_t
struct	coldwave_lte_snapshot_t Last known LTE radio + cell state, as held in the library's cache.
enum	coldwave_result_t Result codes returned from the Coldwave public API.
enum	coldwave_node_t
enum	coldwave_net_device_type_t
enum	cw_transport_t
enum	cw_conn_state_t
enum	cw_reason_t
typedef int(*)(const flake::PropArray &rops)	coldwave_auth_callback_t
typedef void(*)(cw_transport_t transport, cw_conn_state_t st, cw_reason_t reason, uint32_t next_retry_ms)	coldwave_state_callback_t Connection-state observer callback. Invoked from the internal connection thread on every state change. Do NOT call mutating coldwave/service APIs from within it.

Functions Overview

	Name
void	coldwave_set_state_callback(coldwave_state_callback_t cb)
int	coldwave_get_status(coldwave_status_t * out)
const char *	cw_reason_str(cw_reason_t reason)
void	coldwave_conn_policy_defaults(coldwave_node_t node_type, cw_conn_policy_t * out)
int	coldwave_set_conn_policy(const cw_conn_policy_t * policy)
int	coldwave_init(const coldwave_init_t * init, const char * srv_uuid, flake::Service ** srv) Initialize the Coldwave library.
unsigned	coldwave_get_remaining_budget() Retrieves the remaining budget for the current month.
unsigned	coldwave_get_data_usage() Retrieves the transferred amount of data for the current month.
void	coldwave_reset_budget() Resets the monthly budget (cwClient only).
int	coldwave_register_service(const char * srv_uuid, flake::Service ** srv, const PropArray & initial_props =PropArray()) Registers a secondary service.
int	coldwave_backend_attach() Attach to the configured backend and start syncing.
int	coldwave_backend_detach() Detaches the Coldwave backend.
bool	coldwave_backend_attached() Whether the Coldwave backend is currently attached and online.
unsigned	coldwave_sync_failure_streak() Consecutive backend syncs that attempted a round-trip and failed (reset to 0 on the first successful sync).
bool	coldwave_sync_ok_age_ms(uint32_t * out_age_ms) Time since the last sync that actually reached the backend.
bool	coldwave_lte_peek(coldwave_lte_snapshot_t * out) Read the cached LTE state without touching the modem.
int	coldwave_uninit() Tear down the Coldwave library.
int	coldwave_ota_autoupdate_enable(bool e) Enable or disable automatic OTA updates.
bool	coldwave_ota_autoupdate_enabled() Whether OTA autoupdate is enabled.
int	coldwave_sign(const char * message, size_t message_len, const char signature_buf[(64)]) Sign a message using the device's private key.
int	coldwave_verify(const char * message, size_t message_len, const char signature_buf[(64)]) Verify a signature against a message using the device's public key.
int	coldwave_suspend() Suspend the connection management thread.
int	coldwave_resume() Resume connection management after a `[coldwave_suspend()](/embed/2.2.0/API//group__coldwave.md#function-coldwave-suspend)`.

Attributes

	Name
const char *	fqdn Fully-qualified backend host name.
unsigned char *	ca_cert DER-encoded CA cert; null => unencrypted UDP (PTP only).
unsigned	ca_cert_len Byte length of `ca_cert`.
int	no_local_tls if set, local connection will be unencrypted
uint16_t	local_tcp_port if 0, default port (9986/9987) is used
const char *	local_network_interface name of the interface to bind to, default null for all interfaces
coldwave_auth_callback_t	auth_callback called on every new local connection
int	auto_update_disabled if set, the CBE will not start OTA when new versions are available
int	max_clients maximum clients the router will accept, 0 for unlimited
unsigned	monthly_data_limit_bytes if not 0, monthly volume tracked for reporting (see coldwave_get_remaining_budget()); does not throttle syncing
unsigned	remaining_data_budget_bytes if not 0, the budget will be initialized with the remaining budget
int	desired_sync_interval_s
coldwave_router_options_t	router
coldwave_client_options_t	client
coldwave_node_t	node_type Client or router.
const char *	app_semver SemVer version string of current firmware app.
const char *	device_id Unique identifier for the device (required)
const char *	product_id Coldwave product identifier (4 alphanumeric characters)
const char *	hw_id Hardware (SoC) identifier for OTA updates.
coldwave_backend_t	backend Backend connection (required for cwClient)
int	net_device_handle Open-handle of the primary network device (open("modem0")/open("wlan0")/open("eth0")), -1 if none.
coldwave_net_device_type_t	net_device_type Kind of primary network device — drives MAC/LTE readout.
coldwave_options_t	opt Type-specific options.
cw_conn_state_t	state
cw_transport_t	transport
cw_reason_t	last_reason
uint32_t	retry_count
uint32_t	next_retry_ms
unsigned	remaining_budget_bytes
int	sync_interval_s
uint32_t	backoff_base_ms initial reconnect backoff (>=1)
uint32_t	backoff_cap_ms maximum reconnect backoff
uint32_t	jitter_ms random 0..jitter_ms added per backoff
uint16_t	mtu transport MTU for client connections
uint32_t	udp_idle_timeout_s UDP/DTLS inactivity timeout (client)
uint32_t	service_init_timeout_ms per-service registration / initial-sync timeout
int32_t	rsrp_dbm
int32_t	rsrq_db
int32_t	sinr_raw
uint16_t	mcc
uint16_t	mnc
uint32_t	lac
uint32_t	ci
uint8_t	rat
uint32_t	signal_age_ms
uint32_t	reg_age_ms
bool	signal_valid
bool	reg_valid
uint32_t	fields OR'd CW_POWER_INFO_* — only fields whose bit is set are read.
uint16_t	battery_mv Battery rail voltage in mV.
uint8_t	battery_pct Estimated battery state-of-charge in percent (0-100)
int16_t	temperature_c10 On-die / ambient temperature in deci-celsius (°C * 10)
uint8_t	slot 1..(COLDWAVE_HW_SLOTS_MAX-1); slot 0 is reserved for SW-OTA
int	ota_target_id Value used in `[ota_t::target](/embed/2.2.0/API/Classes/structota__t.md#variable-target)` / `ota_register_target_handler`.
void *	ctx Opaque context forwarded to the integrator callbacks.
cw_hw_ota_begin_t	on_begin Optional. Called when the OS-side OTA flow starts the target.
cw_hw_ota_append_t	on_append Required. Called for every chunk of bytes.
cw_hw_ota_finalize_t	on_finalize Optional. Called on successful completion.
cw_hw_ota_abort_t	on_abort Optional. Called on abort/failure.

Defines

Name
SSID_MAX_LEN
MAC_ADDR_LEN
IP_ADDR_LEN
COLDWAVE_INIT_DEFAULT
COLDWAVE_HAS_LTE_PEEK	Signals that this build exposes `[coldwave_lte_peek()](/embed/2.2.0/API//group__coldwave.md#function-coldwave-lte-peek)`.

Types Documentation

enum coldwave_result_t

Enumerator	Description
CW_OK	Success.
CW_ERR_FAILED	Generic failure (kept for compatibility with E_FAILED).
CW_ERR_NOT_INITIALIZED	coldwave_init() has not completed successfully.
CW_ERR_ALREADY_ATTACHED	coldwave_backend_attach() called while already attached.
CW_ERR_NOT_ATTACHED	Operation requires an attached backend.
CW_ERR_INVALID_ARG	A required parameter was null or out of range.
CW_ERR_NO_BACKEND	Backend FQDN missing or could not be resolved.
CW_ERR_NO_NETWORK_IF	No suitable network interface for the backend.
CW_ERR_TRANSPORT	Wire/transport setup failed.
CW_ERR_NOT_SUPPORTED	Feature compiled out (e.g. router disabled).

Result codes returned from the Coldwave public API.

The public surface uses the same numeric E_OK / E_FAILED constants as libflake; the values below are distinct error categories so callers can distinguish failure modes without parsing log output.

enum coldwave_node_t

Enumerator	Description
cwClient
cwRouter

enum coldwave_net_device_type_t

Enumerator	Description
cwNetNone
cwNetEthernet
cwNetWiFi
cwNetLte

Type of the primary network device used to reach the backend. Values align with NETIF_* in platform/network_if.h so the same enum can drive the P_DEVICE_IF_TYPE property.

enum cw_transport_t

Enumerator	Description
CW_TR_NONE	no active transport
CW_TR_CLOUD_UDP	client: plain UDP to backend
CW_TR_CLOUD_DTLS	client: DTLS to backend
CW_TR_CLOUD_TCP	router: reversed TCP to backend
CW_TR_LOCAL_TCP	router: local TCP server (LAN)
CW_TR_LOCAL_BLE	bridge: local BLE server (proximity, no IP)

Which transport the backend connection is currently using.

enum cw_conn_state_t

Enumerator	Description
CW_ST_STOPPED
CW_ST_DISCONNECTED
CW_ST_CONNECTING
CW_ST_ONLINE
CW_ST_BACKOFF
CW_ST_DETACHING
CW_ST_SUSPENDED

Public mirror of the internal connection state machine.

enum cw_reason_t

Enumerator	Description
CW_REASON_OK
CW_REASON_NO_NETWORK
CW_REASON_DNS_FAIL
CW_REASON_TLS_HANDSHAKE
CW_REASON_CERT_REJECT
CW_REASON_AUTH_REJECT
CW_REASON_TIMEOUT
CW_REASON_BUDGET_EXHAUSTED
CW_REASON_PEER_RESET

Note: Some reasons need typed errors from libflake to be reported precisely; until then the connect path reports best-effort values.

Structured reason for the most recent connection outcome. Prefixed CW_REASON_ to stay distinct from the coldwave_result_t CW_* codes.

typedef coldwave_auth_callback_t

cpp

typedef int(* coldwave_auth_callback_t) (const flake::PropArray &rops);

typedef coldwave_state_callback_t

cpp

typedef void(* coldwave_state_callback_t) (cw_transport_t transport, cw_conn_state_t st, cw_reason_t reason, uint32_t next_retry_ms);

Connection-state observer callback. Invoked from the internal connection thread on every state change. Do NOT call mutating coldwave/service APIs from within it.

Parameters:

next_retry_ms when st is CW_ST_BACKOFF, ms to the next attempt; else 0.

Function Details

function coldwave_set_state_callback

cpp

void coldwave_set_state_callback(
    coldwave_state_callback_t cb
)

function coldwave_get_status

cpp

int coldwave_get_status(
    coldwave_status_t * out
)

Return: CW_OK, or an error code.

Fill out with a current status snapshot.

function cw_reason_str

cpp

const char * cw_reason_str(
    cw_reason_t reason
)

Short human-readable string for a reason code (never NULL).

function coldwave_conn_policy_defaults

cpp

void coldwave_conn_policy_defaults(
    coldwave_node_t node_type,
    cw_conn_policy_t * out
)

Fill out with the default policy for a node type.

function coldwave_set_conn_policy

cpp

int coldwave_set_conn_policy(
    const cw_conn_policy_t * policy
)

Override the active connection policy (clamped); takes effect on next (re)connect.

function coldwave_init

cpp

int coldwave_init(
    const coldwave_init_t * init,
    const char * srv_uuid,
    flake::Service ** srv
)

Initialize the Coldwave library.

Parameters:

init Initialization parameters.
srv_uuid UUID for the primary application service.
srv Pointer to the application service. If *srv is null a default ServiceWrapper is allocated.

Return: CW_OK on success; otherwise a coldwave_result_t error code.

For cwClient nodes this creates the wire from init->backend, calls [flakeInitialize()](/embed/2.2.0/API/Files/_connection_8h.md#function-flakeinitialize) (which spins up the flake CoreWorker), and starts the internal connection thread in an idle state. No network traffic happens until [coldwave_backend_attach()](/embed/2.2.0/API//group__coldwave.md#function-coldwave-backend-attach) is called.

For cwRouter nodes this brings up the local server.

function coldwave_get_remaining_budget

cpp

unsigned coldwave_get_remaining_budget()

Retrieves the remaining budget for the current month.

Return: The remaining budget in bytes, or 0 if not initialized / no budget configured.

Only meaningful when running as cwClient with a non-zero monthly limit.

function coldwave_get_data_usage

cpp

unsigned coldwave_get_data_usage()

Retrieves the transferred amount of data for the current month.

Return: The used budget in bytes, or 0 if not initialized / no budget configured.

Only meaningful when running as cwClient

function coldwave_reset_budget

cpp

void coldwave_reset_budget()

Resets the monthly budget (cwClient only).

function coldwave_register_service

cpp

int coldwave_register_service(
    const char * srv_uuid,
    flake::Service ** srv,
    const PropArray & initial_props =PropArray()
)

Registers a secondary service.

Parameters:

srv_uuid The UUID of the service.
srv Pointer to the service. If *srv is null a default ServiceWrapper is allocated.

Return: CW_OK on success; otherwise a coldwave_result_t error code.

function coldwave_backend_attach

cpp

int coldwave_backend_attach()

Attach to the configured backend and start syncing.

Return: CW_OK if the attach was scheduled; CW_ERR_NOT_INITIALIZED if the library is not initialized; CW_ERR_ALREADY_ATTACHED if already attached; CW_ERR_NO_BACKEND if no backend FQDN was supplied at init.

Backend FQDN and (optional) CA certificate are taken from init->backend passed to [coldwave_init()](/embed/2.2.0/API//group__coldwave.md#function-coldwave-init). The call is non-blocking; the connection is established asynchronously by the internal connection thread.

function coldwave_backend_detach

cpp

int coldwave_backend_detach()

Detaches the Coldwave backend.

Return: CW_OK on success; otherwise a coldwave_result_t error code.

Disconnects from the backend but keeps the flake CoreWorker and the connection object alive so that [coldwave_backend_attach()](/embed/2.2.0/API//group__coldwave.md#function-coldwave-backend-attach) can be called again without going through [coldwave_init()](/embed/2.2.0/API//group__coldwave.md#function-coldwave-init).

function coldwave_backend_attached

cpp

bool coldwave_backend_attached()

Whether the Coldwave backend is currently attached and online.

function coldwave_sync_failure_streak

cpp

unsigned coldwave_sync_failure_streak()

Consecutive backend syncs that attempted a round-trip and failed (reset to 0 on the first successful sync).

Unlike [coldwave_backend_attached()](/embed/2.2.0/API//group__coldwave.md#function-coldwave-backend-attached)– a connection-setup flag that stays true even when every sync times out – this reflects real data-plane health. Idle cycles (E_NO_CHANGES) and locally refused syncs (E_REFUSED) do not inflate it. A product supervisor can treat a sustained streak as an "attached-but-dead" backend and escalate recovery (e.g. modem reset, then reboot).

function coldwave_sync_ok_age_ms

cpp

bool coldwave_sync_ok_age_ms(
    uint32_t * out_age_ms
)

Time since the last sync that actually reached the backend.

Parameters:

out_age_ms receives the elapsed milliseconds since the last E_OK sync. May be nullptr to probe only for the presence of a sample.

Return: false if no sync has ever succeeded since boot (out_age_ms is left untouched), true otherwise.

Prefer this over [coldwave_sync_failure_streak()](/embed/2.2.0/API//group__coldwave.md#function-coldwave-sync-failure-streak) for an "attached-but-dead" supervisor. The streak is cleared by the library's own recovery (COLDWAVE_SYNC_FAIL_RECONNECT), so any product threshold above that value is unreachable by construction. The age survives a recovery attempt: a reconnect that does not restore the backend leaves it growing.

The value is wrap-safe; a supervisor may compare it directly against a timeout. The false case is not an error – it is the pre-first-sync window, in which a liveness verdict is not yet meaningful.

function coldwave_lte_peek

cpp

bool coldwave_lte_peek(
    coldwave_lte_snapshot_t * out
)

Read the cached LTE state without touching the modem.

Parameters:

out receives the snapshot. Must not be nullptr.

Return: false if no LTE device is open, or if neither half has ever been sampled. true otherwise – check the per-half *_valid flags, since radio and cell identity are refreshed independently.

This is the non-blocking counterpart to the device_info_get_lte_* readers. Those refresh on the calling thread, and a refresh is three AT transactions that escape a live PPP session to command mode – each waiting on the modem driver's request mutex, whose bound is measured in minutes. A thread that must stay responsive (a link supervisor, a watchdog feeder) cannot afford that and calls this instead.

The cache is refreshed by the library's own connection loop. The snapshot therefore ages between calls; signal_age_ms / reg_age_ms let the caller decide whether it is still fresh enough, rather than this function guessing.

A caller polling faster than that loop can tell a new sample from a repeat: a half was refreshed since the previous visit exactly when its age is younger than the time that has passed since. This matters for anything that feeds the values into a time-decaying model – handing it the same reading twice makes a fluctuating link look steadier than it is.

function coldwave_uninit

cpp

int coldwave_uninit()

Tear down the Coldwave library.

Return: CW_OK on success; CW_ERR_NOT_INITIALIZED if the library was not initialized.

Disconnects the backend (if attached), stops internal threads, uninitializes flake and frees all owned resources.

function coldwave_ota_autoupdate_enable

cpp

int coldwave_ota_autoupdate_enable(
    bool e
)

Enable or disable automatic OTA updates.

Return: 0 on success, non-zero on failure.

function coldwave_ota_autoupdate_enabled

cpp

bool coldwave_ota_autoupdate_enabled()

Whether OTA autoupdate is enabled.

function coldwave_sign

cpp

int coldwave_sign(
    const char * message,
    size_t message_len,
    const char signature_buf[(64)]
)

Sign a message using the device's private key.

Return: E_OK on success, otherwise an error code.

function coldwave_verify

cpp

int coldwave_verify(
    const char * message,
    size_t message_len,
    const char signature_buf[(64)]
)

Verify a signature against a message using the device's public key.

Return: E_OK on success, otherwise an error code.

function coldwave_suspend

cpp

int coldwave_suspend()

Suspend the connection management thread.

Disconnects from the backend if connected but keeps the flake CoreWorker running and the connection object alive. Resume with [coldwave_resume()](/embed/2.2.0/API//group__coldwave.md#function-coldwave-resume).

function coldwave_resume

cpp

int coldwave_resume()

Resume connection management after a [coldwave_suspend()](/embed/2.2.0/API//group__coldwave.md#function-coldwave-suspend).

If the user previously called [coldwave_backend_attach()](/embed/2.2.0/API//group__coldwave.md#function-coldwave-backend-attach), reconnection will be triggered automatically.

Attributes Documentation

variable fqdn

cpp

const char* coldwave_backend_t::fqdn

Fully-qualified backend host name.

variable ca_cert

cpp

unsigned char* coldwave_backend_t::ca_cert

DER-encoded CA cert; null => unencrypted UDP (PTP only).

variable ca_cert_len

cpp

unsigned coldwave_backend_t::ca_cert_len

Byte length of ca_cert.

variable no_local_tls

cpp

int coldwave_router_options_t::no_local_tls

if set, local connection will be unencrypted

variable local_tcp_port

cpp

uint16_t coldwave_router_options_t::local_tcp_port

if 0, default port (9986/9987) is used

variable local_network_interface

cpp

const char* coldwave_router_options_t::local_network_interface

name of the interface to bind to, default null for all interfaces

variable auth_callback

cpp

coldwave_auth_callback_t coldwave_router_options_t::auth_callback

called on every new local connection

variable auto_update_disabled

cpp

int coldwave_router_options_t::auto_update_disabled

if set, the CBE will not start OTA when new versions are available

variable max_clients

cpp

int coldwave_router_options_t::max_clients

maximum clients the router will accept, 0 for unlimited

variable monthly_data_limit_bytes

cpp

unsigned coldwave_client_options_t::monthly_data_limit_bytes

if not 0, monthly volume tracked for reporting (see coldwave_get_remaining_budget()); does not throttle syncing

variable remaining_data_budget_bytes

cpp

unsigned coldwave_client_options_t::remaining_data_budget_bytes

if not 0, the budget will be initialized with the remaining budget

variable desired_sync_interval_s

cpp

int coldwave_client_options_t::desired_sync_interval_s

Deprecated:

ignored — syncs are no longer paced on-device, rate limiting is enforced by the backend

variable router

cpp

coldwave_router_options_t coldwave_options_t::router

variable client

cpp

coldwave_client_options_t coldwave_options_t::client

variable node_type

cpp

coldwave_node_t coldwave_init_t::node_type

Client or router.

variable app_semver

cpp

const char* coldwave_init_t::app_semver

SemVer version string of current firmware app.

variable device_id

cpp

const char* coldwave_init_t::device_id

Unique identifier for the device (required)

variable product_id

cpp

const char* coldwave_init_t::product_id

Coldwave product identifier (4 alphanumeric characters)

variable hw_id

cpp

const char* coldwave_init_t::hw_id

Hardware (SoC) identifier for OTA updates.

variable backend

cpp

coldwave_backend_t coldwave_init_t::backend

Backend connection (required for cwClient)

variable net_device_handle

cpp

int coldwave_init_t::net_device_handle

Open-handle of the primary network device (open("modem0")/open("wlan0")/open("eth0")), -1 if none.

variable net_device_type

cpp

coldwave_net_device_type_t coldwave_init_t::net_device_type

Kind of primary network device — drives MAC/LTE readout.

variable opt

cpp

coldwave_options_t coldwave_init_t::opt

Type-specific options.

variable state

cpp

cw_conn_state_t coldwave_status_t::state

variable transport

cpp

cw_transport_t coldwave_status_t::transport

variable last_reason

cpp

cw_reason_t coldwave_status_t::last_reason

variable retry_count

cpp

uint32_t coldwave_status_t::retry_count

variable next_retry_ms

cpp

uint32_t coldwave_status_t::next_retry_ms

variable remaining_budget_bytes

cpp

unsigned coldwave_status_t::remaining_budget_bytes

variable sync_interval_s

cpp

int coldwave_status_t::sync_interval_s

Deprecated:

always 0 — syncs are no longer paced on-device

variable backoff_base_ms

cpp

uint32_t cw_conn_policy_t::backoff_base_ms

initial reconnect backoff (>=1)

variable backoff_cap_ms

cpp

uint32_t cw_conn_policy_t::backoff_cap_ms

maximum reconnect backoff

variable jitter_ms

cpp

uint32_t cw_conn_policy_t::jitter_ms

random 0..jitter_ms added per backoff

variable mtu

cpp

uint16_t cw_conn_policy_t::mtu

transport MTU for client connections

variable udp_idle_timeout_s

cpp

uint32_t cw_conn_policy_t::udp_idle_timeout_s

UDP/DTLS inactivity timeout (client)

variable service_init_timeout_ms

cpp

uint32_t cw_conn_policy_t::service_init_timeout_ms

per-service registration / initial-sync timeout

variable rsrp_dbm

cpp

int32_t coldwave_lte_snapshot_t::rsrp_dbm

as reported by the modem

variable rsrq_db

cpp

int32_t coldwave_lte_snapshot_t::rsrq_db

variable sinr_raw

cpp

int32_t coldwave_lte_snapshot_t::sinr_raw

raw register value, NOT dB

variable mcc

cpp

uint16_t coldwave_lte_snapshot_t::mcc

variable mnc

cpp

uint16_t coldwave_lte_snapshot_t::mnc

variable lac

cpp

uint32_t coldwave_lte_snapshot_t::lac

variable ci

cpp

uint32_t coldwave_lte_snapshot_t::ci

variable rat

cpp

uint8_t coldwave_lte_snapshot_t::rat

variable signal_age_ms

cpp

uint32_t coldwave_lte_snapshot_t::signal_age_ms

since the radio values were refreshed

variable reg_age_ms

cpp

uint32_t coldwave_lte_snapshot_t::reg_age_ms

since the cell identity was refreshed

variable signal_valid

cpp

bool coldwave_lte_snapshot_t::signal_valid

false until a first radio sample succeeded

variable reg_valid

cpp

bool coldwave_lte_snapshot_t::reg_valid

false until a first cell identity was parsed

variable fields

cpp

uint32_t cw_power_info_t::fields

OR'd CW_POWER_INFO_* — only fields whose bit is set are read.

variable battery_mv

cpp

uint16_t cw_power_info_t::battery_mv

Battery rail voltage in mV.

variable battery_pct

cpp

uint8_t cw_power_info_t::battery_pct

Estimated battery state-of-charge in percent (0-100)

variable temperature_c10

cpp

int16_t cw_power_info_t::temperature_c10

On-die / ambient temperature in deci-celsius (°C * 10)

variable slot

cpp

uint8_t cw_hw_ota_target_t::slot

1..(COLDWAVE_HW_SLOTS_MAX-1); slot 0 is reserved for SW-OTA

variable ota_target_id

cpp

int cw_hw_ota_target_t::ota_target_id

Value used in [ota_t::target](/embed/2.2.0/API/Classes/structota__t.md#variable-target) / ota_register_target_handler.

variable ctx

cpp

void* cw_hw_ota_target_t::ctx

Opaque context forwarded to the integrator callbacks.

variable on_begin

cpp

cw_hw_ota_begin_t cw_hw_ota_target_t::on_begin

Optional. Called when the OS-side OTA flow starts the target.

variable on_append

cpp

cw_hw_ota_append_t cw_hw_ota_target_t::on_append

Required. Called for every chunk of bytes.

variable on_finalize

cpp

cw_hw_ota_finalize_t cw_hw_ota_target_t::on_finalize

Optional. Called on successful completion.

variable on_abort

cpp

cw_hw_ota_abort_t cw_hw_ota_target_t::on_abort

Optional. Called on abort/failure.

Macros Documentation

define SSID_MAX_LEN

cpp

#define SSID_MAX_LEN 32

define MAC_ADDR_LEN

cpp

#define MAC_ADDR_LEN 6

define IP_ADDR_LEN

cpp

#define IP_ADDR_LEN 4

define COLDWAVE_INIT_DEFAULT

cpp

#define COLDWAVE_INIT_DEFAULT {                                                   \
    /* .node_type        */ cwClient,               \
    /* .app_semver       */ nullptr,                \
    /* .device_id        */ nullptr,                \
    /* .product_id       */ nullptr,                \
    /* .hw_id            */ "default",              \
    /* .backend          */ { nullptr, nullptr, 0 },\
    /* .net_device_handle*/ -1,                     \
    /* .net_device_type  */ cwNetNone,              \
    /* .opt              */ { {                     \
    /*   .no_local_tls   */ 0,                      \
    /*   .local_tcp_port */ 9986,                   \
    /*   .local_network_interface */ nullptr,       \
    /*   .auth_callback  */ nullptr,                \
    /*   .auto_update_disabled */ 0,                \
    /*   .max_clients    */ 0                       \
    } }                                             \
}

define COLDWAVE_HAS_LTE_PEEK

cpp

#define COLDWAVE_HAS_LTE_PEEK 1

Signals that this build exposes [coldwave_lte_peek()](/embed/2.2.0/API//group__coldwave.md#function-coldwave-lte-peek).

A consumer that must also compile against an older SDK guards its use of the snapshot on this macro and keeps its own modem query as the fallback.

Coldwave API ​

Modules ​

Types ​

Functions Overview ​

Attributes ​

Defines ​

Types Documentation ​

enum coldwave_result_t ​

enum coldwave_node_t ​

enum coldwave_net_device_type_t ​

enum cw_transport_t ​

enum cw_conn_state_t ​

enum cw_reason_t ​

typedef coldwave_auth_callback_t ​

typedef coldwave_state_callback_t ​

Function Details ​

function coldwave_set_state_callback ​

function coldwave_get_status ​

function cw_reason_str ​

function coldwave_conn_policy_defaults ​

function coldwave_set_conn_policy ​

function coldwave_init ​

function coldwave_get_remaining_budget ​

function coldwave_get_data_usage ​

function coldwave_reset_budget ​

function coldwave_register_service ​

function coldwave_backend_attach ​

function coldwave_backend_detach ​

function coldwave_backend_attached ​

function coldwave_sync_failure_streak ​

function coldwave_sync_ok_age_ms ​

function coldwave_lte_peek ​

function coldwave_uninit ​

function coldwave_ota_autoupdate_enable ​

function coldwave_ota_autoupdate_enabled ​

function coldwave_sign ​

function coldwave_verify ​

function coldwave_suspend ​

function coldwave_resume ​

Attributes Documentation ​

variable fqdn ​

variable ca_cert ​

variable ca_cert_len ​

variable no_local_tls ​

variable local_tcp_port ​

variable local_network_interface ​

variable auth_callback ​

variable auto_update_disabled ​

variable max_clients ​

variable monthly_data_limit_bytes ​

variable remaining_data_budget_bytes ​

variable desired_sync_interval_s ​

variable router ​

variable client ​

variable node_type ​

variable app_semver ​

variable device_id ​

variable product_id ​

variable hw_id ​

variable backend ​

variable net_device_handle ​

variable net_device_type ​

variable opt ​

variable state ​

variable transport ​

variable last_reason ​

variable retry_count ​

variable next_retry_ms ​

variable remaining_budget_bytes ​

variable sync_interval_s ​

variable backoff_base_ms ​

variable backoff_cap_ms ​

variable jitter_ms ​

variable mtu ​

variable udp_idle_timeout_s ​

variable service_init_timeout_ms ​

variable rsrp_dbm ​

variable rsrq_db ​

variable sinr_raw ​

variable mcc ​

Coldwave API

Modules

Types

Functions Overview

Attributes

Defines

Types Documentation

enum coldwave_result_t

enum coldwave_node_t

enum coldwave_net_device_type_t

enum cw_transport_t

enum cw_conn_state_t

enum cw_reason_t

typedef coldwave_auth_callback_t

typedef coldwave_state_callback_t

Function Details

function coldwave_set_state_callback

function coldwave_get_status

function cw_reason_str

function coldwave_conn_policy_defaults

function coldwave_set_conn_policy

function coldwave_init

function coldwave_get_remaining_budget

function coldwave_get_data_usage

function coldwave_reset_budget

function coldwave_register_service

function coldwave_backend_attach

function coldwave_backend_detach

function coldwave_backend_attached

function coldwave_sync_failure_streak

function coldwave_sync_ok_age_ms

function coldwave_lte_peek

function coldwave_uninit

function coldwave_ota_autoupdate_enable

function coldwave_ota_autoupdate_enabled

function coldwave_sign

function coldwave_verify

function coldwave_suspend

function coldwave_resume

Attributes Documentation

variable fqdn

variable ca_cert

variable ca_cert_len

variable no_local_tls

variable local_tcp_port

variable local_network_interface

variable auth_callback

variable auto_update_disabled

variable max_clients

variable monthly_data_limit_bytes

variable remaining_data_budget_bytes

variable desired_sync_interval_s

variable router

variable client

variable node_type

variable app_semver

variable device_id

variable product_id

variable hw_id

variable backend

variable net_device_handle

variable net_device_type

variable opt

variable state

variable transport

variable last_reason

variable retry_count

variable next_retry_ms

variable remaining_budget_bytes

variable sync_interval_s

variable backoff_base_ms

variable backoff_cap_ms

variable jitter_ms

variable mtu

variable udp_idle_timeout_s

variable service_init_timeout_ms

variable rsrp_dbm

variable rsrq_db

variable sinr_raw

variable mcc