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
struct	coldwave_options_t
struct	coldwave_init_t
typedef int(*)(const flake::PropArray &rops)	coldwave_auth_callback_t

Functions Overview

	Name
int	coldwave_init(coldwave_init_t * init, const char * srv_uuid, flake::Service ** srv) Initializes the Coldwave library.
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.
int	coldwave_deinit() Deinitialize 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 WiFi 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 WIFI commissioning.
void	coldwave_end_wifi_commissioning(void ) Ends the WiFi 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.

Attributes

	Name
int	no_local_tls if set, local connection ("Broadband" only) will be unencrypted
uint16_t	local_tcp_port if set to 0 the default port (9986) will be used
coldwave_auth_callback_t	auth_callback called on every new local connection ("Broadband") only
int	auto_update_disabled if set, the CBE will not start OTA when new versions are available
uint8_t	networking_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_t	opts

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)

Coldwave API ​

Types ​

Functions Overview ​

Attributes ​

Defines ​

Types Documentation ​

typedef coldwave_auth_callback_t ​

Function Details ​

function coldwave_init ​

function coldwave_backend_attach ​

function coldwave_backend_detach ​

function coldwave_deinit ​

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 ​

Attributes Documentation ​

variable no_local_tls ​

variable local_tcp_port ​

variable auth_callback ​

variable auto_update_disabled ​

variable networking_bw ​

variable app_semver ​

variable device_id ​

variable product_id ​

variable hw_id ​

variable opts ​

Macros Documentation ​

define CW_PTP ​

define CW_NETWORK ​

Coldwave API

Types

Functions Overview

Attributes

Defines

Types Documentation

typedef coldwave_auth_callback_t

Function Details

function coldwave_init

function coldwave_backend_attach

function coldwave_backend_detach

function coldwave_deinit

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

Attributes Documentation

variable no_local_tls

variable local_tcp_port

variable auth_callback

variable auto_update_disabled

variable networking_bw

variable app_semver

variable device_id

variable product_id

variable hw_id

variable opts

Macros Documentation

define CW_PTP

define CW_NETWORK