Coldwave API

Coldwave API Functions.

Types

	Name
struct	coldwave_router_options_t
struct	coldwave_client_options_t
union	coldwave_options_t
struct	coldwave_init_t
enum	coldwave_node_t
typedef int(*)(const flake::PropArray &rops)	coldwave_auth_callback_t

Functions Overview

	Name
int	coldwave_init(const coldwave_init_t * init, const char * srv_uuid, flake::Service ** srv) Initializes the Coldwave library.
unsigned	coldwave_get_remaining_budget()
void	coldwave_reset_budget() Resets the monthly budget for the connected client's synchronization manager.
int	coldwave_register_service(const char * srv_uuid, flake::Service ** srv) Registers a secondary service.
int	coldwave_backend_attach(const char * cbe_fqdn, unsigned char * cbe_ca_cert, unsigned cbe_ca_cert_len) Attaches the Coldwave backend to the system.
int	coldwave_backend_detach(void ) Detaches the Coldwave backend.
bool	coldwave_backend_attached()
int	coldwave_uninit() Uninitialize the ColdWave library.
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) Starts the AP Wi-Fi commissioning process.
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) Start BLE Wi-Fi commissioning.
void	coldwave_end_wifi_commissioning(void ) Ends the Wi-Fi commissioning process.
int	coldwave_ota_autoupdate_enable(bool e) Enable or disable automatic updates for ColdWave OTA.
bool	coldwave_ota_autoupdate_enabled(void ) Checks if coldwave OTA autoupdate is enabled.
int	coldwave_sign(const char * message, size_t message_len, const char signature_buf[(64)]) Signs a message using a cryptographic key.
int	coldwave_verify(const char * message, size_t message_len, const char signature_buf[(64)]) verify a signature of a message
int	coldwave_suspend()
int	coldwave_resume()

Attributes

	Name
int	no_local_tls if set, local connection will be unencrypted
uint16_t	local_tcp_port if set to 0 the default port (9986) will be 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 availabl
int	max_clients maximum clients the router will accept, 0 for unlimited
unsigned	monthly_data_limit_bytes if not 0, the syncing interval will be adjusted to stay in the budget
unsigned	remaining_data_budget_bytes if not 0, the budget will be updated with the remaining budget
int	dasired_sync_interval_s if not 0, reqular syncs will be tried at the interval, if the budget allows it
coldwave_router_options_t	router
coldwave_client_options_t	client
coldwave_node_t	node_type Narrowband or Broadband connectivity.
const char *	app_semver SemVer Version String of current firmware app.
const char *	device_id unique identifier for the device
const char *	product_id Coldwave Product Identifier (4 alphanumeric characters)
const char *	hw_id Hardware (SoC) Identifier for Updates.
coldwave_options_t	opt Type Specific Options.

Defines

Name
SSID_MAX_LEN
MAC_ADDR_LEN
IP_ADDR_LEN
COLDWAVE_INIT_DEFAULT

Types Documentation

enum coldwave_node_t

Enumerator	Description
cwClient
cwRouter

typedef coldwave_auth_callback_t

cpp

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

Function Details

function coldwave_init

cpp

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

Initializes the Coldwave library.

Parameters:

init The initialization parameters for Coldwave.
srv_uuid The UUID of the service.
srv Pointer to the pointer of the service.

Return: E_OK if the initialization is successful, otherwise an error code.

This function initializes the Coldwave library with the given parameters.

function coldwave_get_remaining_budget

cpp

unsigned coldwave_get_remaining_budget()

Return: The remaining budget as an unsigned integer. Returns 0 if the session is not initialized or if the node type is not set to client.

Retrieves the remaining budget for the current month, if initialized and operating as a client.

function coldwave_reset_budget

cpp

void coldwave_reset_budget()

Resets the monthly budget for the connected client's synchronization manager.

This function verifies whether the Coldwave module is initialized and the node type is set to client. If both conditions are met, it reset the budget. parameters.

function coldwave_register_service

cpp

int coldwave_register_service(
    const char * srv_uuid,
    flake::Service ** srv
)

Registers a secondary service.

Parameters:

srv_uuid The UUID of the service.
srv Pointer to the pointer of the service.

Return: E_OK if the initialization is successful, otherwise an error code.

function coldwave_backend_attach

cpp

int coldwave_backend_attach(
    const char * cbe_fqdn,
    unsigned char * cbe_ca_cert,
    unsigned cbe_ca_cert_len
)

Attaches the Coldwave backend to the system.

Parameters:

cbe_fqdn The fully-qualified domain name (FQDN) of the Coldwave backend.
cbe_ca_cert The CA certificate needed for secure communication with the Coldwave backend.
cbe_ca_cert_len The length of the CA certificate.

Return: E_OK if the attachment was successful, E_FAILED if the system is not initialized or the Coldwave backend is already attached.

Note: for CW_NETWORK sessions, the cbe_ca_cert is mandatory, for CW_PTP connections it is optional. If set to nullptr in that case an unencrypted UDP "connection" will be used, if a valid certificate is passed, coldwave will set up an encrypted DTLS connection.

This function attaches the Coldwave backend to the system using the provided fully-qualified domain name (FQDN) and CA certificate.

function coldwave_backend_detach

cpp

int coldwave_backend_detach(
    void 
)

Detaches the Coldwave backend.

Return: int Returns E_OK if successful, otherwise E_FAILED.

This function detaches the Coldwave backend by setting coldwave_cbe_detach to true and disconnecting from the connection. If the networking bandwidth is set to CW_PTP, it waits for the coldwave_cbe_attached flag to become false before uninitializing the connection.

function coldwave_backend_attached

cpp

bool coldwave_backend_attached()

Return: true if the Coldwave backend is attached; otherwise, false.

Checks if the Coldwave backend is currently attached.

function coldwave_uninit

cpp

int coldwave_uninit()

Uninitialize the ColdWave library.

Return: Returns E_OK if the deinitialization was successful, otherwise returns E_FAILED.

This function uninitializes the ColdWave library by performing necessary cleanup tasks. It should be called after ColdWave has been initialized using the coldwave_init() function.

function coldwave_start_ap_wifi_commissioning

cpp

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
)

Starts the AP Wi-Fi commissioning process.

Parameters:

wifi_dev The Wi-Fi device to use for commissioning.
ssid The SSID of the access point to be started.
pass The password for the access point.
timeout_ms The timeout duration in milliseconds for the commissioning process.
cb The callback function to be called when commissioning data is available.

Return: Integer value indicating the result of starting the commissioning process. It is zero if the process was started successfully, otherwise a non-zero error code is returned.

This function initiates the AP Wi-Fi commissioning process with the specified parameters. The AP Wi-Fi commissioning starts an access point (AP) using the provided SSID and password.

This example demonstrates the use of the coldwave_start_ap_wifi_commissioning function to initiate the AP Wi-Fi commissioning process. This involves connecting a device to an access point using the provided SSID and password.

cpp

// Callback function when commissioning data is available
static void wifi_data_callback (int result, wifi_commissioning_data_t *data)
{
   printf("Received Wi-Fi Commissioning data for SSID: %s\n", data->ssid);
}

int main()
{
   // ...
   int wifi_dev = 1; // Wi-Fi device ID
   const char* ssid = "SSID_NAME"; // SSID of the access point
   const char* pass = "PASSWORD"; // Password of the access point
   uint32_t timeout_ms = 10000; // Timeout for the commissioning process

   int result = coldwave_start_ap_wifi_commissioning(wifi_dev, ssid, pass, timeout_ms, wifi_data_callback);
   if (result == 0)
   {
       printf("Successfully started AP Wi-Fi commissioning.\n");
   }
   else
   {
       printf("Failed to start AP Wi-Fi commissioning.\n");
   }

   // ...
}

function coldwave_start_ble_wifi_commissioning

cpp

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
)

Start BLE Wi-Fi commissioning.

Parameters:

wifi_dev The ID of the Wi-Fi device to use.
ble_dev The ID of the BLE device to use.
ble_name The name of the BLE device to connect.
timeout_ms The timeout value in milliseconds for commissioning.
cb The callback function for commissioning data.

Return: The status of the commissioning process.

Returns 0 on success.
Returns a negative value on failure.

This function starts the BLE Wi-Fi commissioning process by passing the necessary parameters.

function coldwave_end_wifi_commissioning

cpp

void coldwave_end_wifi_commissioning(
    void 
)

Ends the Wi-Fi commissioning process.

This function is used to end the Wi-Fi commissioning process in the Coldwave application. It calls the wifi_commissioning_end() function with parameter 0.

function coldwave_ota_autoupdate_enable

cpp

int coldwave_ota_autoupdate_enable(
    bool e
)

Enable or disable automatic updates for ColdWave OTA.

Parameters:

e The flag indicating whether to enable or disable automatic updates.

Return: An integer value indicating the success or failure of the operation. 0 indicates success, while any other value indicates failure.

This function enables or disables automatic updates for ColdWave OTA. When enabled, the device will automatically update its firmware and software. When disabled, the device will not perform automatic updates.

function coldwave_ota_autoupdate_enabled

cpp

bool coldwave_ota_autoupdate_enabled(
    void 
)

Checks if coldwave OTA autoupdate is enabled.

Return: true if autoupdate is enabled, false otherwise.

This function returns a boolean value indicating whether the autoupdate feature for coldwave OTA is enabled or not.

function coldwave_sign

cpp

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

Signs a message using a cryptographic key.

Parameters:

message A pointer to the message to be signed.
message_len The length of the message.
signature_buf A buffer to store the signature.

Return: Returns E_OK (0) if the message was successfully signed, or E_FAILED (-1) if an error occurred.

This function signs a message using a devices unique cryptographic key. It takes the message to be signed, the length of the message, and a buffer to store the signature.

function coldwave_verify

cpp

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

verify a signature of a message

Parameters:

message A pointer to the message to be signed.
message_len The length of the message.
signature_buf The signature to verify

Return: Returns E_OK (0) if the message was successfully signed, or E_FAILED (-1) if an error occurred.

This function verifies a message using a devices unique cryptographic key. It takes the message, the length of the message and the signature to verify

function coldwave_suspend

cpp

int coldwave_suspend()

function coldwave_resume

cpp

int coldwave_resume()

Attributes Documentation

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 set to 0 the default port (9986) will be 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 availabl

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, the syncing interval will be adjusted to stay in the budget

variable remaining_data_budget_bytes

cpp

unsigned coldwave_client_options_t::remaining_data_budget_bytes

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

variable dasired_sync_interval_s

cpp

int coldwave_client_options_t::dasired_sync_interval_s

if not 0, reqular syncs will be tried at the interval, if the budget allows it

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

Narrowband or Broadband connectivity.

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

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 Updates.

variable opt

cpp

coldwave_options_t coldwave_init_t::opt

Type Specific Options.

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 */ APP_VERSION_STR,      \
  /* .device_id */ 0,                     \
  /* .product_id */ nullptr,              \
  /* .hw_id */ "default",          	      \
  /* .opts */ {                           \
  /*   .no_local_tls */ 0,                \
  /*   .local_tcp_port */ 9986,           \
  /*   .monthly_data_limit_bytes */ 0,    \
  /*   .remaining_data_budget_bytes */ 0, \
  /*   .dasired_sync_interval_s */ 0      \
  }                                       \
}

Coldwave API ​

Types ​

Functions Overview ​

Attributes ​

Defines ​

Types Documentation ​

enum coldwave_node_t ​

typedef coldwave_auth_callback_t ​

Function Details ​

function coldwave_init ​

function coldwave_get_remaining_budget ​

function coldwave_reset_budget ​

function coldwave_register_service ​

function coldwave_backend_attach ​

function coldwave_backend_detach ​

function coldwave_backend_attached ​

function coldwave_uninit ​

function coldwave_start_ap_wifi_commissioning ​

function coldwave_start_ble_wifi_commissioning ​

function coldwave_end_wifi_commissioning ​

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

variable router ​

variable client ​

variable node_type ​

variable app_semver ​

variable device_id ​

variable product_id ​

variable hw_id ​

variable opt ​

Macros Documentation ​

define SSID_MAX_LEN ​

define MAC_ADDR_LEN ​

define IP_ADDR_LEN ​

define COLDWAVE_INIT_DEFAULT ​

Coldwave API

Types

Functions Overview

Attributes

Defines

Types Documentation

enum coldwave_node_t

typedef coldwave_auth_callback_t

Function Details

function coldwave_init

function coldwave_get_remaining_budget

function coldwave_reset_budget

function coldwave_register_service

function coldwave_backend_attach

function coldwave_backend_detach

function coldwave_backend_attached

function coldwave_uninit

function coldwave_start_ap_wifi_commissioning

function coldwave_start_ble_wifi_commissioning

function coldwave_end_wifi_commissioning

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 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 dasired_sync_interval_s

variable router

variable client

variable node_type

variable app_semver

variable device_id

variable product_id

variable hw_id

variable opt

Macros Documentation

define SSID_MAX_LEN

define MAC_ADDR_LEN

define IP_ADDR_LEN

define COLDWAVE_INIT_DEFAULT