SDK Reference Part 6

Yes

Step 8: C - Properties

Step 8: C - Properties

In the ThingWorx environment, a Property represents a data point, which has a:

Name
Value
Timestamp
Quality (optional)

Define Properties

You can define attributes, base types and other aspects of ThingWorx properties.

Attributes

The table below provides information on the different attributes that are used to define a property.

Attribute	Details
name	Specifies the name of the property that will appear in ThingWorx when users browse to bind the related Thing.
description	Provides additional information for the property.
baseType	Specifies the type of the property. For a list of base types supported by the SDK, refer to the BaseTypes chart below.

BaseTypes

The table below provides information on the different types of properties that can be created in ThingWorx.

BaseType	Description
TW_NOTHING	An empty value.
TW_STRING	A modified UTF8 encoded string. Data and length are stored in val.bytes and val.len, respectively. The twPrimitive owns the data pointer and will free it when deleted. TW_STRING types are null terminated.
TW_NUMBER	A C double value, stored in val.double.
TW_BOOLEAN	Represented as a single char, stored in val.boolean.
TW_DATETIME	A DATETIME value, which is an unsigned 64 bit value representing milliseconds since the epoch 1/1/1970. Data is stored in val.datetime.
TW_INFOTABLE	A pointer to a complex structure (defined in the next section) and stored in val.infotable. The twPrimitive owns this pointer and will free up the memory pointed to when the twPrimitive is deleted.
TW_LOCATION	A structure consisting of three double floating point values – longitude, latitude, and elevation. Stored as val.location.
TW_BLOB	A pointer to a character array. Data and length are stored in val.bytes and val.len, respectively. Differs from TW_STRING in that the array may contain nulls. The twPrimitive owns the data pointer and will free it when deleted.
TW_IMAGE	Identical to TW_BLOB except for the type difference.
TW_INTEGER	Assigned 4 by integral value. Stored as val.integer.
TW_VARIANT	Pointer to a structure that contain a type enum and a twPrimitive value. The pointer is stored as val.variant. The twPrimitive owns the pointer and will free the structure when deleted.

The following base types are all of the TW_STRING family and are stored similarly:

TW_XML,TW_JSON
TW_QUERY
TW_HYPERLINK
TW_IMAGELINK
TW_PASSWORD
TW_HTML
TW_TEXT
TW_TAGS
TW_GUID
TW_THINGNAME
TW_THINGSHAPENAME
TW_THINGTEMPLATENAME
TW_DATASHAPENAME
TW_MASHUPNAME
TW_MENUNAME
TW_BASETYPENAME
TW_USERNAME
TW_GROUPNAME
TW_CATEGORYNAME
TW_STATEDEFINITIONNAME
TW_STYLEDEFINITIONNAME
TW_MODELTAGVOCABULARYNAME
TW_DATATAGVOCABULARYNAME
TW_NETWORKNAME
TW_MEDIAENTITYNAME
TW_APPLICATIONKEYNAME
TW_LOCALIZATIONTABLENAME
TW_ORGANIZATIONNAME

Aspects

Aspects define the ways to interact with a property. The table below provides information on details that make up the Aspects attribute of a property.

Attribute	Macro	Description
isPersistent	TW_ASPECT_ISPERSISTENT	Set to TRUE for the ThingWorx server to persist 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	TW_ASPECT_ISREADONLY	Set to TRUE to inform the ThingWorx server that this value is only readable and cannot be changed by a request from the server.
dataChangeType	TW_ASPECT_DATACHANGETYPE	Describes how the ThingWorx server responds when the value changes in the client application. Subscriptions to these value changes can be modeled in ThingWorx Platform. If nothing needs to react to the property change, set this value to NEVER.
dataChangeThreshold	TW_ASPECT_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	TW_ASPECT_DEFAULT_VALUE	The default value is the value that 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.
cacheTime	N/A	The amount of time that ThingWorx Platform caches the value before reading it again. A value of -1 informs the server that the client application always sends its value and the server should never go and get it. A value of 0 (zero) indicates that every time the server uses the value, it should go and get it from the client application. Any other positive value indicates that the server caches the value for that many seconds and then retrieves it from the client application only after that time expired.
pushType	TW_ASPECT_PUSHTYPE	Informs ThingWorx Platform how the client application pushes its values to the server.

NOTE: cacheTime and dataChangeThreshold are for subscribed (bound) properties ONLY.

DataChangeType Values

This field acts as the default value for the data change type field of the property when it is added to the remote Thing. The possible dataChangeType values are below:

Value	Description
ALWAYS	Always notify of the value change even if the new value is the same as the last reported value.
VALUE	Only notify of a change when a newly reported value is different than 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.

PushType Values

This aspect works in conjunction with cacheTime. The possible pushType values are below:

Value	Description
ALWAYS	Send updates even if the value has not changed. It is common to use a cacheTime setting of -1 in this case.
VALUE	Send updates only when the value changes. It is common to use a cacheTime setting of -1 in this case.
NEVER	Never send the value, which indicates that ThingWorx server only writes to this value.It is common to use a cacheTime setting of 0 or greater in this case.
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.

With Macros

The C SDK provides a list of macros to help make development easier and faster.

The macros TW_PROPERTY and TW_PROPERTY_LONG define a property of a Thing. This macro must be preceeded by either TW_DECLARE_SHAPE,TW_DECLARE_TEMPLATE or TW_MAKE_THING macros because these macros declare variables used by the property that follow them. The functions return TW_OK on success, {TW_NULL_OR_INVALID_API_SINGLETON,TW_ERROR_ALLOCATING_MEMORY,TW_INVALID_PARAM,TW_ERROR_ITEM_EXISTS} on failure.

NOTE: The macros are defined in the file, twMacros.h.

This example shows how to utilize these functions:

TW_MAKE_THING(thingName,TW_THING_TEMPLATE_GENERIC);
    TW_PROPERTY("Pressure", TW_NO_DESCRIPTION, TW_NUMBER);
        TW_ADD_BOOLEAN_ASPECT("Pressure", TW_ASPECT_ISREADONLY,TRUE);
        TW_ADD_BOOLEAN_ASPECT("Pressure", TW_ASPECT_ISLOGGED,TRUE);
    TW_PROPERTY("Temperature", TW_NO_DESCRIPTION, TW_NUMBER);
        TW_ADD_BOOLEAN_ASPECT("Temperature", TW_ASPECT_ISREADONLY,TRUE);
        TW_ADD_BOOLEAN_ASPECT("Pressure", TW_ASPECT_ISLOGGED,TRUE);
    TW_PROPERTY("TemperatureLimit", TW_NO_DESCRIPTION, TW_NUMBER);
        TW_ADD_NUMBER_ASPECT("TemperatureLimit", TW_ASPECT_DEFAULT_VALUE,320.0);
    TW_PROPERTY("Location", TW_NO_DESCRIPTION, TW_LOCATION);
        TW_ADD_BOOLEAN_ASPECT("Location", TW_ASPECT_ISREADONLY,TRUE);
    TW_PROPERTY("Logfile", TW_NO_DESCRIPTION, TW_STRING);
        TW_ADD_BOOLEAN_ASPECT("Logfile", TW_ASPECT_ISREADONLY,TRUE);

NOTE: TW_PROPERTY_LONG performs the same actions as TW_PROPERTY, except that it offers more options. When using TW_PROPERTY to declare a property you are accepting the use of the default property handler. This property handler will allocate and manage the storage used for this property automatically.

Without Macros

Property values can be set with defaults using the aspects setting. Setting a default value in the client will affect the property in the ThingWorx platform after binding. It will not set a local value in the client application. Two types of structures are used by the C SDK to define properties.

Structure	Notes	Code
Property Definitions	Describes the basic information for the properties that are going to be available to ThingWorx and can be added to a client application.	twPropertyDef *property1 = twPropertyDef_Create(property, TW_BOOLEAN, "Description for Property1", "NEVER", 0); cJSON_AddStringToObject(tmp->aspects,"isReadOnly", "FALSE"); cJSON_AddStringToObject(tmp->aspects,"isPersistent", "FALSE"); cJSON_AddStringToObject(tmp->aspects,"isPersistent", "FALSE");
Property Values	Associates the property name with a value, timestamp, and quality.	twPrimitive * value = twPrimitive_CreateFromNumber(properties.TempProp); twProperty * tempProp = twProperty_Create("TempProperty", value, NULL);

Click here to view Part 7 of this guide