Using Aspects
Aspects further define properties and how you want to send values to your ThingWorx Platform. Aspects define what happens when the value of a property changes, what threshold generates a change event, and whether a property is persisted or and can be changed at the ThingWorx Platform. Further, the cacheTime and pushType aspects define how the platform behaves when it needs to read the value of a property.
 |
It is good practice to define aspects at the edge because the platform user may not know what to set on a property.
|
Aspects can also be set as part of an annotation. The section, Annotations, shows how.
Click a section title below to display its content:
Data Collection
The Edge Java SDK and the ThingWorx Platform provide the following ways to collect information about a device:
• Collect a new value at the device, store it, and then forward it to the ThingWorx Platform. The device sends the value only when it changes. In this case, use the dataChangeThreshold aspect on the property to push by value change with a non-zero threshold.
• Set up a cycle at the device for collecting property values and pushing them to the platform In this instance, set the pushType to ALWAYS.
• Fetch a property value when the platform needs it by sending a request from the platform to the device. The device sends the current property value only on request. In this instance, since you always want to fetch (read a property value) from the remote device, set the cacheTime aspect of the property to any positive value.
 | This last way to collect property values is rarely used. |
All of these options work with edge subscribed properties APIs. When working with the SDK, you need to use the APIs to set values for properties and to set up when and how you want to send them to the platform, such as individually or in a group, by setting the aspects for properties: dataChangeType, pushType, cacheTime, dataChangeThreshold, isFolded, isPersistent, isReadOnly, and defaultValue. The SDK APIs for subscribed properties inspect these aspects and adjust automatically, but you must use the APIs to send data to the ThingWorx Platform. For more information about aspects, refer to Using Aspects.
Aspect Definitions
The following table describes aspects that are frequently used as part of a property definition. The aspect names are found in the file, com.thingworx.types.constants.Aspects. You can use them either in an annotation or in methods.
Aspect | Definition | ||
|---|---|---|---|
dataChangeType | This aspect acts as the default value for the data change type field of the property when it is added to the Remote Thing on the ThingWorx Platform. The data change type describes how the platform responds when the value in the Remote Thing on the platform changes. Subscriptions to these value changes can be created on the server. For details about implementing subscriptions, refer to the Help Center for the ThingWorx Platform. For now, what you need to remember is that the setting you choose for the dataChangeType field affects what the platform does when the value of the property changes. If nothing needs to react to the property change, it is recommended that this value be set to NEVER. Refer too the table, Table 13, for information about the possible values for this aspect. | ||
dataChangeThreshold | This aspect acts as the default value for the data change threshold field of the property once the property is bound to the Remote Thing on the ThingWorx Platform. This aspect 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, for example, means that an update is not triggered unless the value changes by an amount greater than or equal to 10. | ||
isPersistent | Set the value of this aspect to true for the ThingWorx Platform to persist the value, even if the platform restarts. It is extremely expensive to have persistent values, so it is recommended to set this value to false unless persistence is absolutely necessary. | ||
isReadOnly | Set the value of this aspect to true to inform the ThingWorx Platform that this property's value can only be read by the platform, not written. | ||
cacheTime | Tells the ThingWorx Platform how to behave when reading a remote property. This aspect works in conjunction with the pushType aspect and can take the following values: • -1 — The platform should always get a property value from the edge. • 0 — The platform always gets a property value from the cache. • Any other positive value — The platform caches the value for the number of seconds specified and then only after that time expires, requests it from the edge.
| ||
pushType | The value of this aspect informs the ThingWorx Platform how the VirtualThing pushes its values to it. This aspect works in conjunction with the cacheTime. aspect. Refer too the table, Table 14, below for the available values for this aspect. These evaluations are performed whenever the updateSubscribedProperties() method of the VirtualThing is called to determine which properties to push to the platform. | ||
defaultValue | This aspect defines the value that the ThingWorx Platform uses when the Remote Thing that is bound to the VirtualThing first starts up and has not had an update from the VirtualThing. The value is different based on the type for each property. | ||
isFolded | This BOOLEAN aspect specifies how property values are pushed to the ThingWorx Platform: • TRUE — Sets of property values are stored, but only the last set of property values is pushed to the platform when updateSubscribedProperties is called. This is the default value of this aspect. • FALSE — All property updates, along with a timestamp, are queued and sent to the platform.. |
Values for the dataChangeType Aspect
Here are definitions of the values for the dataChangeType aspect:
dataChangeType | Description |
|---|---|
ALWAYS | Always notify subscribers that the value has changed, even if the same value comes in multiple times in a row. |
VALUE | Notify subscribers only if the value changes. |
ON | For BOOLEAN properties, notify subscribers only if the value is true. |
OFF | For BOOLEAN properties, notify subscribers only if the value is false. |
NEVER | The ThingWorx Platform should do nothing when the value of the property changes. |
Values for the pushType Aspect
Here are the possible values for the pushType aspect:
Push Type | Description |
|---|---|
ALWAYS | The VirtualThing sends updates even if the value has not changed since the lat time it was sent.. It is common to use a cacheTime setting of 0 in this case, so that the platform always reads from the cache. |
NEVER | The VirtualThing never sends the value. It is common to use a cacheTime setting that is greater than zero, so that the platform requests the value from the device, but only if the cached value is older than the number of seconds that is specified for cacheTime. |
VALUE | The VirtualThing sends updates only when the value changes. It is common to use a cacheTime setting of 0 in this case, so that the server always reads from the cache. You could also use a value greater than 0 for cacheTime with a pushType of VALUE. Then, the platform would read the value from the cache, as long as the value is not too old. The device would keep the cache on the platform up to date with the latest change. That would allow dataChange events to fire on the platform, but also give users the latest value if they requested it. |