Device Attributes
Attributes are properties of a device that define the data that can be reported as state against that device.
State data cannot be reported against the device unless the values in the state report have first been defined as attributes. Furthermore, the format of the data per attribute must conform to the data type for the attribute.
A device’s attributes can be viewed, created, and modified by doing the following:
- Navigate to a Device page.
- Select the “Attributes” tab.
Creating Device Attributes
Each attribute requires two properties (except system devices and Blobs):
Attribute Name: Must contain only uppercase and lowercase letters, numbers, hyphens (-), and underscores (_).
Many applications will use the same attribute name (such as temperature
) across multiple devices. You may perform aggregations on attributes of the same name across devices.
Data Type: Type of data that will be reported against the device. The default value is ”Number“.
Including Optional Fields
Optionally, you can choose “Include optional description fields” to include an attribute’s description and tag fields when creating new attributes.
For system devices, this checkbox is not present and the optional fields are always visible.
Attribute Data Types
When creating an attribute, you must choose a data type. The type should be determined both by the expected format of the data you will report against the attribute and how you wish to utilize and visualize that data.
Numbers
Number attributes only accept integers or floating points, positive or negative (or zero).
This is the most commonly used attribute data type within the platform. Number attributes can be used to store, for example, temperature and pressure information, voltage and amperage, and many other types of numerical data common to an IoT application.
Booleans
Boolean attributes accept true
or false
values in their state reports. You may report values in other types and cast them as either truthy or falsy.
Booleans are best used to answer yes (1
) or no (0
) questions, such as whether a machine is running or if a room is occupied.
Strings
String attributes are for reporting alphanumeric characters and symbols that cannot be cast as numbers, booleans, or GPS coordinates.
The max size of a string attribute is 1023 characters. If you need more storage, use a Blob.
Blobs
Blob attributes are for reporting large amounts of arbitrary binary or image data. They are reported as base64 encoded strings. You must also provide a content-type to specify a file type for your Blob Data.
GPS
GPS attributes are used specifically for tracking the position of resources in the physical world.
While the raw data is reported as a string, it must adhere to one of four strict formats to be accepted as a state report:
Decimal Degrees - (latitude, longitude)
37.33233141,-122.0312186
Degrees Minutes Seconds - (also known as Sexagesimal)
37°19'56.39"N,122°1'52.38"W
$GPGLL,3719.940,N,12201.873,S,225444,A,*1C
$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47
System Attributes
Systems are a special device type that allow you to build complex, hierarchical relationships between your application’s devices and to construct a ”digital twin” model of your device.
System device attributes are configured the same way as other device attitudes, and contain a unique name per device, a data type as described above, and some optional descriptive information.
However, System device attributes don’t report data in the same manner as other device attributes. Attributes for systems are calculated from the attributes of other devices.
Modifying Device Attributes
After creation, you cannot change an attribute’s name or data type.
If you must change an attribute’s name or data type, you must first delete the existing attribute and recreate it with the new settings.
You can, however, change an attribute’s description or tags.
For system devices, you may change its attribute calculation methods such as aggregation and child attributes.
To change these properties:
- Expand the attribute’s detail panel and make the necessary edits.
- Click “Update Attributes” to save your changes.
Deleting Device Attributes
Warning: Deleting an attribute from a device removes all data that has been reported against that attribute for the device.
To delete an attribute:
- Click the “Remove” (trash can) icon within the header of an existing attribute’s panel. This will display a checkbox near the form’s submission button.
- Using the checkbox, acknowledge that this will also delete state data.
- Click the “Update Attributes” button.
Limits
Each device has a limit of 256 attributes.
Aggregation Methods
For information concerning aggregation methods, see the References: Aggregations Section.