IoT App SDKCommercial Lighting App SDKiOS PlatformArea Management

Area Management

Last Updated on : 2022-02-17 05:22:13download

You can use the TuyaLightingProject+TYArea class to get a list of areas for a project, use the management class TuyaLightingAreaManager to create an area, and then initialize the area class TuyaLightingArea to get information about an area and control devices in the area.

TuyaLightingArea defines the properties and methods for a specific area. For example, control groups in the area and assign devices.

Query all areas in a project

Returns a hierarchy of areas in a project.

API description

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

Parameters

Parameter	Description
needUnassignedArea	Indicates whether the unassigned area is returned.
needPublicArea	Indicates whether the public area is returned.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Query level-1 areas in a project

Returns level-1 areas in a project.

API description

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

Parameters

Parameter	Description
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Create an indoor area

Creates an area in an indoor project.

API description

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

Parameters

Parameter	Description
projectId	The project ID. This parameter is required.
currentAreaId	The ID of the current area. If the area ID is not necessary for you, set the value to the parent area ID of the new area. This parameter is required.
name	The name of the area. This parameter is required.
roomLevel	The level of the area. You can call the API method `getSpaceAttributesWithProjectId` of the class `TuyaLightingProjectManager` to get the value. This parameter is required.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Create an outdoor area

Creates an area in an outdoor project.

API description

Different from the API method for creating an indoor area, this API method can be used to store the geographical location of an area.

+ (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;

Parameters

Parameter	Description
projectId	The project ID. This parameter is required.
currentAreaId	The ID of the current area. If the area ID is not necessary for you, set the value to the parent area ID of the new area. This parameter is required.
name	The name of the area. This parameter is required.
roomLevel	The level of the area. You can call the API method `getSpaceAttributesWithProjectId` of the class `TuyaLightingProjectManager` to get the value. This parameter is required.
longitude	The longitude of the area. This parameter is optional.
latitude	The latitude of the area. This parameter is optional.
address	The address of the area. This parameter is optional.
success	The success callback.
failure	The failure callback.

Example

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");
    }];

Create a sub-area (indoor area)

Creates a sub-area in the current area. For example, a floor can be regarded as a sub-area of a building.

API description

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

Parameters

Parameter	Description
subAreaName	The name of the sub-area. This parameter is required.
success	The success callback with `areaModel` for the sub-area returned. This parameter is optional.
failure	The failure callback.

Example

ObjC:

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

Create a sub-area (outdoor area)

Creates a sub-area in the current area. For example, the West Lake district can be regarded as a sub-area of Hangzhou, China.

API description

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

Parameters

Parameter	Description
subAreaName	The name of the sub-area. This parameter is required.
longitude	The longitude of the area. This parameter is optional.
latitude	The latitude of the area. This parameter is optional.
address	The address of the sub-area. This parameter is optional.
success	The success callback with `areaModel` for the sub-area returned. This parameter is optional.
failure	The failure callback.

Example

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");
                       }];

Create a parent area (indoor area)

Creates a parent area for the current area. For example, a building can be regarded as the parent area of a floor.

API description

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

Parameters

Parameter	Description
parentAreaName	The name of the parent area. This parameter is required.
success	The success callback with `areaModel` for the parent area returned. This parameter is optional.
failure	The failure callback.

Example

ObjC:

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

Create a parent area (outdoor area)

Creates a parent area for the current area. For example, Hangzhou, China can be regarded as the parent area of the West Lake district.

API description

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

Parameters

Parameter	Description
parentAreaName	The name of the parent area. This parameter is required.
longitude	The longitude of the area. This parameter is optional.
latitude	The latitude of the area. This parameter is optional.
address	The address of the parent area. This parameter is optional.
success	The success callback with `areaModel` for the parent area returned. This parameter is optional.
failure	The failure callback.

Example

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");
                          }];

Query a list of sub-areas in the current area

Returns a list of sub-areas from the cloud. Details of groups in the sub-areas are also returned.

API description

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

Parameters

Parameter	Description
success	The success callback with the list of sub-areas returned.
failure	The failure callback.

Example

ObjC:

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

Query details of an area including sub-areas

Returns details of the current area from the cloud. A list of sub-areas is also returned.

API description

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

Parameters

Parameter	Description
success	The success callback with `areaModel` for the current area returned.
failure	The failure callback.

Example

ObjC:

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

Query details of the parent area for the current area

API description

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

Parameters

Parameter	Description
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Modify an indoor area

API description

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

Parameters

Parameter	Description
name	The name of the area.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Modify an outdoor area

API description

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

Parameters

Parameter	Description
name	The name of the area.
longitude	The longitude of the device.
latitude	The latitude of the device.
address	The address of the area.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Delete an area

API description

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

Parameters

Parameter	Description
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Add devices to an area

API description

Procedure:

First, remove local devices that are connected without gateways if any:
- Remove the devices from the original group.
- Add the devices to the target area.
- Add the devices to a local group in the area.
Request the cloud to assign other available devices to the area.

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

Parameters

Parameter	Description
devIds	The list of target device IDs.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Add ungrouped devices to a group

Procedure:

First, remove local devices that are connected without gateways if any:
- Remove the devices from the original group.
- Add the removed devices to the target area.
- Add the devices to a local group in the area.
Request the cloud to assign other available devices to the area.

API description

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

Parameters

Parameter	Description
devIds	The array of device IDs.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Remove devices from the current area

Procedure:

First, remove local devices that are connected without gateways if any:
- Remove the devices from the original group.
Add the devices to the unassigned area.

API description

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

Parameters

Parameter	Description
devIds	The array of device IDs.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Add devices to the unassigned area

Adds devices to the unassigned area if these devices are not required to be assigned.

API description

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

Parameters

Parameter	Description
devIds	The array of device IDs.
projectId	The project ID.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Query details of device assignment in an area

Returns the details of device assignment in an area from the cloud. This provides the criteria to query the device list.

API description

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

Parameters

Parameter	Description
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Update details of device assignment in an area

API description

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

Parameters

Parameter	Description
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Query a list of devices in the current area

API description

Pagination is supported.

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

Parameters

Parameter	Description
offsetKey	The current page number.
tag	The device category.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Query local Bluetooth devices connected without gateways

API description

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

Parameters

Parameter	Description
devIds	The array of device IDs.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Control groups in an area

Centrally controls devices in an area. Currently, device features such as switches, brightness, modes, and color temperature can be controlled. TuyaLightingArea provides the following properties to indicate the status in an area.

Data model of TuyaLightingArea

Field	Data type	Description
dps	NSDictionary	The data points (DPs) of a device.
switchStatus	BOOL	The switch status.
sceneStatus	NSString	The scene status. Valid values: TUYA_LIGHTING_SCENE_WORK (working) TUYA_LIGHTING_SCENE_MEETING (meeting) TUYA_LIGHTING_SCENE_SIESTA (siesta) TUYA_LIGHTING_SCENE_OFF_DUTY (off duty)
workModel	NSString	The working mode. TUYA_LIGHTING_MODE_WHITE (white light), TUYA_LIGHTING_MODE_COLOUR (colored light) TUYA_LIGHTING_MODE_SCENE (scene)
brightPercent	NSInteger	The brightness percentage. Valid values: `0` to `100`.
temperaturePercent	NSInteger	The color temperature percentage. Valid values: `0` to `100`.
colorData	NSString	The data of the colored mode. This property takes effect only in colored mode. The response returns a 12-digit value in the format of `hhhhssssvvvv`. In the response, `hhhh` indicates the hexadecimal hue value, `ssss` indicates the hexadecimal saturation value, and `vvvv` indicates the hexadecimal brightness value. `TuyaLightingColorUtil` provides the method `decodeNewHsvWithHsvString` to decode `colorData` into the HSV color model.

Send DPs to an area

API description

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

Parameters

Parameter	Description
dps	The collection of DPs in an area.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Set a shortcut switch in an area

API description

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

Parameters

Parameter	Description
switchStatus	The switch status.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Set a scene mode

API description

This API method takes effect only when the target area stays in scene mode.

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

Parameters

Parameter	Description
sceneId	The scene ID. Valid values: TUYA_LIGHTING_SCENE_WORK (working) TUYA_LIGHTING_SCENE_MEETING (meeting) TUYA_LIGHTING_SCENE_SIESTA (siesta) TUYA_LIGHTING_SCENE_OFF_DUTY (off duty)
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Set the working mode

API description

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

Parameters

Parameter	Description
workMode	The working mode. Valid values: `MODE_WHITE` (white light) `MODE_COLOUR` (colored light) `MODE_SCENE` (scene mode)
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Set brightness

API description

This API method takes effect only when the target area stays in white light mode.

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

Parameters

Parameter	Description
brightPercent	The brightness percentage. Valid values: `0` to `100`.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Set color temperature

API description

This API method takes effect only when the target area stays in white light mode.

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

Parameters

Parameter	Description
TemperaturePercent	The color temperature percentage. Valid values: `0` to `100`.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Set brightness and color temperature

API description

This API method takes effect only when the target area stays in white light mode.

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

Parameters

Parameter	Description
brightPercent	The brightness percentage. Valid values: `0` to `100`.
temperaturePercent	The color temperature percentage. Valid values: `0` to `100`.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Set colored light

API description

This API method takes effect only when the target area stays in colored mode. colors indicates the result string of HSV encoding. TuyaLightingAreaHelper provides the method encodeNewHsvWithHue:saturation:brightness: to encode an HSV value into colorData.

Example

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

Parameters

Parameter	Description
colors	The data of colored light.
success	The success callback.
failure	The failure callback.

Example

ObjC:

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

Prev DocProject Management

Next DocGroup Management