Important knowledge for this chapter

Please make sure you have read the How to manage your device fleet documentation before going ahead here.

What is the Device State?

A device's state is a JSON document that is used to store and retrieve current state information for a device. The Device State service maintains a shadow for each device you connect to thingsHub. You can use the "Desired State" to set the configuration of a device remotely, regardless of whether the device is online / connected at the moment. As soon as the device is online again, thingsHub takes over the task of transferring the new configuration to the device.Each device's state is uniquely identified by the name of the corresponding device.

In thingsHub, the Device State is the tool for managing the OTA configuration of devices in a uniform format and for making the various setting options easy to use in the first place. This is necessary because every LNS and every manufacturer deals differently with the administration and use of feedback on the configuration status.

The Device State is maintained generically in JSON format and refers to exactly one device at a time. Accordingly, each individual device in the thingsHub has its own state. With a newly created device, the Device State is always empty until a first data packet from the device has been successfully processed by the device driver.

Note that a device almost never sends its entire configuration at once, but normally always distributed over several data packets that can be far apart in time. Some manufacturers allow you to query individual parameters separately. This is another advantage of the Device State: it allows you to see all settings at a glance without having to search for and evaluate different messages.

Difference between Reported State and Desired State

A devices "Reported state" (device shadow/twin) is a JSON representation used to store all received state changes of a device. Such information can be the measured values such as "temperature" and "pulse numbers" or a configuration such as the frequency at which the device transmits its data. The "Reported state" is fully managed by thingsHub´s device drivers and cannot be manipulated by the user directly.

The "Desired State" of a device can be used for remote configuration of a device. After setting a "Desired State" thingsHub uses the assigned device driver to determine the necessary downlink payloads. This passes thingsHub to the LoRaWAN Network Server so that it can send the downlinks to the device. There's no guarantee that a device has exactly the "Desired state" given. It only represents up-to-date state desired by user.

Where to find the Reported or Desired State?

The Device State of a device can be viewed or retrieved via the device detail page (see 1 or 2):

How to retrieve the Reported State through the REST API or MQTT Broker

See the REST API documentation of your thingsHub instance.

How to set the Desired State

See chapter "How to configure a device" below.

How to configure a device? How to set a device configuration remotely?

The Desired State, on the other hand, describes the desired configuration or target configuration, which Over-The-Air is to be sent to the device. Here you can specify the desired changes, which are then packed into a payload by the driver and finally sent by the LNS via downlink to the device.

As soon as a change has been made successfully, the value is transferred from the Desired State to the Reported State in order to do justice to the actual configuration. If all changes were successfully applied thingsHub will stop sending configuration changes to the device.

There is also the possibility to check whether the driver from the Desired State could successfully create a payload for the downlink. For this you can use 'PUT /api/v3/devices/{id}' via the REST API endpoint with the Desired State in the body, formatted as JSON, to query the driver. The answer "Success" means that the driver has successfully created a payload.