Lock Management

Last Updated on : 2024-11-22 02:19:32download

This topic describes how to manage a lock.

Connect to a Bluetooth lock

API description

- (void)startListening:(BOOL)clearCache;

Parameters

Parameter	Description
clearCache	Specifies whether to clear the cache.

Example

This method scans for nearby paired devices and establishes a connection.

- (void)scanAndConnectAllDevices {

    NSPredicate *pre = [NSPredicate predicateWithBlock:^BOOL(ThingSmartDeviceModel * _Nullable evaluatedObject, NSDictionary<NSString *,id> * _Nullable bindings) {
        return evaluatedObject.deviceType == ThingSmartDeviceModelTypeBle;
    }];

    NSMutableArray *deviceList = [NSMutableArray array];
    for (NSString *devId in self.dataArray) {
        ThingSmartDeviceModel *deviceModel = [ThingSmartDevice deviceWithDeviceId:devId].deviceModel;
        [deviceList addObject:deviceModel];
    }

    BOOL needScan = [deviceList filteredArrayUsingPredicate:pre].count;
    if (needScan) {
        self.centralManager = [[CBCentralManager alloc] initWithDelegate:self queue:nil];
    }
}

Subscribe to notifications of device status updates.

[NSNotificationCenter.defaultCenter addObserver:self
                                       selector:@selector(updateDeviceState:)
                                           name:@"kNotificationDeviceOnlineUpdate"
                                         object:nil];

Update the device online status in the callback.

- (void)updateDeviceState:(NSNotification *)not {
    ThingSmartDeviceModel *device = [ThingSmartDevice deviceWithDeviceId:self.devId].deviceModel;
    self.isOnline.text = device.isOnline ? @"Online" : @"Offline";
}

Or connect to a specific Bluetooth lock.

ThingDeviceConnectParams *params = [[ThingDeviceConnectParams alloc] init];
params.sourceType = ThingDeviceConnectSourceTypeNormal;
params.connectType = ThingDeviceConnectTypeNormal;
params.connectTimeoutMills = 10000;
[device connectDeviceWithParams:params success:^{

} failure:^(NSError *error) {
    NSLog(@"%@", error);
}];

Device status changes will be notified through kNotificationDeviceOnlineUpdate.

Lock capability and status

/// Whether the lock has been unlocked
@property (nonatomic, assign, readonly) BOOL isUnlocked;

/// Whether the lock is automatic lock
@property (nonatomic, assign, readonly) BOOL isAutomaticLock;

/// Whether automatic locking is supported
@property (nonatomic, assign, readonly) BOOL isSupportAutomaticLock;

/// Whether manual locking is supported
@property (nonatomic, assign, readonly) BOOL isSupportManualLock;

/// Double locking state
@property (nonatomic, assign, readonly) ThingLockReverseLockState reverseLockState;

/// Door state
@property (nonatomic, assign, readonly) ThingLockDoorState doorState;

isUnlocked: Whether the door is unlocked.
isAutomaticLock: Whether auto-locking is enabled.
isSupportAutomaticLock: Whether the lock supports auto-locking.
isSupportManualLock: Whether the lock supports manual locking.
reverseLockState: The double locking status.
doorState: The door status. For example, if the lock is unlocked but the door has not been pushed open, the door is considered closed.

Get the list of added locks

API description

+ (void)getLockDeviceListWithSiteId:(long long)siteId
                           pageSize:(NSInteger)pageSize
                            startId:(NSInteger)startId
                            success:(ThingLockDeviceListSuccess)success
                            failure:(ThingFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
pageSize	The number of items returned per page.
startId	The pagination cursor. Pass `0` for the first request. On subsequent requests, its value is the `lastId` returned in the previous response.
success	The success callback.
failure	The failure callback.

Example

Save the lastIndex from the result of the previous page and use it as the request parameter for the next page.

[ThingResidenceSiteManager getLockDeviceListWithSiteId:siteId
                                              pageSize:20
                                               startId:self.lastIndex
                                               success:^(NSArray<NSString *> * _Nullable deviceIdList, NSInteger lastIndex) {
    self.lastIndex = lastIndex;
} failure:^(NSError *error) {

}];

Get lock details

API description

This method returns the additional fields for the lock. You can get the basic information about the lock through [ThingSmartDevice deviceWithDeviceId:self.devId].deviceModel.

+ (void)getLockDetailWithSiteId:(long long)siteId
                        deviceId:(NSString *)deviceId
                         success:(ThingLockDetailSuccess)success
                         failure:(ThingFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
deviceId	The device ID.
success	The success callback.
failure	The failure callback.

Example

[ThingLockDevice getLockDetailWithSiteId:siteId
                                deviceId:self.devId
                                 success:^(ThingLockDeviceModel * _Nullable lockModel) {

} failure:^(NSError *error) {

}];

Fields in ThingLockDeviceModel

Field	Description
deviceId	The device ID of the lock.
deviceName	The device name of the lock.
gatewayId	The device ID of the gateway connected to the lock. The value is null if there is no gateway.
gatewayName	The device name of the gateway connected to the lock. The value is null if there is no gateway.
deviceType	The type of the lock. `single-ble`: A Bluetooth Low Energy (LE) lock, with no gateway connected. `gateway-device`: A lock connected to a gateway.
electricQuantity	The lock’s battery level.
deviceRole	The role of the current user. `owner`: Device owner `admin`: Device admin `member`: Common user
supportAbilities	The capabilities supported by the lock, including: `e-key`: E-key `offline-passcode`: Offline password `temporary-passcode`: Online password `card`: Card `fingerprint`: Fingerprint `admin`: Admin `log`: Device logs `remote-unlock`: Remote unlocking `setting`: Settings `remote-close`: Remote locking
livecycleType	Password validity `permanent`: Permanent `periodicity`: Time-limited `once`: One-time
timeScheduleInfo	The device time setting.
eKeyId	The ID of the e-key.
isSupportOta	Whether OTA updates are supported.
timeZoneId	The time zone of the device.
account	The account associated with the device.

Unlock a door

API description

The device must be online. Otherwise, unlocking will fail.

- (void)unLockWithSiteId:(long long)siteId
                deviceId:(NSString *)deviceId
                 success:(ThingSuccessHandler)success
                 failure:(ThingFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
deviceId	The device ID.
success	The success callback.
failure	The failure callback.

Example

See Connect to a lock for device connection.

[ThingLockManager.shared unLockWithSiteId:SiteManager.shared.siteId
                                deviceId:self.devId
                                 success:^{

} failure:^(NSError *error) {

}];

Lock a door

API description

The device must be online. Otherwise, locking will fail.

- (void)lockWithSiteId:(long long)siteId
              deviceId:(NSString *)deviceId
               success:(ThingSuccessHandler)success
               failure:(ThingFailureError)failure;

Parameters

Parameter	Description
siteId	The site ID.
deviceId	The device ID.
success	The success callback.
failure	The failure callback.

Example

See Connect to a lock for device connection.

[ThingLockManager.shared lockWithSiteId:SiteManager.shared.siteId
                               deviceId:self.devId
                                success:^{

} failure:^(NSError *error) {

}];

The execution of manual locking depends on several factors, such as DP configuration, double locking status, door status, and auto-locking status.
Before calling the lock method, checking manual locking support with isSupportManualLock is recommended. A response of YES indicates support.

Rename a lock

API description

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

Parameters

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

Example

ThingSmartDevice *device = [ThingSmartDevice deviceWithDeviceId:self.devId];
[device updateName:@""
           success:^{

} failure:^(NSError *error) {

}];

Delete a lock

API description

+ (void)deleteWithDeviceId:(NSString *)devId
                 success:(ThingSuccessHandler)success
                 failure:(ThingFailureError)failure;

Parameters

Parameter	Description
devId	The device ID.
success	The success callback.
failure	The failure callback.

Example

[ThingLockDevice deleteWithDeviceId:self.devId success:^{
    [MBProgressHUD hideHUDForView:self.view animated:YES];
    [self.navigationController popViewControllerAnimated:YES];
    [NSNotificationCenter.defaultCenter postNotificationName:@"UpateDeviceList" object:nil];
} failure:^(NSError *error) {
    [MBProgressHUD hideHUDForView:self.view animated:YES];
    [Alert showBasicAlertOnVC:self withTitle:@(error.code).errorText message:@""];
}];

Force delete a lock

Unlike the regular lock deletion method, this method does not check if the lock is online before deleting it.

API description

+ (void)forceDeleteWithDeviceId:(NSString *)devId
                        success:(ThingSuccessHandler)success
                        failure:(ThingFailureError)failure;

Parameters

Parameter	Description
devId	The device ID.
success	The success callback.
failure	The failure callback.

Example

[ThingLockDevice forceDeleteWithDeviceId:self.devId success:^{

} failure:^(NSError *error) {

}];

If a device malfunctions or fails to connect, you can use this method to remove it.
Calling this method while the device is offline will not delete any data that has already been written. Manually reset the device when needed to activate pairing mode.

Set auto-locking on/off

API description

- (void)setAutoLockSwitchWithDeviceId:(NSString *)deviceId
                              success:(ThingSuccessHandler)success
                              failure:(ThingFailureError)failure;

Parameters

Parameter	Description
devId	The device ID.
success	The success callback.
failure	The failure callback.

Example

[ThingLockManager.shared setAutoLockSwitchWithDeviceId:self.devId success:^{

} failure:^(NSError *error) {

}];

Check support for auto-locking

API description

@property (nonatomic, assign, readonly) BOOL isSupportAutomaticLock;

Parameters

Parameter	Description
Return value	Whether the device supports auto-locking. `YES`: Support `NO`: Not support

Example

    self.automaticLockCell.userInteractionEnabled = deviceModel.isSupportAutomaticLock

Listen for DP changes

Set a delegate to listen for changes in device DPs.

    self.lockDevice = [ThingSmartDevice deviceWithDeviceId:self.devId];
    self.lockDevice.delegate = self;

Process data in the callback, such as locking/unlocking and double locking changes.

- (void)device:(ThingSmartDevice *)device dpsUpdate:(NSDictionary *)dps {
    NSLog(@"%s dps ==> %@", __func__, dps);
    [self updateDeviceStatus];
}