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
Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version String The version of the protocol. Valid value: 1.0.
sys Object The 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.
ack Integer The 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: indicates that IoT Platform needs to return response data.
  • 0: indicates that IoT Platform does not need to return response data.
Note

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

params List The 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"
 ]
method String The request method. Valid value: thing.property.desired.get.
Table 2. Response parameters
Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
code Integer The HTTP status code in the response. For more information, see Common codes on devices.
data Object The 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
Parameter Type Description
key String The identifier of the property, such as power in this example.
value Object The desired value.
version Integer The 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
Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version String The version of the protocol. Valid value: 1.0.
sys Object The 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.
ack Integer The 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: indicates that IoT Platform needs to return response data.
  • 0: indicates that IoT Platform does not need to return response data.
Note

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

params Object The 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.

method String The request method. Valid value: thing.property.desired.delete.
Table 5. params
Parameter Type Description
key String The identifier of the property. In this example, the following property identifiers are listed: power and temperature.
version Integer The 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
Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
code Integer The HTTP status code in the response. For more information, see Common codes on devices.
data Object The returned data. In the response to a request to delete the desired property values, no data is returned.

References