English
English
简体中文
Contact Us
Register
Log In
layoutIndex

Wi-Fi Smart Lock

Last Updated on : 2022-03-01 08:33:07download

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 Smart Life 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