Skip to content

Coldwave API

Coldwave API Functions.

Here's an example on how to initialize coldwave locally and then attach to a remote backend

cpp
coldwave_init_t cw_init = {};

cw_init.networking_bw = CW_NETWORK;
cw_init.app_semver = "1.0.0";
cw_init.device_id = "Device123";
cw_init.product_id = "CW01";
cw_init.hw_id = "Hardware123";

cw_init.opts.no_local_tls = 1;
cw_init.opts.local_tcp_port = 9986;
cw_init.opts.auth_callback = NULL;
cw_init.opts.auto_update_disabled = 0;

const char *backend_fqdn = "your-backend-fqdn.com";
unsigned char *ca_cert = (unsigned char *) "your-ca-certificate"; // replace with your Backend CA certificate
unsigned cert_len = strlen ((char *) ca_cert);

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

int result = coldwave_init (&cw_init, cw_service_uuid, &cw_service);

if (result != E_OK) {
  printf("Failed to initialize Coldwave, error: %d\n", result);
} else {
  printf("Coldwave is initialized successfully.\n");

  result = coldwave_backend_attach (backend_fqdn, ca_cert, cert_len);

  if (result != E_OK) {
     printf("Failed to attach the Coldwave backend, error: %d\n", result);
  } else {
     printf("Coldwave backend attached successfully.\n");
  }
}

Types

Name
structcoldwave_options_t
structcoldwave_init_t
typedef int(*)(const flake::PropArray &rops)coldwave_auth_callback_t

Functions Overview

Name
intcoldwave_init(coldwave_init_t * init, const char * srv_uuid, flake::Service ** srv)
Initializes the Coldwave library.
intcoldwave_backend_attach(const char * cbe_fqdn, unsigned char * cbe_ca_cert, unsigned cbe_ca_cert_len)
Attaches the Coldwave backend to the system.
intcoldwave_backend_detach(void )
Detaches the Coldwave backend.
intcoldwave_deinit()
Deinitialize the Coldwave library.
intcoldwave_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 WiFi commissioning process.
intcoldwave_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 WIFI commissioning.
voidcoldwave_end_wifi_commissioning(void )
Ends the WiFi commissioning process.
intcoldwave_ota_autoupdate_enable(bool e)
Enable or disable automatic updates for Coldwave OTA.
boolcoldwave_ota_autoupdate_enabled(void )
Checks if coldwave OTA autoupdate is enabled.

Attributes

Name
intno_local_tls
if set, local connection ("Broadband" only) will be unencrypted
uint16_tlocal_tcp_port
if set to 0 the default port (9986) will be used
coldwave_auth_callback_tauth_callback
called on every new local connection ("Broadband") only
intauto_update_disabled
if set, the CBE will not start OTA when new versions are available
uint8_tnetworking_bw
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_topts

Defines

Name
CW_PTP
CW_NETWORK

Types Documentation

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(
    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_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.

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_deinit

cpp
int coldwave_deinit()

Deinitialize the Coldwave library.

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

This function deinitializes 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 WiFi 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 WiFi commissioning process with the specified parameters.. The AP WiFi 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 WiFi 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 WiFi Commissioning data for SSID: %s\n", data->ssid);
}

int main()
{
   // ...
   int wifi_dev = 1; // WiFi 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 WiFi commissioning.\n");
   }
   else
   {
       printf("Failed to start AP WiFi 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 WIFI commissioning.

Parameters:

  • wifi_dev The ID of the WiFi 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 WIFI commissioning process by passing the necessary parameters.

function coldwave_end_wifi_commissioning

cpp
void coldwave_end_wifi_commissioning(
    void 
)

Ends the WiFi commissioning process.

This function is used to end the WiFi 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.

Attributes Documentation

variable no_local_tls

cpp
int coldwave_options_t::no_local_tls

if set, local connection ("Broadband" only) will be unencrypted

variable local_tcp_port

cpp
uint16_t coldwave_options_t::local_tcp_port

if set to 0 the default port (9986) will be used

variable auth_callback

cpp
coldwave_auth_callback_t coldwave_options_t::auth_callback

called on every new local connection ("Broadband") only

variable auto_update_disabled

cpp
int coldwave_options_t::auto_update_disabled

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

variable networking_bw

cpp
uint8_t coldwave_init_t::networking_bw

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 opts

cpp
coldwave_options_t coldwave_init_t::opts

Macros Documentation

define CW_PTP

cpp
#define CW_PTP (0)

define CW_NETWORK

cpp
#define CW_NETWORK (1)