Device List

The Device List Block allows you to display various data from one or more devices.

Device List Block

Configuration

The block parameters are broken up into the following sections.

Filter List

Device List Block Filter List

You may choose one of the following options to filter what devices show up in your list:

  • Show all devices from the application: Does not filter the device list.
  • Show devices that match any of the filters below…: Returns all of your application’s devices that match any of a set of additional filters you provide.
  • Show devices that match all of the filters below…: Returns all of your application’s devices that match all of a set of additional filters you provide.

You can also optionally add a name filter to the block itself. This allows viewers of the dashboard to filter the device list down further to find specific devices, in case there are multiple pages of devices to display. This filter is always applied in addition to the filters defined by your configuration. (Note that the inline filter field will be hidden at small block sizes, even if it is enabled here, in order to maximize the display area of the block.)

There are three types of filter you may provide:

Device Tags

Filtering by a device tag will return devices that match the key and value pair you provide. If choosing a tag that matches only against a key, any device with the key defined will be returned regardless of its value. The same holds true for choosing a tag that matches only against a value; if any key has a value matching your query, the device will be returned.

Experience User

Filtering by an experience user context variable will return devices that are associated with that experience user through their membership in experience groups. Such a filter is useful when building experience dashboard pages that should display a list of all devices associated with the current user.

Note: When building a device list using an Experience User context variable, it is extremely likely that you want to choose the “Match any of the filters below” option. Choosing the “Match all” option will, in most cases, return no devices in your list.

Search String

Filtering by a search string will return devices whose name matches the provided string. This filter accepts an asterisk * to search for any occurrence of the given characters in the device name. For example:

  • Filtering with “dev” will display a device called “Device A” but hide one called “Second Device”
  • Filtering with ”*dev” will show both the “Device A” and “Second Device” devices

Limit Data

Device List Block Limit Data

You may choose to limit the data returned for this block. Doing so can expose less information to your end-users and also reduce the time if takes this block to load. You may choose one of the following options to limit your data:

  • Return the most recent values for all device attributes: Returns the most recent values for all device attributes.
  • Return no attribute values: Does not return any device attribute values.
  • Return the most recent values for only the following attributes…: Returns the most recent values for some device attributes. If you choose this option, you must manually select the attributes you wish to include from the dropdown.

Configure Columns

The Device List Block allows for a very flexible table layout, and this section lets you determine how you want it to display your data. If a column has an input field for either header or row templates, you may use string templates and/or Markdown to further customize how your data is displayed. All header templates have a single variable available, name, which is the name of the data source for the column. All row templates have the name variable available, as well as a value variable, which is the actual value of the data for that cell.

You may choose any (or all!) of the following column types to include in your table configuration:

Device Connection Status

The Device Connection Status column is the simplest of the column types and requires no further configuration once you’ve selected it. The column includes an icon that will indicate whether or not the device is connected.

Note: New Device List Blocks will automatically include this column.

Device Name & Description

The Device Name & Description column displays text containing the device’s name as well as the description of the device (if it is set). This column does not require any further configuration unless you wish to change the default link behavior. By default, device names link to their respective configuration pages. (For public users and users who do not have permission to edit the devices’ application, no link is provided.)

You may override this behavior and link to a URL of your choosing. The custom URL supports Handlebars helpers, and information about the device (such as the name, ID and tags) is available within the template. This field also supports context variables. If a custom URL is provided, the link will always display, regardless of the user’s permission level or public status.

Note: New Device List Blocks will automatically include this column.

Device ID

The Device ID column displays the device’s ID, along with a button you can click to easily copy the ID to your clipboard. You may customize what is displayed in the header cell for this template. If you choose to keep the default header template for this column, it will display as “Device ID.”

Note: New Device List Blocks will automatically include this column.

Attribute

The Attribute column defaults to displaying the most recently reported value for a device attribute. You may alternately use the attribute’s properties (name, description, and attributeTags), which can be found on the attribute object. For example, if you wanted to display the value for the units attribute tag, you can include {{attribute.attributeTags.units}} in your row template. If you choose to keep the default header template for this column, it will display as the name of the attribute chosen in the column configuration.

Note: In order to select an attribute for this column, you must either choose to return all attributes or select it from the attribute dropdown (if only returning some additional attributes) in the “Limit Data” section.

Device Tag

The Device Tag column defaults to displaying the device tag value of the key you choose. If you choose to keep the default header template for this column, it will display as the key of the tag chosen in the column configuration.

Creation Date

The Last Updated column defaults to displaying the date the device was created. If you choose to keep the default header and row templates for this column, they will display as “Creation Date” and the date in the form of ll HH:mm, respectively.

Note: This column will sort by the pre-render value.

Last Updated

The Last Updated column defaults to displaying the date the device was last updated. If you choose to keep the default header and row templates for this column, they will display as “Last Updated” and the date in the form of ll HH:mm, respectively.

Note: This column will sort by the pre-render value.

Custom

The Custom column provides access to all available device information to be displayed in a completely custom way. It defaults to displaying the name of the device but includes a device object, which holds all device properties. These include:

  • attributes: An array of all attributes set on the device. Each attribute has a name, dataType, and attributeTags property included with it.
  • attributeValues: An object including the data for each device attribute requested in the “Limit Data” section. Each attribute is keyed by its name. For example, to find the value for the “temp” attribute, you would write {{device.attributeValues.temp}}.
  • connectionInfo: An object that holds information about the device’s connection status. It includes the connected property, which can be one of three values: true, meaning the device is connected, false, meaning the device is not connected, or null, which means the connection status of the device is currently unknown.
  • deviceClass: The type of the device. This can be one of standalone, gateway, edgeCompute, peripheral, or system. You can read more about device types here.
  • id: The device’s ID.
  • name: The device’s name.
  • tags: An object including all of the device’s tags. They are stored in key/value pairs, so to retrieve the value for a tag with the key “myTag”, you would write {{device.tags.myTag}}.

If you choose to keep the default header template for this column, it will display as “Custom.”

Sort Your Data

Device List Block Sort Arrows

After all columns have been added to your table, you have the option of setting a default sort method from the block editing screen. In the block preview, click on a column header to select it as the default column to sort by. Click the column a second time to switch the order from ascending to descending.

When viewing the block on the dashboard, you may sort by the other columns at any time by clicking the appropriate column header. However, should you refresh the page, the block’s sort order will revert to the default method that was set while editing the block.