Skip to content

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
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
structcoldwave_backend_t
Backend connection parameters.
structcoldwave_router_options_t
structcoldwave_client_options_t
unioncoldwave_options_t
structcw_persist_t
Reboot-fester Speicher fuer den NH2N-Zustand (Reconnect-Leiter, 24-h-Zaehler, NAT-Keepalive).
structcoldwave_init_t
structcoldwave_status_t
structcw_conn_policy_t
structcoldwave_lte_snapshot_t
Last known LTE radio + cell state, as held in the library's cache.
enumcoldwave_result_t
Result codes returned from the Coldwave public API.
enumcoldwave_node_t
enumcoldwave_net_device_type_t
enumcw_transport_t
enumcw_conn_state_t
enumcw_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
voidcoldwave_set_state_callback(coldwave_state_callback_t cb)
intcoldwave_get_status(coldwave_status_t * out)
const char *cw_reason_str(cw_reason_t reason)
voidcoldwave_conn_policy_defaults(coldwave_node_t node_type, cw_conn_policy_t * out)
intcoldwave_set_conn_policy(const cw_conn_policy_t * policy)
intcoldwave_init(const coldwave_init_t * init, const char * srv_uuid, flake::Service ** srv)
Initialize the Coldwave library.
unsignedcoldwave_get_remaining_budget()
Retrieves the remaining budget for the current month.
unsignedcoldwave_get_data_usage()
Retrieves the transferred amount of data for the current month.
voidcoldwave_reset_budget()
Resets the monthly budget (cwClient only).
intcoldwave_register_service(const char * srv_uuid, flake::Service ** srv, const PropArray & initial_props =PropArray())
Registers a secondary service.
intcoldwave_backend_attach()
Attach to the configured backend and start syncing.
intcoldwave_backend_detach()
Detaches the Coldwave backend.
boolcoldwave_backend_attached()
Whether the Coldwave backend is currently attached and online.
unsignedcoldwave_sync_failure_streak()
Consecutive backend syncs that attempted a round-trip and failed (reset to 0 on the first successful sync).
boolcoldwave_sync_ok_age_ms(uint32_t * out_age_ms)
Time since the last sync that actually reached the backend.
boolcoldwave_peer_rx_age_ms(uint32_t * out_age_ms)
Time since the last datagram RECEIVED from the backend peer.
boolcoldwave_contact_interval_ms(uint32_t * out_ms)
Kontaktintervall, auf das sich Geraet und Router geeinigt haben.
boolcoldwave_peer_tx_age_ms(uint32_t * out_age_ms)
Zeit seit dem letzten Sendeversuch zum Backend (Sync oder Connect).
boolcoldwave_conn_progress_age_ms(uint32_t * out_age_ms)
Zeit seit dem letzten vollstaendigen Durchlauf des Verbindungsthreads.
intcoldwave_mark_immediate(flake::Service * srv, const cw_tag_range_t * ranges, size_t count)
Tag-Bereiche, die auf srv sofort gesendet werden.
intcoldwave_mark_history(flake::Service * srv, const cw_tag_range_t * ranges, size_t count, uint8_t history_class)
History-Klasse fuer Tag-Bereiche auf srv.
boolcoldwave_report_window_ms(uint32_t * out_ms)
Laenge des Report-Fensters, solange es aktiv ist.
intcoldwave_flush_now()
Sendet alles Aufgelaufene aller Services sofort, ohne zu blockieren.
intcoldwave_report_power_state(uint8_t state)
Last Gasp: setzt P_POWER_STATE und sendet sofort, ohne zu blockieren.
cw_link_class_tcoldwave_link_class()
cw_send_mode_tcoldwave_send_mode()
boolcoldwave_lte_peek(coldwave_lte_snapshot_t * out)
Read the cached LTE state without touching the modem.
intcoldwave_uninit()
Tear down the Coldwave library.
intcoldwave_ota_autoupdate_enable(bool e)
Enable or disable automatic OTA updates.
boolcoldwave_ota_autoupdate_enabled()
Whether OTA autoupdate is enabled.
intcoldwave_sign(const char * message, size_t message_len, const char signature_buf[(64)])
Sign a message using the device's private key.
intcoldwave_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.
intcoldwave_suspend()
Suspend the connection management thread.
intcoldwave_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).
unsignedca_cert_len
const char *push_sources
intno_local_tls
if set, local connection will be unencrypted
uint16_tlocal_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_tauth_callback
called on every new local connection
intauto_update_disabled
if set, the CBE will not start OTA when new versions are available
intmax_clients
maximum clients the router will accept, 0 for unlimited
unsignedmonthly_data_limit_bytes
if not 0, monthly volume tracked for reporting (see coldwave_get_remaining_budget()); does not throttle syncing
unsignedremaining_data_budget_bytes
if not 0, the budget will be initialized with the remaining budget
intdesired_sync_interval_s
uint32_tnat_keepalive_s
SIM hinter Carrier-NAT (z. B. 1NCE): Keepalive in s, 0 = kein NAT. Ein Backend-Write auf P_NAT_KEEPALIVE_S hat Vorrang.
coldwave_router_options_trouter
coldwave_client_options_tclient
int(*)(void *ctx, uint16_t key, void *buf, size_t len)read
int(*)(void *ctx, uint16_t key, const void *buf, size_t len)write
void *ctx
coldwave_node_tnode_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_tbackend
Backend connection (required for cwClient)
intnet_device_handle
Open-handle of the primary network device (open("modem0")/open("wlan0")/open("eth0")), -1 if none.
coldwave_net_device_type_tnet_device_type
Kind of primary network device — drives MAC/LTE readout.
coldwave_options_topt
Type-specific options.
cw_persist_tpersist
optional, see cw_persist_t
cw_conn_state_tstate
cw_transport_ttransport
cw_reason_tlast_reason
uint32_tretry_count
uint32_tnext_retry_ms
unsignedremaining_budget_bytes
intsync_interval_s
uint32_tbackoff_base_ms
initial reconnect backoff (>=1)
uint32_tbackoff_cap_ms
maximum reconnect backoff
uint32_tjitter_ms
random 0..jitter_ms added per backoff
uint16_tmtu
transport MTU for client connections
uint32_tudp_idle_timeout_s
UDP/DTLS inactivity timeout (client)
uint32_tservice_init_timeout_ms
per-service registration / initial-sync timeout
uint32_tsync_timeout_ms
wait for a sync answer (liveness, heartbeat, first sync); 0 = default 5000
uint32_tsync_fail_reconnect
unanswered syncs in a row before the transport is rebuilt; 0 = default 3
cw_lp_profile_tltem
LTE-M, 2G und unbekannte Technik auf einem Modem.
cw_lp_profile_tnbiot
NB-IoT.
uint32_tstartup_jitter_ms
erster Connect nach dem Boot wartet U(0, x), nur Mobilfunk; 0 = Vorgabe (aus)
uint32_tsession_idle_ms
Sofort-Sitzung endet nach so viel Stream-Stille; 0 = 30 min.
uint8_ttraffic_policy
CW_TRAFFIC_*.
uint32_tstable_session_ms
so lange online setzt die Reconnect-Leiter zurueck; 0 = max(10 min, Rueckweg-Wache), CW_LP_OFF = nur ein beantworteter Sync
int32_trsrp_dbm
int32_trsrq_db
int32_tsinr_raw
uint16_tmcc
uint16_tmnc
uint32_tlac
uint32_tci
uint8_trat
uint32_tsignal_age_ms
uint32_treg_age_ms
boolsignal_valid
boolreg_valid
uint32_tfields
OR'd CW_POWER_INFO_* — only fields whose bit is set are read.
uint16_tbattery_mv
Battery rail voltage in mV.
uint8_tbattery_pct
Estimated battery state-of-charge in percent (0-100)
int16_ttemperature_c10
On-die / ambient temperature in deci-celsius (°C * 10)
uint8_tslot
1..(COLDWAVE_HW_SLOTS_MAX-1); slot 0 is reserved for SW-OTA
intota_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_ton_begin
Optional. Called when the OS-side OTA flow starts the target.
cw_hw_ota_append_ton_append
Required. Called for every chunk of bytes.
cw_hw_ota_finalize_ton_finalize
Optional. Called on successful completion.
cw_hw_ota_abort_ton_abort
Optional. Called on abort/failure.

Defines ​

Name
SSID_MAX_LEN
MAC_ADDR_LEN
IP_ADDR_LEN
COLDWAVE_INIT_DEFAULT
CW_TRAFFIC_AUTO
CW_TRAFFIC_OFF
CW_TRAFFIC_FORCE
COLDWAVE_HAS_CONTACT_INTERVALFeature-Makros fuer Verbraucher, die auch gegen aeltere SDKs bauen.
COLDWAVE_HAS_PEER_TX_AGE
COLDWAVE_HAS_CONN_PROGRESS
COLDWAVE_HAS_POWER_STATE
COLDWAVE_HAS_REPORT_WINDOW
COLDWAVE_HAS_IMMEDIATE
COLDWAVE_HAS_HISTORY_CLASS
CW_HISTORY_CONDENSABLEHistory-Klassen je Property (README "History auf NB-IoT"), Werte wie libflake.
CW_HISTORY_COMPLETEnie ausgeduennt
CW_HISTORY_LATESTbei knappem Budget nur der Endwert je Fenster
COLDWAVE_HAS_LTE_PEEKSignals 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 ​

EnumeratorDescription
CW_OKSuccess.
CW_ERR_FAILEDGeneric failure (kept for compatibility with E_FAILED).
CW_ERR_NOT_INITIALIZEDcoldwave_init() has not completed successfully.
CW_ERR_ALREADY_ATTACHEDcoldwave_backend_attach() called while already attached.
CW_ERR_NOT_ATTACHEDOperation requires an attached backend.
CW_ERR_INVALID_ARGA required parameter was null or out of range.
CW_ERR_NO_BACKENDBackend FQDN missing or could not be resolved.
CW_ERR_NO_NETWORK_IFNo suitable network interface for the backend.
CW_ERR_TRANSPORTWire/transport setup failed.
CW_ERR_NOT_SUPPORTEDFeature 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 ​

EnumeratorDescription
cwClient
cwRouter

enum coldwave_net_device_type_t ​

EnumeratorDescription
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 ​

EnumeratorDescription
CW_TR_NONEno active transport
CW_TR_CLOUD_UDPclient: plain UDP to backend
CW_TR_CLOUD_DTLSclient: DTLS to backend
CW_TR_CLOUD_TCProuter: reversed TCP to backend
CW_TR_LOCAL_TCProuter: local TCP server (LAN)
CW_TR_LOCAL_BLEbridge: local BLE server (proximity, no IP)

Which transport the backend connection is currently using.

enum cw_conn_state_t ​

EnumeratorDescription
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 ​

EnumeratorDescription
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
)

Register a connection-state observer (NULL clears it).

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_peer_rx_age_ms ​

cpp
bool coldwave_peer_rx_age_ms(
    uint32_t * out_age_ms
)

Time since the last datagram RECEIVED from the backend peer.

Parameters:

  • out_age_ms receives the elapsed milliseconds since the last datagram arrived from the CBE peer on the flake (D)TLS wire. May be nullptr to probe only for the presence of a sample.

Return: false if no datagram has ever been received since boot (out_age_ms is left untouched) – the pre-first-attach window; true otherwise. On a host build without a datagram wire, always false.

The strongest "attached-but-dead" signal, and unlike [coldwave_sync_ok_age_ms()](/embed/2.2.0/API//group__coldwave.md#function-coldwave-sync-ok-age-ms) it is not gated on a past success: a silent return path never produces the E_OK that ages that value, so a device wedged from its first mute datagram would never be declared dead by it. A received datagram cannot be forged –[sendto()](/embed/2.2.0/API//group__tcpip.md#function-sendto) succeeds locally into a dead path, and NTP/DNS/ICMP keep a netif counter alive while the backend session is gone. Stamped in the receive BIO (handshake included), so it carries for the whole session once attached.

The value is wrap-safe; a supervisor may compare it directly against a timeout.

function coldwave_contact_interval_ms ​

cpp
bool coldwave_contact_interval_ms(
    uint32_t * out_ms
)

Kontaktintervall, auf das sich Geraet und Router geeinigt haben.

Return: true nur, solange die Verkehrsfunktionen aktiv sind – der Router hat das angekuendigte Intervall bestaetigt. Dann sendet das Geraet spaetestens nach *out_ms Stille selbst, und Wachen ueber dem Geraet (Totmann, Modem-Waechter) leiten ihre Fristen daraus ab. false: kein Echo, die bisherigen festen Fristen gelten weiter.

function coldwave_peer_tx_age_ms ​

cpp
bool coldwave_peer_tx_age_ms(
    uint32_t * out_age_ms
)

Zeit seit dem letzten Sendeversuch zum Backend (Sync oder Connect).

Return: false, solange noch nie gesendet wurde.

function coldwave_conn_progress_age_ms ​

cpp
bool coldwave_conn_progress_age_ms(
    uint32_t * out_age_ms
)

Zeit seit dem letzten vollstaendigen Durchlauf des Verbindungsthreads.

Ein Wert weit ueber der laengsten Sync-Frist heisst: der Thread steht. Das ist die einzige Lage, in der ein Neustart durch das Produkt etwas heilt.

function coldwave_mark_immediate ​

cpp
int coldwave_mark_immediate(
    flake::Service * srv,
    const cw_tag_range_t * ranges,
    size_t count
)

Tag-Bereiche, die auf srv sofort gesendet werden.

Alles andere sammelt die Plattform zu einem Report je Fenster. Gilt je Service, denn dieselbe ID kann auf zwei Services Verschiedenes bedeuten. srv muss ein von libcoldwave angelegter Service sein.

function coldwave_mark_history ​

cpp
int coldwave_mark_history(
    flake::Service * srv,
    const cw_tag_range_t * ranges,
    size_t count,
    uint8_t history_class
)

History-Klasse fuer Tag-Bereiche auf srv.

Return: CW_ERR_NOT_SUPPORTED, wenn der libflake-Pin keine History-Klassen kennt.

Wirkt erst, wenn das NB-IoT-Monatsbudget knapp wird. Einmal je Klasse und Service, vor dem ersten set(); hoechstens acht Bereiche je Klasse.

function coldwave_report_window_ms ​

cpp
bool coldwave_report_window_ms(
    uint32_t * out_ms
)

Laenge des Report-Fensters, solange es aktiv ist.

Return: true nur, wenn die Verkehrsfunktionen aktiv sind und libflake verlustfrei ablegen kann; dann sammelt libcoldwave, und ein Produkt darf seine eigenen Sammelfenster abgeben und je Aenderung sync() rufen.

function coldwave_flush_now ​

cpp
int coldwave_flush_now()

Sendet alles Aufgelaufene aller Services sofort, ohne zu blockieren.

function coldwave_report_power_state ​

cpp
int coldwave_report_power_state(
    uint8_t state
)

Last Gasp: setzt P_POWER_STATE und sendet sofort, ohne zu blockieren.

Parameters:

  • state 0 Netz, 1 Netzausfall erkannt, 2 Abschaltung.
cpp
cw_link_class_t coldwave_link_class()

Aktuelle Funktechnik-Klasse, wie in P_LINK_CLASS.

function coldwave_send_mode ​

cpp
cw_send_mode_t coldwave_send_mode()

Aktueller Sendemodus, wie in P_SEND_MODE.

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 push_sources ​

cpp
const char* coldwave_backend_t::push_sources

Forwarder subnets from which server-initiated records are accepted after the load balancer forgot the flow (direct return path), e.g. "10.3.192.0/18,10.3.200.0/24:9994". Ring-specific like the FQDN; null = off.

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 nat_keepalive_s ​

cpp
uint32_t coldwave_client_options_t::nat_keepalive_s

SIM hinter Carrier-NAT (z. B. 1NCE): Keepalive in s, 0 = kein NAT. Ein Backend-Write auf P_NAT_KEEPALIVE_S hat Vorrang.

variable router ​

cpp
coldwave_router_options_t coldwave_options_t::router

variable client ​

cpp
coldwave_client_options_t coldwave_options_t::client

variable read ​

cpp
int(* cw_persist_t::read) (void *ctx, uint16_t key, void *buf, size_t len)

variable write ​

cpp
int(* cw_persist_t::write) (void *ctx, uint16_t key, const void *buf, size_t len)

variable ctx ​

cpp
void* cw_persist_t::ctx

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 persist ​

cpp
cw_persist_t coldwave_init_t::persist

optional, see cw_persist_t

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 sync_timeout_ms ​

cpp
uint32_t cw_conn_policy_t::sync_timeout_ms

wait for a sync answer (liveness, heartbeat, first sync); 0 = default 5000

variable sync_fail_reconnect ​

cpp
uint32_t cw_conn_policy_t::sync_fail_reconnect

unanswered syncs in a row before the transport is rebuilt; 0 = default 3

variable ltem ​

cpp
cw_lp_profile_t cw_conn_policy_t::ltem

LTE-M, 2G und unbekannte Technik auf einem Modem.

variable nbiot ​

cpp
cw_lp_profile_t cw_conn_policy_t::nbiot

NB-IoT.

variable startup_jitter_ms ​

cpp
uint32_t cw_conn_policy_t::startup_jitter_ms

erster Connect nach dem Boot wartet U(0, x), nur Mobilfunk; 0 = Vorgabe (aus)

variable session_idle_ms ​

cpp
uint32_t cw_conn_policy_t::session_idle_ms

Sofort-Sitzung endet nach so viel Stream-Stille; 0 = 30 min.

variable traffic_policy ​

cpp
uint8_t cw_conn_policy_t::traffic_policy

CW_TRAFFIC_*.

variable stable_session_ms ​

cpp
uint32_t cw_conn_policy_t::stable_session_ms

so lange online setzt die Reconnect-Leiter zurueck; 0 = max(10 min, Rueckweg-Wache), CW_LP_OFF = nur ein beantworteter Sync

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, nullptr },\
    /* .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                       \
    } },                                            \
    /* .persist          */ { nullptr, nullptr, nullptr } \
}

define CW_TRAFFIC_AUTO ​

cpp
#define CW_TRAFFIC_AUTO (0u)

Verkehrsfunktionen: kein Heartbeat, Monitoring-Meldung in Stille, Report- Fenster, Deckel und Wachen aus dem Kontaktintervall.

AUTO schaltet sie je Verbindung nur ein, wenn der Router das angekuendigte Kontaktintervall (flake-Parameter CONTACT_INTERVAL 0x0040) in der connect-Bestaetigung zurueckgibt. Ein Router ohne diese Faehigkeit pingt weiter alle 30 s; gegen ihn bleibt das Verhalten wie zuvor. FORCE ist fuer Bench und Tests.

define CW_TRAFFIC_OFF ​

cpp
#define CW_TRAFFIC_OFF (1u)

define CW_TRAFFIC_FORCE ​

cpp
#define CW_TRAFFIC_FORCE (2u)

define COLDWAVE_HAS_CONTACT_INTERVAL ​

cpp
#define COLDWAVE_HAS_CONTACT_INTERVAL 1

Feature-Makros fuer Verbraucher, die auch gegen aeltere SDKs bauen.

define COLDWAVE_HAS_PEER_TX_AGE ​

cpp
#define COLDWAVE_HAS_PEER_TX_AGE 1

define COLDWAVE_HAS_CONN_PROGRESS ​

cpp
#define COLDWAVE_HAS_CONN_PROGRESS 1

define COLDWAVE_HAS_POWER_STATE ​

cpp
#define COLDWAVE_HAS_POWER_STATE 1

define COLDWAVE_HAS_REPORT_WINDOW ​

cpp
#define COLDWAVE_HAS_REPORT_WINDOW 1

define COLDWAVE_HAS_IMMEDIATE ​

cpp
#define COLDWAVE_HAS_IMMEDIATE 1

define COLDWAVE_HAS_HISTORY_CLASS ​

cpp
#define COLDWAVE_HAS_HISTORY_CLASS 1

define CW_HISTORY_CONDENSABLE ​

cpp
#define CW_HISTORY_CONDENSABLE (0u)

History-Klassen je Property (README "History auf NB-IoT"), Werte wie libflake.

Standard; muss nie registriert werden

define CW_HISTORY_COMPLETE ​

cpp
#define CW_HISTORY_COMPLETE (1u)

nie ausgeduennt

define CW_HISTORY_LATEST ​

cpp
#define CW_HISTORY_LATEST (2u)

bei knappem Budget nur der Endwert je Fenster

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.