cloud.h File Reference

Cloud implementation. More...

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include <virgil/iot/firmware/firmware.h>
#include <global-hal.h>
#include <virgil/iot/status_code/status_code.h>

Go to the source code of this file.

Data Structures
struct	vs_cloud_impl_t
	Cloud implementation. More...
struct	vs_cloud_mb_topics_list_t
	List of available topics. More...
struct	vs_cloud_message_bin_impl_t
	Message Bin implementation. More...

Macros
#define	VS_UPD_URL_STR_SIZE   200
	Length of the update URL string. More...

Typedefs
typedef size_t(*	vs_fetch_handler_cb_t) (const char *contents, size_t chunksize, void *userdata)
	Implementation for data header download. More...
typedef vs_status_e(*	vs_cloud_http_request_func_t) (vs_cloud_http_method_e method, const char *url, const char *request_body, size_t request_body_size, char *out_data, vs_fetch_handler_cb_t fetch_handler, void *hander_data, size_t *in_out_size)
	Implementation for GET and POST requests processing. More...
typedef void(*	vs_cloud_mb_process_custom_topic_cb_t) (const char *topic, uint16_t topic_sz, const uint8_t *data, uint16_t length)
	Implementation for custom topics processing. More...
typedef void(*	vs_cloud_mb_process_default_topic_cb_t) (const uint8_t *url, uint16_t length)
	Implementation for default topics processing. More...
typedef vs_status_e(*	vs_cloud_mb_init_func_t) (const char *host, uint16_t port, const char *device_cert, const char *priv_key, const char *ca_cert)
	Message bin initialization. More...
typedef vs_status_e(*	vs_cloud_mb_connect_subscribe_func_t) (const char *client_id, const char *login, const char *password, const vs_cloud_mb_topics_list_t *topic_list, vs_cloud_mb_process_custom_topic_cb_t process_topic)
	Message bin connection and subscription to topic implementation. More...
typedef vs_status_e(*	vs_cloud_mb_process_func_t) (void)
	Message Bin processing. More...

Enumerations
enum	vs_cloud_http_method_e { VS_CLOUD_REQUEST_GET, VS_CLOUD_REQUEST_POST }
enum	vs_cloud_mb_topic_id_t { VS_CLOUD_MB_TOPIC_TL, VS_CLOUD_MB_TOPIC_FW }
	Default topics. More...

Functions
vs_status_e	vs_cloud_fetch_and_store_fw_file (const char *fw_file_url, vs_firmware_header_t *fetched_header)
	Fetch and store Firmware. More...
vs_status_e	vs_cloud_fetch_and_store_tl (const char *tl_file_url)
	Fetch and store Trust List. More...
vs_status_e	vs_cloud_message_bin_register_default_handler (vs_cloud_mb_topic_id_t topic_id, vs_cloud_mb_process_default_topic_cb_t handler)
	Register processing handlers for default topics from vs_cloud_mb_topic_id_t enumeration. More...
vs_status_e	vs_cloud_message_bin_register_custom_handler (vs_cloud_mb_process_custom_topic_cb_t handler)
	Register custom handler implementation. More...
vs_status_e	vs_cloud_message_bin_process (void)
	Process message bin. More...
vs_status_e	vs_cloud_init (const vs_cloud_impl_t *cloud_impl, const vs_cloud_message_bin_impl_t *message_bin_impl, vs_secmodule_impl_t *secmodule)
	Initialize message bin. More...

Detailed Description

Cloud implementation.

Cloud is a library that implements functions for communication with the Cloud and is used for the following :

• obtaining credentials from thing service
• connecting to message bin broker over MQTT and subscribing to the list of topics
• processing messages received over message bin
• downloading firmware binaries and trust list files from cloud storage

Virgil IoT KIT provides MQTT implementation based on AWS IoT library.

Cloud Usage

Function vs_cloud_message_bin_process tries to obtain credentials for connecting to message bin broker from thing service using vs_cloud_http_request_func_t and connect to the broker using vs_cloud_mb_connect_subscribe_func_t. Then it waits for new messages, periodically calling vs_cloud_mb_process_func_t. User can register own handlers for events of new firmware or trust list by calling vs_cloud_message_bin_register_default_handler or custom handler for raw data processing from some topics by calling vs_cloud_message_bin_register_custom_handler. Cloud module uses provision and firmware modules, which must be initialized before.

Note

vs_cloud_init requires vs_cloud_impl_t, vs_cloud_message_bin_impl_t and vs_secmodule_impl_t implementations. You can provide yours or use standard ones : vs_curl_http_impl() that uses cURL HTTP, vs_aws_message_bin_impl() that implements MQTT, vs_soft_secmodule_impl() that returns software security module implementation.

Here you can see an example of Cloud module initialization :

const vs_cloud_impl_t *cloud_impl;                          // Cloud implementation
const vs_cloud_message_bin_impl_t *message_bin_impl;        // Message bin implementation
vs_secmodule_impl_t *secmodule_impl;                        // Security module implementation
vs_cloud_mb_process_default_topic_cb_t tl_topic_process;    // Trust List topic processor
vs_cloud_mb_process_default_topic_cb_t fw_topic_process;    // Firmware topic processor
vs_storage_op_ctx_t tl_storage_impl;                        // Trust List storage implementation
vs_storage_op_ctx_t fw_storage_impl;                        // Firmware storage implementation
static vs_device_manufacture_id_t manufacture_id;           // Manufacture ID
static vs_device_type_t device_type;                        // Device type
 
// Initialize secmodule_impl, cloud_impl, message_bin_impl, tl_storage_impl, fw_storage_impl,
// manufacture_id, device_type
 
// Provision module
STATUS_CHECK(vs_provision_init(&tl_storage_impl, secmodule_impl), "Cannot initialize Provision module");
 
// Firmware module
STATUS_CHECK(vs_firmware_init(&fw_storage_impl, secmodule_impl, manufacture_id, device_type), "Unable to initialize
Firmware module");
 
// Cloud module
STATUS_CHECK(vs_cloud_init(cloud_impl, message_bin_impl, secmodule_impl), "Unable to initialize Cloud module");
STATUS_CHECK(vs_cloud_message_bin_register_default_handler(VS_CLOUD_MB_TOPIC_TL, tl_topic_process),
    "Error register handler for Trust List topic");
 
STATUS_CHECK(vs_cloud_message_bin_register_default_handler(VS_CLOUD_MB_TOPIC_FW, fw_topic_process), "Error register
handler for Firmware topic");

You can use vs_curl_http_impl() for cloud_impl, vs_aws_message_bin_impl() for message_bin_impl, vs_soft_secmodule_impl() for secmodule_impl.

fw_topic_process receives an URL that can be used to fetch a new version of Firmware. See firmware_usage for details.

Here you can see an example of Cloud library usage:

// Processing of cloud library functionality example
void
message_bin_mqtt_task(void *params) {
   while (true) {
       if (VS_CODE_OK == vs_cloud_message_bin_process()) {
           sleep(500);
       } else {
           sleep(5000);
       }
    }
 }
 
// Handlers for default topics example
void
fw_topic_process(const uint8_t *url, uint16_t length) {
     vs_status_e res;
     vs_firmware_header_t header;
 
     res = vs_cloud_fetch_and_store_fw_file(url, &header);
 
     if (VS_CODE_OK == res) {
         res = vs_firmware_verify_firmware(&header.descriptor);
         if (VS_CODE_OK == res) {
            // Fetched firmware is correct. Process it
         } else {
             // Incorrect firmware image. You can delete it.
             vs_firmware_delete_firmware(&header.descriptor);
         }
     }
 }
 
void
tl_topic_process(const uint8_t *url, uint16_t length) {
 
     if (VS_CODE_OK == vs_cloud_fetch_and_store_tl(url)) {
         // Trust list is correct. Process it
     }
 }

Macro Definition Documentation

VS_UPD_URL_STR_SIZE

#define VS_UPD_URL_STR_SIZE   200

Length of the update URL string.

Typedef Documentation

vs_cloud_http_request_func_t

typedef vs_status_e(* vs_cloud_http_request_func_t) (vs_cloud_http_method_e method, const char *url, const char *request_body, size_t request_body_size, char *out_data, vs_fetch_handler_cb_t fetch_handler, void *hander_data, size_t *in_out_size)

Implementation for GET and POST requests processing.

This function implementation loads requested data and stores it in the out_data output buffer.

Parameters

[in]	method	HTTP method, which will be performed
[in]	url	URL for data download. Must not be NULL.
[in]	request_body	The body of the POST request.
[in]	request_body_size	The size of the POST request body.
[out]	out_data	Output buffer to store processed data if fetch_handler has not been specified. Must not be NULL.
[in]	fetch_handler	Implementation to process information that has been downloaded. If NULL, default processing will be used.
[in]	fetch_hander_data	Context from fetch_handler . userdata parameter.
[in,out]	in_out_size	Data size storage. Must not be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_cloud_mb_connect_subscribe_func_t

typedef vs_status_e(* vs_cloud_mb_connect_subscribe_func_t) (const char *client_id, const char *login, const char *password, const vs_cloud_mb_topics_list_t *topic_list, vs_cloud_mb_process_custom_topic_cb_t process_topic)

Message bin connection and subscription to topic implementation.

This implementation connects to the message bin broker and subscribes to topics. vs_aws_message_bin_impl() returns vs_cloud_message_bin_impl_t structure with default implementation provided by Virgil IoT KIT library. You can analyze function which connect_subscribe member points to for an example.

Parameters

[in]	client_id	Client identifier. Cannot be NULL.
[in]	login	Login. Cannot be NULL.
[in]	password	Password. Cannot be NULL.
[in]	topic_list	Pointer to the list of topics. Cannot be NULL.
[in]	process_topic	Implementation for topics processing. Cannot be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_cloud_mb_init_func_t

typedef vs_status_e(* vs_cloud_mb_init_func_t) (const char *host, uint16_t port, const char *device_cert, const char *priv_key, const char *ca_cert)

Message bin initialization.

This implementation initializes MQTT with specified URL and certificates. vs_aws_message_bin_impl() returns vs_cloud_message_bin_impl_t structure with default implementation provided by Virgil IoT KIT library. You can analyze function which init member points to for an example.

Parameters

[in]	host	Host URL. Must not be NULL.
[in]	port	Port for host access.
[in]	device_cert	Device certificate to be send to the broker.
[in]	priv_key	Device private key.
[in]	ca_cert	Broker's certificate. Must not be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_cloud_mb_process_custom_topic_cb_t

typedef void(* vs_cloud_mb_process_custom_topic_cb_t) (const char *topic, uint16_t topic_sz, const uint8_t *data, uint16_t length)

Implementation for custom topics processing.

This implementation processes messages from topics as raw data.

Parameters

[in]	topic	Topic name. Cannot be NULL.
[in]	topic_sz	Topic name size. Cannot be zero.
[in]	data	Topic data. Cannot be NULL
[in]	length	Topic data size. Cannot be zero.

vs_cloud_mb_process_default_topic_cb_t

typedef void(* vs_cloud_mb_process_default_topic_cb_t) (const uint8_t *url, uint16_t length)

Implementation for default topics processing.

Virgil IoT KIT preprocesses topics from vs_cloud_mb_topic_id_t enumeration. It calls this function when receives a notification about a new version of Trust List or Firmware to load data for this topic.

Parameters

[in]	url	URL where user can fetch a new version of file.
[in]	length	Topic URL size.

vs_cloud_mb_process_func_t

typedef vs_status_e(* vs_cloud_mb_process_func_t) (void)

Message Bin processing.

Implementation for message bin processing. vs_aws_message_bin_impl() returns vs_cloud_message_bin_impl_t structure with default implementation provided by Virgil IoT KIT library. You can analyze function which process member points to for an example.

Returns

VS_CODE_OK in case of success or error code.

vs_fetch_handler_cb_t

typedef size_t(* vs_fetch_handler_cb_t) (const char *contents, size_t chunksize, void *userdata)

Implementation for data header download.

This function implementation stores loaded handler in internal buffers.

Parameters

[in]	contents	Input data. Must not be NULL.
[in]	chunksize	Input data size. Must not be zero.
[in,out]	userdata	Data specific context. Must not be NULL.

Returns

Loaded data size of vs_status_e error code

Enumeration Type Documentation

vs_cloud_http_method_e

enum vs_cloud_http_method_e

Enumerator
VS_CLOUD_REQUEST_GET	HTTP request by GET method.
VS_CLOUD_REQUEST_POST	HTTP request by POST method.

vs_cloud_mb_topic_id_t

enum vs_cloud_mb_topic_id_t

Default topics.

This is the list of default topics processed by vs_cloud_mb_process_default_topic_cb_t() implementation.

Enumerator
VS_CLOUD_MB_TOPIC_TL	Trust List.
VS_CLOUD_MB_TOPIC_FW	Firmware.

Function Documentation

vs_cloud_fetch_and_store_fw_file()

vs_status_e vs_cloud_fetch_and_store_fw_file	(	const char *	fw_file_url,
		vs_firmware_header_t *	fetched_header
	)

Fetch and store Firmware.

Fetches Firmware and stores it in internal storage.

Parameters

[in]	fw_file_url	Firmware URL to fetch. Must not be NULL.
[out]	fetched_header

Returns

VS_CODE_OK in case of success or error code.

vs_cloud_fetch_and_store_tl()

vs_status_e vs_cloud_fetch_and_store_tl

(

const char *

tl_file_url

)

Fetch and store Trust List.

Fetches Trust List and stores it in internal storage.

Parameters

[in]

tl_file_url

Trust List URL to fetch. Must not be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_cloud_init()

vs_status_e vs_cloud_init	(	const vs_cloud_impl_t *	cloud_impl,
		const vs_cloud_message_bin_impl_t *	message_bin_impl,
		vs_secmodule_impl_t *	secmodule
	)

Initialize message bin.

Parameters

[in]	cloud_impl	Cloud implementation. Must not be NULL.
[in]	message_bin_impl	Message bin implementation. You can use default implementation returned by vs_aws_message_bin_impl(). Must not be NULL.
[in]	secmodule	Security module implementation. You can use default implementation returned by vs_soft_secmodule_impl(). Must not be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_cloud_message_bin_process()

vs_status_e vs_cloud_message_bin_process

(

void

)

Process message bin.

Initializes message bin if needed and processes protocol. Normally this function is called in the MQTT processing infinite loop.

Returns

VS_CODE_OK in case of success or error code.

vs_cloud_message_bin_register_custom_handler()

vs_status_e vs_cloud_message_bin_register_custom_handler

(

vs_cloud_mb_process_custom_topic_cb_t

handler

)

Register custom handler implementation.

Registers custom topics processing. You can use vs_cloud_message_bin_register_default_handler() if it is enough for your default topics processing.

Parameters

[in]

handler

Custom topics processing handler. Must not be NULL.

Returns

VS_CODE_OK in case of success or error code.

vs_cloud_message_bin_register_default_handler()

vs_status_e vs_cloud_message_bin_register_default_handler	(	vs_cloud_mb_topic_id_t	topic_id,
		vs_cloud_mb_process_default_topic_cb_t	handler
	)

Register processing handlers for default topics from vs_cloud_mb_topic_id_t enumeration.

Registers topic processing handlers.

Parameters

[in]	topic_id	Topic identifier.
[in]	handler	Topic processing implementation. Must not be NULL.

Returns

VS_CODE_OK in case of success or error code.