Zigbee Lock
Last Updated on : 2024-10-21 07:20:40download
This topic describes various features of Zigbee door locks, including home members, unlocking methods, temporary passwords, unlocking history, remote operation, and settings.
Functional description
| Class name | Description |
|---|---|
TuyaSmartZigbeeLockDevice |
Zigbee lock operation class, inherited from ThingSmartDevice. |
TuyaSmartZigbeeLockDeviceDelegate |
Zigbee lock protocol delegate, extended from ThingSmartDeviceDelegate. |
Sample code
The following code block shows how to create a Zigbee lock class based on a device ID.
// Create a Zigbee lock device object.
TuyaSmartZigbeeLockDevice *zigbeeDevice = [TuyaSmartZigbeeLockDevice deviceWithDeviceId:devId];
// Set a lock object delegate.
zigbeeDevice.delegate = self;
Terms
| Term | Description |
|---|---|
| Duress alarm | 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 that will be sent to a list of contacts. |
| Lock member | Lock members are home members, the same as that defined in the Smart Life App SDK. The Smart Lock SDK can be used to bind a lock password ID with a home member account. For more information, see Home Management. |
| lockUserId | A lockUserId is a member ID that the cloud assigns to a lock when you create a lock member. Each lockUserId indicates the member ID that is recorded in the firmware. |
| userId | A userId is the ID that the cloud assigns to a lock member when you create a lock member. Each userId is a unique ID of each user and is recorded in a database. |
| unlockDpCode | The identifier of a data point (DP) for a device. Each DP is assigned a name and an identifier indicated by dpCode. |
| unlockId | An unlockId is the unlocking method ID that consists of an unlocking DP ID plus a lock ID. For example, 12-c, where c is the hexadecimal converted from the decimal. |
| opmodeId | The ID of an unlocking method in the cloud. |
Home members
This section describes the operations regarding home members.
Get the list of home members
API description
/// Get the list of home members.
/// @param devId The device ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)getMemberListWithDevId:(NSString *)devId
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Parameters
| Field | Description |
|---|---|
| devId | The device ID. |
| success | The success callback. |
| failure | The failure callback. |
Sample code
[self.zigbeeDevice getMemberListWithDevId:self.devId success:^(id result) {
NSArray *memberList = (NSArray *)result;
NSLog(@"The list of home members was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the list of home members.");
}];
Get member details
Get details of the current user or a specified user.
API description
/// The details of a specified member.
/// @param devId The device ID.
/// @param userId The user ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)getMemberInfoWithDevId:(NSString *)devId
userId:(NSString *)userId
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Parameters
| Field | Description |
|---|---|
| devId | The device ID. |
| userId | The user ID. |
| success | The success callback. |
| failure | The failure callback. |
Sample code
[self.zigbeeDevice getMemberInfoWithDevId:devId userId:userId success:^(id result) {
NSDictionary *memberInfo = (NSDictionary *)result;
NSLog(@"The details of a specified home member was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the details of a specified home member.");
}];
Add a home member
Create a home member as a lock member. An account of the app must be created for the home member.
API description
/// Add a home member.
/// @param homeId The ID of the home.
/// @param requestModel The model of the request to add a member.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)addMemberWithHomeId:(long long)homeId
requestModel:(TuyaSmartHomeAddMemberRequestModel *)requestModel
success:(TYSuccessDict)success
failure:(TYFailureError)failure;
Data model of TuyaSmartHomeAddMemberRequestModel
For more information, see Member Information Management.
Sample code
[self.zigbeeDevice addMemberWithHomeId:homeId requestModel:model success:^(NSDictionary *dict) {
NSLog(@"The home member was created successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to create a home member.");
}];
Delete a home member
Delete a home member and all unlocking methods that are associated with this member from the device.
API description
/// Delete a specified home member.
/// @param memberId The user ID.
/// @param isAdmin Specifies whether the member is an administrator.
/// @param lockUserId The user ID in the lock firmware.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)removeMemberWithMemberId:(NSString *)memberId
isAdmin:(BOOL)isAdmin
lockUserId:(int)lockUserId
success:(TYSuccessHandler)success
failure:(nullable TYFailureError)failure;
Parameters
| Field | Description |
|---|---|
| memberId | The user ID. |
| isAdmin | Specifies whether a specified member is an admin. |
| lockUserId | The user ID in the lock firmware. |
| success | The success callback. |
| failure | The failure callback. |
Sample code
int userType = [model[@"userType"] intValue];
BOOL isAdmin = (userType == 10 || userType == 50) ? YES : NO;
[self.zigbeeDevice removeMemberWithMemberId:model[@"userId"] isAdmin:isAdmin lockUserId:lockUserId success:^{
NSLog(@"The lock member was deleted successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to delete the lock member.");
}];
Modify information about a member
Modify only the nickname and role of a specified member.
API description
/// Modify the information about a specified home member.
/// @param memberRequestModel The model of the home member.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)updateMemberWithRequestModel:(TuyaSmartHomeMemberRequestModel *)memberRequestModel
success:(TYSuccessHandler)success
failure:(TYFailureError)failure;
Data model of TuyaSmartHomeMemberRequestModel
For more information, see Member Information Management.
Sample code
[self.zigbeeDevice updateMemberWithRequestModel:model success:^{
NSLog(@"The home member was modified successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to modify the home member.");
}];
Get unlocking methods
Get the list of bound unlocking methods
API description
/// Get the list of unlocking methods bound with a specified user.
/// @param devId The device ID.
/// @param userId The user ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)getMemberOpmodeListWithDevId:(NSString *)devId
userId:(NSString *)userId
success:(nullable void(^)(NSArray<TuyaSmartZigbeeLockOpmodeModel *> *models))success
failure:(nullable TYFailureError)failure;
Fields in data model of TuyaSmartZigbeeLockOpmodeModel
| Field | Description |
|---|---|
| opmode | The unlocking method. dpId is returned. For more information, see Function Definition > Standard Functions > Unlock Method DP ID. |
| opmodeValue | The number of a specified unlocking method in the cloud, equivalent to SN. |
| unlockId | The ID of an unlocking method. |
| lockUserId | The user ID in the lock firmware. |
| opmodeId | The ID of a specified unlocking method in the cloud. |
| unlockAttr | The attribute of an unlocking method. Valid values:
|
| unlockName | The name of a specified unlocking method. |
| userName | The nickname of the user. |
| userId | The user ID. |
Parameters
| Field | Description |
|---|---|
| devId | The device ID. |
| userId | The user ID. |
| success | The success callback. |
| failure | The failure callback. |
Sample code
[self.zigbeeDevice getMemberOpmodeListWithDevId:devId userId:memberId success:^(NSArray<TuyaSmartZigbeeLockOpmodeModel *> * _Nonnull models) {
NSLog(@"The list of unlocking methods was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the list of unlocking methods.");
}];
Get the list of unbound unlocking methods
API description
/// Get the list of unlocking methods unbound with a specified user.
/// @param devId The device ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)getUnallocOpModeWithDevId:(NSString *)devId
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Parameters
| Field | Description |
|---|---|
| devId | The device ID. |
| success | The success callback. |
| failure | The failure callback. |
Sample code
[self.zigbeeDevice getUnallocOpModeWithDevId:self.devId success:^(id result) {
NSArray *datalist = (NSArray *)result;
NSLog(@"The list of unassigned unlocking methods was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the list of unassigned unlocking methods.");
}];
Assign unlocking method to a user
API description
/// Assign a specified unlocking method to a user.
/// @param devId The device ID.
/// @param userId The user ID.
/// @param unlockIds The ID of the unlocking method.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)allocUnlockOpModeWithDevId:(NSString *)devId
userId:(NSString *)userId
unlockIds:(NSString *)unlockIds
success:(TYSuccessID)success
failure:(nullable TYFailureError)failure;
Parameters
| Field | Description |
|---|---|
| devId | The device ID. |
| userId | The user ID. |
| unlockIds | The list of unlocking methods. |
| success | The success callback. |
| failure | The failure callback. |
Sample code
[self.zigbeeDevice allocUnlockOpModeWithDevId:self.devId userId:userId unlockIds:@[unlockId].tysdk_JSONString success:^(id result) {
BOOL isSuccess = [result boolValue];
NSLog(@"The unlocking method was assigned successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to assign the unlocking method.");
}];
Add unlocking method
API description
/// Add an unlocking method.
/// @param devId The device ID.
/// @param isAdmin Specifies whether the member is an administrator.
/// @param unlockOpType The unlocking method.
/// @param unlockDpCode The DP code of a specified unlocking method. For more information, see product definitions.
/// @param lockUserId The user ID in the lock firmware.
/// @param userId The user ID.
* @param unlockName The name of a specified unlocking method.
/// @param needHijacking Specifies whether to enable duress alarms.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)addUnlockOpmodeForMemberWithDevId:(NSString *)devId
isAdmin:(BOOL)isAdmin
unlockOpType:(TYUnlockOpType)unlockOpType
unlockDpCode:(NSString *)unlockDpCode
lockUserId:(int)lockUserId
userId:(NSString *)userId
unlockName:(NSString *)unlockName
needHijacking:(BOOL)needHijacking
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
/// Add an unlocking method (sending with password).
/// @param devId The device ID.
/// @param isAdmin Specifies whether the member is an administrator.
/// @param password The password.
/// @param lockUserId The user ID in the lock firmware.
/// @param userId The user ID.
* @param unlockName The name of a specified unlocking method.
/// @param needHijacking Specifies whether to enable duress alarms.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)addPasswordOpmodeForMemberWithDevId:(NSString *)devId
isAdmin:(BOOL)isAdmin
password:(NSString *)password
lockUserId:(int)lockUserId
userId:(NSString *)userId
unlockName:(NSString *)unlockName
needHijacking:(BOOL)needHijacking
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Parameters
| Field | Description |
|---|---|
| devId | The device ID. |
| isAdmin | Specifies whether a specified member is an admin. |
| unlockOpType | Get unlocking methods |
| unlockDpCode | The DP code of a specified unlocking method. |
| lockUserId | The user ID in the lock firmware. |
| userId | The user ID. |
| unlockName | The name of a specified unlocking method. |
| needHijacking | Specifies whether to enable duress alarms. |
| password | The password, required when a command is sent with password. |
| success | The success callback. |
| failure | The failure callback. |
Differences in adding an unlocking method with a password
addUnlockOpmodeForMemberWithDevId: Enter the password on the device to add a specified unlocking method, including door card, fingerprint, and password.addPasswordOpmodeForMemberWithDevId: Enter the password on the app to add the method of unlocking by password.
Sample code for getting cloud capabilities
Determine which of the two APIs to use depending on the return tyabitmqxx value.
| Field | Description |
|---|---|
| true | Use addUnlockOpmodeForMemberWithDevId |
| false | Use addPasswordOpmodeForMemberWithDevId |
self.tyabitmqxx = YES;
WEAKSELF_TYSDK
[self.zigbeeDevice getLockDeviceConfigWithProductId:self.zigbeeDevice.deviceModel.productId options:@"uiContent,cloudDp,powerCode" success:^(id result) {
if (!result){
weakSelf_TYSDK.tyabitmqxx = NO;
}
else{
NSDictionary *powerCode = result[@"powerCode"];
if (powerCode[@"tyabitmqxx"]){
weakSelf_TYSDK.tyabitmqxx = [powerCode[@"tyabitmqxx"] boolValue];
}
}
} failure:^(NSError *error) {
NSLog(@"Failed to invoke the cloud capability API.");
}];
Sample code for adding an unlocking method
[self.zigbeeDevice addUnlockOpmodeForMemberWithDevId:self.devId
isAdmin:isAdmin
unlockOpType:self.unlockModeType
unlockDpCode:@"unlock_password"
lockUserId:self.lockUserId
userId:self.memberId
unlockName:@"Zigbee password test-01"
needHijacking:NO
success:^(id result) {
NSDictionary *data = (NSDictionary*)result;
NSLog(@"The password was added successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to add the password.");
}];
[self.zigbeeDevice addPasswordOpmodeForMemberWithDevId:self.devId
isAdmin:isAdmin
password:password
lockUserId:lockUserId
userId:userId
unlockName:@"Zigbee password test-08"
needHijacking:NO
success:^(id result) {
NSDictionary *data = (NSDictionary*)result;
NSLog(@"The password was added successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to add the password.");
}];
Update unlocking method
This method can only be used to update the name of a specified unlocking method. For more information about anti-duress operations, refer to Set the duress alarm feature and Remove the duress alarm feature.
API description
/// Update the information about a specified unlocking method.
/// @param devId The device ID.
/// @param opmodeId The ID of a specified unlocking method.
* @param unlockName The name of a specified unlocking method.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)modifyUnlockOpmodeForMemberWithDevId:(NSString *)devId
opmodeId:(NSString *)opmodeId
unlockName:(NSString *)unlockName
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice modifyUnlockOpmodeForMemberWithDevId:self.devId
opmodeId:opmodeId
unlockName:unlockName
success:^(id result) {
NSDictionary *data = (NSDictionary*)result;
NSLog(@"The unlocking method was updated successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to update the unlocking method.");
}];
Delete unlocking method
API description
/// Delete a specified unlocking method.
/// @param devId The device ID.
/// @param isAdmin Specifies whether the member is an administrator.
/// @param lockUserId The user ID in the lock firmware.
/// @param opmodeId The ID of a specified unlocking method.
/// @param firmwareId The device hardware ID.
/// @param unlockDpCode The DP code of a specified unlocking method. For more information, see product definitions.
/// @param unlockOpType The unlocking method.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)removeUnlockOpmodeForMemberWithDevId:(NSString *)devId
isAdmin:(BOOL)isAdmin
lockUserId:(int)lockUserId
opmodeId:(NSString *)opmodeId
firmwareId:(NSString *)firmwareId
unlockDpCode:(NSString *)unlockDpCode
unlockOpType:(TYUnlockOpType)unlockOpType
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Parameters
| Field | Description |
|---|---|
| devId | The device ID. |
| isAdmin | Specifies whether a specified member is an admin. |
| lockUserId | The user ID in the lock firmware. |
| opmodeId | The ID of a specified unlocking method in the cloud. |
| firmwareId | The hardware ID. |
| unlockDpCode | The DP code of a specified unlocking method. |
| unlockOpType | The unlocking method. |
| success | The success callback. |
| failure | The failure callback. |
Sample code
[self.zigbeeDevice removeUnlockOpmodeForMemberWithDevId:self.devId
isAdmin:isAdmin
lockUserId:lockUserId
opmodeId:opmodeId
firmwareId:opmodeValue
unlockDpCode:@"unlock_fingerprint"
unlockOpType:TYUnlockOpTypeFinger
success:^(id result) {
BOOL isSuccess = [result boolValue];
NSLog(@"The fingerprint was deleted successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to delete the fingerprint.");
}];
Cancel the enrollment of an unlocking method
API description
/// Cancel enrollment.
/// @param isAdmin Specifies whether the member is an administrator.
/// @param lockUserId The user ID in the lock firmware.
/// @param unlockOpType The unlocking method.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)cancelUnlockOpmodeWithAdmin:(BOOL)isAdmin
lockUserId:(int)lockUserId
unlockOpType:(TYUnlockOpType)unlockOpType
success:(nullable TYSuccessBOOL)success
failure:(nullable TYFailureError)failure;
Parameters
| Field | Description |
|---|---|
| isAdmin | Specifies whether the user is an admin. |
| lockUserId | The user ID in the lock firmware. |
| unlockOpType | Get unlocking methods |
| success | The success callback. |
| failure | The failure callback. |
Sample code
[self.zigbeeDevice cancelUnlockOpmodeWithAdmin:isAdmin
lockUserId:lockUserId
unlockOpType:unlockOpType
success:^(BOOL result) {
NSLog(@"The enrollment was canceled successfully.");
}failure:^(NSError *error) {
NSLog(@"Failed to cancel the enrollment.");
}];
Set the duress alarm feature
API description
/// Set the duress alarm feature.
/// @param devId The device ID.
/// @param dpId The DP ID.
/// @param unlockId The ID of the unlocking method.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)addHijackingConfigWithDevId:(NSString *)devId
dpId:(NSString *)dpId
unlockId:(NSString *)unlockId
success:(nullable TYSuccessBOOL)success
failure:(nullable TYFailureError)failure;
Parameters
| Field | Description |
|---|---|
| devId | The device ID. |
| dpId | The ID of the device DP. |
| unlockId | The ID of an unlocking method. |
| success | The success callback. |
| failure | The failure callback. |
Sample code
[self.zigbeeDevice addHijackingConfigWithDevId:self.devId
dpId:dpId
unlockId:unlockId
success:^(BOOL result) {
NSLog(@"The duress alarm feature was set successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to set the duress alarm feature.");
}];
Remove the duress alarm feature
API description
/// Remove the duress alarm feature.
/// @param devId The device ID.
/// @param dpId The DP ID.
/// @param unlockId The ID of the unlocking method.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)removeHijackingConfigWithDevId:(NSString *)devId
dpId:(NSString *)dpId
unlockId:(NSString *)unlockId
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice removeHijackingConfigWithDevId:self.devId
dpId:dpId
unlockId:unlockId
success:^(id result) {
NSLog(@"The duress alarm feature was removed successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to remove the duress alarm feature.");
}];
Temporary password
Get the list of temporary passwords
API description
/// The list of valid temporary passwords.
/// @param devId The device ID.
/// @param offset The number of the entry starting from which entries are returned.
* @param limit The maximum number of entries returned on each page.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)getPasswordListWithDevId:(NSString *)devId
offset:(int)offset
limit:(int)limit
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice getPasswordListWithDevId:self.devId offset:0 limit:50 success:^(id result) {
NSLog(@"The list of valid temporary passwords was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the list of valid temporary passwords.");
}];
Get the list of invalid temporary passwords
API description
/// The list of invalid temporary passwords.
/// @param devId The device ID.
/// @param offset The number of the entry starting from which entries are returned.
* @param limit The maximum number of entries returned on each page.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)getInvalidPasswordListWithDevId:(NSString *)devId
offset:(int)offset
limit:(int)limit
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice getInvalidPasswordListWithDevId:self.devId offset:0 limit:50 success:^(id result) {
NSLog(@"The list of invalid temporary passwords was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the list of invalid temporary passwords.");
}];
Clear invalid passwords
API description
/// Clear invalid passwords.
/// @param devId The device ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)removeInvalidPasswordWithDevId:(NSString *)devId
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice removeInvalidPasswordWithDevId:self.devId success:^(id result) {
NSLog(@"Invalid passwords were cleared successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to clear invalid passwords.");
}];
Get dynamic password
API description
/// Get a dynamic password.
/// @param devId The device ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)getDynamicPasswordWithDevId:(NSString *)devId
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice getDynamicPasswordWithDevId:self.devId success:^(id result) {
NSLog(@"The dynamic password was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the dynamic password.");
}];
Add temporary password
API description
/// Add a temporary password.
/// @param devId The device ID.
/// @param name The password name.
/// @param effectiveTime The effective time.
/// @param invalidTime The expiration time.
/// @param password The password.
/// @param schedule The schedule.
/// @param oneTime Specifies whether it is a one-time password. 0: no, 1: yes.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)addTemporaryPasswordWithDevId:(NSString *)devId
name:(NSString *)name
effectiveTime:(NSTimeInterval)effectiveTime
invalidTime:(NSTimeInterval)invalidTime
password:(NSString *)password
schedule:(NSString *)schedule
oneTime:(NSInteger)oneTime
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Parameters
| Field | Description |
|---|---|
| devId | The device ID. |
| name | The password name. |
| effectiveTime | The effective time. |
| invalidTime | The expiration time. |
| password | The password content. |
| schedule | The list of a specified schedule. For more information, see NSArray <TuyaSmartBLELockScheduleModel*> *. |
| oneTime | The number of maximum times the password can be used. Valid values:
|
| success | The success callback. |
| failure | The failure callback. |
Data model of TuyaSmartBLELockScheduleModel
| Field | Type | Description |
|---|---|---|
| workingDay | NSInteger | Indicates whether the password is valid on a working day. For more information, see the description of workingDay. |
| allDay | BOOL | Indicates whether the password is valid all the day. |
| effectiveTime | NSInteger | The start time in minutes. Example: To make the setting take effect at 8 o’clock in the morning on the current day, the value is 800. |
| invalidTime | NSInteger | The end time in minutes. Example: To make the setting expire at 18 o’clock in the afternoon on the current day, the value is 1800. |
Description of workingDay
The weekly recurring field workingDay consists of seven bits, and each bit is 1 or 0. A value of 1 represents ON and a value of 0 represents OFF. The following examples show the conversion from binary to decimal for different settings in the field.
| Sunday | Monday | Tuesday | Wednesday | Thursday | Friday | Saturday | Binary | Calculation result (decimal) |
|---|---|---|---|---|---|---|---|---|
| 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1111111 | 127 |
| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0000000 | 0 |
| 0 | 1 | 1 | 1 | 1 | 0 | 0 | 0111100 | 60 |
Sample code
NSArray<ThingSmartBLELockScheduleModel *> *scheduleList = data;
NSString *schedule = scheduleList.yy_modelToJSONString;
[self.zigbeeDevice addTemporaryPasswordWithDevId:self.devId
name:name
effectiveTime:effectiveTime
invalidTime:invalidTime
password:password
schedule:schedule
oneTime:0
success:^(id result) {
NSDictionary *data = (NSDictionary*)result;
NSLog(@"The periodic password was created successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to create a periodic password.");
}];
Rename temporary password
API description
/// Rename a temporary password.
/// @param devId The device ID.
/// @param pwdId The password ID.
/// @param name The password name.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)updateTemporaryPasswordWithDevId:(NSString *)devId
pwdId:(NSInteger)pwdId
name:(NSString *)name
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice updateTemporaryPasswordWithDevId:self.devId
pwdId:pwdId
name:name
success:^(id result) {
NSLog(@"The password was renamed successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to rename the password.");
}];
Modify temporary password
Modify a periodic temporary password.
API description
/// Modify the validity period of a specified password (hardware interaction).
/// @param devId The device ID.
/// @param pwdId The password ID.
/// @param name The password name.
/// @param effectiveTime The effective time.
/// @param invalidTime The expiration time.
/// @param schedule The schedule.
/// @param oneTime Specifies whether it is a one-time password. 0: no, 1: yes.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)modifyTemporaryPasswordWithDevId:(NSString *)devId
pwdId:(NSInteger)pwdId
name:(NSString *)name
effectiveTime:(NSTimeInterval)effectiveTime
invalidTime:(NSTimeInterval)invalidTime
schedule:(NSString *)schedule
oneTime:(NSInteger)oneTime
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice modifyTemporaryPasswordWithDevId:self.devId
pwdId:pwdId
effectiveTime:effectiveTime
invalidTime:invalidTime
schedule:schedule
oneTime:oneTime
success:^(id result) {
NSLog(@"The password was modified successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to modify the password.");
}];
Delete temporary password
API description
/// Delete a temporary password.
/// @param devId The device ID.
/// @param pwdId The password ID.
/// @param name The password name.
/// @param effectiveTime The effective time.
/// @param invalidTime The expiration time.
/// @param oneTime Specifies whether it is a one-time password. 0: no, 1: yes.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)removeTemporaryPasswordWithDevId:(NSString *)devId
pwdId:(NSInteger)pwdId
name:(NSString *)name
effectiveTime:(NSTimeInterval)effectiveTime
invalidTime:(NSTimeInterval)invalidTime
oneTime:(NSInteger)oneTime
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice removeTemporaryPasswordWithDevId:self.devId
pwdId:pwdId
name:name
effectiveTime:effectiveTime
invalidTime:invalidTime
oneTime:oneTime
success:^(id result) {
NSLog(@"The password was deleted successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to delete the password.");
}];
Freeze temporary password
API description
/// Freeze a temporary password.
/// @param devId The device ID.
/// @param pwdId The password ID.
/// @param name The password name.
/// @param effectiveTime The effective time.
/// @param invalidTime The expiration time.
/// @param oneTime Specifies whether it is a one-time password. 0: no, 1: yes.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)freezeTemporaryPasswordWithDevId:(NSString *)devId
pwdId:(NSInteger)pwdId
name:(NSString *)name
effectiveTime:(NSTimeInterval)effectiveTime
invalidTime:(NSTimeInterval)invalidTime
oneTime:(NSInteger)oneTime
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice freezeTemporaryPasswordWithDevId:self.devId
pwdId:pwdId
name:name
effectiveTime:effectiveTime
invalidTime:invalidTime
oneTime:oneTime
success:^(id result) {
NSLog(@"The password was frozen successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to freeze the password.");
}];
Unfreeze temporary password
API description
/// Unfreeze a temporary password.
/// @param devId The device ID.
/// @param pwdId The password ID.
/// @param name The password name.
/// @param effectiveTime The effective time.
/// @param invalidTime The expiration time.
/// @param oneTime Specifies whether it is a one-time password. 0: no, 1: yes.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)unfreezeTemporaryPasswordWithDevId:(NSString *)devId
pwdId:(NSInteger)pwdId
name:(NSString *)name
effectiveTime:(NSTimeInterval)effectiveTime
invalidTime:(NSTimeInterval)invalidTime
oneTime:(NSInteger)oneTime
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice unfreezeTemporaryPasswordWithDevId:self.devId
pwdId:pwdId
name:name
effectiveTime:effectiveTime
invalidTime:invalidTime
oneTime:oneTime
success:^(id result) {
NSLog(@"The password was unfrozen successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to unfreeze the password.");
}];
Get the status of temporary passwords
Based on the data returned by the list, the corresponding status is displayed in the UI.
History
Number of unread alerts
API description
/// The number of unread alerts.
/// @param devId The device ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)getUnreadAlarmNumberWithDevId:(NSString *)devId
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice getUnreadAlarmNumberWithDevId:self.devId success:^(id result){
int value = [result intValue];
NSLog(@"The number of unread alerts was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the number of unread alerts.");
}];
Alert history (doorbell + alert + duress)
API description
/// Alerts.
/// @param devId The device ID.
/// @param dpIds The DP IDs of alert types.
/// @param offset The number of the entry starting from which entries are returned.
* @param limit The maximum number of entries returned on each page.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)getAlarmRecordListWithDevId:(NSString *)devId
dpIds:(NSArray *)dpIds
offset:(int)offset
limit:(int)limit
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice getAlarmRecordListWithDevId:self.devId
dpIds:@[@"hijack",@"alarm_lock",@"doorbell"]
offset:0
limit:50
success:^(id result) {
NSLog(@"The alert history was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the alert history.");
}];
Unlocking history
API description
/// Unlocking history.
/// @param devId The device ID.
/// @param dpIds The DP IDs of the unlocking history.
/// @param startTime The start time.
/// @param endTime The end time.
/// @param offset The number of the entry starting from which entries are returned.
* @param limit The maximum number of entries returned on each page.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)getUnlockRecordListWithDevId:(NSString *)devId
dpIds:(NSArray *)dpIds
startTime:(NSInteger)startTime
endTime:(NSInteger)endTime
offset:(int)offset
limit:(int)limit
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice getUnlockRecordListWithDevId:self.devId
dpIds:dpIds
startTime:0
endTime:0
offset:0
limit:50
success:^(id result) {
NSLog(@"The unlocking history was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the unlocking history.");
}];
Bind unlocking history with a user
API description
/// Bind an unlocking history with a specific user.
/// @param devId The device ID.
/// @param userId The user ID.
/// @param unlockIds The list of the unlocking methods.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)bindUnlockOpModeWithDevId:(NSString *)devId
userId:(NSString *)userId
unlockIds:(NSString *)unlockIds
success:(TYSuccessID)success
failure:(nullable TYFailureError)failure;
Parameters
| Field | Description |
|---|---|
| devId | The device ID. |
| userId | The user ID. |
| unlockIds | The list of unlocking methods. |
| success | The success callback. |
| failure | The failure callback. |
Sample code
NSString *unlockIds = [NSString stringWithFormat:@"%@-%@",[self.currentDic[@"dpId"] stringValue],[self.currentDic[@"dpValue"] stringValue]];
[self.zigbeeDevice bindUnlockOpModeWithDevId:self.devId userId:[dic[@"userId"] stringValue] unlockIds:@[unlockIds].tysdk_JSONString success:^(id result) {
BOOL isSuccess = [result boolValue];
NSLog(@"Bound successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to bind.");
}];
Remote features
Remote unlocking
You need to listen to the DPs supported by the device to show whether the door is opened correctly. The API only returns successful execution.
API description
/// Remote unlocking.
/// @param devId The device ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)remoteUnlockWithDevId:(NSString *)devId
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice remoteUnlockWithDevId:self.devId success:^(id result) {
NSLog(@"Remotely unlocked without password successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to perform remote unlocking without password.");
}];
Remote locking
API description
/// Remote locking.
/// @param devId The device ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)remoteLockWithDevId:(NSString *)devId
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice remoteLockWithDevId:self.devId success:^(id result) {
NSLog(@"Remotely locked successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to perform remote locking.");
}];
Query on/off status of remote unlocking
API description
/// Query on/off status of remote unlocking.
/// @param devId The device ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)fetchRemoteUnlockTypeWithDevId:(NSString *)devId
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
WEAKSELF_TYSDK
[self.zigbeeDevice fetchRemoteUnlockTypeWithDevId:self.devId
success:^(id result) {
weakSelf_TYSDK.isRemoteOpen = [result[@"isRemoteOpen"] boolValue];
NSLog(@"The status was queried successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to query the status.");
}];
Set on/off status of remote unlocking
API description
/// Set on/off status of remote unlocking.
/// @param devId The device ID.
/// @param open The on/off status.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)setRemoteUnlockTypeWithDevId:(NSString *)devId
open:(BOOL)open
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice setRemoteUnlockTypeWithDevId:self.devId
open:isOpen
success:^(id result) {
NSLog(@"Set successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to set the feature.");
}];
Get remote unlocking permission
Prerequisite: The device needs to support two remote DP codes, remote_no_dp_key and remote_unlock, where remote_unlock is the prerequisite for remote unlocking with password. If remote_unlock is not supported, password-related features need to be hidden.
API description
/// Get remote unlocking permission.
/// @param devId The device ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)getRemoteUnlockPermissionValueWithDevId:(NSString *)devId
success:(nullable void(^)(TuyaSmartZigbeeLockRemotePermissionModel *model))success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice getRemoteUnlockPermissionValueWithDevId:self.devId success:^(TuyaSmartZigbeeLockRemotePermissionModel * _Nonnull model) {
NSLog(@"The remote unlocking permission was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the remote unlocking permission.");
}];
Parse the returned data
{
"remoteOpenState": {
"type": "password",
"user": "admin",
"way": "remote_no_dp_key"//remote_unlock
}
}
Data model of TuyaSmartZigbeeLockRemotePermissionModel
If the administrator unlocks the door without or with a password, it will be displayed as unavailable to ordinary users.
| Field | Type | Description |
|---|---|---|
| type | NSString | The type, with the password unchanged. |
| user | NSString | The type of user. Valid values:
|
| way | NSString |
|
For more information, see ThingRemotePermissionType enumeration.
Remote unlocking with password
API description
/// Remote unlocking with password.
/// @param devId The device ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)remoteUnlockWithDevId:(NSString *)devId
password:(NSString *)password
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice remoteUnlockWithDevId:self.devId
password:password
success:^(id result) {
NSLog(@"Remotely unlocked with password successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to perform remote unlocking with password.");
}];
Set remote unlocking permission
API description
/// Set remote unlocking permission.
/// @param devId The device ID.
/// @param remotePermissionType The permission type.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)setRemoteUnlockPermissionValueWithDevId:(NSString *)devId
remotePermissionType:(TYRemotePermissionType)remotePermissionType
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
ThingRemotePermissionType enumeration type:
| Type | Description |
|---|---|
| ThingRemotePermissionType_NonePwd_Admin | Without password - Administrator |
| ThingRemotePermissionType_NonePwd_All | Without password - Everyone |
| ThingRemotePermissionType_Pwd_Admin | With password - Administrator |
| ThingRemotePermissionType_Pwd_All | With password - Everyone |
Sample code
[self.zigbeeDevice setRemoteUnlockPermissionValueWithDevId:self.devId remotePermissionType:TYRemotePermissionType_NonePwd_Admin success:^(id result) {
NSLog(@"The admin's unlocking without password was set successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to set the admin's unlocking without password.");
}];
Check if the speaker password is enabled
API description
/// Check if the speaker password is enabled.
/// @param devId The device ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)fetchRemoteVoiceUnlockWithDevId:(NSString *)devId
success:(TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice fetchRemoteVoiceUnlockWithDevId:self.devId
success:^(id result) {
NSLog(@"The enabling status of the speaker password was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the enabling status of the speaker password.");
}];
Set or cancel a speaker password
API description
/// Set or cancel a speaker password.
/// @param devId The device ID.
/// @param open Set or cancel a speaker password.
/// @param pwd The password.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)setRemoteVoiceUnlockWithDevId:(NSString *)devId
open:(BOOL)open
pwd:(NSString *)pwd
success:(TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice setRemoteVoiceUnlockWithDevId:self.devId open:isOpen pwd:pwd success:^(id result) {
NSLog(@"The speaker password was set successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to set the speaker password.");
}];
Additional features
Get the device’s activation time up to now
Get the device’s activation time up to now. For example, how many days it has protected the user.
API description
/// Get the device's activation time up to now.
/// @param devId The device ID.
/// @param success The success callback.
/// @param failure The failure callback.
- (void)getSecurityGuardDaysWithDevId:(NSString *)devId
success:(nullable TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice getSecurityGuardDaysWithDevId:self.devId success:^(id result){
NSLog(@"The number of days was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the number of days.");
}];
Get cloud capabilities
Get the panel cloud capabilities of a specified device.
API description
/// Get the cloud capabilities of a specified device.
/// @param productId The product ID.
/// @param options The query items (uiContent, cloudDp, powerCode).
/// @param success The success callback.
/// @param failure The failure callback.
- (void)getLockDeviceConfigWithProductId:(NSString *)productId
options:(NSString *)options
success:(TYSuccessID)success
failure:(nullable TYFailureError)failure;
Sample code
[self.zigbeeDevice getLockDeviceConfigWithProductId:self.zigbeeDevice.deviceModel.productId options:@"uiContent,cloudDp,powerCode" success:^(id result) {
NSLog(@"The configuration was gotten successfully.");
} failure:^(NSError *error) {
NSLog(@"Failed to get the configuration.");
}];
Miscellaneous
Error codes
Service error code
| Error codes | Description |
|---|---|
| 4,000 | Product definition error |
| 4001 | Username error |
| 4002 | Time error |
| 4003 | Device processing timeout |
| 4004 | Device disconnected |
Error code reported by the firmware
ThingUnlockOpErrorCode enumeration type
| Error code | Description |
|---|---|
| ThingUnlockOpErrorCodeTimeout | Add unlocking methods - timeout |
| ThingUnlockOpErrorCodeWriteError | Add unlocking methods - write failure |
| ThingUnlockOpErrorCodeRepeatWrite | Add unlocking methods - repeat write |
| ThingUnlockOpErrorCodeFirmwareIdUnavailable | Add unlocking methods - no available hardware ID |
| ThingUnlockOpErrorCodePasswordTypeError | Add unlocking methods - password type error, non-digit |
| ThingUnlockOpErrorCodePasswordLengthError | Add unlocking methods - password length error |
| ThingUnlockOpErrorCodeUnspoortOpType | Add unlocking methods - the unlocking method is not supported |
| ThingUnlockOpErrorCodeFingerWriting | Add unlocking methods - a fingerprint is being enrolled |
| ThingUnlockOpErrorCodeCardWriting | Add unlocking methods - a card is being enrolled |
| ThingUnlockOpErrorCodeFaceWriting | Add unlocking methods - a face is being enrolled |
| ThingUnlockOpErrorCodePasswordIsTooSimple | Add unlocking methods - password is too simple |
| ThingUnlockOpErrorCodeFirmwareIdError | Add unlocking methods - wrong hardware ID |
DPs of unlocking history
| DP | Functional description |
|---|---|
| unlock_fingerprint | Unlock with fingerprint |
| unlock_password | Unlock with password |
| unlock_temporary | Unlock with temporary password |
| unlock_dynamic | Unlock with dynamic password |
| unlock_card | Unlock with card |
| unlock_face | Unlock with face recognition |
| unlock_key | Unlock with mechanical key |
| unlock_remote | Remote unlocking |
| open_inside | Unlock from the inside of the door |
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedbackMarketing Cooperation
Business Cooperation
Customer Service
Media Inquiry
© 2024 Tuya Inc.