Arduino WolkConnect library  4.0.0
Data Structures | Macros | Typedefs | Enumerations | Functions
WolkConn.h File Reference

Header file with library function descriptions. More...

Go to the source code of this file.

Data Structures

struct  _wolk_ctx_t
 

Macros

#define FW_VERSION_MAJOR   3
 
#define FW_VERSION_MINOR   1
 
#define FW_VERSION_PATCH   4
 

Typedefs

typedef unsigned char WOLK_ERR_T
 WOLK_ERR_T Boolean used for error handling in Wolk connection module.
 
typedef unsigned char WOLK_BOOL_T
 WOLK_ERR_T Boolean used in Wolk connection module.
 
typedef void(* actuation_handler_t) (const char *reference, const char *value)
 Declaration of actuator handler. Actuator reference and value are the pairs of data on the same place in their own arrays. More...
 
typedef actuator_status_t(* actuator_status_provider_t) (const char *reference)
 Declaration of actuator status. More...
 
typedef void(* configuration_handler_t) (char(*reference)[CONFIGURATION_REFERENCE_SIZE], char(*value)[CONFIGURATION_VALUE_SIZE], size_t num_configuration_items)
 Declaration of configuration handler. Configuration reference and value are the pairs of data on the same place in their own arrays. More...
 
typedef size_t(* configuration_provider_t) (char(*reference)[CONFIGURATION_REFERENCE_SIZE], char(*value)[CONFIGURATION_VALUE_SIZE], size_t max_num_configuration_items)
 Declaration of configuration provider. More...
 
typedef struct _wolk_ctx_t wolk_ctx_t
 WolkAbout IoT Platform connector context. Most of the parameters are used to initialize WolkConnect library forwarding to wolk_init().
 

Enumerations

enum  protocol_t { PROTOCOL_WOLKABOUT = 0 }
 Supported protocols, WolkConnect libararies currently support only PROTOCOL_WOLKABOUT.
 
enum  WOLK_BOOL_T_values { W_FALSE = 0, W_TRUE = 1 }
 

Functions

WOLK_ERR_T wolk_init (wolk_ctx_t *ctx, actuation_handler_t actuation_handler, actuator_status_provider_t actuator_status_provider, configuration_handler_t configuration_handler, configuration_provider_t configuration_provider, const char *device_key, const char *device_password, PubSubClient *client, const char *server, int port, protocol_t protocol, const char **actuator_references, uint32_t num_actuator_references)
 Initializes WolkAbout IoT Platform connector context. More...
 
WOLK_ERR_T wolk_init_in_memory_persistence (wolk_ctx_t *ctx, void *storage, uint32_t size, bool wrap)
 Initializes persistence mechanism with in-memory implementation. More...
 
WOLK_ERR_T wolk_init_custom_persistence (wolk_ctx_t *ctx, persistence_push_t push, persistence_peek_t peek, persistence_pop_t pop, persistence_is_empty_t is_empty)
 Initializes persistence mechanism with custom implementation. More...
 
WOLK_ERR_T wolk_connect (wolk_ctx_t *ctx)
 Connect to WolkAbout IoT Platform. More...
 
WOLK_ERR_T wolk_disconnect (wolk_ctx_t *ctx)
 Disconnect from WolkAbout IoT Platform. More...
 
WOLK_ERR_T wolk_process (wolk_ctx_t *ctx)
 Must be called periodically to keep the connection to the WolkAbout IoT platform alive, obtain and perform actuation requests. It also serves as a diagnostic tool for the MQTT client, printing it's state when an error occurs. Client state will be -3 if the connection is lost and -4 if the broker can't be reached. More...
 
WOLK_ERR_T wolk_add_string_sensor_reading (wolk_ctx_t *ctx, const char *reference, const char *value, uint32_t utc_time)
 Add string reading. More...
 
WOLK_ERR_T wolk_add_multi_value_string_sensor_reading (wolk_ctx_t *ctx, const char *reference, const char(*values)[READING_SIZE], uint16_t values_size, uint32_t utc_time)
 Add multi-value string reading. More...
 
WOLK_ERR_T wolk_add_numeric_sensor_reading (wolk_ctx_t *ctx, const char *reference, double value, uint32_t utc_time)
 Add numeric reading. More...
 
WOLK_ERR_T wolk_add_multi_value_numeric_sensor_reading (wolk_ctx_t *ctx, const char *reference, double *values, uint16_t values_size, uint32_t utc_time)
 Add multi-value numeric reading. More...
 
WOLK_ERR_T wolk_add_bool_sensor_reading (wolk_ctx_t *ctx, const char *reference, bool value, uint32_t utc_time)
 Add bool reading. More...
 
WOLK_ERR_T wolk_add_multi_value_bool_sensor_reading (wolk_ctx_t *ctx, const char *reference, bool *values, uint16_t values_size, uint32_t utc_time)
 Add multi-value bool reading. More...
 
WOLK_ERR_T wolk_add_alarm (wolk_ctx_t *ctx, const char *reference, bool state, uint32_t utc_time)
 Add alarm. More...
 
WOLK_ERR_T wolk_publish_actuator_status (wolk_ctx_t *ctx, const char *reference)
 Obtains actuator status via actuator_status_provider_t and publishes it. If actuator status can not be published, it is persisted. More...
 
WOLK_ERR_T wolk_publish_configuration (wolk_ctx_t *ctx)
 Obtains configuration via configuration_provider and publishes it. If configuration can not be published, it is persisted. More...
 
WOLK_ERR_T wolk_publish (wolk_ctx_t *ctx)
 Publish accumulated sensor readings, and alarms. More...
 
WOLK_ERR_T wolk_disable_keep_alive (wolk_ctx_t *ctx)
 Disables internal keep alive mechanism. More...
 
WOLK_ERR_T wolk_update_epoch (wolk_ctx_t *ctx)
 Requests the epoch time from the platform and awaits reply. If the reply did not arrive within 60 seconds it returns W_TRUE. More...
 
uint64_t wolk_request_timestamp (wolk_ctx_t *ctx)
 Get last received UTC from platform. More...
 

Detailed Description

Header file with library function descriptions.

Typedef Documentation

◆ actuation_handler_t

typedef void(* actuation_handler_t) (const char *reference, const char *value)

Declaration of actuator handler. Actuator reference and value are the pairs of data on the same place in their own arrays.

Parameters
referenceactuator references defined in device template on the WolkAbout IoT Platform.
valuevalue received from WolkAbout IoT Platform.

◆ actuator_status_provider_t

typedef actuator_status_t(* actuator_status_provider_t) (const char *reference)

Declaration of actuator status.

Parameters
referenceactuator references defined in device template on the WolkAbout IoT Platform

◆ configuration_handler_t

typedef void(* configuration_handler_t) (char(*reference)[CONFIGURATION_REFERENCE_SIZE], char(*value)[CONFIGURATION_VALUE_SIZE], size_t num_configuration_items)

Declaration of configuration handler. Configuration reference and value are the pairs of data on the same place in their own arrays.

Parameters
referenceactuator references defined in the device template on the WolkAbout IoT Platform
valueactuator values received from the WolkAbout IoT Platform.
num_configuration_itemsnumber of used configuration parameters

◆ configuration_provider_t

typedef size_t(* configuration_provider_t) (char(*reference)[CONFIGURATION_REFERENCE_SIZE], char(*value)[CONFIGURATION_VALUE_SIZE], size_t max_num_configuration_items)

Declaration of configuration provider.

Parameters
referenceconfiguration references defined in the device template on the WolkAbout IoT Platform
valueconfiguration values received from the WolkAbout IoT Platform
num_configuration_itemsnumber of used configuration parameters

Function Documentation

◆ wolk_add_alarm()

WOLK_ERR_T wolk_add_alarm ( wolk_ctx_t ctx,
const char *  reference,
bool  state,
uint32_t  utc_time 
)

Add alarm.

Parameters
ctxContext
referenceAlarm reference
messageAlarm message
utc_timeUTC time when alarm was risen [seconds]
Returns
Error code

◆ wolk_add_bool_sensor_reading()

WOLK_ERR_T wolk_add_bool_sensor_reading ( wolk_ctx_t ctx,
const char *  reference,
bool  value,
uint32_t  utc_time 
)

Add bool reading.

Parameters
ctxContext
referenceSensor reference
valueSensor value
utc_timeUTC time of sensor value acquisition [seconds]
Returns
Error code

◆ wolk_add_multi_value_bool_sensor_reading()

WOLK_ERR_T wolk_add_multi_value_bool_sensor_reading ( wolk_ctx_t ctx,
const char *  reference,
bool *  values,
uint16_t  values_size,
uint32_t  utc_time 
)

Add multi-value bool reading.

Parameters
ctxContext
referenceSensor reference
valuesSensor values
values_sizeNumber of sensor dimensions
utc_timeUTC time of sensor value acquisition [seconds]
Returns
Error code

◆ wolk_add_multi_value_numeric_sensor_reading()

WOLK_ERR_T wolk_add_multi_value_numeric_sensor_reading ( wolk_ctx_t ctx,
const char *  reference,
double *  values,
uint16_t  values_size,
uint32_t  utc_time 
)

Add multi-value numeric reading.

Parameters
ctxContext
referenceSensor reference
valuesSensor values
values_sizeNumber of sensor dimensions
utc_timeUTC time of sensor value acquisition [seconds]
Returns
Error code

◆ wolk_add_multi_value_string_sensor_reading()

WOLK_ERR_T wolk_add_multi_value_string_sensor_reading ( wolk_ctx_t ctx,
const char *  reference,
const char(*)  values[READING_SIZE],
uint16_t  values_size,
uint32_t  utc_time 
)

Add multi-value string reading.

Parameters
ctxContext
referenceSensor reference
valuesSensor values
values_sizeNumber of sensor dimensions
utc_timeUTC time of sensor value acquisition [seconds]
Returns
Error code

◆ wolk_add_numeric_sensor_reading()

WOLK_ERR_T wolk_add_numeric_sensor_reading ( wolk_ctx_t ctx,
const char *  reference,
double  value,
uint32_t  utc_time 
)

Add numeric reading.

Parameters
ctxContext
referenceSensor reference
valueSensor value
utc_timeUTC time of sensor value acquisition [seconds]
Returns
Error code

◆ wolk_add_string_sensor_reading()

WOLK_ERR_T wolk_add_string_sensor_reading ( wolk_ctx_t ctx,
const char *  reference,
const char *  value,
uint32_t  utc_time 
)

Add string reading.

Parameters
ctxlibrary context
referenceSensor reference
valueSensor value
utc_timeUTC time. If unable to retrieve UTC set 0
Returns
Error code

◆ wolk_connect()

WOLK_ERR_T wolk_connect ( wolk_ctx_t ctx)

Connect to WolkAbout IoT Platform.

  1. Context must be initialized via wolk_init(wolk_ctx_t* ctx, actuation_handler_t actuation_handler, actuator_status_provider_t actuator_status_provider, configuration_handler_t configuration_handler, configuration_provider_t configuration_provider, const char* device_key, const char* device_password, PubSubClient client, const char *server, int port, protocol_t protocol, const char** actuator_references, uint32_t num_actuator_references)
  2. Persistence must be initialized using wolk_initialize_in_memory_persistence(wolk_ctx_t *ctx, void storage, uint16_t num_elements, bool wrap) or wolk_initialize_custom_persistence(wolk_ctx_t *ctx, persistence_push_t push, persistence_pop_t pop, persistence_is_empty_t is_empty, persistence_size_t size)
    Parameters
    ctxContext
    Returns
    Error code

◆ wolk_disable_keep_alive()

WOLK_ERR_T wolk_disable_keep_alive ( wolk_ctx_t ctx)

Disables internal keep alive mechanism.

Parameters
ctxContext
Returns
Error code

◆ wolk_disconnect()

WOLK_ERR_T wolk_disconnect ( wolk_ctx_t ctx)

Disconnect from WolkAbout IoT Platform.

Parameters
ctxlibrary context
Returns
Error value is returned

◆ wolk_init()

WOLK_ERR_T wolk_init ( wolk_ctx_t ctx,
actuation_handler_t  actuation_handler,
actuator_status_provider_t  actuator_status_provider,
configuration_handler_t  configuration_handler,
configuration_provider_t  configuration_provider,
const char *  device_key,
const char *  device_password,
PubSubClient *  client,
const char *  server,
int  port,
protocol_t  protocol,
const char **  actuator_references,
uint32_t  num_actuator_references 
)

Initializes WolkAbout IoT Platform connector context.

Parameters
ctxContext
actuation_handlerfunction pointer to 'actuation_handler_t' implementation
actuator_status_providerfunction pointer to 'actuator_status_provider_t' implementation
configuration_handlerfunction pointer to 'configuration_handler_t' implementation
configuration_providerfunction pointer to 'configuration_provider_t' implementation
device_keyDevice key provided by WolkAbout IoT Platform upon device creation
passwordDevice password provided by WolkAbout IoT Platform device upon device creation
clientMQQT Client
serverMQQT Server
portPort to connect to
protocolProtocol specified for device
actuator_referencesArray of strings containing references of actuators that device possess
num_actuator_referencesNumber of actuator references contained in actuator_references
Returns
Error code

◆ wolk_init_custom_persistence()

WOLK_ERR_T wolk_init_custom_persistence ( wolk_ctx_t ctx,
persistence_push_t  push,
persistence_peek_t  peek,
persistence_pop_t  pop,
persistence_is_empty_t  is_empty 
)

Initializes persistence mechanism with custom implementation.

Parameters
ctxContext
pushFunction pointer to 'push' implemenation
peekFunction pointer to 'peek' implementation
popFunction pointer to 'pop' implementation
is_emptyFunction pointer to 'is empty' implementation
Returns
Error code
See also
persistence.h for signatures of methods to be implemented, and implementation contract

◆ wolk_init_in_memory_persistence()

WOLK_ERR_T wolk_init_in_memory_persistence ( wolk_ctx_t ctx,
void *  storage,
uint32_t  size,
bool  wrap 
)

Initializes persistence mechanism with in-memory implementation.

Parameters
ctxContext
storageAddress to start of the memory which will be used by persistence mechanism
sizeSize of memory in bytes
wrapIf storage is full overwrite oldest item when pushing new item
Returns
Error code

◆ wolk_process()

WOLK_ERR_T wolk_process ( wolk_ctx_t ctx)

Must be called periodically to keep the connection to the WolkAbout IoT platform alive, obtain and perform actuation requests. It also serves as a diagnostic tool for the MQTT client, printing it's state when an error occurs. Client state will be -3 if the connection is lost and -4 if the broker can't be reached.

Parameters
ctxContext
Returns
Error code

◆ wolk_publish()

WOLK_ERR_T wolk_publish ( wolk_ctx_t ctx)

Publish accumulated sensor readings, and alarms.

Parameters
ctxContext
Returns
Error code

◆ wolk_publish_actuator_status()

WOLK_ERR_T wolk_publish_actuator_status ( wolk_ctx_t ctx,
const char *  reference 
)

Obtains actuator status via actuator_status_provider_t and publishes it. If actuator status can not be published, it is persisted.

Parameters
ctxContext
referenceActuator reference
Returns
Error code

◆ wolk_publish_configuration()

WOLK_ERR_T wolk_publish_configuration ( wolk_ctx_t ctx)

Obtains configuration via configuration_provider and publishes it. If configuration can not be published, it is persisted.

Parameters
ctxContext
Returns
Error code

◆ wolk_request_timestamp()

uint64_t wolk_request_timestamp ( wolk_ctx_t ctx)

Get last received UTC from platform.

Parameters
ctxContext
Returns
UTC in miliseconds

◆ wolk_update_epoch()

WOLK_ERR_T wolk_update_epoch ( wolk_ctx_t ctx)

Requests the epoch time from the platform and awaits reply. If the reply did not arrive within 60 seconds it returns W_TRUE.

Parameters
ctxContext
Returns
Error code