Device State

Device state is one of the core communication and data components of the Losant Platform. A device’s state represents a snapshot of the device at some point in time. For example, if the device has a temperature sensor, it might report the temperature every minute. Losant stores every state request and makes them available in visualizations and workflow triggers.

State is defined as one or more attributes. Typically an attribute maps to a single sensor or other data source. For Losant to process and store device state, you must define the attributes that the device reports.

Reporting State

A device can report state as often as needed, as long as it’s in the Losant Platform’s rate limitations or below two per second. Devices are not required to report all attributes every time. For example, a thermostat might report the inside-temp attribute every few minutes, but only report the temp-setting attribute when the user changes it.

Standalone or Gateway devices typically report state over an MQTT or REST connection. The Losant MQTT clients allow you to form MQTT connections and report state to Losant. If your device only reports state every few minutes or every few hours, then the REST interface is a better option since it doesn’t maintain a persistent connection.

Edge Compute devices typically report state using the Device State Node in Edge Workflows that are deployed to the device. The state reports generated by those workflows are then sent to Losant over the same MQTT topics that Standalone or Gateway devices use.

Peripheral devices do not connect to Losant or report their own state. A Gateway or Edge Compute device generally reports the state of a Peripheral device on behalf of that hardware.

System devices cannot report state directly to the system. Rather, state is derived from the child devices that make up the system and these state reports occur on a fixed interval.

Application workflows can also report state using the Device State Node. In addition, when authenticated against the Losant API as a user or using an application API token, the Device: Send State API endpoint can be used to record state for any type of device. (Exception: Neither the Device: State Node nor the API endpoint report state for a System device.)

Including Meta Information

Optionally, a meta value may be included with a state report to provide additional information to any Application Workflows that may fire as a result of the state report. The value of the meta property may take any shape: string, number, object, etc. A state report payload containing a meta value resembles the following:

{
  "data": {
    "myAttribute": 42
  },
  "meta": {
    "reportedBy": "Mr. Tibbs",
    "quality": 95
  }
}

This value is available on the initial payload of any Device: State Trigger, and it also appears with the state report in the live application and device communication logs. The value is not stored in the time series database, nor can it be retrieved from any API request or interface after the fact.

Including Timestamps

Devices may optionally include a time to correspond to the data being reported. If provided, the time can be provided in a number of different formats.

• EJSON format (e.g. {"time": { "$date" : "<ISO Date String>" } }).
• Seconds since the Unix Epoch (e.g. {"time": 1476479740 }).
• Milliseconds since the Unix Epoch (e.g. {"time": 1476479740543 }).
• A string that is recognizable by the JavaScript Date.parse() method (e.g. {"time": "2016-10-14T21:16:34" }).
• Negative numbers are treated as relative milliseconds, for example,. {"time": -60000 } is treated as 60 seconds ago.

If the time field is omitted, or if the provided string cannot be parsed, Losant automatically uses the current time instead.

The ability to pass a time along with state data is important for three reasons:

Batch Reporting

If your use case allows for it, your state reports can be collected on the device and sent to the Losant API as an array of payloads in one request. This can, for example, provide for more efficient power consumption or allow the device to continue recording state when it loses an Internet connection.

Overwriting Previous States

If a state payload is sent with a timestamp, and that timestamp corresponds to a previously reported state down to the millisecond, the new payload overwrites any attribute values reported within that payload. Any attributes reported on the original payload that are not part of the new payload remain intact. Overwriting device states will still trigger workflows that are tied to that device’s reporting of state.

Reporting Historical State

You can also set a timestamp on a payload to report historical state information, for example, if a device is offline when it attempts to report a value. When the device comes back online, it can report the state payload with the timestamp of when the value actually occurred. There are some limitations to this. Losant only accepts reported state whose timestamp is in the past 30 days. If state is reported with a timestamp older than 30 days, that state report will be ignored. It will not be recorded, and workflows will not run.

Reporting Future State

Overall, reporting future state is not recommended. If state is reported with a timestamp more than 24 hours in the future, that state report is ignored. It will not be recorded, and workflows will not run.

Using State

Once your device is reporting state, the information is most commonly used for dashboard visualizations and workflow triggers.

There are many dashboard blocks that show state information. The blocks can either show the real-time value as it’s reported or show aggregates over time. For a thermostat, for example, you could graph the average indoor temperature per day over the last 30 days.

Device state can also trigger workflows. Workflows are the primary method your devices will connect with each other and the outside world. A typical workflow for a thermostat might be to send an SMS if the indoor temperature drops below 40 degrees, which would indicate the user’s furnace is malfunctioning.

Device Data Tab

To quickly view a device’s past reported states, you can navigate to the Data tab available in the device’s detail page. From here you can construct a data query for specific attributes, time ranges, and optionally an aggregation method. Clicking Fetch Data will display the results of your query in the table, after which you may sort the values, export the data, or delete data.

Data Actions

Once you have constructed a query and returned data, you may perform several different actions on the returned data. By clicking the dropdown menu in the top right of the table, you can download the table contents to a CSV file, or you can delete all the data presented in the table.

Clicking the “remove” icon in any one of the table’s rows allows you to remove that specific data point. Removing a singular data point is unavailable when querying aggregated data.

Note: If you are querying a subset of the device’s attributes, deletion will only occur for those attributes you are viewing (i.e. when viewing a specific subset of attributes a data point may have contained data for other attributes not in the query. The data of those other attributes will not be affected).