Wi-Fi Lock

Last Updated on : 2023-11-30 14:28:04download

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.

LockUserAppCloudEnter a 7-digitnumeric temporarypassword.Create a temporary password.Return the result.Enter the password on the lockkeypad, triggering the updateof the password list.Update the passwordlist.Enter password.ExecuteLockUserAppCloudUnlock with a temporary password

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.

LockUserAppCloudRequest a dynamic password.Return the result.Send the password.Get the dynamicpassword.Enter the dynamic password.ExecuteLockUserAppCloudUnlock with a dynamic password

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.

UserLockAppOperate the lock.Initiate a remote unlockingrequest.Notify the lockowner of therequest.Send the response to theremote unlocking request.ProcessUserLockAppRemote unlocking

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