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 Attributes

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

Device Attributes

Losant supports and understands a built-in set of data types for device attributes. These include String, Number, GPS String, and Boolean. If you specify a state attribute as one data type and report something different, the Losant Platform will attempt to convert the incoming data type into the one specified. Values for a string attribute have a maximum size of 64KiB.

GPS attributes must be reported in one of four ways:

  • Decimal Degrees (latitude, longitude) Example: 37.33233141,-122.0312186
  • Degrees Minutes Seconds (also known as Sexagesimal)
    Example: 37°19'56.39"N,122°1'52.38"W
    Example: $GPGLL,3719.940,N,12201.873,S,225444,A,*1C
    Example: $GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47

Attributes can be added and removed from a device at any time. If you change the data type of an existing attribute, the previous data for that attribute will be lost. This is because Losant won’t be able to aggregate data of two different data types for the same attribute.

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.

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, doing so means fewer HTTP requests, 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 which has a timestamp older than 30 days, that state report will be ignored - it will not be recorded, and workflows will not be 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 be 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. A thermostat, for example, might want 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.