XDK API  3.6.0
Documentation
Data Structures | Macros | Typedefs | Functions
LWM2MUtil.h File Reference

This file provides the Implementation of LWM2M Util. More...

#include <Serval_Lwm2m.h>
#include "FreeRTOS.h"
#include "task.h"
#include "semphr.h"
+ Include dependency graph for LWM2MUtil.h:
+ This graph shows which files directly or indirectly include this file:

Data Structures

struct  Lwm2m_Call_T
 Data to synchronize call with scheduler. More...
 
struct  Lwm2m_Pair_Resource_Update_T
 Data to synchronize resource transfer for two values. More...
 
struct  Lwm2m_Single_Resource_Update_T
 Data to synchronize resource transfer for a single value. More...
 
struct  Lwm2m_Tripple_Resource_Update_T
 Data to synchronize resource transfer for three values. More...
 
struct  Lwm2mDynamicChanges_S
 

Macros

#define INIT_LWM2M_DYNAMIC_CHANGES(C)   Lwm2mDynamicChanges_T C = { .changes = 0 }
 Initialize dynamic changes data. More...
 
#define LWM2M_DYNAMIC_CHANGES_REPORT(C, U)   if (0 < C.changes) LWM2MUtil_ReportChanges(&C, &U)
 Report changes from dynamic changes data. More...
 
#define LWM2M_DYNAMIC_CHANGES_SET_FLOAT_MAX_VALUE(C, T, R, V)   LWM2MUtil_SetFloatMaxValue(&C, (const Lwm2mResource_T*) &T, &(T.R), V)
 set new float resource value, if its larger then the current value. More...
 
#define LWM2M_DYNAMIC_CHANGES_SET_FLOAT_MIN_VALUE(C, T, R, V)   LWM2MUtil_SetFloatMinValue(&C, (const Lwm2mResource_T*) &T, &(T.R), V)
 set new float resource value, if its less then the current value. More...
 
#define LWM2M_DYNAMIC_CHANGES_SET_FLOAT_VALUE(C, T, R, V)   LWM2MUtil_SetFloatValue(&C, (const Lwm2mResource_T*) &T, &(T.R), V)
 set new float resource value. More...
 
#define LWM2M_MAX_DYNAMIC_CHANGES   4
 Maximum number of supported resources changes using Lwm2mDynamicChanges_S . More...
 
#define LWM2M_MUTEX_CREATE(M)   (M) = xSemaphoreCreateMutex()
 Creates mutex. More...
 
#define LWM2M_MUTEX_INIT_VALUE   NULL
 Initial value of a mutex. More...
 
#define LWM2M_MUTEX_INSTANCE(M)   xSemaphoreHandle M
 Declare/define an instance of a mutex. More...
 
#define LWM2M_MUTEX_IS_CREATED(M)   (NULL != (M))
 Check, if mutex is already created. More...
 
#define LWM2M_MUTEX_LOCK(M)   LWM2M_MUTEX_LOCK_TIMEOUT((M), 2000)
 Lock mutex. More...
 
#define LWM2M_MUTEX_LOCK_TIMEOUT(M, T)   (pdTRUE == xSemaphoreTake((M), (T)))
 Lock mutex with timeout. More...
 
#define LWM2M_MUTEX_UNLOCK(M)   xSemaphoreGive(M)
 Unlock mutex. More...
 

Typedefs

typedef void(* lwm2m_set_pair_float )(float value1, float value2)
 Function to set a two float values. More...
 
typedef void(* lwm2m_set_single_float )(float value)
 Function to set a single float value. More...
 
typedef void(* lwm2m_set_tripple_float )(float value1, float value2, float value3)
 Function to set a three float values. More...
 
typedef struct
Lwm2mDynamicChanges_S 
Lwm2mDynamicChanges_T
 

Functions

void LWM2MUtil_ReportChanges (Lwm2mDynamicChanges_T *changes, const Lwm2m_URI_Path_T *instanceUriPath)
 Report changes from dynamic changes data. More...
 
void LWM2MUtil_Schedule (Lwm2m_Call_T *call)
 Schedule a call to lwm2m scheduler. More...
 
bool LWM2MUtil_SetFloatMaxValue (Lwm2mDynamicChanges_T *changes, const Lwm2mResource_T *resourceTable, Lwm2mResource_T *resource, float value)
 set new float resource value, if its larger then the current value. More...
 
bool LWM2MUtil_SetFloatMinValue (Lwm2mDynamicChanges_T *changes, const Lwm2mResource_T *resourceTable, Lwm2mResource_T *resource, float value)
 set new float resource value, if its less then the current value. More...
 
bool LWM2MUtil_SetFloatValue (Lwm2mDynamicChanges_T *changes, const Lwm2mResource_T *resourceTable, Lwm2mResource_T *resource, float value)
 set new float resource value. More...
 
void LWM2MUtil_UpdatePairResources (float value1, float value2, Lwm2m_Pair_Resource_Update_T *updater)
 Update two resource values. Delegate the transfer to the scheduler. More...
 
void LWM2MUtil_UpdateSingleResource (float value, Lwm2m_Single_Resource_Update_T *updater)
 Update single float resource value. Delegate the transfer to the scheduler. More...
 
void LWM2MUtil_UpdateTrippleResources (float value1, float value2, float value3, Lwm2m_Tripple_Resource_Update_T *updater)
 Update three resource values. Delegate the transfer to the scheduler. More...
 

Detailed Description

The LWM2M util offers the possibility to report multiple resources changes on instance base and to synchronize changes in the resources with the serval scheduler to ensure data consistency.

The LWM2M serval API (Serval_lwm2m.h) offers two function for reporting changes:

The first one reports the change of a singel resource. Multiple calls for changes on different resources of the same instance will be reported with multiple notification even on instances.

e.g.:
observe /3313/0 (accelerometer)
result (current state) { 5603 = -2.0, 5604 = 2.0, 5701 = "g", 5702 = 0.03, 5703 = 0.04, 5704 = 9.8 }

change /3313/0/5702 0.01 (x-axis)
change /3313/0/5703 0.02 (y-axis)

will result in two instance notification:
(notification /3313/0) { 5603 = -2.0, 5604 = 2.0, 5701 = "g", 5702 = 0.01, 5703 = 0.04, 5704 = 9.8 }
(notification /3313/0) { 5603 = -2.0, 5604 = 2.0, 5701 = "g", 5702 = 0.01, 5703 = 0.02, 5704 = 9.8 }

So, if the traffic should be reduced, or the changes should be visible only together (atomic) Lwm2mReporting_resourceChanged could not be used.

Therefore Lwm2mReporting_multipleResourcesChanged is available. Reporting both changes (x-Axis and y-Axis) will result in one instance notification:
(notification /3313/0) { 5603 = -2.0, 5604 = 2.0, 5701 = "g", 5702 = 0.01, 5703 = 0.02, 5704 = 9.8 }

To simplify the preparation of the call of Lwm2mReporting_multipleResourcesChanged the LWM2M utils offers several MACROS.

The INIT_LWM2M_DYNAMIC_CHANGES defines the required data structure Lwm2mDynamicChanges_S to store the changes.
The LWM2M_DYNAMIC_CHANGES_SET_FLOAT_VALUE, LWM2M_DYNAMIC_CHANGES_SET_FLOAT_MIN_VALUE, LWM2M_DYNAMIC_CHANGES_SET_FLOAT_MAX_VALUE process the new value and store resulting changes in the defined data structure. LWM2M_DYNAMIC_CHANGES_REPORT then reports the stored changes.

e.g.

LWM2MObjectAccelerometer_Resource_S

struct LWM2MObjectAccelerometer_Resource_S accelerometerResources =
{
...
};
.... function(float newValue1, float newValue2, float newValue3)
{
LWM2M_DYNAMIC_CHANGES_SET_FLOAT_VALUE(changes, accelerometerResources, xAxis, newValue1);
LWM2M_DYNAMIC_CHANGES_SET_FLOAT_VALUE(changes, accelerometerResources, yAxis, newValue2);
LWM2M_DYNAMIC_CHANGES_SET_FLOAT_VALUE(changes, accelerometerResources, zAxis, newValue3);
}

For some resources representing minimum or maximum values, special macros exist.

BarometerResource_S

struct BarometerResource_S barometerResources =
{
...
};
... function(float newValue)
{
if (LWM2M_DYNAMIC_CHANGES_SET_FLOAT_VALUE(changes, barometerResources, sensorValue, newValue)) {
LWM2M_DYNAMIC_CHANGES_SET_FLOAT_MIN_VALUE(changes, barometerResources, minMeasuredValue, newValue);
LWM2M_DYNAMIC_CHANGES_SET_FLOAT_MAX_VALUE(changes, barometerResources, maxMeasuredValue, newValue);
}
}

The LWM2M serval uses scheduler jobs to serialize lwm2m object instances (encode the resources to a message). If multiple resource changes should be visible only in a atomic manner, the schedule must be synchronized with the resource access. Therefore the transfer of the values is splitted into two steps:

Four functions are used support that synchronization: LWM2MUtil_updateSingleResource, LWM2MUtil_updatePairResources, LWM2MUtil_updateTrippleResources, and LWM2MUtil_schedule.

To use them, you need to define a associated data structure: Lwm2m_Single_Resource_Update_T, Lwm2m_Pair_Resource_Update_T, Lwm2m_Tripple_Resource_Update_T, and Lwm2m_Call_T.

Intialize the required fields: Lwm2m_Single_Resource_Update_T.set_single, Lwm2m_Pair_Resource_Update_T.set_pair, Lwm2m_Tripple_Resource_Update_T.set_tripple, and Lwm2m_Call_T.call. and all mutex fields (note: a lwm2m object may share a mutex across multiple synchronization data structures).

e.g.

static void ObjectAccelerometer_internalEnable(float minRange, float maxRange);
static void ObjectAccelerometer_internalDisable(void);
static void ObjectAccelerometer_internalSetValues(float xAxis, float yAxis, float zAxis);
static Lwm2m_Pair_Resource_Update_T enabler = {.set_pair = ObjectAccelerometer_internalEnable, .mutex = LWM2M_MUTEX_INIT_VALUE };
static Lwm2m_Call_T disabler = {.call = ObjectAccelerometer_internalDisable };
static Lwm2m_Tripple_Resource_Update_T updater = {.set_tripple = ObjectAccelerometer_internalSetValues, .mutex = LWM2M_MUTEX_INIT_VALUE };
...
void ObjectAccelerometer_init(void)
{
...
LWM2M_MUTEX_CREATE(updater.mutex);
enabler.mutex = updater.mutex;
}

Call function the transfer values synchronized to resoruces: e.g.

void ObjectAccelerometer_setValues(float xAxis, float yAxis, float zAxis)
{
LWM2MUtil_updateTrippleResources(xAxis, yAxis, zAxis, &updater);
}

Macro Definition Documentation

#define INIT_LWM2M_DYNAMIC_CHANGES (   C)    Lwm2mDynamicChanges_T C = { .changes = 0 }
Parameters
Clocal name of changes
#define LWM2M_DYNAMIC_CHANGES_REPORT (   C,
 
)    if (0 < C.changes) LWM2MUtil_ReportChanges(&C, &U)
Parameters
[in]Cdynamic changes data
[in]Uuri path to changed instance
See also
LWM2MUtil_ReportChanges
#define LWM2M_DYNAMIC_CHANGES_SET_FLOAT_MAX_VALUE (   C,
  T,
  R,
 
)    LWM2MUtil_SetFloatMaxValue(&C, (const Lwm2mResource_T*) &T, &(T.R), V)

Check, if the new value is larger then the current resource value. If so, change the resource value and store the resource index in the dynamic changes data.

Parameters
[in,out]Cdynamic changes data
[in]Tresource table the resource belongs to
[in,out]Rresource of the resource table
[in]Vnew value
Returns
true, if resource value was changed, false, otherwise
See also
LWM2MUtil_SetFloatMaxValue
#define LWM2M_DYNAMIC_CHANGES_SET_FLOAT_MIN_VALUE (   C,
  T,
  R,
 
)    LWM2MUtil_SetFloatMinValue(&C, (const Lwm2mResource_T*) &T, &(T.R), V)

Check, if the new value is less then the current resource value. If so, change the resource value and store the resource index in the dynamic changes data.

Parameters
[in,out]Cdynamic changes data
[in]Tresource table the resource belongs to
[in,out]Rresource of the resource table
[in]Vnew value
Returns
true, if resource value was changed, false, otherwise
See also
LWM2MUtil_SetFloatMinValue
#define LWM2M_DYNAMIC_CHANGES_SET_FLOAT_VALUE (   C,
  T,
  R,
 
)    LWM2MUtil_SetFloatValue(&C, (const Lwm2mResource_T*) &T, &(T.R), V)

Check, if the new value changes the resource value. If changed, store the resource index in the dynamic changes data.

Parameters
[in,out]Cdynamic changes data
[in]Tresource table the resource belongs to
[in,out]Rresource of the resource table
[in]Vnew value
Returns
true, if resource value was changed, false, otherwise
See also
LWM2MUtil_SetFloatValue
#define LWM2M_MAX_DYNAMIC_CHANGES   4
#define LWM2M_MUTEX_CREATE (   M)    (M) = xSemaphoreCreateMutex()
Parameters
[in]Mmutex name
#define LWM2M_MUTEX_INIT_VALUE   NULL
#define LWM2M_MUTEX_INSTANCE (   M)    xSemaphoreHandle M
Parameters
[in]Mmutex name
#define LWM2M_MUTEX_IS_CREATED (   M)    (NULL != (M))
Parameters
[in]Mmutex name
#define LWM2M_MUTEX_LOCK (   M)    LWM2M_MUTEX_LOCK_TIMEOUT((M), 2000)
Parameters
[in]Mmutex name
Returns
true, it the mutex could be locked within 2000ms, false otherwise.
#define LWM2M_MUTEX_LOCK_TIMEOUT (   M,
 
)    (pdTRUE == xSemaphoreTake((M), (T)))
Parameters
[in]Mmutex name
[in]Ttimeout in milliseconds
Returns
true, it the mutex could be locked within the timeout, false otherwise.
#define LWM2M_MUTEX_UNLOCK (   M)    xSemaphoreGive(M)
Parameters
[in]Mmutex name

Typedef Documentation

typedef void(* lwm2m_set_pair_float)(float value1, float value2)
Parameters
[in]value1first value to be set.
[in]value2second value to be set.
typedef void(* lwm2m_set_single_float)(float value)
Parameters
[in]valuevalue to be set.
typedef void(* lwm2m_set_tripple_float)(float value1, float value2, float value3)
Parameters
[in]value1first value to be set.
[in]value2second value to be set.
[in]value3third value to be set.

Data for dynamic reporting changes.

Function Documentation

void LWM2MUtil_ReportChanges ( Lwm2mDynamicChanges_T changes,
const Lwm2m_URI_Path_T instanceUriPath 
)

Intended to be used by LWM2M_DYNAMIC_CHANGES_REPORT .

Parameters
[in]changesdynamic changes data
[in]instanceUriPathuri path to changed instance

Refer interface header for description

+ Here is the call graph for this function:

void LWM2MUtil_Schedule ( Lwm2m_Call_T call)
Parameters
[in]callcallback executed in context of scheduler

Refer interface header for description

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

bool LWM2MUtil_SetFloatMaxValue ( Lwm2mDynamicChanges_T changes,
const Lwm2mResource_T resourceTable,
Lwm2mResource_T resource,
float  value 
)

Check, if the new value is larger then the current resource value. If so, change the resource value and store the resource index in the dynamic changes data. Intended to be used by LWM2M_DYNAMIC_CHANGES_SET_FLOAT_MAX_VALUE .

Parameters
[in,out]changesdynamic changes data
[in]resourceTableresource table the resource belongs to
[in,out]resourceresource of the resource table
[in]valuenew value
Returns
true, if resource value was changed, false, otherwise

Refer interface header for description

+ Here is the call graph for this function:

bool LWM2MUtil_SetFloatMinValue ( Lwm2mDynamicChanges_T changes,
const Lwm2mResource_T resourceTable,
Lwm2mResource_T resource,
float  value 
)

Check, if the new value is less then the current resource value. If so, change the resource value and store the resource index in the dynamic changes data. Intended to be used by LWM2M_DYNAMIC_CHANGES_SET_FLOAT_MIN_VALUE .

Parameters
[in,out]changesdynamic changes data
[in]resourceTableresource table the resource belongs to
[in,out]resourceresource of the resource table
[in]valuenew value
Returns
true, if resource value was changed, false, otherwise

Refer interface header for description

+ Here is the call graph for this function:

bool LWM2MUtil_SetFloatValue ( Lwm2mDynamicChanges_T changes,
const Lwm2mResource_T resourceTable,
Lwm2mResource_T resource,
float  value 
)

Check, if the new value changes the resource value. If changed, store the resource index in the dynamic changes data. Intended to be used by LWM2M_DYNAMIC_CHANGES_SET_FLOAT_VALUE .

Parameters
[in,out]changesdynamic changes data
[in]resourceTableresource table the resource belongs to
[in,out]resourceresource of the resource table
[in]valuenew value
Returns
true, if resource value was changed, false, otherwise

Refer interface header for description

+ Here is the caller graph for this function:

void LWM2MUtil_UpdatePairResources ( float  value1,
float  value2,
Lwm2m_Pair_Resource_Update_T updater 
)
Parameters
[in]value1new value
[in]value2new value
[in]updaterdata for synchronized resource transfer

Refer interface header for description

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void LWM2MUtil_UpdateSingleResource ( float  value,
Lwm2m_Single_Resource_Update_T updater 
)
Parameters
[in]valuenew value
[in]updaterdata for synchronized resource transfer

Refer interface header for description

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void LWM2MUtil_UpdateTrippleResources ( float  value1,
float  value2,
float  value3,
Lwm2m_Tripple_Resource_Update_T updater 
)
Parameters
[in]value1new value
[in]value2new value
[in]value3new value
[in]updaterdata for synchronized resource transfer

Refer interface header for description

+ Here is the call graph for this function:

+ Here is the caller graph for this function:


All rights reserved. The use is subject to the XDK SDK EULA by Bosch Connected Devices and Solutions GmbH.
This documentation file has been automatically generated on Thu Mar 14 2019 19:12:41 by doxygen 1.8.8