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 of so. Losant stores every state request and makes them available in visualizations and workflow triggers.

Device State

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

Reporting State

A device can report state as often as needed, as long as it’s within 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 make it easy 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 likely makes more sense so it doesn’t have to 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 would 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 peripheral.

System devices are a special case, in that you 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 for any type of device using the Device State Node. In addition, when authenticated against the Losant API as a user or using an application API token, the Device Post State API endpoint can be used to record state for any type of device.

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 - (e.g. {"time": -60000 } is treated as 60 seconds ago).

If the time field is omitted, or if the provided string cannot be parsed, Losant will automatically use 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. However, if any workflows are tied to that device reporting its state, the workflow will run for each payload in the array.

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 will overwrite any attribute values reported within that payload. Any attributes reported on the original payload that are not part of the new payload will remain intact. Note that 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 in order to report historical state information - for example, if a device is offline when it wants 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, however: Losant will only accept reported state whose timestamp is within 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 a day in the future, that state report will be 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 might want to graph the average indoor temperature per day over the last 30 days.

Device state can also trigger workflows. Workflows are the primary way 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.