Every data card reads a data source: a query that returns a value, a series, a table or a record. Parameters make one board work for many devices or sites. Key filters narrow a set of devices by their values. This page lists the IoT sources, explains how the time window and aggregates work, and shows how to build a board that follows whatever device or site the viewer picks.
How a card gets its data
A widget declares slots: what it needs, never where it comes from. A gauge needs one value; a line chart needs a series; a table needs rows. In the card’s Data tab you fill each slot:
- Pick the source and the query, for example A value of a device (live).
- Fill its fields: the device (or Take it from the dashboard, see below) and the value.
- Select Save.
A line, bar or area chart’s series slot takes up to 8 sources (+ Add another source), so one chart can show values of several devices.
Also list the sample data and the developer sources shows sources meant for testing. Leave it off for production boards.
IoT data sources
| Query | Gives | Live |
|---|---|---|
| A value of a device (live) | One key of one device, picked from the values the device sends | Yes |
| Device readings over time (live) | Up to 20 keys of one device over the time window, aggregated per interval. auto follows the first numbers the device sends. | Yes |
| Latest values of many devices (a row per device) | A row per device (all, one profile, or a parameter’s devices) with up to 20 keys; at most 500 rows | Polled |
| Latest values of a device as one record | Up to 20 keys of one device as one record (for Attributes or a Form) | Polled |
| Every latest value of a device | A row per key with its name and unit (at most 500) | Polled |
| The live values of a device, for its drawing or 3D view | A row per element of a device that sends <element>.<field> keys | Polled |
| One element of a device’s process diagram, One element of a device over time (live), One element’s readings, named for a person | One element’s row, its trend, or its readings by name | Mixed |
| Devices (live connection state) | Your devices with connection, status, profile and last seen; filters for profile, status and connection; at most 500 rows | Yes |
| One attribute of the device at a position of a set | A server or shared attribute, for example a camera’s live address | Polled |
| Alarms (live) | Alarms by status (Active, Open, Acknowledged, Resolved, Every status) and severity; at most 500 rows | Yes |
| Alarm counts by severity (live) | One count per severity | Yes |
| Sites and assets (the tree as rows), Assets of an alias, Devices under an asset | The asset tree, assets of a parameter, devices under one asset | Polled |
| Status under an asset | A row per child: worst status, devices, open alarms | Polled |
| One site for a page header | Name, place, status, devices, open alarms, last seen | Polled |
Names, units, decimals and value ranges come from the device profile’s telemetry keys. Each query checks your permissions: a device you may not read answers as empty, the same as one that does not exist.
Time window and aggregates
A chart that follows the board window (Use the dashboard time window) shows the period the viewer picks in the toolbar. A card can also pin its own window (Pin: last …) or show the period just before (same length) to compare.
| Setting | Values |
|---|---|
| Relative windows | Last 5, 15 or 30 minutes; 1, 6, 12 or 24 hours; 3, 7, 14, 30, 90 or 365 days; any other “last N minutes, hours or days” |
| Calendar periods | This hour, Today, This week, This week (Mon), This month, This quarter, This half year, This year, and the previous one of each; Yesterday, Day before yesterday, This day last week |
| Longest window | 366 days |
| Grouping interval | auto, 1, 5, 10, 15 or 30 minutes, 1, 2, 6 or 12 hours, 1 or 7 days |
| Most intervals in one window | 500 (a finer interval is coarsened) |
With auto, a window up to 1 hour is grouped by the minute, up to 1 day by 5 minutes, up to 7 days by the hour, and longer windows by the day.
The aggregate of Device readings over time is one of:
| Aggregate | Per interval |
|---|---|
avg, min, max | Average, lowest, highest value |
last | The last value |
sum, count | Total, number of readings |
increase | For counters (energy, water meters): the rise since the previous interval. A drop is taken as a counter reset and counts from zero. The first interval counts what rose inside it. |
Windows longer than 24 hours are answered from stored aggregates, not raw readings. Raw readings are kept 7 to 90 days depending on your organisation’s retention class (set by your plan); minute aggregates up to 31 days; hourly and daily aggregates for the whole class (up to 1,095 days). See How long data is kept and Aggregates and rollups.
A window without a time zone uses the viewer’s browser time zone. Board settings can let viewers change the Grouping interval, Aggregation (Average, Minimum, Maximum, Sum, Count, None (raw values)) and Time zone. Save as default (writers only) keeps the window for everyone.
Parameters
A parameter is a value or an entity the cards read. Open Manage parameters… while customising. A board holds up to 16 value parameters and 48 parameters in all; the filter bar shows at most 16.
| Kind | Example |
|---|---|
| Value: text, Value: number, Value: date, Value: yes or no, Value: fixed list, Value: list from an address | A threshold, a shift, a product |
| Entity (a device, an asset…) | The device a page is about |
For an entity parameter you choose:
| Setting | Choices |
|---|---|
| How it is chosen | The viewer picks; The page or a link sets it; Fixed: one entity; Fixed: a list; All of the type; By name; By subtype or profile; Related to another parameter or entity |
| One or many | One entity or Many entities |
| In the filter bar | Shown, viewers can change it, Shown, not changeable, Hidden |
A parameter’s key starts with a lowercase letter and has at most 40 letters, digits or underscores. Renaming a key breaks cards and links that use the old one. You cannot remove a parameter that cards, pages, filters or other parameters still use; the window names them.
Bind a card to a parameter
In the card’s data field, choose Take it from the dashboard and pick the parameter, or The device this page shows. When a card takes one device and the parameter holds a site, the card takes the devices under the site; if there are several, it says “?p.device=…), so a copied link opens the same view.
Caps: a resolved set holds at most 500 entities (the first 500 by name); a fixed list holds at most 100; relation depth 1 to 10 levels.
Key filters
A key filter narrows an entity parameter by values, for example “devices whose temperature is above 30″. Open Manage key filters….
- A key is an Entity field, an Attribute (any, client, shared or server scope) or Latest telemetry.
- Value types: Text, Number, Boolean, Date and time.
- Operations: equal, not equal, greater, greater or equal, less, less or equal, between, in, not in, is set, is not set, is true, is false, starts with, ends with, contains, does not contain.
- Join conditions with And: all of them match or Or: any of them matches.
- Mark a filter editable to let viewers change it.
Caps: 16 filters per board, 8 key filters per filter, 4 conditions per key filter.
Live data
Cards marked live update while the board is open. A board uses one connection for all its cards. Cards that cannot update live refresh on their interval; a table that pages always refreshes on its interval. When the live connection is unavailable the board says “Live updates unavailable — polling”.
Readings in business records
A device key can also feed a field of a business record, for example an asset’s meter. Set this up under Readings mapping in the ⋯ menu of Devices, or on a device’s Feeds tab.