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.
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");
}];
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");
}];
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");
}];
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");
}];
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");
}];
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");
}];
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");
}];
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");
}];
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");
}];
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");
}];
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");
}];
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");
}];
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");
}];
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");
}];
API description
Procedure:
- (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");
}];
Procedure:
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");
}];
Procedure:
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");
}];
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");
}];
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");
}];
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");
}];
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");
}];
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");
}];
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:
|
workModel | NSString | The working mode.
|
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. |
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");
}];
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");
}];
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:
|
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");
}];
API description
- (void)publishWorkMode:(NSString *)workMode
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Parameters
Parameter | Description |
---|---|
workMode | The working mode. Valid values:
|
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");
}];
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");
}];
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");
}];
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");
}];
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");
}];
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedback