Area Management

Last Updated on : 2024-03-28 10:26:10download

ThingLightingArea 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 <ThingLightingAreaModel *> *areas, NSInteger totalRoomDeviceCount))success
                                    failure:(nullable ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

ThingLightingProject *project = [ThingLightingProject projectWithProjectId:currentProjectId];
[project getAreaLevelsWithNeedUnassignedArea:YES
                              needPublicArea:YES
                                     success:^(NSArray <ThingLightingAreaModel *> *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 <ThingLightingAreaModel *> *areas))success
                       failure:(nullable ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

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

Create a sub-area (for indoor project and parking lot project)

Creates a sub-area in an indoor project and parking lot project.

API description

+ (void)createAreaWithProjectId:(long long)projectId
                  currentAreaId:(long long)currentAreaId
                           name:(NSString *)name
                      roomLevel:(NSInteger)roomLevel
                        success:(nullable ThingSuccessID)success
                        failure:(nullable ThingFailureError)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 `ThingLightingProjectManager` to get the value. This parameter is required.
success	The success callback. Optional.
failure	The failure callback. Optional.

Sample code

Objective-C:

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

Create a sub-area (for outdoor project)

Creates a sub-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 ThingSuccessID)success
                        failure:(nullable ThingFailureError)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 `ThingLightingProjectManager` 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. Optional.
failure	The failure callback. Optional.

Sample code

Objective-C:

[ThingLightingAreaManager createAreaWithProjectId:123
                                   currentAreaId:456
                                            name:@"area name"
                                       roomLevel:1
                                       longitude:-1
                                        latitude:-1
                                         address:@""
                                         success:^(id result) {
        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 <ThingLightingAreaModel *> *areas))success
                          failure:(ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

[self.area getSubAreaListWithSuccess:^(NSArray<ThingLightingAreaModel *> * _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(^)(ThingLightingAreaModel *))success
                       failure:(nullable ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

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

Get a relation ID (gid) of an area

API description

@property (nonatomic, assign) long long gId;

Sample code

Objective-C:

    ThingLightingArea *area = [ThingLightingArea areaWithAreaId:0 projectId:0];
    long long gid = area.areaModel.gId;

Query details of the parent area for the current area

API description

- (void)getParentAreaWithSuccess:(nullable void(^)(ThingLightingAreaModel * _Nullable parentAreaModel))success
                         failure:(nullable ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

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

Modify an indoor area

API description

- (void)updateAreaInfoWithName:(NSString *)name
                       success:(nullable ThingSuccessHandler)success
                       failure:(nullable ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

[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 ThingSuccessHandler)success
                       failure:(nullable ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

[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:(ThingSuccessHandler)success
                  failure:(ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

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

Add devices to an area

API description

Procedure:

First, filter local devices that are connected without gateways if any.
1. Remove the devices from the original group.
2. Add the devices to the target area.
3. 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 ThingFailureError)failure;

Parameters

Parameter	Description
devIds	The list of target device IDs.

success	The success callback.
failure	The failure callback.

Sample code

Objective-C:

[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, filter local devices that are connected without gateways if any.
1. Remove the devices from the original group.
2. Add the removed devices to the target area.
3. 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 ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

[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, filter local devices that are connected without gateways if any, and remove them from original groups.
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 ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

[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 ThingSuccessID)success
                          failure:(nullable ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

[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<ThingLightingDeviceSummaryModel *> *summaryList))success
                        failure:(nullable ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

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

Update details of device assignment in an area

API description

- (void)updateSummaryWithSuccess:(nullable ThingSuccessList)success
                         failure:(nullable ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

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

Locally add devices to an area

Adds devices to an area, rather than a group, when these devices are locally transferred.

API description

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

Parameters

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

Sample code

Objective-C:

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

Query a list of devices in the current area

API description

Returns a list of devices in the current area on pages.

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

Parameters

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

Sample code

Objective-C:

[self.area getDeviceListWithOffsetKey:@"1" tag:@"summary" success:^(NSArray<ThingSmartDeviceModel *> *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<ThingSmartDeviceAssignedModel *> *array))success
                                   failure:(nullable ThingFailureError)failure;

Parameters

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

Sample code

Objective-C:

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

Prev DocProject Management

Next DocArea Control