To control a device, you can call the SetDeviceDesiredProperty operation in IoT Platform to set desired property values for the device. After you set a desired property value for a device in IoT Platform, the property value is updated in real time if the device is online. If the device is offline, the desired property value is cached in IoT Platform. When the device comes online again, the device obtains the desired property value and updates the existing property value. This topic describes the message formats that are related to desired device property values.

Note For more information about how to call the SetDeviceDesiredProperty operation in IoT Platform to set desired property values for a device, see SetDeviceDesiredProperty.

Obtain desired property values

The following topics are used when a device sends requests to IoT Platform and IoT Platform sends responses to the device:

A device sends a request to obtain the desired property values from IoT Platform.

  • Request topic: /sys/${productKey}/${deviceName}/thing/property/desired/get
  • Response topic: /sys/${productKey}/${deviceName}/thing/property/desired/get_reply

Sample request in the Alink JSON format:

{
    "id" : "123",
    "version":"1.0",
    "sys":{
      "ack":0
  },
    "params" : [
        "power",
        "temperature"
    ],
    "method":"thing.property.desired.get"
}

Sample response in the Alink JSON format:

{
    "id":"123",
    "code":200,
    "data":{
        "power": {
            "value": "on",
            "version": 2
        }
    }
}
Table 1. Request parameters
ParameterTypeDescription
idStringThe ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
versionStringThe version of the protocol. Valid value: 1.0.
sysObjectThe parameter for extended features. The value contains the fields for each feature.
Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ackIntegerThe extended feature field in the sys parameter. This field specifies whether IoT Platform needs to return response data for the registration request. Valid values:
  • 1: IoT Platform needs to return response data.
  • 0: IoT Platform does not need to return response data.
Important For more information about the parameter, see Examples on how to use a TSL model.

If the feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.

paramsListThe identifier list of properties of which you want to obtain the desired values.

In this example, the following property identifiers are listed:

[ 
 "power",
 "temperature"
 ]

The identifier of a custom module property is in the format of Module identifier:Property identifier. Example:

[ 
 "test:power",
 "test:temperature"
 ]
methodStringThe request method. Valid value: thing.property.desired.get.
Table 2. Response parameters
ParameterTypeDescription
idStringThe ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
codeIntegerThe HTTP status code in the response. For more information, see Common codes on devices.
dataObjectThe desired value information that is returned.

In this example, the desired value information about the power property is returned. The information includes the value and version of the property.

{
  "power": {
    "value": "on", 
    "version": 2
  }
}

The identifier of a custom module property is in the format of Module identifier:Property identifier. Example:

{
  "test:power": {
    "value": "on", 
    "version": 2
  }
}
Note If no desired value is set for a property in IoT Platform or the desired value has been deleted, the returned data does not contain the identifier of this property. In this example, the temperature property does not have a desired value. Therefore, the returned data does not contain this property identifier.

For more information about the parameters in data, see the following table.

Table 3. data
ParameterTypeDescription
keyStringThe identifier of the property, such as power in this example.
valueObjectThe desired value.
versionIntegerThe current version of the desired value.
Note When you set the desired property value for the first time, the version is 1. Then, the version increases by 1 every time you set the desired value.

Delete desired property values

The following topics are used when a device sends requests to IoT Platform and IoT Platform sends responses to the device:

A device sends a request to delete the desired property values that are cached in IoT Platform.

  • Request topic: /sys/${productKey}/${deviceName}/thing/property/desired/delete
  • Response topic: /sys/${productKey}/${deviceName}/thing/property/desired/delete_reply

Sample request in the Alink JSON format:

{
    "id": "123",
    "version": "1.0",
    "sys":{
      "ack":0
  },
    "params": {
        "power": {
            "version": 1
        },
        "temperature": { }
    },
    "method":"thing.property.desired.delete"  
}

Sample response in the Alink JSON format:

{
    "id": "123",
    "code": 200,
    "data": { }
}
Table 4. Request parameters
ParameterTypeDescription
idStringThe ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
versionStringThe version of the protocol. Valid value: 1.0.
sysObjectThe parameter for extended features. The value contains the fields for each feature.
Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ackIntegerThe extended feature field in the sys parameter. This field specifies whether IoT Platform needs to return response data for the registration request. Valid values:
  • 1: IoT Platform needs to return response data.
  • 0: IoT Platform does not need to return response data.
Important For more information about the parameter, see Examples on how to use a TSL model.

If the feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.

paramsObjectThe list of the properties of which you want to delete the desired values. A property is identified by the identifier and version. Example:
{
  "power": {
    "version": 1
  }, 
  "temperature": { }
}

The identifier of a custom module property is in the format of Module identifier:Property identifier. Example:

{
  "test:power": {
    "version": 1
  }, 
  "test:temperature": { }
}

For more information about the parameters in params, see the following table.

methodStringThe request method. Valid value: thing.property.desired.delete.
Table 5. params
ParameterTypeDescription
keyStringThe identifier of the property. In this example, the following property identifiers are listed: power and temperature.
versionIntegerThe version of the desired value to be deleted.
Note
  • You can obtain the value of the version parameter from the /sys/${productKey}/${deviceName}/thing/property/desired/get topic.
  • If you set the version parameter to 2, IoT Platform deletes the desired value only if the current version is 2. If the current version of the desired value is 3 in IoT Platform, this delete request is ignored.
  • If the version parameter is not specified in the request, IoT Platform does not verify the version, but directly deletes the desired value.
Table 6. Response parameters
ParameterTypeDescription
idStringThe ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
codeIntegerThe HTTP status code in the response. For more information, see Common codes on devices.
dataObjectThe returned data. In the response to a request to delete the desired property values, no data is returned.

References