Last Updated on : 2024-06-18 09:31:25download
This topic describes the features of Wi-Fi door locks.
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. |
Class name | Description |
---|---|
ThingSmartLockDevice |
Wi-Fi lock operation class, inherited from ThingSmartDevice . |
ThingSmartLockDeviceDelegate |
Wi-Fi lock protocol delegate, extended from ThingSmartDeviceDelegate . |
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.
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.
|
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)")
}
})
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)")
}
})
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)")
}
})
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)")
}
})
Creates a temporary password. Users can enter this password to unlock a door.
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)")
}
})
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)")
}
})
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)")
}
})
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)")
}
})
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)")
}
}
}
}
API description
- (void)fetchRemoteVoiceUnlockWithDevId:(NSString *)devId
success:(ThingSuccessID)success
failure:(nullable ThingFailureError)failure;
Parameters
Parameter | Description |
---|---|
devId | The device ID. |
success | The success callback. |
failure | The failure callback. |
Example
Objective-C:
[self.wifiDevice fetchRemoteVoiceUnlockWithDevId:self.wifiDevice.deviceModel.devId
success:^(id result) {
NSLog(@"Succeeded %@", result);
} failure:^(NSError *error) {
NSLog(@"Failed %@", error);
}];
API description
- (void)setRemoteVoiceUnlockWithDevId:(NSString *)devId
open:(BOOL)open
pwd:(NSString *)pwd
success:(ThingSuccessID)success
failure:(nullable ThingFailureError)failure;
Parameters
Parameter | Description |
---|---|
devId | The device ID. |
open | The on/off status. |
pwd | The password. |
success | The success callback. |
failure | The failure callback. |
Example
Objective-C:
[self.wifiDevice setRemoteVoiceUnlockWithDevId:self.wifiDevice.deviceModel.devId
open:YES
pwd:pwd
success:^(id result) {
NSLog(@"Succeeded %@", result);
} failure:^(NSError *error) {
NSLog(@"Failed %@", error);
}];
Returns the lock records, including unlocking records, doorbell records, and alerts.
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. |
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. |
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.
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. |
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. |
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. |
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 |
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedback