Device Image

Device image is a json file allocated by OneNET for each device to store its latest status/configuration information.

Scenarios

Device image can be applied to the following scenarios:

• Store static device properties, e.g. device installation location

• Store current device status information, e.g. current networking mode and running status

• Synchronize the execution status of long-running tasks between devices and applications, e.g. all status and result notifications the devices report during firmware upgrade

• The application layer queries device configuration/status information

• When the application layer expects the device to reach a certain long-term configuration/state in a very bad network/low power mode, the device image can host the communication process and accomplish the communication under expectations set for the configuration/state after the device goes online.

An image json file contains the following information:

• System properties

  System-defined properties of a device, e.g. device ID, creation time, online status, etc., which are invisible to the device and read-only to the application layer.

• Tags

  Used to mark device type, e.g. deployment area and application project, which are invisible to the device and read-write to the application layer.

• Desired property (desired)

  Used in the application layer to express the desired state/configuration of a device, which is read-write to both the application layer and the device.

• Reported property (reported)

  Used for a device to report its current status/configuration information, which is combined with the desired property. When there is a difference between the reported property and the desired property, the platform can send the difference to the device so that the configuration/status of the device can be synchronized and be read-write to both the application layer and the device.

• Difference (delta)

  Used to express the difference value between the reported property and the desired property, which will trigger difference calculation every time image json is updated. If a difference value exists, the platform can send the difference message to the device, and the difference is read-only to both the application layer and the device.

Common Usage Modes

In real-life scenarios, users can refer to the following usage modes:

• The device subscribes to delta messaging and reports properties to reported.

• The application layer updates the desired property when the status/configuration information of the required device changes.

• When the device is online and subscribed to delta messaging, the platform sends a delta message to the device.

• The device receives the delta message, adjusts the status/configuration, and reports new properties to reported.

• When reported is consistent with desired, the delta property disappears. Device and application can periodically check all properties.

• The application can mark one device type with a tag.

Image json

Below is an example of image json:

{
    "deviceId": "638612",
    "createTime": 1469564492,
    "status": "enabled",
    "statusReason": "created",
    "statusUpdateTime": 1469564492,
    "connectionState": "online",
    "lastActivityTime": 1469564492,

    "tags": {
        "building": "43",
        "floor": "1"
    },

    "properties": {
        "state": {
            "desired": {
                "lights": {
                    "color": "RED"
                },
                "engine": "ON"
            },
            "reported": {
                "lights": {
                    "color": "GREEN"
                },
                "engine": "ON"
            },
            "delta": {
                "lights": {
                    "color": "RED"
                }
            }
        },
        "metadata": {
            "desired": {
                "lights": {
                    "color": {
                        "timestamp": 1469564492
                    }
                },
                "engine": {
                    "timestamp": 1469564492
                }
            },
            "reported": {
                "lights": {
                    "color": {
                        "timestamp": 1469564492
                    }
                },
                "engine": {
                    "timestamp": 1469564492
                }
            }
        },
        "version": 10,
        "timestamp": 1469564492
    }
}

The system property field in json is described as follows:

Usage restrictions

The following limits apply when using image json objects:

• The overall size of json data must not exceed 4k.

• Usage limits of key in properties: 1-30 in length, which is composed of English letters, numbers and underscores.

• In properties, when value is a string, the maximum length has a limit of 512 bytes.

• In properties, when value is an integer, the range is -4503599627370496 - 4503992777.

• In properties, the maximum depth of nested json objects that are reported and desired properties is 4 layers. For example, the following objects are valid:

{
    "state": {
        "reported": {
            "one": {
                "two": {
                    "three": {
                        "four": {
                            "key": "value"
                        }
                    }
                }
            }
        }
    }
}

More Help

• Learn how to use the device image console

• Learn the Device Development Guide, as shown in the device image topic cluster manual