Tuya.com
简体中文
English
注册
登录 IoT 平台
简体中文
English
注册
登录 IoT 平台

IoT App SDK

search
根据文档目录筛选
IoT App SDK商用照明 App SDKiOS 开发指南区域管理

区域管理

更新时间：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");
}];
上一篇项目管理
下一篇群组管理
语言
简体中文
简体中文
English
400-881-8611
7×24小时服务热线
市场合作
marketing@tuya.com
业务合作
service@tuya.com
媒体联络
pr@tuya.com
关注“涂鸦智能”
涂鸦服务尽在掌握
关注“全球智能商业”
第一时间获取物联网资讯
联系我们加入我们Tuya ExpoApp 商城涂鸦智选智选服务商查询
法律声明隐私协议加州隐私权利声明服务条款廉正合规安全应急响应中心
©2014-2023 杭州涂鸦信息技术有限公司 版权
浙ICP备14011795号
浙B2-20210233号
浙公网安备33010602004238号
简体中文
简体中文
English