Device Control

Last Updated on : 2024-08-22 08:33:39download

Smart devices have gained ground in many sites and industries, but how to deliver secure and flexible permission management has become a challenge. In the old days, application scenarios were 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.

Device DPs

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

  • In each dictionary 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)"
}

The following sample code shows the DPs 1, 4, 5, 6, and 15 of a light product that is created on the Tuya Developer Platform:

Objective-C:

- (void)publishDps {
    // self.device = [ThingSmartDevice deviceWithDeviceId:@"your_device_id"];

    NSDictionary *dps;
    // Set the data point of Boolean type with `dpId` of `1`. Feature: turns on the switch.
    dps = @{@"1": @(YES)};

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

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

    // Set the data point of value type with `dpId` of `6`. Feature: sets the temperature value to `20`.
    dps = @{@"6": @(20)};

    // Set the data point of raw type with `dpId` of `15`. Feature: passes through the infrared data `1122`.
    dps = @{@"15": @"1122"};

    // Send multiple DPs in a command.
    dps = @{@"1": @(YES), @"4": @(ff5500)};

    [self.device publishDps:dps success:^{
        NSLog(@"publishDps success");

        // The DP is sent successfully. The status is reported through the `deviceDpsUpdate` callback.

    } failure:^(NSError *error) {
        NSLog(@"publishDps failure: %@", error);
    }];

}

Swift:

func publishDps() {
    var dps = [String : Any]()

    // For more information about the DPs, see the function definitions of the product.
    device?.publishDps(dps, success: {
         print("publishDps success")

        // The DP is sent successfully. The status is reported through the `deviceDpsUpdate` callback.
    }, failure: { (error) in
        if let e = error {
            print("publishDps failure: \(e)")
        }
    })
}

Data types must be correct when a control command is sent.

Example:

  • A DP of value type can be sent in the format of {"2": 25} rather than {"2": "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 @{@"1": @"011f"} rather than @{@"1": @"11f"}.

Device control

Send DPs to a device to change its status or features.

Ordinary control

Control a device through an auto select channel, local-area network (LAN), or cloud. The auto select channel is recommended.

  • Auto select channel:

    Check the availability of channels in the sequence specified by communication.communicationModes that is defined in the device model ThingSmartDeviceModel, and select an appropriate channel to control the device.

    [self.device publishDps:dps success:^{
        NSLog(@"publishDps success");
    } failure:^(NSError *error) {
        NSLog(@"publishDps failure: %@", error);
    }];
    
    // or use
    
    [self.device publishDps:dps mode:ThingDevicePublishModeAuto success:^{
        NSLog(@"publishDps success");
    } failure:^(NSError *error) {
        NSLog(@"publishDps failure: %@", error);
    }];
    
  • LAN:

    Control a device over the LAN only. The device must be online on a LAN.

    [self.device publishDps:dps mode:ThingDevicePublishModeLocal success:^{
        NSLog(@"publishDps success");
    } failure:^(NSError *error) {
        NSLog(@"publishDps failure: %@", error);
    }];
    
  • Cloud:

    Control a device through the cloud only. The device must be online in the cloud.

    [self.device publishDps:dps mode:ThingDevicePublishModeInternet success:^{
        NSLog(@"publishDps success");
    } failure:^(NSError *error) {
        NSLog(@"publishDps failure: %@", error);
    }];
    

Cache DP data for low power devices

Cache the dps intended for the device in the cloud. When the device wakes up, it will proactively request the cache or receive the push from the cloud.

This method applies to low power devices only and can be invoked even when the device is offline.

API description

/// Publish dps cached in the cloud, and then the device itself requests to pull OR receives push from cloud.
///
/// Note: Only suitable for low-power device.
/// When the device is dormant, sending dps through this API will be cached in the cloud for a period of time.
/// When the device wakes up within the validity period, the device can get the cached dps.
///
/// @param dps The DP dictionary.
/// @param validity The cached dps validity period. (Unit: second, Range: 1 ~ 172800).
/// @param dpCacheType The dps cache type. (0: device itself requests to pull, 1: device receives push from cloud).
/// @param success Called when the task is finished.
/// @param failure Called when the task is interrupted by an error.
- (void)sendCacheDps:(NSDictionary *)dps
            validity:(NSUInteger)validity
         dpCacheType:(NSUInteger)dpCacheType
             success:(ThingSuccessID)success
             failure:(ThingFailureError)failure;

Parameters

Parameter Description
dps The DP.
validity The validity time for the cache, in seconds, ranging from 1 to 172800.
dpCacheType The type of the DP cache.
  • 0: The device proactively pulls the cache.
  • 1: The device receives the push from the cloud.
success The success callback.
failure The failure callback.

Example

Objective-C:

- (void)sendCacheDPS {
    // validity = 10, indicating the DP data is cached in the cloud for 10s.
    // dpCacheType = 0, indicating the device proactively pulls the cache.
    // After the method is invoked, the dps will be cached in the cloud for 10s, and the device will wake up in 10s to pull the cache.

    // self.device = [ThingSmartDevice deviceWithDeviceId:devId];
    [self.device sendCacheDps:dps validity:10 dpCacheType:0 success:^(id result) {
        NSLog(@"send cache dps success");
    } failure:^(NSError *error) {
        NSLog(@"send cache dps failure");
    }];
}

Swift:

func sendCacheDPS() {
    // validity = 100, indicating the DP data is cached in the cloud for 100s.
    // dpCacheType = 1, indicating the device receives the push from the cloud.
    // After the method is invoked, the dps will be cached in the cloud for 100s, and the device will wake up in 100s to receive the cache from the cloud.

    // device = ThingSmartDevice(deviceId: devId)
    device?.sendCacheDps(dps, validity: 100, dpCacheType: 1, success: { _ in
        print("send cache dps success")
    }, failure: { error in
        print("send cache dps failure")
    })
}