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:

  1. 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.
  2. 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:

  1. 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.
  2. 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:

  1. First, remove local devices that are connected without gateways if any:
    • Remove the devices from the original group.
  2. 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");
}];