Smart App SDKSmart Life App SDKSmart Lock SDKDevelopment Guide for iOSWi-Fi Lock

Wi-Fi Lock

Last Updated on : 2024-04-26 07:55:48download

This topic describes the features of Wi-Fi door locks.

Terms

Term	Explanation
Duress alarm	The duress alarm feature allows the user to enroll a password or fingerprint as a duress code. If the user is coerced by hostile persons, unlocking with the duress code can trigger alert messages to be sent to a list of contacts.
Lock member	Lock members are classified into home members and non-home members. Home members are specific to a smart home. A lock password ID can be associated with a home member. Non-home members are specific to a lock. They can be created and assigned to a lock password ID to establish an association.
dpCode	An identifier of a data point (DP) for a device. Each DP is assigned a name and ID. For more information, see the List of Door Lock DPs.

Classes

Class name	Description
`ThingSmartLockDevice`	Wi-Fi lock operation class, inherited from `ThingSmartDevice`.
`ThingSmartLockDeviceDelegate`	Wi-Fi lock protocol delegate, extended from `ThingSmartDeviceDelegate`.

Lock members

Lock members are classified into home members and non-home members. Home members are specified in a smart home. For more information, see Home Management.

This section describes the operations regarding non-home members.

Query the list of lock members

API description

- (void)getLockMemberListWithSuccess:(nullable void(^)(NSArray<ThingSmartLockMemberModel *> *lockMemberModels))success
                             failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
success	The success callback. The list of lock members is returned.
failure	The failure callback.

Data model of ThingSmartLockMemberModel

Field	Type	Description
userId	NSString	The member ID.
userName	NSString	The nickname of the user.
avatarUrl	NSString	The URL of the avatar.
contact	NSString	The contact method.
unlockRelations	NSArray<ThingSmartLockRelationModel *>	The mapping between an unlocking method and the user ID.
devId	NSString	The device ID.
ownerId	NSString	The home ID.
userType	NS_ENUM	The type of the lock member. `1`: Home member `2`: Non-home member

Example

Objective-C:

    ThingSmartLockDevice *lock = [ThingSmartLockDevice deviceWithDeviceId:@"your_lock_device_id"];
    [lock getLockMemberListWithSuccess:^(id result) {
        NSLog(@"result %@", result);
    } failure:^(NSError *error) {
        NSLog(@"error %@", error);
    }];

Swift:

    let lockDevice = ThingSmartLockDevice(deviceId: "your_lock_device_id")
    lockDevice?.getLockMemberList(success: { (members) in
        print("List of lock members \(members)")
    }, failure: { (error) in
        if let e = error {
           print("error \(e)")
        }
    })

Create a lock member

Creates a non-home member to be associated with an unlocking record in later operations.

API description

- (void)addLockNormalUserWithUserName:(NSString *)userName
                          avatarImage:(nullable UIImage *)avatarImage
                      unlockRelations:(nullable NSArray<ThingSmartLockRelationModel *> *)unlockRelations
                              success:(nullable ThingSuccessString)success
                              failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
userName	The name of the member.
avatarImage	The avatar of the member. If it is not set, the default avatar is used.
unlockRelations	The mapping between the unlocking method and the password serial number.
success	The success callback. The member ID of string type is returned.
failure	The failure callback.

Data model of ThingSmartLockRelationModel

Field	Type	Description
unlockType	TYLockUnlockType	Unlocking methods
sn	NSInteger	The associated password serial number. Valid values: 0 to 999.

typedef NS_ENUM(NSUInteger, TYLockUnlockType) {
    TYLockUnlockTypeFingerprint, // Unlock with a fingerprint
    TYLockUnlockTypePassword,    // Unlock with a password
    TYLockUnlockTypeTemporary,   // Unlock with a temporary password
    TYLockUnlockTypeDynamic,     // Unlock with a dynamic password
    TYLockUnlockTypeCard,        // Unlock with a card
    TYLockUnlockTypeFace,        // Unlock with biometric recognition
    TYLockUnlockTypeKey,         // Unlock with a mechanical key
};

Example

Objective-C:

    ThingSmartLockRelationModel *fingerModel = [[ThingSmartLockRelationModel alloc] init];
    fingerModel.unlockType = TYLockUnlockTypeFingerprint; // Unlock with fingerprint
    fingerModel.sn = 123;

    ThingSmartLockRelationModel *faceModel = [[ThingSmartLockRelationModel alloc] init];
    faceModel.unlockType = TYLockUnlockTypeFace; // Unlock with face recognition
    faceModel.sn = 23;

    // ThingSmartLockDevice *lock
    // Note: It must be set as a property.
    self.lock = [ThingSmartLockDevice deviceWithDeviceId:@"your_lock_device_id"];
        [self.lock addLockNormalUserWithUserName:@"user name"
                                 avatarImage:[UIImage imageNamed:@"xxx.png"]
                                   unlockIds:@[fingerModel, faceModel]
                                     success:^(NSString *userId) {
        NSLog(@"result %@", userId);
    } failure:^(NSError *error) {
        NSLog(@"error %@", error);
    }];

Swift:

    let finger = ThingSmartLockRelationModel()
    finger.unlockType = .fingerprint // Unlock with fingerprint
    finger.sn = 123

    let face = ThingSmartLockRelationModel()
    face.unlockType = .face // Unlock with face recognition
    face.sn = 23
    // Note: It must be set as a property.
    self.lockDevice = ThingSmartLockDevice(deviceId: "your_lock_device_id")
    self.lockDevice?.addLockNormalUser(withUserName: "user name", avatarImage: UIImage(named: "xxx.png"), unlockIds: [finger, face], success: { (userId) in
        print("User added \(userId)")
    }, failure: { (error) in
        if let e = error {
            print("error \(e)")
        }
    })

Update a lock member

Updates the information about a lock member, including the username, avatar, and mapping with the unlocking password.

API description

- (void)updateLockNormalUserWithUserId:(NSString *)userId
                              userName:(nullable NSString *)userName
                           avatarImage:(nullable UIImage *)avatarImage
                       unlockRelations:(nullable NSArray<ThingSmartLockRelationModel *> *)unlockRelations
                               success:(nullable ThingSuccessBOOL)success
                               failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
userId	The member ID, required.
userName	(Optional) The username of the member. If not specified, no change will be made.
avatarImage	(Optional) The avatar of the member. If not specified, no change will be made.
unlockRelations	(Optional) The mapping between the unlocking method and the password serial number. If not specified, no change will be made.
success	The success callback. The member ID of string type is returned.
failure	The failure callback.

Example

Objective-C:

    ThingSmartLockRelationModel *fingerModel = [[ThingSmartLockRelationModel alloc] init];
    fingerModel.unlockType = TYLockUnlockTypeFingerprint; // Unlock with fingerprint
    fingerModel.sn = 123;

    ThingSmartLockRelationModel *faceModel = [[ThingSmartLockRelationModel alloc] init];
    faceModel.unlockType = TYLockUnlockTypeFace; // Unlock with face recognition
    faceModel.sn = 23;

    // ThingSmartLockDevice *lock
    // Note: It must be set as a property.
    self.lock = [ThingSmartLockDevice deviceWithDeviceId:@"your_lock_device_id"];
    [self.lock updateLockNormalUserWithUserId:@"user id" userName:@"" avatarImage:nil unlockRelations:@[fingerModel,faceModel] success:^(BOOL result) {
        NSLog(@"result %d", result);
    } failure:^(NSError *error) {
        NSLog(@"error %@", error);
    }];

Swift:

    let finger = ThingSmartLockRelationModel()
    finger.unlockType = .fingerprint // Unlock with fingerprint
    finger.sn = 123

    let face = ThingSmartLockRelationModel()
    face.unlockType = .face // Unlock with face recognition
    face.sn = 23
    // Note: It must be set as a property.
    self.lockDevice = ThingSmartLockDevice(deviceId: "your_lock_device_id")
        self.lockDevice?.updateLockNormalUser(withUserId: "user id", userName: "new user name", avatarImage: nil, unlockRelations: [finger, face], success: { (result) in
            print("The update result \(result)")
     }, failure: { (error) in
        if let e = error {
          print("error \(e)")
        }
     })

Delete a lock member

Deletes a lock member. The existing password will not be deleted.

API description

- (void)deleteLockUserWithUserId:(NSString *)userId
                         success:(nullable ThingSuccessBOOL)success
                         failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
userId	The member ID.
success	The success callback. The deletion result of Boolean type is returned.
failure	The failure callback.

Example

Objective-C:

    ThingSmartLockDevice *lock = [ThingSmartLockDevice deviceWithDeviceId:@"your_lock_device_id"];
    [lock deleteLockUserWithUserId:@"0000004zl1" success:^(BOOL result) {
         NSLog(@"The deletion result %d", result);
    } failure:^(NSError *error) {
         NSLog(@"error %@", error);
    }];

Swift:

    let lockDevice = ThingSmartLockDevice(deviceId: "your_lock_device_id")
    lockDevice?.deleteLockUser(withUserId: "0000004zl1", success: { (result) in
        print("The deletion result \(result)")
    }, failure: { (error) in
        if let e = error {
            print("error \(e)")
        }
    })

Temporary password

Creates a temporary password. Users can enter this password to unlock a door.

Get a temporary password

Returns the list of temporary passwords along with the usage status.

API description

- (void)getLockTempPwdListWithSuccess:(nullable void (^)( NSArray<ThingSmartLockTempPwdModel *> *lockTempPwdModels))success
                              failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
success	The success callback. The list of temporary passwords is returned.
failure	The failure callback.

Data model of ThingSmartLockTempPwdModel

Field	Type	Description
phone	NSString	The mobile phone number.
name	NSString	The name of a specified temporary password.
invalidTime	NSTimeInterval	The 10-digit timestamp when the temporary password expires.
effectiveTime	NSTimeInterval	The 10-digit timestamp when the temporary password takes effect.
createTime	NSTimeInterval	The 13-digit timestamp when the temporary password was created.
code	NSInteger	The unique ID of the temporary password.
sn	NSInteger	The serial number of the password, associated with a user account.
phase	TYLockTempPwdStatusType	The status of the temporary password.
effective	TYLockTempPwdEffectiveType	The validity status of the temporary password.

// The password status.
typedef NS_ENUM(NSUInteger, TYLockTempPwdStatusType) {
    TYLockTempPwdStatusTypeRemoved     = 0, // Deleted
    TYLockTempPwdStatusTypeToBeDeleted = 3, // To be deleted

    TYLockTempPwdStatusTypeToBePubilsh = 1, // To be sent
    TYLockTempPwdStatusTypePublished   = 2, // Sent
};

// The validity status of the password.
typedef NS_ENUM(NSUInteger, TYLockTempPwdEffectiveType) {
    TYLockMemberStatusTypeInvalid     = 1, // Expired
    TYLockMemberStatusTypeToBePubilsh = 2, // To be sent
    TYLockMemberStatusTypeWorking     = 3, // In use
    TYLockMemberStatusTypeToBeDeleted = 4, // To be deleted
    TYLockTempPwdEffectiveTypeExpired = 5, // Expired
};

Example

Objective-C:

        ThingSmartLockDevice *lock = [ThingSmartLockDevice deviceWithDeviceId:@"your_lock_device_id"];
        [lock getLockTempPwdListWithSuccess:^(NSArray<ThingSmartLockTempPwdModel *> * _Nullable lockTempPwdModels) {
         NSLog(@"result %@", lockTempPwdModels);
    } failure:^(NSError *error) {
         NSLog(@"error %@", error);
    }];

Swift:

    let lockDevice = ThingSmartLockDevice(deviceId: "your_lock_device_id")
        lockDevice?.getLockTempPwdList(success: { (lockTempPwdModels) in
        print("The result of requesting the list of temporary passwords \(lockTempPwdModels)")
    }, failure: { (error) in
        if let e = error {
            print("error \(e)")
        }
    })

Create a temporary password

Creates a temporary password with a custom start and end date and time. The created password should be synchronized with the lock.

API description

- (void)createLockTempPwd:(NSString *)password
                     name:(NSString *)name
            effectiveDate:(NSDate *)effectiveDate
              invalidDate:(NSDate *)invalidDate
              countryCode:(NSString *)countryCode
                    phone:(NSString *)phone
                  success:(nullable ThingSuccessBOOL)success
                  failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
password	The 7-digit numeric password.
name	The name of the temporary password. The system does not show a hint of the password after it is created. Users must take a note of the password.
effectiveDate	The start date and time.
invalidDate	The end date and time.
countryCode	The country code. Example: 86.
phone	The mobile phone number. After the password is created, a notification will be sent to this mobile phone number.
success	The success callback. The creation result of Boolean type is returned.
failure	The failure callback.

Example

Objective-C:

    ThingSmartLockDevice *lock = [ThingSmartLockDevice deviceWithDeviceId:@"your_lock_device_id"];
    // Create a password valid for 20 minutes.
        NSDate *invalidDate = [NSDate dateWithTimeInterval:60 * 20 sinceDate:[NSDate date]];
    [lock createLockTempPwd:@"1472589"
                       name:@"1472589hkk"
              effectiveDate:[NSDate date]
                invalidDate:invalidDate
                countryCode:@"86"
                      phone:@"13912345678"
                    success:^(BOOL result) {
        NSLog(@"The creation result %d", result);
    } failure:^(NSError *error) {
        NSLog(@"error %@", error);
    }];

Swift:

    let lockDevice = ThingSmartLockDevice(deviceId: "your_lock_device_id")
        lockDevice?.createLockTempPwd("1472589", name: "1472589hkk", effectiveDate: Date(), invalidDate: Date(timeIntervalSince1970: 60 * 20), countryCode: "86", phone: "13912345678", success: { (result) in
        print("The creation result \(result)")
    }, failure: { (error) in
        if let e = error {
           print("error \(e)")
        }
    })

Delete a temporary password

Deletes a temporary password. This operation must be synchronized with the lock.

API description

- (void)deleteLockTempPwdWithPwdId:(NSInteger)tempPwdId
                             force:(BOOL)force
                           success:(nullable ThingSuccessBOOL)success
                           failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
tempPwdId	The unique ID of the temporary password.
force	Specifies whether to force delete the password. `yes`: The password is removed from the list immediately without the lock confirming the operation. `no`: The password remains on the list until the lock confirms the operation.
success	The success callback. The deletion result of Boolean type is returned.
failure	The failure callback.

Example

Objective-C:

    ThingSmartLockDevice *lock = [ThingSmartLockDevice deviceWithDeviceId:@"your_lock_device_id"];
    [lock deleteLockTempPwdWithPwdId:1274067 force:YES success:^(BOOL result) {
        NSLog(@"The deletion result %d", result);
    } failure:^(NSError *error) {
        NSLog(@"error %@", error);
    }];

Swift:

    let lockDevice = ThingSmartLockDevice(deviceId: "your_lock_device_id")
    lockDevice?.deleteLockTempPwd(withPwdId: 1274067, force: true, success: { (result) in
        print("The deletion result \(result)")
    }, failure: { (error) in
        if let e = error {
            print("error \(e)")
        }
    })

Dynamic password

Returns a dynamic password that is valid for five minutes. The user can enter the password to unlock the door.

API description

- (void)getLockDynamicPasswordWithSuccess:(nullable ThingSuccessString)success
                                  failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
success	The success callback. The dynamic password is returned.
failure	The failure callback.

Example

Objective-C:

    ThingSmartLockDevice *lock = [ThingSmartLockDevice deviceWithDeviceId:@"your_lock_device_id"];
    [lock getLockDynamicPasswordWithSuccess:^(NSString *result) {
        NSLog(@"The result of requesting dynamic password %@", result);
    } failure:^(NSError *error) {
        NSLog(@"error %@", error);
    }];

Swift:

    let lockDevice = ThingSmartLockDevice(deviceId: "your_lock_device_id")
    lockDevice?.getLockDynamicPassword(success: { (pwd) in
        print("The result of requesting dynamic password \(pwd)")
    }, failure: { (error) in
        if let e = error {
            print("error \(e)")
        }
    })

Remote unlocking

A visitor initiates a remote unlocking request through the lock. The user can accept or reject the request on the app.

API description

- (void)replyRemoteUnlock:(BOOL)open
                  success:(nullable ThingSuccessHandler)success
                  failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
open	Specifies whether to accept the remote unlocking request. `yes`: Accept. `no`: Reject.
success	The success callback.
failure	The failure callback.

Callback for ThingSmartLockDeviceDelegate

When the delegate is set for ThingSmartLockDevice, after the user accepts the remote unlocking request, the SDK will trigger the callback.

/// After the remote unlock request is received, the lock must process this request within a certain period.
///
/// @param device The lock.
/// @param seconds The remaining time for processing the request.
- (void)device:(ThingSmartLockDevice *)device didReceiveRemoteUnlockRequest:(NSInteger)seconds;

Example

Objective-C:

    // Operate the lock 4+#
      // ThingSmartLockDevice *lock;
    self.lock = [ThingSmartLockDevice deviceWithDeviceId:@"your_lock_device_id"];
    self.lock.delegate = self;

    // Implement the delegate method.
    - (void)device:(ThingSmartLockDevice *)device didReceiveRemoteUnlockRequest:(NSInteger)seconds {
        NSLog(@"A remote unlocking command is received. It should be processed within %d", seconds);

        // second = 0, indicating the command has been processed.
        // Cases:
        if (seconds > 0) {
            BOOL open = YES; // Specifies whether the remote unlocking request is accepted.
            // The result of remote unlocking execution.
            [device replyRemoteUnlock:open success:^{
                NSLog(@"success");
            } failure:^(NSError *error) {
                NSLog(@"error %@", error);
            }];
        }
    }

Swift:

    // Operate the lock 4+#
      // var lock: ThingSmartLockDevice
    self.lock = ThingSmartLockDevice(deviceId: "your_lock_device_id")
    self.lock.delegate = self;

    // Implement the delegate method
    func device(_ device: ThingSmartLockDevice, didReceiveRemoteUnlockRequest seconds: Int) {
        print("A remote unlocking command is received. It should be processed within \(seconds)";
        if seconds > 0 {
            let open = true; // Whether to unlock the door.
            // The result of remote unlocking execution.
            device.replyRemoteUnlock(open, success: {
                print("success")
            }) { (error) in
                if let e = error {
                    print("error: \(e)")
                }
            }
        }
    }

Lock records

Returns the lock records, including unlocking records, doorbell records, and alerts.

Query lock records

API description

- (void)getLockRecordListWithDpCodes:(NSArray<NSString *> *)dpCodes
                              offset:(NSInteger)offset
                               limit:(NSInteger)limit
                             success:(nullable void(^)(NSArray<ThingSmartLockRecordModel *> *lockRecordModels))success
                             failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
dpCodes	The DP code of the record to be queried.
offset	The total number of returned pages.
limit	The total number of returned entries.
success	The success callback. The list of records is returned.
failure	The failure callback.

Data model of ThingSmartLockRecordModel

Field	Type	Description
userId	NSString	The member ID.
userName	NSString	The nickname of the user.
time	NSTimeInterval	The 13-digit timestamp when the record was generated.
devId	NSString	The device ID.
dpData	NSDictionary	The DP data.
tags	NSInteger	The flag. `0`: Others. `1`: Duress alarm.
dpsArray	NSArray<NSDictionary *>	An array of DPs.

Get unlocking records

Returns unlocking records, including unlocking with fingerprint, normal password, temporary password, dynamic password, card, biometric recognition, or mechanical key.

API description

- (void)getUnlockRecordList:(NSInteger)offset
                      limit:(NSInteger)limit
                    success:(nullable void(^)(NSArray<ThingSmartLockRecordModel *> *lockRecordModels))success
                    failure:(nullable ThingFailureError)failure

Parameter description

Parameters	Description
offset	The total number of returned pages.
limit	The total number of returned entries.
success	The success callback. The list of records is returned.
failure	The failure callback.

Duress alarm

Specify a password or fingerprint as a duress code. If the user is coerced by hostile persons, unlocking with the duress code can trigger alarms to be sent to a list of contacts.

Add a duress alarm flag

Adds a duress alarm flag to an unlocking method. The associated password or fingerprint will be specified as a duress code.

API description

- (void)setHijackingConfigWithDevId:(NSString *)devId
                               dpId:(NSString *)dpId
                            dpValue:(NSString *)dpValue
                            success:(ThingSuccessBOOL)success
                            failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
dpId	The DP ID.
dpValue	The DP value.
success	The success callback.
failure	The failure callback.

Remove a duress alarm flag

Removes the duress alarm flag from an unlocking method.

API description

- (void)removeHijackingConfigWithDevId:(NSString *)devId
                                  dpId:(NSString *)dpId
                               dpValue:(NSString *)dpValue
                               success:(ThingSuccessID)success
                               failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
dpId	The DP ID.
dpValue	The DP value.
success	The success callback.
failure	The failure callback.

Query duress alarm records

Returns the duress alarm records based on the specified DP.

API description

- (void)getLockHijackRecordListWithDpCodes:(NSArray<NSString *> *)dpCodes
                                    offset:(NSInteger)offset
                                     limit:(NSInteger)limit
                                   success:(void(^)(NSArray<ThingSmartLockRecordModel *> *))success
                                   failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
dpCodes	The DP code of the unlocking method to be queried.
offset	The total number of returned pages.
limit	The total number of returned entries.
success	The success callback. The list of records is returned.
failure	The failure callback.

Wi-Fi lock DPs

DP name	DP code
Unlock with fingerprint	unlock_fingerprint
Unlock with password	unlock_password
Unlock with temporary password	unlock_temporary
Unlock with dynamic password	unlock_dynamic
Unlock with card	unlock_card
Unlock with face recognition	unlock_face
Unlock with mechanical key	unlock_key
Alert	alarm_lock
Remote unlocking countdown	unlock_request
Reply to a remote unlocking request	reply_unlock_request
Battery status	battery_state
Remaining battery capacity	residual_electricity
Double locking state	reverse_lock
Child lock	child_lock
Remote unlocking with app	unlock_app
Duress alarm	hijack
Unlock from the inside of the door	open_inside
Open and closed status of the door	closed_opened
Doorbell call	doorbell
SMS notification	message
Lift-up double locking	anti_lock_outside
Unlock with iris	unlock_eye
Unlock with palm print	unlock_hand
Unlock with finger vein	unlock_finger_vein
Sync all fingerprint IDs	update_all_finger
Sync all password IDs	update_all_password
Sync all card IDs	update_all_card
Sync all face IDs	update_all_face
Sync all iris IDs	update_all_eye
Sync all palm print IDs	update_all_hand
Sync all finger vein IDs	update_all_fin_vein
Report offline password unlocking	unlock_offline_pd
Report emptying all offline passwords	unlock_offline_clear
Report clearing a single offline password	unlock_offline_clear_single

Prev DocDevelopment Guide for iOS

Next DocBluetooth Lock