Device Control

Last Updated on : 2024-06-26 09:54:04download

Smart devices have gained ground in many homes and industries, but how to deliver secure and flexible permission management has become a challenge. In the old days, application scenarios are pretty simple, and a mobile app was used to control only one smart device. However, nowadays, more and more smart devices are serving smart scenes. Each mobile app is used to control a host of smart devices.

In specific scenarios, certain devices are controlled by multiple users. For example, furniture-like smart power strips can be switched on or off by all home members. In this case, the following requirements must be met: a mobile app can be used to control multiple devices. Multiple users can be authorized to mutually control multiple devices. Therefore, group management and smart scenes are designed to achieve these purposes.

This topic describes how to achieve device control.

Data points

  • The dps property for the class DeviceBean defines the current device status. The status is known as one or more data points (DPs).

  • In each array of dps, key matches dpId of a DP, and dpValue matches the value of the DP.

    You can check the definitions of DPs for a product on the Tuya Developer Platform. The following figure shows a list of DPs.

    Device Control

    For more information, see Product Functions.

Command format

Send a control command in the following format:

{
	"(dpId)":"(dpValue)"
}

Sample DPs

The following sample code shows the DPs 101, 102, 103, 104, and 105 of a light product that is created on the Tuya Developer Platform:

// The data point of Boolean type with the `dpId` value of `101`. Feature: switches on the light.
dps = {"101": true};

// The data point of String type with the `dpId` value of `102`. Feature: sets the red, green, and blue (RGB) value to `ff5500`.
dps = {"102": "ff5500"};

// The data point of Enumeration type with the `dpId` value of `103`. Feature: sets the lighting level to `2`.
dps = {"103": "2"};

// The data point of Value type with the `dpId` value of `104`. Feature: sets the temperature to `20`.
dps = {"104": 20};

// The data point of Raw type with the `dpId` value of `105`. Feature: passes through the infrared data `1122`.
dps = {"105": "1122"};

// Sends multiple DPs in a command.
dps = {"101": true, "102": "ff5500"};

mDevice.publishDps(dps, new IResultCallback() {
		@Override
		public void onError(String code, String error) {
		// The error code 11001 is returned due to the following causes:
		//1: Data has been sent in an incorrect format. For example, the data of String type has been sent in the format of Boolean data.
		//2: Read-only DPs cannot be sent. For more information, see SchemaBean getMode. `ro` indicates the read-only type.
		//3: Data of Raw type has been sent in a format rather than a hexadecimal string.
		}
		@Override
		public void onSuccess() {
		}
	});

Data types must be correct when DPs are sent. Example:

  • A DP of Value type can be sent in the format of {"104": 25} rather than {"104": "25"}.
  • A byte array of Raw type is a hexadecimal string with an even number of digits. In this case, the array can be sent in the format of {"105": "0110"} rather than {"105": "110"}.

Control devices

You must initialize device control first. DPs can be sent to a device to change the device status or features and control the device.

Devices can be controlled automatically, over a local area network (LAN), or in the cloud. If the LAN is connected, control over the LAN is recommended. Otherwise, control in the cloud is recommended.

API description

  • Control over the LAN

    ITuyaDevice.publishDps(dps, TYDevicePublishModeEnum.TYDevicePublishModeLocal, callback);
    
  • Device control from the cloud

    ITuyaDevice.publishDps(dps, TYDevicePublishModeEnum.TYDevicePublishModeInternet, callback);
    
  • Automatic control

    ITuyaDevice.publishDps(dps, TYDevicePublishModeEnum.TYDevicePublishModeAuto, callback);
    

    Or

    ITuyaDevice.publishDps(dps, callback);
    

    We recommend that you call ITuyaDevice.publishDps(dps, callback) to control devices.

  • Control through a specified channel

    ITuyaDevice.publishDps(dps, orders, callback);
    

Parameters

Parameter Description
dps The DPs of the device in the format of JSON strings. For more information, see Data points.
callback The callback that indicates whether the control request is successful.
TYDevicePublishModeEnum The device control method.
orders The sequence of channels through which device control is achieved. Take the enumeration class CommunicationEnum for example. [3 , 1] represents that devices are controlled over Bluetooth in priority. If Bluetooth is unavailable, cloud-based control is implemented.

Example for Java

The following sample code shows how to switch on a light by using DP 101:

mDevice.publishDps("{\"101\": true}", new IResultCallback() {
	@Override
	public void onError(String code, String error) {
		Toast.makeText(mContext, "Failed to switch on the light.", Toast.LENGTH_SHORT).show();
	}

	@Override
	public void onSuccess() {
		Toast.makeText(mContext, "The light is switched on successfully.", Toast.LENGTH_SHORT).show();
	}
});
  • Device control is not finished after a command is sent. The device has been controlled as expected only after IDevListener onDpUpdate returns the response.
  • The command string is converted to a JSON string in the format of Map<String,Object>. In this string, String matches dpId, and Object matches dpValue.
  • Each command string can include multiple DPs in each request.