Device Management

Last Updated on : 2023-06-05 02:23:04download

This topic describes the device management operations that are supported by Smart Residence App SDK for iOS. For example, listen for changes in device status, rename devices, update device firmware, remove devices, and restore default settings.

Functional description

The following table lists the classes for device management.

Class name Description

TuyaSmartDevice The device management class.

TuyaSmartDeviceModel The device data model class.

Class name	Description
TuyaSmartDevice	The device management class.
TuyaSmartDeviceModel	The device data model class.

The following table describes the data model specified by TuyaSmartDeviceModel.

Property	Type	Description
devId	NSString	The unique ID of a device.
name	NSString	The name of a device.
iconUrl	NSString	The URL of a device icon.
isOnline	Boolean	Indicates whether a device is online. The device is online when it is connected to a Wi-Fi network, a local area network (LAN), or a Bluetooth network.
isCloudOnline	Boolean	Indicates whether a device is connected to a Wi-Fi network.
isLocalOnline	Boolean	Indicates whether a device is connected to a LAN.
isShare	Boolean	Indicates whether a device is a shared device.
dps	NSDictionary	The data points (DPs) of a device.
dpCodes	NSDictionary	The DPs in the `code-value` format.
schemaArray	NSArray	The schema array of DP rules.
productId	NSString	The product ID (PID) of a device.
capability	NSUInteger	The product capability of a device.
deviceType	TuyaSmartDeviceModelType	The type of device.
supportGroup	Boolean	Indicates whether groups can be created.
gwType	NSString	A value of `v` indicates a virtual device, and an empty value indicates a real device for pairing.
pv	NSString	The protocol version of a device. A Wi-Fi protocol version or a Bluetooth protocol version are supported.
lpv	NSString	The LAN protocol version of a device. By default, this parameter is empty. The value is specified after the device is connected to a LAN.
latitude	NSString	The latitude of the site.
longitude	NSString	The longitude of the site.
localKey	NSString	The key that a device uses for communication.
uuid	NSString	The universally unique identifier (UUID) of a device.
homeId	LongLong	The ID of the site that a device belongs to.
roomId	LongLong	The ID of the room that a device belongs to.
upgrading	Boolean	Indicates whether an update is in progress.
timezoneId	NSString	The time zone of a device.
nodeId	NSString	The short URL of a device. This parameter is empty for non-sub-devices. Each sub-device of a gateway is assigned a unique short URL.
parentId	NSString	The ID of a parent device. This parameter is empty for non-sub-devices. Sub-devices search for the gateway ID by this parameter. For Bluetooth mesh sub-devices, this parameter means the mesh ID or gateway ID.
isMeshBleOnline	Boolean	Indicates whether a Bluetooth mesh device is connected to a LAN.
devKey	NSString	The Bluetooth communication key for a standard Bluetooth mesh device.
standard	Boolean	Indicates whether a device is a standard device. Standard DPs are available to standard devices.
standSchemaModel	TuyaSmartStandSchemaModel	The schema array of standard DP rules.
activeTime	NSTimeInterval	The time when a device is activated.
homeDisplayOrder	NSInteger	The serial number of a device. When a list of devices is returned for a site, the devices can be sorted by this parameter.
sharedTime	LongLong	The time when a device is shared.
isAccessDevice	Boolean	Indicates whether a device is an access control device.
isPublicAreaDevice	Boolean	Indicates whether a device is located in a public area.

Initialize devices

Initializes the device control class by device ID.

You must use TuyaResidenceSite to initialize a site instance and call fetchSiteDetailWithSuccess:failure: to get site details. The device is initialized only after site details are synchronized.
An incorrect device ID might cause failed initialization. In this case, the device instance returns nil.

API description

/**
* Returns a device instance. If the current user does not have the device, `nil` is returned.
*
* @param devId Device ID
* @return instance
*/
+ (nullable instancetype)deviceWithDeviceId:(NSString *)devId;

Parameters

Parameter	Description
devId	The device ID.

Example

TuyaSmartDevice *device = [TuyaSmartDevice deviceWithDeviceId:devId];
device.delegate = self;

Listen for a delegate

After you implement the delegate protocol TuyaSmartDeviceDelegate, you can process the callback to invoke when device status is changed and refresh the UI of the control panel on your app.

Example

Objective-C:

- (void)initDevice {
    self.device = [TuyaSmartDevice deviceWithDeviceId:@"your_device_id"];
    self.device.delegate = self;
}

#pragma mark - TuyaSmartDeviceDelegate

- (void)device:(TuyaSmartDevice *)device dpsUpdate:(NSDictionary *)dps {
    // The UI is refreshed when device DPs are changed.
}

- (void)deviceInfoUpdate:(TuyaSmartDevice *)device {
    // The current device data such as the device name and online or offline status is updated.
}

- (void)deviceRemoved:(TuyaSmartDevice *)device {
    // The current device is removed.
}

- (void)device:(TuyaSmartDevice *)device signal:(NSString *)signal {
    // The Wi-Fi signal strength.
}

- (void)device:(TuyaSmartDevice *)device firmwareUpgradeProgress:(NSInteger)type progress:(double)progress {
    // The progress of the firmware update.
}

- (void)device:(TuyaSmartDevice *)device firmwareUpgradeStatusModel:(TuyaSmartFirmwareUpgradeStatusModel *)upgradeStatusModel {
    // The callback to invoke to get the device update status.
}

Swift:

func initDevice() {
    device = TuyaSmartDevice(deviceId: "your_device_id")
    device?.delegate = self
}

// MARK: - TuyaSmartDeviceDelegate

func device(_ device: TuyaSmartDevice?, dpsUpdate dps: [AnyHashable : Any]?) {
    // The UI is refreshed when device DPs are changed.
}

func deviceInfoUpdate(_ device: TuyaSmartDevice?) {
    // The current device data such as the device name and online or offline status is updated.
}

func deviceRemoved(_ device: TuyaSmartDevice?) {
    // The current device is removed.
}

func device(_ device: TuyaSmartDevice?, signal: String?) {
    // The Wi-Fi signal strength.
}

func device(_ device: TuyaSmartDevice?, firmwareUpgradeProgress type: Int, progress: Double) {
    // The progress of the firmware update.
}

func device(_ device: TuyaSmartDevice?, firmwareUpgradeStatusModel upgradeStatusModel: TuyaSmartFirmwareUpgradeStatusModel?) {
    // The callback to invoke to get the device update status.
}

Query device information

Queries the data of a single DP.

This API method does not apply to synchronous requests. The response is returned by the callback of the delegate - (void)device:(TuyaSmartDevice *)device dpsUpdate:(NSDictionary *)dps.
This API method applies to DPs that do not initiate data transmission. For example, query countdown information. For regular DP query, we recommend that you call TuyaSmartDeviceModel.dps.

Example

Objective-C:

- (void)queryDP {
    // self.device = [TuyaSmartDevice deviceWithDeviceId:@"your_device_id"];
    // Returns the data of DP `1`.
[self.device publishDps:@{@"1":null} mode:TYDevicePublishModeAuto success:^{
        NSLog(@"query dp success");
    } failure:^(NSError *error) {
        NSLog(@"query dp failure: %@", error);
    }];
}

Swift:

func queryDP() {
    // self.device = [TuyaSmartDevice deviceWithDeviceId:@"your_device_id"];
    // Returns the data of DP `1`.
    device.publishDps([
        "1": null
    ], mode: TYDevicePublishModeAuto, success: {
        print("query dp success")
    }, failure: { error in
        if let error = error {
            print("query dp failure: \(error)")
        }
    })
}

Rename a device

API description

- (void)updateName:(NSString *)name success:(nullable TYSuccessHandler)success failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
name	The new name of the device.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

- (void)modifyDeviceName:(NSString *)mame {
    // self.device = [TuyaSmartDevice deviceWithDeviceId:@"your_device_id"];

    [self.device updateName:name success:^{
        NSLog(@"updateName success");
    } failure:^(NSError *error) {
        NSLog(@"updateName failure: %@", error);
    }];
}

Swift:

func modifyDeviceName(_ name: String) {
    device?.updateName(name, success: {
        print("updateName success")
    }, failure: { (error) in
        if let e = error {
            print("updateName failure: \(e)")
        }
    })
}

Remove a device

After a device is removed, it enters the state ready for pairing. By default, the device enters the Wi-Fi Easy Connect (EZ) mode.

API description

- (void)remove:(nullable TYSuccessHandler)success failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
success	The success callback.
failure	The failure callback.

Example

Objective-C:

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

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

Swift:

func removeDevice() {
    device?.remove({
        print("remove success")
    }, failure: { (error) in
        if let e = error {
            print("remove failure: \(e)")
        }
    })
}

Restore factory defaults

After default settings are restored for a device, it enters the state ready for pairing. By default, the device enters the Wi-Fi EZ mode. In this case, device data is cleared.

API description

- (void)resetFactory:(nullable TYSuccessHandler)success failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
success	The success callback.
failure	The failure callback.

Example

Objective-C:

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

    [self.device resetFactory:^{
        NSLog(@"reset success");
    } failure:^(NSError *error) {
        NSLog(@"reset failure: %@", error);
    }];
}

Swift:

func removeDevice() {
    device?.resetFactory({
        print("reset success")
    }, failure: { (error) in
        if let e = error {
            print("reset failure: \(e)")
        }
    })
}

Query the Wi-Fi signal strength

After the Wi-Fi signal of a device is queried, the response is returned by the callback of the method device:signal: of TuyaSmartDeviceDelegate.

API description

- (void)getWifiSignalStrengthWithSuccess:(nullable TYSuccessHandler)success failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
success	The success callback.
failure	The failure callback.

Example

Objective-C:

- (void)getWifiSignalStrength {
    // self.device = [TuyaSmartDevice deviceWithDeviceId:@"your_device_id"];
    // self.device.delegate = self;

    [self.device getWifiSignalStrengthWithSuccess:^{
        NSLog(@"get wifi signal strength success");
    } failure:^(NSError *error) {
        NSLog(@"get wifi signal strength failure: %@", error);
    }];
}

#pragma mark - TuyaSmartDeviceDelegate

- (void)device:(TuyaSmartDevice *)device signal:(NSString *)signal {
    NSLog(@" signal : %@", signal);
}

Swift:

func getWifiSignalStrength() {
    self.device?.getWifiSignalStrength(success: {
        print("get wifi signal strength success")
    }, failure: { (error) in
        if let e = error {
            print("get wifi signal strength failure: \(e)")
        }
    })
}

// MARK: - TuyaSmartDeviceDelegate
func device(_ device: TuyaSmartDevice!, signal: String!) {

}

Query a list of sub-devices for a gateway

Returns a list of sub-devices for a specific gateway.

API description

- (void)getSubDeviceListFromCloudWithSuccess:(nullable void (^)(NSArray <TuyaSmartDeviceModel *> *subDeviceList))success failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
success	The success callback. A list of sub-devices for the gateway is returned.
failure	The failure callback.

Example

Objective-C:

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

    [self.device getSubDeviceListFromCloudWithSuccess:^(NSArray<TuyaSmartDeviceModel *> *subDeviceList) {
        NSLog(@"get sub device list success");
    } failure:^(NSError *error) {
        NSLog(@"get sub device list failure: %@", error);
    }];
}

Swift:

func getSubDeviceList() {
    device?.getSubDeviceListFromCloud(success: { (subDeviceList) in
        print("get sub device list success")
    }, failure: { (error) in
        if let e = error {
            print("get sub device list failure: \(e)")
        }
    })
}