Appearance
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 | |
|---|---|
| struct | coldwave_backend_t Backend connection parameters. |
| struct | coldwave_router_options_t |
| struct | coldwave_client_options_t |
| union | coldwave_options_t |
| struct | cw_persist_t Reboot-fester Speicher fuer den NH2N-Zustand (Reconnect-Leiter, 24-h-Zaehler, NAT-Keepalive). |
| 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_peer_rx_age_ms(uint32_t * out_age_ms) Time since the last datagram RECEIVED from the backend peer. |
| bool | coldwave_contact_interval_ms(uint32_t * out_ms) Kontaktintervall, auf das sich Geraet und Router geeinigt haben. |
| bool | coldwave_peer_tx_age_ms(uint32_t * out_age_ms) Zeit seit dem letzten Sendeversuch zum Backend (Sync oder Connect). |
| bool | coldwave_conn_progress_age_ms(uint32_t * out_age_ms) Zeit seit dem letzten vollstaendigen Durchlauf des Verbindungsthreads. |
| int | coldwave_mark_immediate(flake::Service * srv, const cw_tag_range_t * ranges, size_t count) Tag-Bereiche, die auf srv sofort gesendet werden. |
| 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. |
| bool | coldwave_report_window_ms(uint32_t * out_ms) Laenge des Report-Fensters, solange es aktiv ist. |
| int | coldwave_flush_now() Sendet alles Aufgelaufene aller Services sofort, ohne zu blockieren. |
| int | coldwave_report_power_state(uint8_t state) Last Gasp: setzt P_POWER_STATE und sendet sofort, ohne zu blockieren. |
| cw_link_class_t | coldwave_link_class() |
| cw_send_mode_t | coldwave_send_mode() |
| 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 |
| const char * | push_sources |
| 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 |
| uint32_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. |
| coldwave_router_options_t | router |
| coldwave_client_options_t | client |
| 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_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_persist_t | persist optional, see cw_persist_t |
| 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 |
| uint32_t | sync_timeout_ms wait for a sync answer (liveness, heartbeat, first sync); 0 = default 5000 |
| uint32_t | sync_fail_reconnect unanswered syncs in a row before the transport is rebuilt; 0 = default 3 |
| cw_lp_profile_t | ltem LTE-M, 2G und unbekannte Technik auf einem Modem. |
| cw_lp_profile_t | nbiot NB-IoT. |
| uint32_t | startup_jitter_ms erster Connect nach dem Boot wartet U(0, x), nur Mobilfunk; 0 = Vorgabe (aus) |
| uint32_t | session_idle_ms Sofort-Sitzung endet nach so viel Stream-Stille; 0 = 30 min. |
| uint8_t | traffic_policy CW_TRAFFIC_*. |
| uint32_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 |
| 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 | |
| CW_TRAFFIC_AUTO | |
| CW_TRAFFIC_OFF | |
| CW_TRAFFIC_FORCE | |
| COLDWAVE_HAS_CONTACT_INTERVAL | Feature-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_CONDENSABLE | History-Klassen je Property (README "History auf NB-IoT"), Werte wie libflake. |
| CW_HISTORY_COMPLETE | nie ausgeduennt |
| CW_HISTORY_LATEST | bei knappem Budget nur der Endwert je Fenster |
| 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
stis 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
*srvis null a defaultServiceWrapperis 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
*srvis null a defaultServiceWrapperis 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_OKsync. May benullptrto 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
nullptrto 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.
function coldwave_link_class
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::fqdnFully-qualified backend host name.
variable ca_cert
cpp
unsigned char* coldwave_backend_t::ca_certDER-encoded CA cert; null => unencrypted UDP (PTP only).
variable ca_cert_len
cpp
unsigned coldwave_backend_t::ca_cert_lenByte length of ca_cert.
variable push_sources
cpp
const char* coldwave_backend_t::push_sourcesForwarder 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_tlsif set, local connection will be unencrypted
variable local_tcp_port
cpp
uint16_t coldwave_router_options_t::local_tcp_portif 0, default port (9986/9987) is used
variable local_network_interface
cpp
const char* coldwave_router_options_t::local_network_interfacename of the interface to bind to, default null for all interfaces
variable auth_callback
cpp
coldwave_auth_callback_t coldwave_router_options_t::auth_callbackcalled on every new local connection
variable auto_update_disabled
cpp
int coldwave_router_options_t::auto_update_disabledif set, the CBE will not start OTA when new versions are available
variable max_clients
cpp
int coldwave_router_options_t::max_clientsmaximum clients the router will accept, 0 for unlimited
variable monthly_data_limit_bytes
cpp
unsigned coldwave_client_options_t::monthly_data_limit_bytesif 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_bytesif 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_sDeprecated:
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_sSIM 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::routervariable client
cpp
coldwave_client_options_t coldwave_options_t::clientvariable 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::ctxvariable node_type
cpp
coldwave_node_t coldwave_init_t::node_typeClient or router.
variable app_semver
cpp
const char* coldwave_init_t::app_semverSemVer version string of current firmware app.
variable device_id
cpp
const char* coldwave_init_t::device_idUnique identifier for the device (required)
variable product_id
cpp
const char* coldwave_init_t::product_idColdwave product identifier (4 alphanumeric characters)
variable hw_id
cpp
const char* coldwave_init_t::hw_idHardware (SoC) identifier for OTA updates.
variable backend
cpp
coldwave_backend_t coldwave_init_t::backendBackend connection (required for cwClient)
variable net_device_handle
cpp
int coldwave_init_t::net_device_handleOpen-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_typeKind of primary network device — drives MAC/LTE readout.
variable opt
cpp
coldwave_options_t coldwave_init_t::optType-specific options.
variable persist
cpp
cw_persist_t coldwave_init_t::persistoptional, see cw_persist_t
variable state
cpp
cw_conn_state_t coldwave_status_t::statevariable transport
cpp
cw_transport_t coldwave_status_t::transportvariable last_reason
cpp
cw_reason_t coldwave_status_t::last_reasonvariable retry_count
cpp
uint32_t coldwave_status_t::retry_countvariable next_retry_ms
cpp
uint32_t coldwave_status_t::next_retry_msvariable remaining_budget_bytes
cpp
unsigned coldwave_status_t::remaining_budget_bytesvariable sync_interval_s
cpp
int coldwave_status_t::sync_interval_sDeprecated:
always 0 — syncs are no longer paced on-device
variable backoff_base_ms
cpp
uint32_t cw_conn_policy_t::backoff_base_msinitial reconnect backoff (>=1)
variable backoff_cap_ms
cpp
uint32_t cw_conn_policy_t::backoff_cap_msmaximum reconnect backoff
variable jitter_ms
cpp
uint32_t cw_conn_policy_t::jitter_msrandom 0..jitter_ms added per backoff
variable mtu
cpp
uint16_t cw_conn_policy_t::mtutransport MTU for client connections
variable udp_idle_timeout_s
cpp
uint32_t cw_conn_policy_t::udp_idle_timeout_sUDP/DTLS inactivity timeout (client)
variable service_init_timeout_ms
cpp
uint32_t cw_conn_policy_t::service_init_timeout_msper-service registration / initial-sync timeout
variable sync_timeout_ms
cpp
uint32_t cw_conn_policy_t::sync_timeout_mswait for a sync answer (liveness, heartbeat, first sync); 0 = default 5000
variable sync_fail_reconnect
cpp
uint32_t cw_conn_policy_t::sync_fail_reconnectunanswered syncs in a row before the transport is rebuilt; 0 = default 3
variable ltem
cpp
cw_lp_profile_t cw_conn_policy_t::ltemLTE-M, 2G und unbekannte Technik auf einem Modem.
variable nbiot
cpp
cw_lp_profile_t cw_conn_policy_t::nbiotNB-IoT.
variable startup_jitter_ms
cpp
uint32_t cw_conn_policy_t::startup_jitter_mserster 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_msSofort-Sitzung endet nach so viel Stream-Stille; 0 = 30 min.
variable traffic_policy
cpp
uint8_t cw_conn_policy_t::traffic_policyCW_TRAFFIC_*.
variable stable_session_ms
cpp
uint32_t cw_conn_policy_t::stable_session_msso 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_dbmas reported by the modem
variable rsrq_db
cpp
int32_t coldwave_lte_snapshot_t::rsrq_dbvariable sinr_raw
cpp
int32_t coldwave_lte_snapshot_t::sinr_rawraw register value, NOT dB
variable mcc
cpp
uint16_t coldwave_lte_snapshot_t::mccvariable mnc
cpp
uint16_t coldwave_lte_snapshot_t::mncvariable lac
cpp
uint32_t coldwave_lte_snapshot_t::lacvariable ci
cpp
uint32_t coldwave_lte_snapshot_t::civariable rat
cpp
uint8_t coldwave_lte_snapshot_t::ratvariable signal_age_ms
cpp
uint32_t coldwave_lte_snapshot_t::signal_age_mssince the radio values were refreshed
variable reg_age_ms
cpp
uint32_t coldwave_lte_snapshot_t::reg_age_mssince the cell identity was refreshed
variable signal_valid
cpp
bool coldwave_lte_snapshot_t::signal_validfalse until a first radio sample succeeded
variable reg_valid
cpp
bool coldwave_lte_snapshot_t::reg_validfalse until a first cell identity was parsed
variable fields
cpp
uint32_t cw_power_info_t::fieldsOR'd CW_POWER_INFO_* — only fields whose bit is set are read.
variable battery_mv
cpp
uint16_t cw_power_info_t::battery_mvBattery rail voltage in mV.
variable battery_pct
cpp
uint8_t cw_power_info_t::battery_pctEstimated battery state-of-charge in percent (0-100)
variable temperature_c10
cpp
int16_t cw_power_info_t::temperature_c10On-die / ambient temperature in deci-celsius (°C * 10)
variable slot
cpp
uint8_t cw_hw_ota_target_t::slot1..(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_idValue 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::ctxOpaque context forwarded to the integrator callbacks.
variable on_begin
cpp
cw_hw_ota_begin_t cw_hw_ota_target_t::on_beginOptional. 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_appendRequired. Called for every chunk of bytes.
variable on_finalize
cpp
cw_hw_ota_finalize_t cw_hw_ota_target_t::on_finalizeOptional. Called on successful completion.
variable on_abort
cpp
cw_hw_ota_abort_t cw_hw_ota_target_t::on_abortOptional. Called on abort/failure.
Macros Documentation
define SSID_MAX_LEN
cpp
#define SSID_MAX_LEN 32define MAC_ADDR_LEN
cpp
#define MAC_ADDR_LEN 6define IP_ADDR_LEN
cpp
#define IP_ADDR_LEN 4define 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 1Feature-Makros fuer Verbraucher, die auch gegen aeltere SDKs bauen.
define COLDWAVE_HAS_PEER_TX_AGE
cpp
#define COLDWAVE_HAS_PEER_TX_AGE 1define COLDWAVE_HAS_CONN_PROGRESS
cpp
#define COLDWAVE_HAS_CONN_PROGRESS 1define COLDWAVE_HAS_POWER_STATE
cpp
#define COLDWAVE_HAS_POWER_STATE 1define COLDWAVE_HAS_REPORT_WINDOW
cpp
#define COLDWAVE_HAS_REPORT_WINDOW 1define COLDWAVE_HAS_IMMEDIATE
cpp
#define COLDWAVE_HAS_IMMEDIATE 1define COLDWAVE_HAS_HISTORY_CLASS
cpp
#define COLDWAVE_HAS_HISTORY_CLASS 1define 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 1Signals 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.