Defining Properties
In the ThingWorx environment, a property represents a data point, which has a name, a value, a timestamp, and optionally, a quality. In ThingWorx Platform, properties can also have aspects, which provide additional details about the property. Once a client application binds an entity to a corresponding RemoteThing on the ThingWorx Platform, you can associate properties with the RemoteThing, using ThingWorx Composer.
The C SDK supports two types of properties: properties that do not have Remote Binding Information ”aspects” and so-called subscribed properties that have Remote Binding Information aspects that are displayed in ThingWorx Composer. These aspects are described in the Property Definitions section below.
Two types of structures are used by the C SDK to define properties:
• Property Definitions (twPropertyDef) to describe the basic information for the properties that are going to be available to the ThingWorx Platform and can be added to a client application.
• Property Values (twProperty) to associate the property name with a value, timestamp, and quality.
The structures are defined in the file, twProperties.h.
The following example of a simple property structure from the Steam Sensor example shows how the declaration of properties works:
/*****************
A simple structure to handle
properties.
******************/
struct {
double TotalFlow;
char FaultStatus;
char InletValve;
double Pressure;
double Temperature;
double TemperatureLimit;
twLocation Location;
char * BigGiantString;
} properties;
A simple structure to handle
properties.
******************/
struct {
double TotalFlow;
char FaultStatus;
char InletValve;
double Pressure;
double Temperature;
double TemperatureLimit;
twLocation Location;
char * BigGiantString;
} properties;
To store the values sent by ThingWorx Platform, you must use a callback method to either allocate a new variable or set the memory in an already allocated variable. For information about registering callbacks for properties, refer to Registering Properties and Services. For additional information, refer to Property Access Callbacks and the sections on reading, writing, and pushing properties in the section, SDK Application-Initiated Interaction.
The rest of this topic provides more details about properties:
Property Definitions
The basic information that you provide for a Property Definition includes the following attributes:
• name — Specifies the name of the property that will appear in ThingWorx Composer when users browse the related Thing while the platform is binding to the Thing.
• description — Provides a description of the property that gives further understanding of the meaning of the property.
• baseType — Specifies the type of the property. For a list of base types supported by the SDK, refer to Base Types.
• aspects — Define the ways to interact with a property. All properties have the following aspects:
◦ isPersistent — When set to true, the ThingWorx Platform persists the value even if it restarts. It is extremely expensive to have persistent values, so it is recommended to set this value to FALSE unless absolutely necessary.
◦ isReadOnly — When set to true, informs the ThingWorx Platform that this value is only readable and cannot be changed by a request from the platform.
◦ dataChangeType — Describes how the ThingWorx Platform responds when the value changes in the client application. Subscriptions to these value changes can be modeled in the platform. If nothing needs to react to the property change, this value should be set to NEVER. The possible values are:
▪ ALWAYS — Always notify of the value change even if the new value is the same as the last reported value.
▪ VALUE — Notify of a change only when a newly reported value differs from its previous value.
▪ ON — For BOOLEAN types, notify only when the value is true.
▪ OFF — For BOOLEAN types only, notify when the value is false.
▪ NEVER — Ignore all changes to this value.
◦ dataChangeThreshold — Defines how much the value must change to trigger a change event. For example 0 (zero) indicates that any change triggers an event. A value of 10 (ten) for example would not trigger an update unless the value changed by an amount greater than or equal to 10.
◦ defaultValue — The default value is the value that the ThingWorx Platform uses when the RemoteThing connected to the device first starts up and has not received an update from the device. The value is different based on the different value for each base type.
• Only properties defined as subscribed properties have the following Remote Binding aspects:
◦ cacheTime — When a positive, non-zero value is specified, specifies the number of seconds that the ThingWorx Platform caches the value before requesting it from the client application again. A value of -1 informs the platform that the client application always sends its value and the platform never requests it. A value of 0 (zero) indicates that every time the platform uses the value, it should go and get it from the client application.
 |
For the client application to set the value every time it changes, set this value to -1.
|
◦ pushType — Informs the ThingWorx Platform how the client application pushes its values to the platform. The possible values are as follows:
▪ ALWAYS — Send updates even if the value has not changed. It is common to use a cacheTime setting of -1 in this case.
▪ NEVER — Never send the value, which indicates that ThingWorx Platform only writes to this value.It is common to use a cacheTime setting of 0 or greater in this case.
▪ VALUE — Send updates only when the value changes. It is common to use a cacheTime setting of -1 in this case.
|
|
As of v.1.5.0, if a property is using this push type and only the quality for that property changes, the update is propagated to ThingWorx Platform.
|
▪ DEADBAND — Added to support KEPServer, this push type is an absolute deadband (no percentages). It provides a cumulative threshold, such that the Edge device should send an update if its current data point exceeds Threshold compared to the last value sent to ThingWorx Platform. It follows existing threshold fields limits.
Properties must be registered so that ThingWorx Platform can browse them. Refer to Registering Properties and Services.
Property Values
You can define the property value in two ways:
• With specific settings for timestamp and quality.
• With the default quality.
|
|
Updating a property value does not send the value to the ThingWorx Platform. To send the value to the platform, the twSubscribedPropsMgr_PushSubscribedProperties function must be called.
|
Helper functions for creating property values include:
• setPropertyVTQ — Sets a property’s value using a VTQ (value, time, and quality) structure.
◦ name — The name of the property.
◦ value — The VTQ (value, time, and quality) for the property’s value.
◦ forceChange — Set this value to true to force the value to be sent to the ThingWorx Platform even if it has not changed. This option can be used to send the first value or to send a value immediately after reconnect.
• setPropertyValue — Sets the value of a property, using a Primitive type.
◦ name — The name of the property.
◦ value — The Primitive type for the value.
• setProperty — Sets a property’s value from an object.
◦ name — The name of the property.
◦ value — The value to set. The value will be cast to the type of property if possible; otherwise an exception will be thrown.
Setting Up the Subscribed Properties Manager
The subscribed properties have a separate manager, called Subscribed Properties Manager, which is defined in the source file, ./subscribedProps/twSubscribedProps.h. . To set up the use of the Subscribed Properties Manager, the twConfig.h files should have the following members:
• #subscribed_props_enabled — Controls whether the Subscribed Property Manager will persist offline property updates in the event of a disconnect from the ThingWorx Platform. This is persistence is on by default.
• #subscribed_props_queue_size — Limits the maximum size of the Subscribed Properties bin that stores property updates between pushes to the platform.
 |
As of v.2.2.8 of the C SDK, the size of the subscribed property update queue matches the setting of the twcfg.subscribed_props_queue_size property instead of the size of the offline message queue set by OFFLINE_MSG_QUEUE_SIZE. This change prevents the error generated when the twSubscribedPropsMgr_setPropertyVTQ function tries to add a property update that would increase the subscribed properties queue past the size limit of the offline message queue.
|
• #subscribed_props_dir — Specifies the path to the directory for subscribed properties.
When initialized, the Subscribed Properties Manager puts properties in a persisted file called subscribed_props.bin if there is no connection.
As of v.1.3.0 of the C SDK, these properties can be set independently during initialization. You can copy them from the twConfig structure in the twDefaultConfig.h file to your twConfig.h file and set the values according to the requirements of your application.
|
|
The Subscribed Properties Manager is initialized automatically when you call twAPI_initialize(). You do not need to initialize it separately.
|
Setting Subscribed Properties
For efficient throughput, the functions twApi_SetSubscribedPropertyVTQ and twApi_PushSubscribedProperties are essential. For even better throughput, consider using the asynchronous version of the call, twApi_PushSubscribedPropertiesAsync.
After setting properties individually using twApi_SetSubscribedPropertyVTQ, you can alternatively use the Subscribed Properties Manager (SPM) to push the subscribed properties all at once to ThingWorx Platform (twSubscribedPropsMgr_PushSubscribedProperties).
Refer to the table below for more information about these functions.
|
Function
|
Description
|
|---|---|
|
twApi_SetSubscribedPropertyVTQ
|
This function sets a specified subscribed property for a specified thing, including the name of the property, its value, timestamp, and quality. Note that this call is blocked while the twApi_PushSubscribedProperties is being called.
|
|
twApi_PushSubscribedProperties
|
This function pushes subscribed properties for a specified thing to ThingWorx Platform. When this function is being called, it blocks the function twApi_SetSubscribedPropertyVTQ. This function does not return until the data is sent to ThingWorx Platform and a response is received (or times out).
|
|
twSubscribedPropsMgr_PushSubscribedProperties()
|
This function sends (“pushes”) subscribed properties to ThingWorx Platform. When this function is called, the calling thread is blocked. This call also blocks other threads from invoking twApi_PushSubscribedProperties at the same time. If you need better throughput, use the asynchronous twApi_PushSubscribedPropertiesAsync instead.
|
|
twApi_PushSubscribedPropertiesAsync(char * entityName, char forceConnect,PushSubscribedPropertiesAsyncCallback cb, void* userdata)
|
This function sends (“pushes”) subscribed properties to ThingWorx Platform asynchronously. The calling thread does not block nor does it block other threads.
The userdata is used as a correlation Id and will be passed into the callback. You can use the callback to handle the asynchronous results from this call.
When this function is called, the calling thread is not blocked, and this call does not block other threads from making the same call..
If twApi_PushSubscribedPropertiesAsync results in multiple UpdateSubscribedPropertyValues calls (due to message size), then the callback is invoked multiple times. In all cases, the final callback invocation is indicated by a char parameter on the callback function.
|