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:

1. Navigate to a Device page.
2. 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.

Learn more about Blobs.

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

NMEA GLL

$GPGLL,3719.940,N,12201.873,S,225444,A,*1C

NMEA GGA

$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.

Learn more about Systems.

Viewing Device Attributes

After creating an attribute, a device attributes table will be displayed showing the attribute name, data type, last reported value, and last reported time. The attributes last reported value and time will be refreshed every 30 seconds. You may also perform a manual refresh.

Depending on the data type of the attribute, the last reported value may be formatted differently. For example, a boolean attribute will be displayed as either True or False. A number attribute will be displayed as a number, and a string attribute will be displayed as a string. A blob attribute will be displayed as a link to the blob. A GPS attribute will be displayed as a link to Google Maps.

In the case that you have a large number of attributes, you may filter the attributes that are displayed by entering the name of the attribute in the text input located above the table.

You will also be able to add, edit, and delete existing attributes from this table as long as you have collaborator or higher permissions.

A System device also displays the current “System Attribute Reporting Behavior” setting shown below.

Viewing Attribute Tags

If you’d like to view all of your attribute tags at once, you can click the dropdown menu icon at the top right of the table and select “Show Attribute Tags”.

The table will now show columns for each attribute tag key that has been created. If an attribute has a value for a given key, it will show that value in its respective row.

To hide the tag columns, reopen the dropdown menu and select “Hide Attribute Tags”.

Modifying Device Attributes

Click on the attribute name displayed in the table to view the attribute’s details.

You cannot change an attribute’s name or data type once the attribute has been created. However, you can change the attribute’s description or tags.

For system devices, you may change its attribute calculation methods such as aggregation and child attributes.

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:

1. Click the dropdown menu icon at the right edge of the attribute’s row.
2. Click the “Delete Attribute” option. This will display a confirmation modal.

Adding Additional Attributes

Click the “Add” button located above the attributes table over on the righthand side of the screen to add a new attribute.

A new attribute form will be displayed where you can enter the attribute name, data type, description, and attribute tags. For system devices, you can select the aggregation method for the last reported value of each child device attributes. After selecting the aggregation method, you can to choose which child device attributes to include in that calculation.

Clicking on “Add another attribute” checkbox will allow you to add additional attributes without closing the modal after submission.

Adding Multiple Attributes

If you wish to quickly create multiple attributes at once, click the dropdown menu icon at the top right of the table and select “Add Multiple Attributes”. This option is only available for non-system devices.

From here you may define the name and type of each attribute you are adding.

Note: You will not be able to define attribute descriptions or tags via this method; however, you may modify the attributes after submission to add these properties if necessary.

Cloning Attributes

To clone an existing attribute, click the dropdown menu icon at the right edge of the attribute’s row. From there you may click “Clone Attributes”. This will open the “New Attribute” modal with all but the name field prepopulated.

Limits

Each device has a limit of 256 attributes.

Aggregation Methods

For information concerning aggregation methods, see the References: Aggregations Section.