设备管理

更新时间:2024-03-21 09:08:37下载pdf

设备管理主要提供设备完成配网后的相关操作,包含设备状态变化监听、设备重命名、设备固件升级、设备移除、设备恢复出厂设置等操作。

进行设备操作之前,确保已经成功 获取家庭下设备、群组

功能说明

  • 设备管理相关类:

    类名 说明
    ThingSmartDevice 设备管理
    ThingSmartDeviceModel 设备数据模型
  • ThingSmartDeviceModel 数据模型:

    属性 类型 说明
    devId NSString 设备唯一 ID。
    name NSString 设备名称。
    iconUrl NSString 设备图标 URL。
    isOnline Boolean 设备在线状态。此状态包含 Wi-Fi、局域网、或蓝牙在线状态,只要其中任意一个网络在线,即为在线。
    isCloudOnline Boolean 设备 Wi-Fi 在线状态。
    isLocalOnline Boolean 设备局域网在线状态。
    isShare Boolean 是否为分享设备。
    dps NSDictionary 设备功能点数据。
    dpCodes NSDictionary 设备功能点数据,表现为键值(code-value)形式。
    schemaArray NSArray 设备 DP 规则信息。
    productId NSString 设备所对应的产品 ID。
    capability NSUInteger 设备产品能力值。
    deviceType ThingSmartDevice
    ModelType
    设备类型。
    supportGroup Boolean 是否支持创建群组。
    gwType NSString v 代表虚拟设备,空代表真实设备。
    pv NSString 设备协议版本,Wi-Fi 协议版本或蓝牙协议版本。
    lpv NSString 设备局域网协议版本。默认为空,该字段在设备局域网连接成功后,才会有值。
    latitude NSString 纬度。
    longitude NSString 经度。
    localKey NSString 设备通信使用的 key。
    uuid NSString 设备 UUID。
    homeId LongLong 设备所在家庭 ID。
    roomId LongLong 设备所在房间 ID。
    upgrading Boolean 是否在升级中。
    timezoneId NSString 设备时区。
    nodeId NSString 设备短地址,用于区分网关下子设备的唯一地址。非子设备类型值为空。
    parentId NSString 父设备(上一级)ID,非子设备类型值为空。子设备用于寻找对应的网关设备 ID。蓝牙 Mesh 子设备为 Mesh ID 或对应的网关设备 ID。
    isMeshBleOnline Boolean 设备蓝牙 Mesh 本地在线状态。
    devKey NSString 标准蓝牙 Mesh 设备蓝牙通信 key。
    standard Boolean 是否为标准化产品设备。如果为标准设备,可以使用标准设备控制功能。
    standSchemaModel ThingSmartStand
    SchemaModel
    设备标准 DP 规则信息。
    activeTime NSTimeInterval 激活时间。
    homeDisplayOrder NSInteger 设备序号,家庭查询设备列表时,可通过该属性进行排序。
    sharedTime LongLong 分享时间。
    accessType NSInteger 区分设备的接入方式:
    • 0:涂鸦 DP 接入
    • 1:Matter 协议接入
    • 2:TuyaLink 接入
    thingModel ThingSmart
    ThingModel
    设备物模型,当 accessType 取值为 2 时需要用到。
    在需要使用之前,通过 - getThingModelWithSuccess:failure:+ getThingModelWithProductId:productVersion:success:failure: 查询设备物模型。
    category NSString 设备品类缩写,例如 dj 表示灯具。详见 类目 Code 列表

初始化设备

根据设备 ID,初始化设备控制类。

  • 您需要通过 ThingSmartHome 初始化一个 home 实例,然后调用 getHomeDetailWithSuccess:failure: 查询家庭详情。只有同步过家庭的详情后,初始化设备才能成功。

  • 错误的设备 ID 可能会导致初始化失败,此时设备的实例返回 nil

接口说明

/**
* 查询设备实例。如果当前用户没有该设备,将会返回 nil。
*
* @param devId Device ID
* @return instance
*/
+ (nullable instancetype)deviceWithDeviceId:(NSString *)devId;

参数说明

参数 说明
devId 设备 ID

示例代码

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

设备代理监听

实现 ThingSmartDeviceDelegate 代理协议后,您可以在设备状态更变的回调中进行处理,刷新 App 设备控制面板的 UI。

示例代码

Objective-C:

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

#pragma mark - ThingSmartDeviceDelegate

- (void)device:(ThingSmartDevice *)device dpsUpdate:(NSDictionary *)dps {
    // 设备的 DP 状态发生变化,刷新界面 UI
}

- (void)deviceInfoUpdate:(ThingSmartDevice *)device {
    //当前设备信息更新,例如设备名称修改、设备在线离线状态等
}

- (void)deviceRemoved:(ThingSmartDevice *)device {
    //当前设备被移除
}

- (void)device:(ThingSmartDevice *)device signal:(NSString *)signal {
    // Wi-Fi 信号强度
}

- (void)device:(ThingSmartDevice *)device otaUpdateStatusChanged:(ThingSmartFirmwareUpgradeStatusModel *)statusModel {
    // 固件升级状态和升级进度回调。
    // 推荐在通过 `-startFirmwareUpgrade:` 升级时使用
}

- (void)device:(ThingSmartDevice *)device firmwareUpgradeProgress:(NSInteger)type progress:(double)progress {
    // 固件升级进度
    // 即将废弃,建议在通过 `-upgradeFirmware:success:failure:` 升级时使用
}

- (void)device:(ThingSmartDevice *)device firmwareUpgradeStatusModel:(ThingSmartFirmwareUpgradeStatusModel *)upgradeStatusModel {
    // 设备升级状态的回调
    // 即将废弃,建议在通过 `-upgradeFirmware:success:failure:` 升级时使用
}

Swift:

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

// MARK: - ThingSmartDeviceDelegate

func device(_ device: ThingSmartDevice?, dpsUpdate dps: [AnyHashable : Any]?) {
    // 设备的 DP 状态发生变化,刷新界面 UI
}

func deviceInfoUpdate(_ device: ThingSmartDevice?) {
    //当前设备信息更新,例如修改设备名称、设备在线离线状态等
}

func deviceRemoved(_ device: ThingSmartDevice?) {
    //当前设备被移除
}

func device(_ device: ThingSmartDevice?, signal: String?) {
    // Wi-Fi 信号强度
}

func device(_ device: ThingSmartDevice?, otaUpdateStatusChanged statusModel: ThingSmartFirmwareUpgradeStatusModel) {
    // 普通固件、PID 版本升级固件的升级状态和升级进度回调(包含单点和蓝牙 Mesh 子设备等)
    // 推荐在通过 -startFirmwareUpgrade: 升级时使用
    // 关于 OTA 的可前往 **固件升级** 章节查看
}

func device(_ device: ThingSmartDevice?, firmwareUpgradeProgress type: Int, progress: Double) {
    // 普通固件的升级进度(不包含单点和蓝牙 Mesh 子设备)
    // 即将废弃,建议在通过 -upgradeFirmware:success:failure: 升级时使用
}

func device(_ device: ThingSmartDevice?, firmwareUpgradeStatusModel upgradeStatusModel: ThingSmartFirmwareUpgradeStatusModel?) {
    // 普通固件的升级状态(不包含单点和蓝牙 Mesh 子设备)
    // 即将废弃,建议在通过 -upgradeFirmware:success:failure: 升级时使用
}

查询设备信息

查询单个 DP 数据,查询后会通过代理 - (void)device:(ThingSmartDevice *)device dpsUpdate:(NSDictionary *)dps 回调数据。

  • 该接口主要是针对不主动发送数据的设备 DP,例如倒计时信息查询。常规查询 DP 数据值时,可通过 ThingSmartDeviceModel.dps 获取。
  • 下发格式详见示例。

示例代码

Objective-C:

- (void)queryDP {
    // self.device = [ThingSmartDevice deviceWithDeviceId:@"your_device_id"];
    // 查询 dpId 是 "1" 的数据
    NSDictionary *queryDpInfo = @{
         @"1": [NSNull null]
    };
    [self.device publishDps:queryDpInfo mode:ThingDevicePublishModeAuto success:^{
        NSLog(@"query dp success");
    } failure:^(NSError *error) {
        NSLog(@"query dp failure: %@", error);
    }];
}

Swift:

func queryDP() {
    // self.device = [ThingSmartDevice deviceWithDeviceId:@"your_device_id"];
    // 查询 dpId 是 "1" 的数据
    let queryDpInfo = [
        "1": NSNull()
    ]
    device.publishDps(queryDpInfo, mode: ThingDevicePublishModeAuto, success: {
        print("query dp success")
    }, failure: { error in
        if let error = error {
            print("query dp failure: \(error)")
        }
    })
}

修改设备名称

接口说明

- (void)updateName:(NSString *)name success:(nullable ThingSuccessHandler)success failure:(nullable ThingFailureError)failure;

参数说明

参数 说明
name 设备名称
success 成功回调
failure 失败回调

示例代码

Objective-C:

- (void)modifyDeviceName:(NSString *)mame {
    // self.device = [ThingSmartDevice 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)")
        }
    })
}

移除设备

设备被移除后,会重新进入待配网状态,Wi-Fi 设备默认进入快连模式。

接口说明

- (void)remove:(nullable ThingSuccessHandler)success failure:(nullable ThingFailureError)failure;

参数说明

参数 说明
success 成功回调
failure 失败回调

示例代码

Objective-C:

- (void)removeDevice {
    // self.device = [ThingSmartDevice 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)")
        }
    })
}

恢复出厂设置

设备恢复出厂设置后,会重新进入待配网状态,Wi-Fi 设备默认进入快连模式。设备的相关数据会被清除掉。

接口说明

- (void)resetFactory:(nullable ThingSuccessHandler)success failure:(nullable ThingFailureError)failure;

参数说明

参数 说明
success 成功回调
failure 失败回调

示例代码

Objective-C:

- (void)removeDevice {
    // self.device = [ThingSmartDevice 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)")
        }
    })
}

查询 Wi-Fi 信号强度

查询设备 Wi-Fi 信号后,会通过 ThingSmartDeviceDelegatedevice:signal: 方法回调。

接口说明

- (void)getWifiSignalStrengthWithSuccess:(nullable ThingSuccessHandler)success failure:(nullable ThingFailureError)failure;

参数说明

参数 说明
success 发送查询 Wi-Fi 强度成功回调
failure 失败回调

示例代码

Objective-C:

- (void)getWifiSignalStrength {
    // self.device = [ThingSmartDevice 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 - ThingSmartDeviceDelegate

- (void)device:(ThingSmartDevice *)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: - ThingSmartDeviceDelegate
func device(_ device: ThingSmartDevice!, signal: String!) {
    print(" signal : \(signal)")
}

查询网关子设备列表

如果是网关设备,可以查询网关下子设备的列表。

接口说明

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

参数说明

参数 说明
success 成功回调,网关下的子设备信息
failure 失败回调

示例代码

Objective-C:

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

    [self.device getSubDeviceListFromCloudWithSuccess:^(NSArray<ThingSmartDeviceModel *> *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)")
        }
    })
}