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