Device Control

Device control is a process of implementing functional control and state changes of smart devices. Cloud service APIs enable you to send control instructions to devices and query the states reported by the devices so as to perceive changes in the operating states of the devices.

Concepts

Property

A property is used to describe the specific information and states of a device at runtime, also known as a data point (DP) in some scenarios. You can call the property APIs to query and modify the states of device parameters.

For example, in the scenarios of colored lights, you can make API requests that modify the color, brightness, and other properties of the colored lights to achieve the desired display effect.

• System procedure:

• List of APIs:

  Service name	API endpoint	Description
  Send Property	POST: /v2.0/cloud/thing/{device_id}/shadow/properties/issue	Immediately send a property setting instruction to the specified device.
  Query Properties	GET: /v2.0/cloud/thing/{device_id}/shadow/properties	Query the property states recently reported by the device to the cloud.
  Modify Properties	POST: /v2.0/cloud/thing/{device_id}/shadow/properties	Modify the property states recently reported by the device to the cloud.
  Report device properties	bizCode: devicePropertyMessage	Receive a notification message that the device properties have been reported.

Desired properties

Device desired properties mean that if the device is offline when you set device properties, the cloud can cache the values that need to be set. After the device goes online, the device gets the desired properties from the cloud.

For example, a low-power device might be periodically put to sleep or woken up, instead of maintaining a persistent connection to the cloud. A device in sleep mode cannot receive instructions from the cloud. Therefore, the desired properties feature makes it possible to send instructions to offline devices. Device instructions are saved in the cloud. After the device is online, the device actively pulls the instructions from the cloud.

• System procedure:

• List of APIs:

  Service name	API endpoint	Description
  Set Desired Property	POST: /v2.0/cloud/thing/{device_id}/shadow/properties/desired	Store the instruction of sending device properties in the cloud. When the device is woken up, the instruction is sent from the cloud to the device.
  Query Desired Properties	GET: /v2.0/cloud/thing/{device_id}/shadow/properties/desired	Query the property sending instructions in the cloud.

Things data model

The things data model describes an abstraction of physical devices. It defines the characteristics and behaviors of a type of device that connects to the cloud. This model defines an abstract representation of a device as a set of properties, actions, and events, and determines how a connected physical device interacts with the cloud applications.

• You can call the things data model APIs to query metadata of device functional definitions.
• This model provides detailed definitions of functional parameters, helping you complete various functional development, such as dynamic rendering of panels and data analytics.

For example, a colored light might have properties such as color, brightness, and switch. The color has three valid values of red, yellow, and blue, and the switch has two valid values of on and off. The following case gives you insight into the data structure of the things data model.

{
    "modelId":"000000er..",
    "name":"Colored Light",
    "services":[
        {
            "code":"",
            "properties":[
                  {
                    "abilityId": 1,
                    "code":"switch",
                    "name":"Switch",
                    "accessMode":"rw",
                    "typeSpec":{
                        "type":"bool"
                    }
                },
                {
                    "abilityId": 2,
                    "code":"color",
                    "name":"Color",
                    "accessMode":"rw",
                    "typeSpec":{
                        "type":"enum",
                        "range":["red", "yellow", "blue"]
                    }
                }
            ]
        }
    ]
}

The following table lists the APIs offered by Tuya.

More capabilities

Besides the device control APIs mentioned herein, Tuya also provides another set of device control solutions based on standard instruction sets. They can be used to control devices in the same category from multiple manufacturers. For more information, see Device Control (Standard Instruction Set).