Viewing the state of device resources

Device Echo stores a snapshot of the last reported state and desired state of the device along with the timestamp information. You can also use Device Echo to store your device configuration and application resources.

You can, for example, build a serverless mobile application for your field engineers to check the device configurations and resource values, and write new ones without implementing your own device database.

Device Echo does not automatically pull in resource values. You need to subscribe to, read or write them to have the information visible in Device Echo.

Device Echo provides for each resource in a device:

• Last reported value - the last reported value of the resource:
  • received in a register message
  • read in by a separate read request or
  • received as an event for a subscription.
• Timestamp of the last reported value - the time of the latest value received from device.
• Last desired value - the value that was asked to be written to the resource.
• Last desired value status - the status of the write command:
  • pending(0)
  • success(1)
  • failure(2)
• Last desired value timestamp. - the time the new values were requested to be written or when the write command succeeded or failed.

Properties and limitations

Note: The device data stored in Device Echo can contain device users' personal data. Please consider this in your data privacy policy and processes. Read more about Izuma IoT platform terms and policies.

Requesting a Device Echo object

To request a device object from Device Echo, use GET /v3/devices/{device-id}/echo. The returned object contains a snapshot of each resource's reported and desired values with the timestamps.

Reading resource values from a device with Device Echo

When you read resources from a device, the returned values are stored in Device Echo:

1. A device registers with resources "Res_1" and "Res_2". Device Echo shows empty resource values.
2. A web application issues a read command for "Res_2" using POST /v2/device-requests/{device-id}.
3. Device Management responds with 202 Accepted. The command is in the command delivery queue waiting for the delivery to the device.
4. Device Management puts the read command to the guaranteed command delivery queue. See Request delivery modes.
5. Device Management delivers the command to the device.
6. The device responds with value 34.
7. Device Management updates Device Echo with the reported value and timestamp.
8. Device Management sends an asynchronous response to the requesting application.

Writing resource values to device with Device Echo

Device Echo shows the result of the last write command as the last desired value with the status information. The write command can be still pending in the queue or it completes with the success or fail status.

1. A device registers with resources "Res_1" and "Res_2". Device Echo shows empty resource values.
2. A web application issues a write command for "Res_1" using POST /v2/device-requests/{device-id}.
3. Device Management responds with status 202 Accepted. The command is in the queue waiting for the delivery to the device.
4. Device Echo is updated with the new write command. The desired_at field of the desired object shows the time of web application issuing the command. The status of the desired value is pending.
5. Device Management sends the write command to the device. See Request delivery modes.
6. The device responds with status success.
7. Device Echo sets the desired value's status to success and updates the timestamp which now indicates the time of the status update.
8. Device Management sends an asynchronous response to the requesting application.

Failure in writing

If a write command to a device fails, the desired value's status shows fail:

• The device does not connect while the command is in the queue. The time the command waits in the queue depends on the expiry_seconds set in POST /v2/device-requests/{device-id}.
• Many of the failures are caused by the device and depend on the application-level configuration. For example, if a resource is not writeable, the write command causes a fail state in Device Echo. The error category is in the asynchronous response, provided only to the application placing the write command.

Subscribing with Device Echo

Subscribing to resources enables data flow from device to Device Echo. Device Management Client does not send an observation without a subscription unless the resource is auto observable.

This is how subscribed resources show in Device Echo:

1. A web application places a presubscription rule with the PUT /v2/subscriptions API to subscribe to "Res_2" of all devices.
2. Device Management responds with 202 Accepted. The presubscribtion rules are checked against all devices when they register or update their registration.
3. A device registers with resources "Res_1" and "Res_2". Device Echo shows empty resource values.
4. Device Management sends a subscribe command to the device for the "Res_2"
5. The device responds with success status and provides the initial value of the "Res_2"
6. Device Management updates Device Echo with subscription status True for "Res_2"
7. Device Management updates the reported value of "Res_2" with the initial value received from the device.
8. Device Management sends an observation event of the initial value to the subscribing web application

Auto-observed (AOBS) resources in Device Echo

Device Echo stores all values coming from a device. The values are received from the device when you use subscribe, read or auto-observation commands. The subscribe and read commands are the most commonly used methods to get data from devices. AOBS provides a way to "hardcode" the subscription to the device. It enables the data flow from devices which do not have RAM retention and start from clean after sleep. Device Echo shows AOBS observations as reported values.

1. A device registers with resources "Res_1" and "Res_2", where "Res_2" is set as AOBS in the device. Device Echo shows empty resource values.

2. The device sends an observation of the value change in resource "Res_2"

3. Device Management updates the reported value in Device Echo according to the observation received.

   Note: Device Management sends the observation event to the web application only if there is a subscription. In this example, there is no subscription from the web application and thus, no observation event is sent to it.

4. To receive a device object, the web application needs to call the GET /v3/devices/{device-id}/echo API.

5. Device Management returns the Device Echo object to the web application. It contains the "Res_2" value received as auto observation.

Adding and removing device resources with Device Echo

A device can introduce new resources to its structure and Device Echo will take them into the device object. If you remove a resource from device, Device Echo does not clear it from its device object.

Note: Deleting a device object or a resource from a device object is feature planned for future.