家庭信息管理

更新时间:2023-11-28 07:09:19下载pdf

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

功能说明

类名(协议名) 说明
ThingSmartHomeManager 查询家庭列表、家庭列表排序、添加家庭
ThingSmartHomeManagerDelegate 增删家庭、MQTT 连接成功回调

单个家庭信息管理相关的所有功能对应 ThingSmartHome 类,需要使用正确的 homeId 进行初始化。错误的 homeId 会导致初始化失败,返回 nil。主要功能:单个家庭信息管理,获取家庭下所有设备、群组,家庭下的家庭成员管理,房间管理等。

类名(协议名) 说明
ThingSmartHome 家庭管理类
ThingSmartHomeDelegate 家庭下信息变更回调

获取家庭下所有设备、群组前需先初始化 home 对象,并查询家庭的详情 getHomeDataWithSuccess:failure:,然后 home 实例对象中的属性 homeModelroomListdeviceListgroupListsharedDeviceListsharedGroupList 才有数据。

创建家庭

接口说明

- (void)addHomeWithName:(NSString *)homeName
                geoName:(NSString *)geoName
                  rooms:(NSArray <NSString *>*)rooms
               latitude:(double)latitude
              longitude:(double)longitude
                success:(ThingSuccessLongLong)success
                failure:(ThingFailureError)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)")
        }
    }
}

查询家庭列表

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

接口说明

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

参数说明

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

示例代码

Objc:

- (void)getHomeList {

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

Swift:

let homeManager: ThingSmartHomeManager = ThingSmartHomeManager()

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:(ThingSuccessHandler)success
                       failure:(ThingFailureError)failure;

参数说明

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

示例代码

Objc:

- (void)updateHomeInfo {
    self.home = [ThingSmartHome 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:(ThingSuccessHandler)success
                       failure:(ThingFailureError)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 实例对象中的属性 homeModelroomListdeviceListgroupListsharedDeviceListsharedGroupList 等才有数据。

接口说明

- (void)getHomeDataWithSuccess:(void (^)(ThingSmartHomeModel *homeModel))success
                       failure:(ThingFailureError)failure;

参数说明

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

示例代码

Objc:

- (void)getHomeDataInfo {
    self.home = [ThingSmartHome homeWithHomeId:homeId];
        [self.home getHomeDataWithSuccess:^(ThingSmartHomeModel *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:(ThingSuccessHandler)success
                               failure:(ThingFailureError)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)")
        }
    })
}

家庭列表变化的回调

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

新增一个家庭的回调

接口说明

- (void)homeManager:(ThingSmartHomeManager *)manager didAddHome:(ThingSmartHomeModel *)home;

参数说明

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

删除一个家庭的回调

接口说明

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

参数说明

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

MQTT 服务连接成功的回调

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

接口说明

- (void)serviceConnectedSuccess;

示例代码

Objc:

#pragma mark - ThingSmartHomeManagerDelegate

// 添加一个家庭
- (void)homeManager:(ThingSmartHomeManager *)manager didAddHome:(ThingSmartHomeModel *)home {

}

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

}

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

Swift:

extension ViewController: ThingSmartHomeManagerDelegate {

    // 添加一个家庭
    func homeManager(_ manager: ThingSmartHomeManager!, didAddHome home: ThingSmartHomeModel!) {

    }

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

    }

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

家庭信息变化的回调

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

示例代码

Objc:

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

#pragma mark - ThingSmartHomeDelegate

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

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

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

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

// 房间信息变更,例如房间 name 变化
- (void)home:(ThingSmartHome *)home roomInfoUpdate:(ThingSmartRoomModel *)room {
    [self reload];
}

// 房间与设备,群组的关系变化
- (void)home:(ThingSmartHome *)home roomRelationUpdate:(ThingSmartRoomModel *)room {
    [self reload];
}

// 添加设备
- (void)home:(ThingSmartHome *)home didAddDeivice:(ThingSmartDeviceModel *)device {
    [self reload];
}

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

// 设备信息更新,例如设备 name 变化,在线状态变化
- (void)home:(ThingSmartHome *)home deviceInfoUpdate:(ThingSmartDeviceModel *)device {
    [self reload];
}

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

// 添加群组
- (void)home:(ThingSmartHome *)home didAddGroup:(ThingSmartGroupModel *)group {
    [self reload];
}

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

// 群组信息更新,例如群组 name 变化
- (void)home:(ThingSmartHome *)home groupInfoUpdate:(ThingSmartGroupModel *)group {
    [self reload];
}

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

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

// the delegate of device firmware upgrade status update
// 家庭下设备升级状态的回调
- (void)home:(ThingSmartHome *)home device:(ThingSmartDeviceModel *)device upgradeStatus:(ThingSmartDeviceUpgradeStatus)upgradeStatus {
    //...
}

Swift:

var home: ThingSmartHome?

extension ViewController: ThingSmartHomeDelegate {

  func initHome() {
      home = ThingSmartHome(homeId: homeId)
      home?.delegate = self
  }

  // 家庭的信息更新,例如 name
  func homeDidUpdateInfo(_ home: ThingSmartHome!) {
//        reload()
  }

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

  }

  // 家庭下新增房间代理回调
  func home(_ home: ThingSmartHome!, didAddRoom room: ThingSmartRoomModel!) {
      //...
  }

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

  // 房间信息变更,例如 name
  func home(_ home: ThingSmartHome!, roomInfoUpdate room: ThingSmartRoomModel!) {
//        reload()/
  }

  // 房间与设备,群组的关系变化
  func home(_ home: ThingSmartHome!, roomRelationUpdate room: ThingSmartRoomModel!) {

  }

  // 添加设备
  func home(_ home: ThingSmartHome!, didAddDeivice device: ThingSmartDeviceModel!) {

  }

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

  }

  // 设备信息更新,例如 name
  func home(_ home: ThingSmartHome!, deviceInfoUpdate device: ThingSmartDeviceModel!) {

  }

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

  // 添加群组
  func home(_ home: ThingSmartHome!, didAddGroup group: ThingSmartGroupModel!) {

  }

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

  }

  // 群组信息更新,例如 name
  func home(_ home: ThingSmartHome!, groupInfoUpdate group: ThingSmartGroupModel!) {

  }

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

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

  // 家庭下设备升级状态的回调
  func home(_ home: ThingSmartHome!, device: ThingSmartDeviceModel!, upgradeStatus status ThingSmartDeviceUpgradeStatus) {
        //....
  }

}

查询家庭所在地区的天气

查询家庭天气简要参数

接口说明

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

- (void)getHomeWeatherSketchWithSuccess:(void(^)(ThingSmartWeatherSketchModel *))success
                                failure:(ThingFailureError)failure;

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

#import <ThingSmartDeviceKit/ThingSmartHome+Weather.h>

参数说明

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

其中,返回的参数 ThingSmartWeatherSketchModel 做如下说明:

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

示例代码

Objc:

- (void)getHomeWeatherSketch {
    [self.home getHomeWeatherSketchWithSuccess:^(ThingSmartWeatherSketchModel *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:(ThingSmartWeatherOptionModel *)optionModel
                               success:(void(^)(NSArray<ThingSmartWeatherModel *> *))success
                               failure:(ThingFailureError)failure;

参数说明

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

ThingSmartWeatherOptionModel 参数在请求前需要手动配置,配置选项如下:

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

请求返回的参数 ThingSmartWeatherModel 内容说明如下:

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

示例代码

Objc:

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

Swift:

func getHomeWeatherDetail() {
    let optionModel = ThingSmartWeatherOptionModel()
    // 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)")
    }
}