区域管理

更新时间:2022-02-17 05:22:13下载pdf

通过 TuyaLightingProject+TYArea 分类来查询项目下区域列表信息,通过 TuyaLightingAreaManager 管理类去创建一个新的区域,然后初始化一个区域类 TuyaLightingArea 查询区域的相关信息,操作区域中的设备等。

TuyaLightingArea 定义了一个具体区域的属性和方法,提供诸如区域群控、设备分区等功能。

查询项目下所有区域

需要查询区域层级结构时调用该接口。

接口说明

- (void)getAreaLevelsWithNeedUnassignedArea:(BOOL)needUnassignedArea
                             needPublicArea:(BOOL)needPublicArea
                                    success:(nullable void(^)(NSArray <TuyaLightingAreaModel *> *areas, NSInteger totalRoomDeviceCount))success
                                    failure:(nullable TYFailureError)failure;

参数说明

参数 说明
needUnassignedArea 是否需要未分区区域信息
needPublicArea 是否需要公共区域信息
success 成功回调,可选
failure 失败回调,可选

示例代码

Objc:

TuyaLightingProject *project = [TuyaLightingProject projectWithProjectId:currentProjectId];
[project getAreaLevelsWithNeedUnassignedArea:YES
                              needPublicArea:YES
                                     success:^(NSArray <TuyaLightingAreaModel *> *areas, NSInteger totalRoomDeviceCount) {
  NSLog(@"success");
} failure:^(NSError *error) {
  NSLog(@"failure");
}];

查询项目中一级区域

需要查询一级区域时调用该接口。

接口说明

- (void)getAreaListWithSuccess:(nullable void(^)(NSArray <TuyaLightingAreaModel *> *areas))success
                       failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objc:

TuyaLightingProject *project = [TuyaLightingProject projectWithProjectId:currentProjectId];
[project getAreaListWithSuccess:^(NSArray <TuyaLightingAreaModel *> *areas) {
  NSLog(@"success");
} failure:^(NSError *error) {
  NSLog(@"failure");
}];

创建一个室内区域

室内项目创建区域时需要调用该接口。

接口说明

+ (void)createAreaWithProjectId:(long long)projectId
                  currentAreaId:(long long)currentAreaId
                           name:(NSString *)name
                      roomLevel:(NSInteger)roomLevel
                        success:(nullable TYSuccessID)success
                        failure:(nullable TYFailureError)failure;

参数说明

参数 说明
projectId 项目ID,必填
currentAreaId 当前区域的ID,若没有,可自定义ID为新区域的父级区域,必填
name 区域名称,必填
roomLevel 区域层级,可以通过 TuyaLightingProjectManager 类的 getSpaceAttributesWithProjectId 方法查询,必填
success 成功回调,可选
failure 失败回调,可选

示例代码

Objc:

[TuyaLightingAreaManager createAreaWithProjectId:123
                                   currentAreaId:456
                                            name:@"area name"
                                       roomLevel:1
                                         success:^(id result) {
        NSLog(@"success");
    } failure:^(NSError *error) {
        NSLog(@"failure");
    }];

创建一个户外区域

户外项目创建区域时需要调用该接口。

接口说明

不同于创建室内区域方法,可以保存区域的地理位置。

+ (void)createAreaWithProjectId:(long long)projectId
                  currentAreaId:(long long)currentAreaId
                           name:(NSString *)name
                      roomLevel:(NSInteger)roomLevel
                      longitude:(double)longitude
                       latitude:(double)latitude
                        address:(nullable NSString *)address
                        success:(nullable TYSuccessID)success
                        failure:(nullable TYFailureError)failure;

参数说明

参数 说明
projectId 项目ID,必填
currentAreaId 当前区域的ID,若没有,可自定义ID为新区域的父级区域,必填
name 区域名称,必填
roomLevel 区域层级,可以通过 TuyaLightingProjectManager 类的 getSpaceAttributesWithProjectId 方法查询,必填
longitude 经度,可选
latitude 纬度,可选
address 区域地址,可选
success 成功回调,可选
failure 失败回调,可选

示例代码

Objc:

[TuyaLightingAreaManager createAreaWithProjectId:123
                                   currentAreaId:456
                                            name:@"area name"
                                       roomLevel:1
                                       longitude:-1
                                        latitude:-1
                                         address:@""
                                         success:^(id result) {
        NSLog(@"success");
    } failure:^(NSError *error) {
        NSLog(@"failure");
    }];

创建一个子区域(适用于室内区域)

在当前区域下创建一个子区域,例如楼宇的子区域是楼层。

接口说明

- (void)createSubAreaWithName:(NSString *)subAreaName
                      success:(nullable void(^)(TuyaLightingAreaModel *))success
                      failure:(nullable TYFailureError)failure;

参数说明

参数 说明
subAreaName 子区域名称,必填
success 成功回调,并返回子区域的 areaModel,可选
failure 失败回调,可选

示例代码

Objc:

[self.area createSubAreaWithName:@"childArea"
                         success:^(TuyaSmartAreaModel * _Nonnull areaModel) {
                           NSLog(@"success");
                       } failure:^(NSError *error) {
                           NSLog(@"failure");
                       }];

创建一个子区域(适用于户外区域)

在当前区域下创建一个子区域,例如杭州市的子区域西湖区。

接口说明

- (void)createSubAreaWithName:(NSString *)subAreaName
                    longitude:(double)longitude
                     latitude:(double)latitude
                      address:(nullable NSString *)address
                      success:(nullable void(^)(TuyaLightingAreaModel *))success
                      failure:(nullable TYFailureError)failure;

参数说明

参数 说明
subAreaName 子区域名称,必填
longitude 经度,可选
latitude 纬度,可选
address 子区域地址,可选
success 成功回调,并返回子区域的 areaModel,可选
failure 失败回调,可选

示例代码

Objc:

[self.area createSubAreaWithName:@"childArea"
                       longitude:(double)longitude
                        latitude:(double)latitude
                         address:(nullable NSString *)address
                         success:^(TuyaSmartAreaModel * _Nonnull areaModel) {
                           NSLog(@"success");
                       } failure:^(NSError *error) {
                           NSLog(@"failure");
                       }];

创建一个父区域(适用于室内区域)

在当前区域下创建一个父区域,例如楼层的子区域楼宇。

接口说明

- (void)createParentAreaWithName:(NSString *)parentAreaName
                         success:(nullable void(^)(TuyaLightingAreaModel *))success
                         failure:(nullable TYFailureError)failure;

参数说明

参数 说明
parentAreaName 父区域名称,必填
success 成功回调,并返回父区域的areaModel,可选
failure 失败回调,可选

示例代码

Objc:

[self.area createParentAreaWithName:@"parentArea"
                            success:^(TuyaSmartAreaModel * _Nonnull areaModel) {
                             NSLog(@"success");
                          } failure:^(NSError *error) {
                             NSLog(@"failure");
                          }];

创建一个父区域(适用于户外区域)

在当前区域下创建一个父区域,例如西湖区的父区域杭州市。

接口说明

- (void)createParentAreaWithName:(NSString *)parentAreaName
                       longitude:(double)longitude
                        latitude:(double)latitude
                         address:(nullable NSString *)address
                         success:(nullable void(^)(TuyaLightingAreaModel *))success
                         failure:(nullable TYFailureError)failure;

参数说明

参数 说明
parentAreaName 父区域名称,必填
longitude 经度,可选
latitude 纬度,可选
address 父区域地址,可选
success 成功回调,并返回父区域的 areaModel,可选
failure 失败回调,可选

示例代码

Objc:

[self.area createParentAreaWithName:@"parentArea"
                          longitude:(double)longitude
                           latitude:(double)latitude
                            address:(nullable NSString *)address
                            success:^(TuyaSmartAreaModel * _Nonnull areaModel) {
                             NSLog(@"success");
                          } failure:^(NSError *error) {
                             NSLog(@"failure");
                          }];

查询当前区域下的子区域列表

从云端查询子区域列表,包含区域信息和区域下的群组列表信息。

接口说明

- (void)getSubAreaListWithSuccess:(void(^)(NSArray <TuyaLightingAreaModel *> *areas))success
                          failure:(TYFailureError)failure;

参数说明

参数 说明
success 成功回调,并返回子空间的列表
failure 失败回调

示例代码

Objc:

[self.area getSubAreaListWithSuccess:^(NSArray<TuyaLightingAreaModel *> * _Nonnull areas) {
    NSLog(@"success");
} failure:^(NSError *error) {
    NSLog(@"failure");
}];

查询区域信息(包含子区域列表)

从云端查询当前区域信息,包含子区域列表信息。

接口说明

- (void)getAreaInfoWithSuccess:(void(^)(TuyaLightingAreaModel *))success
                       failure:(nullable TYFailureError)failure;

参数说明

参数 说明
success 成功回调,并返回当前空间的 areaModel
failure 失败回调

示例代码

Objc:

[self.area getAreaInfoWithSuccess:^(TuyaLightingAreaModel * _Nonnull areaModel) {
    NSLog(@"success");
} failure:^(NSError *error) {
    NSLog(@"failure");
}];

查询当前区域对应的父级区域数据

接口说明

- (void)getParentAreaWithSuccess:(nullable void(^)(TuyaLightingAreaModel * _Nullable parentAreaModel))success
                         failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objc:

[self.area getParentAreaWithSuccess:^(TuyaLightingAreaModel * _Nullable parentAreaModel) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

修改区域信息(适用于室内区域)

接口说明

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

参数说明

参数 说明
name 区域名称
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area updateAreaInfoWithName:@"area name" success:^{
    NSLog(@"success");
} failure:^(NSError *error) {
    NSLog(@"failure");
}];

修改区域信息(适用于户外区域)

接口说明

- (void)updateAreaInfoWithName:(NSString *)name
                     longitude:(double)longitude
                      latitude:(double)latitude
                       address:(nullable NSString *)address
                       success:(nullable TYSuccessHandler)success
                       failure:(nullable TYFailureError)failure;

参数说明

参数 说明
name 区域名称
longitude 经度
latitude 纬度
address 区域地址
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area updateAreaInfoWithName:@"area name" longitude:-1 latitude:-1 address:@"" success:^{
    NSLog(@"success");
} failure:^(NSError *error) {
    NSLog(@"failure");
}];

删除区域

接口说明

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

参数说明

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

示例代码

Objc:

[self.area deleteWithSuccess:^{
    NSLog(@"success");
} failure:^(NSError *error) {
    NSLog(@"failure");
}];

添加设备到此区域

接口说明

具体流程:

  1. 首先筛选出本地直连设备,如果有本地直连设备,先进行本地直连设备的操作。
    • 把设备从原有群组中移除。
    • 把设备添加到对应的区域中。
    • 设备添加到本地群组。
  2. 如果还剩下非直接设备,请求云端将设备分配到区域。
- (void)transferDevicesWithDeviceIds:(NSArray<NSString *> *)devIds
                             success:(void (^ _Nullable)(NSArray<NSString *> * successDevIds, NSArray<NSString *> * failedDevIds))success
                             failure:(nullable TYFailureError)failure;

参数说明

参数 说明
devIds 需要添加的设备 ID 列表
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area transferDevicesWithDeviceIds:deviceIds success:^(NSArray<NSString *> * _Nonnull successDevIds, NSArray<NSString *> * _Nonnull failedDevIds) {
    NSLog(@"success");
} failure:^(NSError *error) {
    NSLog(@"failure");
}];

对未加入群组的设备进行补偿

具体流程:

  1. 首先筛选出本地直连设备,如果有本地直连设备,先进行本地直连设备的操作。
    • 把设备从原有群组中移除。
    • 把移除成功的设备添加到对应的区域中。
    • 把设备添加到本地群组中。
  2. 如果还剩下非直连设备,请求云端将设备分配到区域。

接口说明

- (void)joinGroupWithDeviceIds:(NSArray<NSString *> *)devIds
                       success:(nullable void(^)(NSArray<NSString *> *successDevIds, NSArray<NSString *> *failedDevIds))success
                       failure:(nullable TYFailureError)failure;

参数说明

参数 说明
devIds 设备ID数组
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area joinGroupWithDeviceIds:@[id] success:^(NSArray<NSString *> * _Nonnull successDevIds, NSArray<NSString *> * _Nonnull failedDevIds) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

把设备从当前区域中移除

具体流程:

  1. 首先筛选出本地直连设备,如果有本地直连设备,先进行本地直连设备的操作。
    • 把设备从原有群组中移除。
  2. 把设备添加到未分区中

接口说明

- (void)removeDeviceWithDeviceIds:(NSArray<NSString *> *)devIds
                          success:(nullable void(^)(NSArray<NSString *> *successDevIds, NSArray<NSString *> *failedDevIds))success
                          failure:(nullable TYFailureError)failure;

参数说明

参数 说明
devIds 设备ID数组
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area removeDeviceWithDeviceIds:@[id] success:^(NSArray<NSString *> * _Nonnull successDevIds, NSArray<NSString *> * _Nonnull failedDevIds){
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

把设备保存到未分区里

如果暂时无需将设备分区,可以先将设备分配到未分区中。

接口说明

+ (void)addDeviceToUnassignedZone:(NSArray<NSString *> *)devIds
                        projectId:(long long)projectId
                          success:(nullable TYSuccessID)success
                          failure:(nullable TYFailureError)failure;

参数说明

参数 说明
devIds 设备ID数组
projectId 项目ID
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area addDeviceToUnassignedZone:@[id] projectId:projectId success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

查询区域设备分类信息

从云端查询区域设备分类信息,用于查询设备列表时进行筛选。

接口说明

- (void)fetchSummaryWithSuccess:(nullable void (^)(NSArray<TuyaLightingDeviceSummaryModel *> *summaryList))success
                        failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objc:

[self.area fetchSummaryWithSuccess:@[id] projectId:projectId success:^(NSArray<TuyaLightingDeviceSummaryModel *> * _Nonnull summaryList) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

更新区域设备分类信息

接口说明

- (void)updateSummaryWithSuccess:(nullable TYSuccessList)success
                         failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objc:

[self.area updateSummaryWithSuccess:^(NSArray *list) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

本地转移设备时将设备加入到区域

该接口只是将设备加入区域,设备并未进入群组。

接口说明

- (void)addLocalMeshWithDeviceIds:(NSArray<NSString *> *)devIds
                          success:(nullable TYSuccessHandler)success
                          failure:(nullable TYFailureError)failure;

参数说明

参数 说明
devIds 设备ID数组
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area addLocalMeshWithDeviceIds@[devId] success:^(void) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

查询当前区域下的设备列表

接口说明

支持分页

- (void)getDeviceListWithOffsetKey:(NSString *)offsetKey
                               tag:(NSString *)tag
                           success:(nullable void(^)(NSArray<TuyaSmartDeviceModel *> *devices, NSString *nextOffsetKey, BOOL end))success
                           failure:(nullable TYFailureError)failure;

参数说明

参数 说明
offsetKey 分页页码
tag 设备分类
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area getDeviceListWithOffsetKey:@"1" tag:@"summary" success:^(NSArray<TuyaSmartDeviceModel *> *devices, NSString *nextOffsetKey, BOOL end) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

查询本地直连的蓝牙设备

接口说明

- (void)fetchLocalMeshDeviceListWithDevIds:(NSArray<NSString *> *)devIds
                                   success:(nullable void(^)(NSArray<TuyaSmartDeviceAssignedModel *> *array))success
                                   failure:(nullable TYFailureError)failure;

参数说明

参数 说明
devIds 设备ID数组
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area fetchLocalMeshDeviceListWithDevIds:@[devId] success:^(NSArray<TuyaSmartDeviceAssignedModel *> *array) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

区域群控

区域群控是指对该区域下的设备进行总控的一种功能,目前支持的空间总控功能为开关、亮度、模式、色温等。TuyaLightingArea 类的以下属性可以查询当前区域的状态。

TuyaLightingArea 数据模型

字段 类型 描述
dps NSDictionary 功能点数据
switchStatus BOOL 开关状态
sceneStatus NSString 场景模式,包含以下三种:
  • TUYA_LIGHTING_SCENE_WORK(工作)
  • TUYA_LIGHTING_SCENE_MEETING(会议)
  • TUYA_LIGHTING_SCENE_SIESTA(午休)
  • TUYA_LIGHTING_SCENE_OFF_DUTY(下班)
workModel NSString 工作模式
  • TUYA_LIGHTING_MODE_WHITE(白光),TUYA_LIGHTING_MODE_COLOUR(彩光)
  • TUYA_LIGHTING_MODE_SCENE(场景)
brightPercent NSInteger 当前亮度,范围0到100
temperaturePercent NSInteger 当前色温,范围0到100
colorData NSString 彩光,该操作仅在区域处在彩光模式下有效,返回值为12位的组合数据,组合的规则为hhhhssssvvvv,其中hhhh表示16进制后的色调值,ssss表示16进制后的饱和度值,vvvv表示16进制后的亮度值,可使用TuyaLightingColorUtil的decodeNewHsvWithHsvString方法将colorData解码成hsv的值。

区域 DP 命令下发

接口说明

- (void)publishDps:(NSDictionary *)dps
           success:(nullable TYSuccessHandler)success
           failure:(nullable TYFailureError)failure;

参数说明

参数 说明
dps 区域dp点集合
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area publishDps:@{@"1" : @"1"} success:^(void) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置区域快捷开关

接口说明

- (void)publishSwitchStauts:(BOOL)switchValue
                    success:(nullable TYSuccessID)success
                    failure:(nullable TYFailureError)failure;

参数说明

参数 说明
switchStatus 开关状态
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area publishSwitchStatus:YES success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置场景模式

接口说明

该操作仅在区域处在场景模式下有效。

- (void)publishSceneStatus:(NSString *)sceneId
                   success:(nullable TYSuccessID)success
                   failure:(nullable TYFailureError)failure;

参数说明

参数 说明
sceneId 场景ID,包含以下三种 TUYA_LIGHTING_SCENE_WORK(工作), TUYA_LIGHTING_SCENE_MEETING(会议), TUYA_LIGHTING_SCENE_SIESTA(午休), TUYA_LIGHTING_SCENE_OFF_DUTY(下班)
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area publishSceneStatus:TUYA_LIGHTING_SCENE_WORK success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置工作模式

接口说明

- (void)publishWorkMode:(NSString *)workMode
                success:(nullable TYSuccessID)success
                failure:(nullable TYFailureError)failure;

参数说明

参数 说明
workMode 工作模式,在TUYA_LIGHTING_MODE_WHITE(白光),TUYA_LIGHTING_MODE_COLOUR(彩光),TUYA_LIGHTING_MODE_SCENE(场景)中选一个
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area publishWorkMode:TUYA_LIGHTING_MODE_WHITE success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置亮度

接口说明

该操作仅在区域处在白光模式下有效

- (void)publishBrightPercent:(NSInteger)brightPercent
                     success:(nullable TYSuccessID)success
                     failure:(nullable TYFailureError)failure;

参数说明

参数 说明
brightPercent 亮度,范围0到100
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area publishBrightPercent:100 success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置色温

接口说明

该操作仅在区域处在白光模式下有效

- (void)publishTemperaturePercent:(NSInteger)temperaturePercent
                          success:(nullable TYSuccessID)success
                          failure:(nullable TYFailureError)failure;

参数说明

参数 说明
TemperaturePercent 色温,范围0到100
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area publishTemperaturePercent:100 success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置亮度和色温

接口说明

该操作仅在区域处在白光模式下有效

- (void)publishBrightPercent:(NSInteger)brightPercent
          temperaturePercent:(NSInteger)temperaturePercent
                     success:(nullable TYSuccessID)success
                     failure:(nullable TYFailureError)failure;

参数说明

参数 说明
brightPercent 亮度,范围0到100
temperaturePercent 色温,范围0到100
success 成功回调
failure 失败回调

示例代码

Objc:

[self.area publishBrightPercent:100 temperaturePercent:100 success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置彩光

接口说明

该操作仅在区域处在彩光模式下有效,colors为hsv编码后的字符串,可使用TuyaLightingAreaHelper的encodeNewHsvWithHue:saturation:brightness:方法将hsv值编码成colorData。

待定

- (void)publishColors:(NSString *)colors
              success:(nullable TYSuccessID)success
              failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objc:

[self.area publishColors:@"" success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];