智能生活 App SDK 之家庭信息管理接口（全）

Posted 2022-12-07 IoT砖家涂拉拉

涂鸦智能生活 App SDK 为全屋智能业务场景的移动端开发提供各类模块和组件。因此，家庭是抽象于全屋智能场景的概念，指用户在以家或者场所为单位的范围内所有设备、账号、权限等信息的集合。

家庭管理主要包括以下能力：

• 查询家庭列表
• 添加、修改和移除单个家庭
• 管理家庭名称，地理位置、房间列表信息，成员信息等
• 家庭下，设备添加、信息修改、监听移除、设备状态变化的监听等

用户登录成功后需要通过 TuyaSmartHomeManager 去查询整个家庭列表的信息，然后初始化其中的一个家庭 TuyaSmartHome，查询家庭详情信息，就可以对家庭中的设备进行操作控制。

功能说明

类名（协议名）	说明
TuyaSmartHomeManager	查询家庭列表、家庭列表排序、添加家庭
TuyaSmartHomeManagerDelegate	增删家庭、MQTT 连接成功回调

单个家庭信息管理相关的所有功能对应 TuyaSmartHome 类，需要使用正确的 homeId 进行初始化。错误的 homeId 会导致初始化失败，返回 nil。主要功能：单个家庭信息管理，家庭下的家庭成员管理，房间管理等。

类名（协议名）	说明
TuyaSmartHome	家庭管理类
TuyaSmartHomeDelegate	家庭下信息变更回调

初始化 home 对象之后需要去查询家庭的详情 getHomeDataWithSuccess:failure:，home 实例对象中的属性 homeModel、roomList、deviceList、groupList、sharedDeviceList、sharedGroupList 才有数据。

创建家庭

接口说明

- (void)addHomeWithName:(NSString *)homeName
                geoName:(NSString *)geoName
                  rooms:(NSArray <NSString *>*)rooms
               latitude:(double)latitude
              longitude:(double)longitude
                success:(TYSuccessLongLong)success
                failure:(TYFailureError)failure;

参数说明

参数	说明
homeName	家庭的名称
geoName	家庭的地址
rooms	家庭下房间的名称列表
latitude	家庭地址纬度
longitude	家庭地址经度
success	成功回调
failure	失败回调

示例代码

Objc:

- (void)addHome 
    [self.homeManager addHomeWithName:@"you_home_name"
                          geoName:@"city_name"
                            rooms:@[@"room_name"]
                         latitude:lat
                        longitude:lon
                          success:^(double homeId) 

        // homeId 创建的家庭的 homeId
        NSLog(@"add home success");
     failure:^(NSError *error) 
        NSLog(@"add home failure: %@", error);
    ];

Swift:

 func addHome() 
    homeManager.addHome(withName: "you_home_name",
                         geoName: "city_name",
                           rooms: ["room_name"],
                        latitude: lat,
                       longitude: lon,
                         success:  (homeId) in
        // homeId 创建的家庭的 homeId
        print("add home success")
    )  (error) in
        if let e = error 
            print("add home failure: \\(e)")
        
    

查询家庭列表

本接口返回的数据只是家庭的简单信息。如果要查询具体家庭的详情，您需要去 TuyaSmartHome 初始化一个 home，调用接口 getHomeDataWithSuccess:failure:。

接口说明

// 查询家庭的列表
- (void)getHomeListWithSuccess:(void(^)(NSArray <TuyaSmartHomeModel *> *homes))success
                       failure:(TYFailureError)failure;

参数说明

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

示例代码

Objc:

- (void)getHomeList 

	[self.homeManager getHomeListWithSuccess:^(NSArray<TuyaSmartHomeModel *> *homes) 
        // homes 家庭列表
     failure:^(NSError *error) 
        NSLog(@"get home list failure: %@", error);
    ];

Swift:

let homeManager: TuyaSmartHomeManager = TuyaSmartHomeManager()

func getHomeList() 
    homeManager.getHomeList(success:  (homes) in
        // homes 家庭列表
    )  (error) in
        if let e = error 
            print("get home list failure: \\(e)")
        
    

修改家庭信息

接口说明

- (void)updateHomeInfoWithName:(NSString *)homeName
                       geoName:(NSString *)geoName
                      latitude:(double)latitude
                     longitude:(double)longitude
                       success:(TYSuccessHandler)success
                       failure:(TYFailureError)failure;

参数说明

参数	说明
homeName	家庭名称
geoName	家庭地址名称
latitude	家庭地址纬度
longitude	家庭地址经度
success	成功回调
failure	失败回调

示例代码

Objc:

- (void)updateHomeInfo 
    self.home = [TuyaSmartHome homeWithHomeId:homeId];
    [self.home updateHomeInfoWithName:@"new_home_name" geoName:@"city_name" latitude:lat longitude:lon success:^
        NSLog(@"update home info success");
     failure:^(NSError *error) 
        NSLog(@"update home info failure: %@", error);
    ];

Swift:

func updateHomeInfo() 
    home?.updateInfo(withName: "new_home_name", geoName: "city_name", latitude: lat, longitude: lon, success: 
        print("update home info success")
    , failure:  (error) in
        if let e = error 
            print("update home info failure: \\(e)")
        
    )

注销或删除家庭

接口说明

- (void)dismissHomeWithSuccess:(TYSuccessHandler)success
                       failure:(TYFailureError)failure;

参数说明

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

示例代码

Objc:

- (void)dismissHome 

	[self.home dismissHomeWithSuccess:^() 
        NSLog(@"dismiss home success");
     failure:^(NSError *error) 
        NSLog(@"dismiss home failure: %@", error);
    ];

Swift:

func dismissHome() 
    home?.dismiss(success: 
        print("dismiss home success")
    , failure:  (error) in
        if let e = error 
            print("dismiss home failure: \\(e)")
        
    )

查询家庭的详细信息

只有调用了此接口，home 实例对象中的属性 homeModel、roomList、deviceList、groupList、sharedDeviceList、sharedGroupList 等才有数据。

接口说明

- (void)getHomeDataWithSuccess:(void (^)(TuyaSmartHomeModel *homeModel))success
                       failure:(TYFailureError)failure;

参数说明

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

示例代码

Objc:

- (void)getHomeDataInfo 
	self.home = [TuyaSmartHome homeWithHomeId:homeId];
        [self.home getHomeDataWithSuccess:^(TuyaSmartHomeModel *homeModel) 
        // homeModel 家庭信息
        NSLog(@"get home data success");
     failure:^(NSError *error) 
        NSLog(@"get home data failure: %@", error);
    ];

Swift:

func getHomeDataInfo() 
    home?.getDataWithSuccess( (homeModel) in
        print("get home data success")
    , failure:  (error) in
        if let e = error 
            print("get home data failure: \\(e)")
        
    )

对家庭中设备和群组排序

接口说明

- (void)sortDeviceOrGroupWithOrderList:(NSArray<NSDictionary *> *)orderList
                               success:(TYSuccessHandler)success
                               failure:(TYFailureError)failure;

参数说明

参数	说明
orderList	设备或群组排序列表
success	成功回调
failure	失败回调

示例代码

Objc:

// orderList: [@@"bizId": @"XXX", @"bizType": @"XXX",@@"bizId": @"XXX",@"bizType": @"XXX"] 其中 bizId 为设备的 devId 或群组的 groupId, device 的 bizType = @"6" group 的 bizType = @"5"
- (void)sortDeviceOrGroupWithOrderList:(NSArray<NSDictionary *> *)orderList 
	[self.home sortDeviceOrGroupWithOrderList:orderList success:^ 
        NSLog(@"sort device or group success");
     failure:^(NSError *error) 
        NSLog(@"sort device or group failure: %@", error);
    ];

Swift:

func sortDeviceOrGroup(withOrderList orderList: [[AnyHashable : Any]]?) 
    home.sortDeviceOrGroup(withOrderList: orderList, success: 
        print("sort device or group success")
    , failure:  error in
        if let error = error 
            print("sort device or group failure: \\(error)")
        
    )

家庭列表变化的回调

实现 TuyaSmartHomeManagerDelegate 代理协议后，您可以在家庭列表更变的回调中进行处理。

新增一个家庭的回调

接口说明

- (void)homeManager:(TuyaSmartHomeManager *)manager didAddHome:(TuyaSmartHomeModel *)home;

参数说明

参数	说明
manager	家庭管理类实例
home	添加的家庭模型

删除一个家庭的回调

接口说明

- (void)homeManager:(TuyaSmartHomeManager *)manager didRemoveHome:(long long)homeId;

参数说明

参数	说明
manager	家庭管理类实例
homeId	被删除的家庭 ID

MQTT 服务连接成功的回调

应用进入手机后台，MQTT 长连接会断开连接。再次进入前台后，会进行重连。所以，您需要在此代理这里重新查询当前家庭的详情，保证当前家庭下的数据是最新数据。

接口说明

- (void)serviceConnectedSuccess;

示例代码

Objc:

#pragma mark - TuyaSmartHomeManagerDelegate

// 添加一个家庭
- (void)homeManager:(TuyaSmartHomeManager *)manager didAddHome:(TuyaSmartHomeModel *)home 



// 删除一个家庭
- (void)homeManager:(TuyaSmartHomeManager *)manager didRemoveHome:(long long)homeId 



// MQTT 连接成功
- (void)serviceConnectedSuccess 
    // 去云端查询当前家庭的详情，然后去刷新 UI

Swift:

extension ViewController: TuyaSmartHomeManagerDelegate 

    // 添加一个家庭
    func homeManager(_ manager: TuyaSmartHomeManager!, didAddHome home: TuyaSmartHomeModel!) 

    

    // 删除一个家庭
    func homeManager(_ manager: TuyaSmartHomeManager!, didRemoveHome homeId: Int64) 

    

    // MQTT 连接成功
    func serviceConnectedSuccess() 
        // 去云端查询当前家庭的详情，然后去刷新 UI
    

家庭信息变化的回调

实现 TuyaSmartHomeDelegate 代理协议后，可以在单个家庭信息更变的回调中进行处理。

示例代码

Objc:

- (void)initHome 
    self.home = [TuyaSmartHome homeWithHomeId:homeId];
    self.home.delegate = self;


#pragma mark - TuyaSmartHomeDelegate

// 家庭的信息更新，例如家庭 name 变化
- (void)homeDidUpdateInfo:(TuyaSmartHome *)home 
    [self reload];


// 我收到的共享设备列表变化
- (void)homeDidUpdateSharedInfo:(TuyaSmartHome *)home 
    [self reload];


// 家庭下新增房间代理回调
- (void)home:(TuyaSmartHome *)home didAddRoom:(TuyaSmartRoomModel *)room 
  	[self reload];


// 家庭下删除房间代理回调
- (void)home:(TuyaSmartHome *)home didRemoveRoom:(long long)roomId 
  	[self reload];


// 房间信息变更，例如房间 name 变化
- (void)home:(TuyaSmartHome *)home roomInfoUpdate:(TuyaSmartRoomModel *)room 
    [self reload];


// 房间与设备，群组的关系变化
- (void)home:(TuyaSmartHome *)home roomRelationUpdate:(TuyaSmartRoomModel *)room 
    [self reload];


// 添加设备
- (void)home:(TuyaSmartHome *)home didAddDeivice:(TuyaSmartDeviceModel *)device 
    [self reload];


// 删除设备
- (void)home:(TuyaSmartHome *)home didRemoveDeivice:(NSString *)devId 
    [self reload];


// 设备信息更新，例如设备 name 变化，在线状态变化
- (void)home:(TuyaSmartHome *)home deviceInfoUpdate:(TuyaSmartDeviceModel *)device 
    [self reload];


// 家庭下设备的 dps 变化代理回调
- (void)home:(TuyaSmartHome *)home device:(TuyaSmartDeviceModel *)device dpsUpdate:(NSDictionary *)dps 
    [self reload];


// 添加群组
- (void)home:(TuyaSmartHome *)home didAddGroup:(TuyaSmartGroupModel *)group 
    [self reload];


// 删除群组
- (void)home:(TuyaSmartHome *)home didRemoveGroup:(NSString *)groupId 
    [self reload];


// 群组信息更新，例如群组 name 变化
- (void)home:(TuyaSmartHome *)home groupInfoUpdate:(TuyaSmartGroupModel *)group 
    [self reload];


// 家庭下群组 dps 变化代理回调
- (void)home:(TuyaSmartHome *)home group:(TuyaSmartGroupModel *)group dpsUpdate:(NSDictionary *)dps 
    [self reload];


// the delegate of warning information update
// 家庭下设备的告警信息变化的代理回调
- (void)home:(TuyaSmartHome *)home device:(TuyaSmartDeviceModel *)device warningInfoUpdate:(NSDictionary *)warningInfo 
	//...


// the delegate of device firmware upgrade status update
// 家庭下设备升级状态的回调
- (void)home:(TuyaSmartHome *)home device:(TuyaSmartDeviceModel *)device upgradeStatus:(TuyaSmartDeviceUpgradeStatus)upgradeStatus 
  	//...

Swift:

var home: TuyaSmartHome?

extension ViewController: TuyaSmartHomeDelegate 

  func initHome() 
      home = TuyaSmartHome(homeId: homeId)
      home?.delegate = self
  

  // 家庭的信息更新，例如 name
  func homeDidUpdateInfo(_ home: TuyaSmartHome!) 
//        reload()
  

  // 我收到的共享设备列表变化
  func homeDidUpdateSharedInfo(_ home: TuyaSmartHome!) 

  

  // 家庭下新增房间代理回调
  func home(_ home: TuyaSmartHome!, didAddRoom room: TuyaSmartRoomModel!) 
      //...
  

  // 家庭下删除房间代理回调
  func home(_ home: TuyaSmartHome!, didRemoveRoom roomId: int32!) 
      //...
  

  // 房间信息变更，例如 name
  func home(_ home: TuyaSmartHome!, roomInfoUpdate room: TuyaSmartRoomModel!) 
//        reload()/
  

  // 房间与设备，群组的关系变化
  func home(_ home: TuyaSmartHome!, roomRelationUpdate room: TuyaSmartRoomModel!) 

  

  // 添加设备
  func home(_ home: TuyaSmartHome!, didAddDeivice device: TuyaSmartDeviceModel!) 

  

  // 删除设备
  func home(_ home: TuyaSmartHome!, didRemoveDeivice devId: String!) 

  

  // 设备信息更新，例如 name
  func home(_ home: TuyaSmartHome!, deviceInfoUpdate device: TuyaSmartDeviceModel!) 

  

  // 家庭下设备的 dps 变化代理回调
  func home(_ home: TuyaSmartHome!, device: TuyaSmartDeviceModel!, dpsUpdate dps: [AnyHashable : Any]!) 
      //...
  

  // 添加群组
  func home(_ home: TuyaSmartHome!, didAddGroup group: TuyaSmartGroupModel!) 

  

  // 删除群组
  func home(_ home: TuyaSmartHome!, didRemoveGroup groupId: String!) 

  

  // 群组信息更新，例如 name
  func home(_ home: TuyaSmartHome!, groupInfoUpdate group: TuyaSmartGroupModel!) 

  

  // 家庭下群组的 dps 变化代理回调
  func home(_ home: TuyaSmartHome!, group: TuyaSmartGroupModel!, dpsUpdate dps: [AnyHashable : Any]!) 
			//...
  

  // 家庭下设备的告警信息变化的代理回调
  func home(_ home: TuyaSmartHome!, device: TuyaSmartDeviceModel!, warningInfoUpdate warningInfo: [AnyHashable : Any]!) 
    	//...
  

  // 家庭下设备升级状态的回调
  func home(_ home: TuyaSmartHome!, device: TuyaSmartDeviceModel!, upgradeStatus status TuyaSmartDeviceUpgradeStatus) 
    	//....
  

查询家庭所在地区的天气

查询家庭天气简要参数

接口说明

该请求返回家庭所在城市的简要天气参数，如城市名称、当天的天气状况（晴、多云、雨等）、天气图片信息。

- (void)getHomeWeatherSketchWithSuccess:(void(^)(TuyaSmartWeatherSketchModel *))success
                                failure:(TYFailureError)failure;

如果查询不到相关方法，可以添加以下代码：

#import <TuyaSmartDeviceKit/TuyaSmartHome+Weather.h>

参数说明

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

其中，返回的参数 TuyaSmartWeatherSketchModel 做如下说明：

参数	说明
condition	天气情况，例如晴、阴、雨等
iconUrl	天气图标，高亮
inIconUrl	天气图标
temp	温度

示例代码

Objc:

- (void)getHomeWeatherSketch 
    [self.home getHomeWeatherSketchWithSuccess:^(TuyaSmartWeatherSketchModel *weatherSketchModel) 
        NSLog(@"success get weather summary model: %@",weatherSketchModel);
     failure:^(NSError *error) 
        NSLog(@"failure with error: %@", error);
    ];

Swift:

func getHomeWeatherSketch() 
    home.getWeatherSketch(success:  (weatherSketchModel) in
        print("success get weather summary model: \\(weatherSketchModel)");
    )  (e) in
        print("failure with error: \\(e)")
    ;

查询家庭天气详细参数

接口说明

查询家庭天气详细参数，如温度、湿度、紫外线指数、空气质量等。

• optionModel 可以为 nil。若为 nil，返回的参数会上一次请求成功的参数设置。若只改变一种单位设置进行请求，另外两种也依然会保留上一次请求成功的参数设置。
• 由于天气服务在不同地区的使用的服务不同，不同地区返回的参数有可能不同。特别的，如果家庭位置在中国大陆地区，那么不会返回风速和气压信息。

- (void)getHomeWeatherDetailWithOption:(TuyaSmartWeatherOptionModel *)optionModel
                               success:(void(^)(NSArray<TuyaSmartWeatherModel *> *))success
                               failure:(TYFailureError)failure;

参数说明

参数	说明
optionModel	天气详情参数单位配置
success	成功回调
failure	失败回调

TuyaSmartWeatherOptionModel 参数在请求前需要手动配置，配置选项如下：

参数	说明
pressureUnit	气压单位
windspeedUnit	风速单位
temperatureUnit	温度单位
limit	请求的天气详情的个数，若不配置，则默认全部返回

请求返回的参数 TuyaSmartWeatherModel 内容说明如下：

参数	说明
icon	天气参数图标
name	天气参数名称
unit	参数单位
value	参数值

示例代码

Objc:

- (void)getHomeWeatherDetail 
    [self.home getHomeWeatherDetailWithOption:optionModel
                                      success:^(NSArray<TuyaSmartWeatherModel *> *weatherModels) 
          NSLog(@"success get weather model: %@",weatherModels);
                                     failure:^(NSError *error) 
          NSLog(@"failure with error: %@", error);
    ];

Swift:

func getHomeWeatherDetail() 
    let optionModel = TuyaSmartWeatherOptionModel()
    // do some optionModel config
    home.getWeatherDetail(withOption: optionModel, success:  (weatherSketchModel) in
        print("success get weather summary model: \\(weatherSketchModel)");
    )  (error) in
        print("failure with error: \\(error)")