Device Control

Last Updated on : 2024-06-28 06:02:20download

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:

    DeviceCloudAppSend propertiesControl the device1Send properties2Return results3Send an instruction ofquerying or modifying theproperties4Return results5Report propertiesA message of reportingproperties6The cloud verifiesand saves thereported properties78A message of reportingproperties9Query propertiesView the devicestate10Query properties11The state of properties12DeviceCloudAppQuery and modify properties
  • 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:

    DeviceCloudAppSend desired propertiesControl the device1Set desired properties2Save desiredproperties3Set successfully4The device pulls instructionsWake up the device5Connect to the cloud6Query desired properties onthe device7Return an instruction ofsending properties8Execute theinstruction9Query sending stateView the sendingstate10Query desired properties inthe cloud11Return the state of desiredproperties12DeviceCloudAppSet desired properties
  • 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.

Service name API endpoint Description
Query Things Data Model GET: /v2.0/cloud/thing/{device_id}/model Query the things data model defined for the specified device.

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).