Wi-Fi Smart Lock

Last Updated on : 2023-06-12 07:51:09download

Functional description

Class name	Description
`TuyaSmartLockDevice`	Wi-Fi lock operation class, inherited from `TuyaSmartDevice`
`TuyaSmartLockDeviceDelegate`	Wi-Fi lock protocol delegate, extended from `TuyaSmartDeviceDelegate`

Terms

Term	Description
Locks that support duress alarms	The duress alarm feature allows users to enroll a password or fingerprint as a duress code. If they are coerced by hostile persons, unlocking with the duress code can trigger alarms to be sent to a list of contacts.
Lock members	Lock members are classified into home members and non-home members. Home member: the same as that defined in the SmartLife App SDK. The Smart Lock SDK can be used to associate a lock password ID with a home member account. For more information, see Home Management. Non-home members: an individual member of a smart lock, only associated with the device. This member can be created and assigned. The Smart Lock SDK can be used to associate a lock password ID with this member.
dpCode	An identifier of a data point (DP) for a device. Each DP is assigned a name and an identifier indicated by `dpCode`. For more information, see List of lock DPs.

Lock members

This section describes the operations regarding non-home members.

Query a list of lock members

API description

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

Parameters

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

Data model of TuyaSmartLockMemberModel

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<TuyaSmartLockRelationModel *>	The mapping between a locking method and the user ID.
devId	NSString	The device ID.
ownerId	NSString	The home ID.
userType	NS_ENUM	The type of lock member. Valid values: `1`: home member `2`: non-home member

Example

ObjC:

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

Swift:

let lockDevice = TuyaSmartLockDevice(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<TuyaSmartLockRelationModel *> *)unlockRelations
                              success:(nullable TYSuccessString)success
                              failure:(nullable TYFailureError)failure;

Parameters

Parameter	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 TuyaSmartLockRelationModel

Field	Type	Description
unlockType	TYLockUnlockType	The unlocking method.
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 normal 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

ObjC:

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

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

// TuyaSmartLockDevice *lock
// Note: It must be set as a property.
self.lock = [TuyaSmartLockDevice 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 = TuyaSmartLockRelationModel()
finger.unlockType = .fingerprint // Unlock with a fingerprint
finger.sn = 123

let face = TuyaSmartLockRelationModel()
face.unlockType = .face // Unlock with biometric recognition
face.sn = 23
// Note: It must be set as a property.
self.lockDevice = TuyaSmartLockDevice(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 successfully. \(userId)")
}, failure: { (error) in
	if let e = error {
		print("error \(e)")
	}
})

Update member information

Modifies the information about a lock member, including the user name, avatar, and mapping with the unlocking password.

API description

- (void)updateLockNormalUserWithUserId:(NSString *)userId
                              userName:(nullable NSString *)userName
                           avatarImage:(nullable UIImage *)avatarImage
                       unlockRelations:(nullable NSArray<TuyaSmartLockRelationModel *> *)unlockRelations
                               success:(nullable TYSuccessBOOL)success
                               failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
userId	The member ID, required.
userName	The username of the member. This parameter is optional and not changed if not set.
avatarImage	The avatar of the member. This parameter is optional and not changed if not set.
unlockRelations	The mapping between the unlocking method and the password serial number. This parameter is optional and not changed if not set.
success	The success callback. The member ID of string type is returned.
failure	The failure callback.

Example

ObjC:

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

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

// TuyaSmartLockDevice *lock
// Note: It must be set as a property.
self.lock = [TuyaSmartLockDevice 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 = TuyaSmartLockRelationModel()
finger.unlockType = .fingerprint // Unlock with a fingerprint
finger.sn = 123

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

Delete a lock member

Deletes the information about a lock member. After the member is deleted, the existing password is not deleted.

API description

- (void)deleteLockUserWithUserId:(NSString *)userId
                         success:(nullable TYSuccessBOOL)success
                         failure:(nullable TYFailureError)failure;

Parameters

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

Example

ObjC:

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

Swift:

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

Temporary passwords

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

Wi-Fi Smart Lock

Query temporary password list

Returns a list of temporary passwords. The usage status of each temporary password is also displayed.

API description

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

Parameters

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

Data model of TuyaSmartLockTempPwdModel

Field	Type	Description
phone	NSString	The mobile phone number.
name	NSString	The name of the 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 status of the temporary password.
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 temporary password.
typedef NS_ENUM(NSUInteger, TYLockTempPwdEffectiveType) {
    TYLockMemberStatusTypeInvalid     = 1, // Expired
    TYLockMemberStatusTypeToBePubilsh = 2, // To be sent
    TYLockMemberStatusTypeWorking     = 3, // Being used
    TYLockMemberStatusTypeToBeDeleted = 4, // To be deleted
    TYLockTempPwdEffectiveTypeExpired = 5, // Expired
};

Example

ObjC:

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

Swift:

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

Create a temporary password

The validity period of a temporary password can be customized. This setting must be synced with the lock after the temporary password is created.

API description

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

Parameters

Parameter	Description
password	The 7-digit numeric temporary 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 time when the password takes effect.
invalidDate	The time when the password expires.
countryCode	The country or region code. For example, `86` means mainland China.
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

ObjC:

TuyaSmartLockDevice *lock = [TuyaSmartLockDevice deviceWithDeviceId:@"your_lock_device_id"];
// Creates a temporary password that is 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(@"Creation result %d", result);
} failure:^(NSError *error) {
	NSLog(@"error %@", error);
}];

Swift:

let lockDevice = TuyaSmartLockDevice(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("Creation result \(result)")
}, failure: { (error) in
	if let e = error {
		print("error \(e)")
	}
})

Delete a temporary password

Deletes a temporary password. This setting must be synced with the lock after the temporary password is deleted.

API description

- (void)deleteLockTempPwdWithPwdId:(NSInteger)tempPwdId
                             force:(BOOL)force
                           success:(nullable TYSuccessBOOL)success
                           failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
tempPwdId	The unique ID of the temporary password.
force	Specifies whether to forcibly delete the password. Valid values: `yes`: After users confirm to delete a password, it immediately disappears from the password list. Confirmation on the lock is not required. `no`: After users confirm to delete a password, it still appears in the password list. The password is deleted only after deletion is confirmed on the lock.
success	The success callback. The deletion result of Boolean type is returned.
failure	The failure callback.

Example

ObjC:

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

Swift:

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

Dynamic passwords

Wi-Fi Smart Lock

API description

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

- (void)getLockDynamicPasswordWithSuccess:(nullable TYSuccessString)success
                                  failure:(nullable TYFailureError)failure;

Parameters

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

Example

ObjC:

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

Swift:

let lockDevice = TuyaSmartLockDevice(deviceId: "your_lock_device_id")
lockDevice?.getLockDynamicPassword(success: { (pwd) in
	print("Result of querying a dynamic password \(pwd)")
}, failure: { (error) in
	if let e = error {
		print("error \(e)")
	}
})

Remote unlocking

Users can trigger a remote unlocking request on a lock. Then, the SDK can be used to implement remote locking.

Wi-Fi Smart Lock

API description

- (void)replyRemoteUnlock:(BOOL)open
                  success:(nullable TYSuccessHandler)success
                  failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
open	Specifies whether to unlock the door. `yes`: unlocks the door. `no`: does not unlock the door.
success	The success callback.
failure	The failure callback.

Callback for TuyaSmartLockDeviceDelegate

When the delegate is set for TuyaSmartLockDevice, after users operate the lock to trigger a 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:(TuyaSmartLockDevice *)device didReceiveRemoteUnlockRequest:(NSInteger)seconds;

Example

ObjC:

// The user operates the lock 4+#.
	// TuyaSmartLockDevice *lock;
self.lock = [TuyaSmartLockDevice deviceWithDeviceId:@"your_lock_device_id"];
self.lock.delegate = self;

// Implements the delegate method.
- (void)device:(TuyaSmartLockDevice *)device didReceiveRemoteUnlockRequest:(NSInteger)seconds {
	NSLog(@"The remote unlocking command must be processed within %d seconds after it is received.", seconds);

	// second = 0, indicates that the command is processed.
	// The following conditions might apply.
	if (seconds > 0) {
		BOOL open = YES; // Specifies whether to unlock the door.
		// Unlocks the door.
		[device replyRemoteUnlock:open success:^{
			NSLog(@"success");
		} failure:^(NSError *error) {
			NSLog(@"error %@", error);
		}];
	}
}

Swift:

// The user operates the lock 4+#.
	// var lock: TuyaSmartLockDevice
self.lock = TuyaSmartLockDevice(deviceId: "your_lock_device_id")
self.lock.delegate = self;

// Implements the delegate method.
func device(_ device: TuyaSmartLockDevice, didReceiveRemoteUnlockRequest seconds: Int) {
	print("The remote unlocking command must be processed within \(seconds) seconds after it is received.";
	if seconds > 0 {
		let open = true; // Specifies whether to unlock the door.
		// Unlocks the door.
		device.replyRemoteUnlock(open, success: {
			print("success")
		}) { (error) in
			if let e = error {
				print("error: \(e)")
			}
		}
	}
}

Lock usage records

Lock usage records include unlocking records, doorbell records, and alerts.

Query lock usage records

API description

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

Parameters

Parameter	Description
dpCodes	The list of data points (DPs) of the target device. For more information, see List of lock DPs.
offset	The page number starting from which entries are returned.
limit	The total number of returned entries in each call.
success	The success callback. The list of lock usage records is returned.
failure	The failure callback.

Data model of TuyaSmartLockRecordModel

Field	Type	Description
userId	NSString	The member ID.
devId	NSString	The device ID.
userName	NSString	The nickname of the user.
time	NSTimeInterval	The 13-bit timestamp when the record was generated.
dpData	NSDictionary	The DP data.
tags	NSInteger	The flag of the record. Valid values: `0`: other types of alarms `1`: duress alarm
dpsArray	NSArray<NSDictionary *>	The array of the lock DP data.

Query unlocking records

Unlocking records include the following events: unlock with a fingerprint, unlock with a normal password, unlock with a temporary password, unlock with a dynamic password, unlock with a card, unlock with biometric recognition, and unlock with a mechanical key.

API description

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

Parameters

Parameter	Description
offset	The page number starting from which entries are returned.
limit	The total number of returned entries in each call.
success	The success callback. The list of unlocking records is returned.
failure	The failure callback.

Query duress alarm records

Returns the duress alarm records based on the specified unlocking DP data.

API description

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

Parameters

Parameter	Description
dpCodes	The list of DPs of the target device. For more information, see List of lock DPs.
offset	The page number starting from which entries are returned.
limit	The total number of returned entries in each call.
success	The success callback. The list of duress alarm records is returned.
failure	The failure callback.

List of lock DPs

DP name	DP identifier (dpCode)
Unlock with a fingerprint	unlock_fingerprint
Unlock with a normal password	unlock_password
Unlock with a temporary password	unlock_temporary
Unlock with a dynamic password	unlock_dynamic
Unlock with a card	unlock_card
Unlock with biometric recognition	unlock_face
Unlock with a mechanical key	unlock_key
Alert	alarm_lock
Countdown of remote unlocking	unlock_request
Reply to a remote unlocking request	reply_unlock_request
Battery capacity status	battery_state
Remaining battery capacity	residual_electricity
Double locking status	reverse_lock
Child lock status	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
Double lock by lifting up	anti_lock_outside
Unlock with irises	unlock_eye
Unlock with palm prints	unlock_hand
Unlock with finger veins	unlock_finger_vein
Synchronize all fingerprint numbers	update_all_finger
Synchronize all password numbers	update_all_password
Synchronize all card numbers	update_all_card
Synchronize all face numbers	update_all_face
Synchronize all iris numbers	update_all_eye
Synchronize all palm print numbers	update_all_hand
Synchronize all finger vein numbers	update_all_fin_vein
Report offline password unlocking	unlock_offline_pd
Report the clearing of offline passwords	unlock_offline_clear
Report the clearing of a single offline password	unlock_offline_clear_single

Prev DocSmart Lock SDK

Next DocBluetooth Smart Lock