Sub-device Replacement

Purpose

This topic describes how to replace a faulty sub-device.

Integration

source 'https://github.com/tuya/tuya-pod-specs.git'
platform :ios, '11.0'

target 'Your_Project_Name' do
    pod "ThingSmartBusinessExtensionKit"
end

API description

Model

Management class for sub-device replacement

open class ThingSubDeviceReplaceManager : NSObject {
    ....
}

Role of sub-device replacement

public enum ThingSubDeviceReplaceRole : UInt, @unchecked Sendable {
    case replacer = 0 // Operates as the replacer, typically indicating a fully functional unit
    case replacee = 1 // Operates as the device being replaced, typically indicating a faulty unit
}

Sub-device replacement results

public enum ThingSubDeviceReplaceStatus : Int, @unchecked Sendable {
    case replaceFailure = -1
    case replacing = 0
    case replaceSuccess = 1
}
open class ThingSubDeviceReplaceResult : NSObject {
    open var status: ThingSubDeviceReplaceStatus
    open var failReason: String
}

Sub-device replacement callback event

public protocol ThingSubDeviceReplaceManagerListener : NSObjectProtocol {
    func manager(_ manager: ThingSubDeviceReplaceManager, replaceDidCompleteWithResult success: Bool, error: (any Error)?)
}

Management class interfaces

• Initialize the sub-device replacement management class

  public init(deviceId: String, role: ThingSubDeviceReplaceRole)
  

  The role is typically determined by whether the entry device is faulty. If the entry device is fully functional, it is generally used to replace other devices (role = replacer). Conversely, if the entry device is faulty, it is typically replaced by another device (role = replacee).

  Request parameter	Type	Description
  deviceId	String	The ID of the specified entry device.
  role	ThingSubDeviceReplaceRole	The role of the specified device.

• Check device support for sub-device replacement

  open func supportReplace(success: @escaping (Bool) -> Void, failure: @escaping (any Error) -> Void)
  

  Request parameter	Type	Description
  success	Bool	The success callback. Valid values: true: supported. false: not supported.
  failure	error	The error message.

• Get the list of compatible sub-devices

  open func getCompatibleSubDevices(success: @escaping ([String]) -> Void, failure: @escaping (any Error) -> Void)
  

  Request parameter	Type	Description
  success	[String]	The success callback. A list of sub-device IDs is returned.
  failure	error	The error message.

• Perform sub-device replacement

  open func replace(withOtherDevice deviceId: String, timeout: Int, success: @escaping (String) -> Void, failure: @escaping (any Error) -> Void)
  

  If the role is replacer, the target device will be replaced by the entry device. Conversely, if the role is replacee, the entry device will be replaced by the target device.

  Request parameter	Type	Description
  deviceId	String	The ID of the sub-device.
  timeout	Int	The timeout, in seconds. The minimum value is 30 seconds. Values less than 30 will default to 30.
  success	string	The success callback. A replacement ID is returned.
  failure	error	The error message.

• Get the replacement result

  open func replaceResult(withReplaceId replaceId: String, success: @escaping (ThingSubDeviceReplaceResult) -> Void, failure: @escaping (any Error) -> Void)
  

  This method is not commonly used, as results can be monitored via addListener. It is intended for scenarios where network issues cause mq message loss and the listener fails to callback.

  Request parameter	Type	Description
  replaceId	String	The replacement ID.
  success	ThingSubDeviceReplaceResult	The success callback. The replacement result is returned.
  failure	error	The error message.

• Add a listener for replacement results

  open func add(_ listener: any ThingSubDeviceReplaceManagerListener)
  

  Request parameter	Type	Description
  listener	ThingSubDeviceReplaceManagerListener	The listener.

• Remove the listener for replacement results

  open func remove(_ listener: any ThingSubDeviceReplaceManagerListener)
  

  Request parameter	Type	Description
  listener	ThingSubDeviceReplaceManagerListener	The listener.

Example

Demo

For more information, see the Demo.