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
View full tip
