Skip to content

file coldwave.h ​

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.
structcw_power_info_t
structcw_hw_ota_target_t

Defines ​

Name
COLDWAVE_SIGNATURE_LEN

Macros Documentation ​

define COLDWAVE_SIGNATURE_LEN ​

cpp
#define COLDWAVE_SIGNATURE_LEN (64)

Source code ​

cpp
//
// Created by Sebastian Floss on 13.02.22.
// Copyright (c) 2022 ImagineOn GmbH. All rights reserved.
//

#ifndef COLDWAVE_H_
#define COLDWAVE_H_

#include "Service.h"

using namespace flake;

#if defined(__COLDWAVE_OS__) || defined(__CXOS__)
#include <flake/flake.h>
#include <psa/crypto.h>
#define COLDWAVE_SIGNATURE_LEN          PSA_ECDSA_SIGNATURE_SIZE (256)
#else
#include <flake.h>
#define COLDWAVE_SIGNATURE_LEN          (64)
#endif

#if FLAKE_BUILD_ROUTER && !defined(COLDWAVE_PTP_ONLY)
#define COLDWAVE_HAS_ROUTER 1
#endif

#if COLDWAVE_HAS_ROUTER
#include "commissioning/wifi_commissioning.h"
#endif

#include "cw_link_policy.h"
#include "cw_hw_ota_job.h"

#ifndef SSID_MAX_LEN
#define SSID_MAX_LEN 32
#endif

#define MAC_ADDR_LEN 6
#define IP_ADDR_LEN 4

typedef enum {
    CW_OK                  = 0,    
    CW_ERR_FAILED          = -1,   
    CW_ERR_NOT_INITIALIZED = -10,  
    CW_ERR_ALREADY_ATTACHED= -11,  
    CW_ERR_NOT_ATTACHED    = -12,  
    CW_ERR_INVALID_ARG     = -13,  
    CW_ERR_NO_BACKEND      = -14,  
    CW_ERR_NO_NETWORK_IF   = -15,  
    CW_ERR_TRANSPORT       = -16,  
    CW_ERR_NOT_SUPPORTED   = -17,  
} coldwave_result_t;

#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 } \
}


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

typedef enum {
    cwClient = 0,
    cwRouter = 1
} coldwave_node_t;

typedef enum {
    cwNetNone     = 0,
    cwNetEthernet = 1,
    cwNetWiFi     = 2,
    cwNetLte      = 3,
} coldwave_net_device_type_t;

typedef struct coldwave_backend_t {
    const char* fqdn;             
    unsigned char* ca_cert;       
    unsigned ca_cert_len;         
    const char* push_sources;
} coldwave_backend_t;

typedef struct coldwave_router_options_t {
    int no_local_tls;                       
    uint16_t local_tcp_port;                
    const char* local_network_interface;    
    coldwave_auth_callback_t auth_callback; 
    int auto_update_disabled;               
    int max_clients;                        
} coldwave_router_options_t;

typedef struct coldwave_client_options_t {
    unsigned monthly_data_limit_bytes;      
    unsigned remaining_data_budget_bytes;   
    int desired_sync_interval_s;            
    uint32_t nat_keepalive_s;               
} coldwave_client_options_t;

typedef union coldwave_options_t {
    coldwave_router_options_t router;
    coldwave_client_options_t client;
} coldwave_options_t;

struct cw_persist_t {
    int (*read)(void* ctx, uint16_t key, void* buf, size_t len);
    int (*write)(void* ctx, uint16_t key, const void* buf, size_t len);
    void* ctx;
};

typedef struct coldwave_init_t {
    coldwave_node_t node_type;              
    const char* app_semver;                 
    const char* device_id;                  
    const char* product_id;                 
    const char* hw_id;                      
    coldwave_backend_t backend;             
    int net_device_handle;                  
    coldwave_net_device_type_t net_device_type; 
    coldwave_options_t opt;                 
    cw_persist_t persist;                   
} coldwave_init_t;


/* ----------------------- Observability (connection state) ----------------------- */

typedef enum {
    CW_TR_NONE = 0,     
    CW_TR_CLOUD_UDP,    
    CW_TR_CLOUD_DTLS,   
    CW_TR_CLOUD_TCP,    
    CW_TR_LOCAL_TCP,    
    CW_TR_LOCAL_BLE,    
} cw_transport_t;

typedef enum {
    CW_ST_STOPPED = 0,
    CW_ST_DISCONNECTED,
    CW_ST_CONNECTING,
    CW_ST_ONLINE,
    CW_ST_BACKOFF,
    CW_ST_DETACHING,
    CW_ST_SUSPENDED,
} cw_conn_state_t;

typedef enum {
    CW_REASON_OK = 0,
    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,
} cw_reason_t;

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

typedef struct coldwave_status_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;        
} coldwave_status_t;

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


/* ----------------------- Connection tuning (per device class) ----------------------- */

typedef struct cw_conn_policy_t {
    uint32_t backoff_base_ms;          
    uint32_t backoff_cap_ms;           
    uint32_t jitter_ms;                
    uint16_t mtu;                      
    uint32_t udp_idle_timeout_s;       
    uint32_t service_init_timeout_ms;  
    uint32_t sync_timeout_ms;          
    uint32_t sync_fail_reconnect;      

    // NH2N (GSMA TS.34). 0 heisst ueberall "Vorgabe", CW_LP_OFF "ausdruecklich 0".
    cw_lp_profile_t ltem;              
    cw_lp_profile_t nbiot;             
    uint32_t startup_jitter_ms;        
    uint32_t session_idle_ms;          
    uint8_t  traffic_policy;           
    uint32_t stable_session_ms;        
} cw_conn_policy_t;

#define CW_TRAFFIC_AUTO   (0u)
#define CW_TRAFFIC_OFF    (1u)
#define CW_TRAFFIC_FORCE  (2u)

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


unsigned
coldwave_get_remaining_budget();


unsigned
coldwave_get_data_usage();


void
coldwave_reset_budget();

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


int
coldwave_backend_attach();

int
coldwave_backend_detach();


bool
coldwave_backend_attached();

unsigned
coldwave_sync_failure_streak();

bool
coldwave_sync_ok_age_ms(uint32_t* out_age_ms);

bool
coldwave_peer_rx_age_ms(uint32_t* out_age_ms);

#define COLDWAVE_HAS_CONTACT_INTERVAL 1
#define COLDWAVE_HAS_PEER_TX_AGE      1
#define COLDWAVE_HAS_CONN_PROGRESS    1
#define COLDWAVE_HAS_POWER_STATE      1
#define COLDWAVE_HAS_REPORT_WINDOW    1
#define COLDWAVE_HAS_IMMEDIATE        1
#define COLDWAVE_HAS_HISTORY_CLASS    1

#define CW_HISTORY_CONDENSABLE (0u)   
#define CW_HISTORY_COMPLETE    (1u)   
#define CW_HISTORY_LATEST      (2u)   

bool
coldwave_contact_interval_ms(uint32_t* out_ms);

bool
coldwave_peer_tx_age_ms(uint32_t* out_age_ms);

bool
coldwave_conn_progress_age_ms(uint32_t* out_age_ms);

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

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

bool
coldwave_report_window_ms(uint32_t* out_ms);

int
coldwave_flush_now();

int
coldwave_report_power_state(uint8_t state);

cw_link_class_t
coldwave_link_class();

cw_send_mode_t
coldwave_send_mode();

#define COLDWAVE_HAS_LTE_PEEK 1

typedef struct
{
    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;     
} coldwave_lte_snapshot_t;

bool
coldwave_lte_peek(coldwave_lte_snapshot_t* out);

int
coldwave_uninit();

#if COLDWAVE_HAS_ROUTER
int
coldwave_start_ap_wifi_commissioning(int wifi_dev, const char* ssid, const char* pass, uint32_t timeout_ms,
                                     wifi_commissioning_data_callback_t cb);

int
coldwave_start_ble_wifi_commissioning(int wifi_dev, int ble_dev, const char* ble_name, uint32_t timeout_ms,
                                      wifi_commissioning_data_callback_t cb);

#ifndef EXCLUDE_FROM_DOCS
int
coldwave_start_legacy_wifi_commissioning(int wifi_dev, int ble_dev, const char* ble_name, uint32_t timeout_ms,
                                         wifi_commissioning_data_callback_t cb);
#endif

void
coldwave_end_wifi_commissioning();
#endif // COLDWAVE_HAS_ROUTER

int
coldwave_ota_autoupdate_enable(bool e);


bool
coldwave_ota_autoupdate_enabled();



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


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


int coldwave_suspend();


int coldwave_resume();


#define CW_POWER_INFO_BATTERY_MV    (1u << 0)
#define CW_POWER_INFO_BATTERY_PCT   (1u << 1)
#define CW_POWER_INFO_TEMPERATURE   (1u << 2)

typedef struct cw_power_info_t {
    uint32_t fields;            
    uint16_t battery_mv;        
    uint8_t  battery_pct;       
    int16_t  temperature_c10;   
} cw_power_info_t;

int coldwave_set_power_info(const cw_power_info_t* info);

typedef int (*cw_hw_ota_begin_t)   (void* ctx);
typedef int (*cw_hw_ota_append_t)  (void* ctx, const uint8_t* data, size_t size);
typedef int (*cw_hw_ota_finalize_t)(void* ctx);
typedef int (*cw_hw_ota_abort_t)   (void* ctx);

typedef struct cw_hw_ota_target_t {
    uint8_t slot;                          
    int     ota_target_id;                 
    void*   ctx;                           
    cw_hw_ota_begin_t    on_begin;         
    cw_hw_ota_append_t   on_append;        
    cw_hw_ota_finalize_t on_finalize;      
    cw_hw_ota_abort_t    on_abort;         
} cw_hw_ota_target_t;

int coldwave_register_hw_ota_target(const cw_hw_ota_target_t* t);

#define COLDWAVE_HW_OTA_TARGET_SELECT 1

int coldwave_hw_ota_job(uint8_t slot, cw_hw_ota_job_t* out);

int coldwave_hw_set_unit_info(uint8_t slot, const char* hw_id, const char* fw_version);

#endif //COLDWAVE_H_