Bluetooth Lock

This topic describes comprehensive features supported by Bluetooth locks and provides API descriptions and samples regarding lock members, Bluetooth connection, lock records, and unlocking with password, fingerprint, or card.

Classes

Class name	Description
ThingSmartBLELockDevice	Bluetooth lock operation class, inherited from ThingSmartDevice.
ThingSmartBLELockDeviceDelegate	Bluetooth lock protocol delegate, extended from ThingSmartDeviceDelegate.

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 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 Cube 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 specific to a smart lock, only associated with the lock. This member can be created and assigned. The Smart Lock SDK can be used to associate a lock password ID with this member.
lockUserId	A lockUserId is a unique member ID assigned by the cloud to a lock member. This ID is stored in the firmware.
userId	A userId is a unique database ID assigned by the cloud to a lock member.
dpCode	The identifier of a data point (DP) for a device. Each data point is assigned a name and an identifier. For more information, see List of Bluetooth Lock DPs.

Lock members

This section describes the operations regarding the home members (lock pro) and non-home members (legacy locks).

Get the list of lock members

API description

This API method is available to the legacy standard locks.

- (void)getMemberListWithSuccess:(nullable void(^)(NSArray<ThingSmartBLELockMemberModel *> *members))success
                         failure:(ThingFailureError)failure;

API description

This API method is available to the locks of pro edition.

- (void)getProLockMemberListWithDevId:(NSString *)devId
                              success:(ThingSuccessID)success
                              failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
success	The success callback. The list of members is returned.
failure	The failure callback.

Data model of ThingSmartBLELockMemberModel

Field	Type	Description
userId	NSString	The member ID.
userContact	NSString	The contact method.
avatarUrl	NSString	The URL of the avatar.
nickName	NSString	The name of the member.
userTimeSet	NSString	The validity data of the member.
phase	NSUInteger	The freeze status. 0: Frozen 1: Unfrozen
status	NSUInteger	The status of the user.
lockUserId	int	The user ID stored on the lock.
userType	NSUInteger	The type of user. 10: Admin 20: Common member 30: Anonymous member
supportOpenType	NSArray	The supported unlocking method.
shareUser	NSString	The user account with which the device is shared.
productAttribute	NSUInteger	The product property.

Example

Objective-C:

[self.lock getMemberListWithSuccess:^(NSArray<ThingSmartBLELockMemberModel *> * _Nonnull list) {
    NSLog(@"Member list %@", list);
} failure:^(NSError *error) {
    NSLog(@"Failed to query member list, error: %@", error);
}];

Swift:

self.lock?.getMemberList(success: { (list) in
    print("Member list \(list)")
}, failure: { (error) in
    if let e = error {
        print("Failed to query member list, error: \(e)")
    }
})

Create a lock member

Creates a non-home member to be associated with an unlocking method in later operations.

API description

This API method is available to the legacy standard locks.

- (void)addMemberWithUserName:(NSString *)userName
                  allowUnlock:(BOOL)allowUnlock
                     timeType:(ThingMemberTimeType)timeType
                effectiveDate:(NSDate *)effectiveDate
                  invalidDate:(NSDate *)invalidDate
                      success:(nullable ThingSuccessBOOL)success
                      failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
userName	The name of the member.
allowUnlock	Specifies whether the member can unlock over Bluetooth.
timeType	The validity period. ThingMemberTimeTypePermanent: Permanent. ThingMemberTimeTypePhase: Timed.
effectiveDate	The start date and time.
invalidDate	The end date and time.
success	The success callback.
failure	The failure callback.

API description

This API method is available to the locks of pro edition.

- (void)createProLockMemberWithHomeId:(long long)homeId
                         requestModel:(ThingSmartHomeAddMemberRequestModel *)requestModel
                              success:(ThingSuccessDict)success
                              failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
homeId	The name of the member.
requestModel	See Home Member Management.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

    [self.lock addMemberWithUserName:#<Member name># allowUnlock:YES timeType:ThingMemberTimeTypePhase effectiveDate:[NSDate date] invalidDate:[[NSDate date] dateByAddingTimeInterval:60 * 60 * 8] success:^(BOOL result) {
        NSLog(@"Lock member created.");
    } failure:^(NSError *error) {
        NSLog(@"Failed to create lock member, error: %@", error);
    }];

Swift:

    self.lock?.addMember(withUserName: "name", allowUnlock: true, timeType: .phase, effectiveDate: Date(), invalidDate: Date().addingTimeInterval(60 * 60 * 8), success: { (result) in
        print("Lock member created.")
    }, failure: { (error) in
        if let e = error {
            print("Failed to create lock member, error: \(e)")
        }
    })

Modify member information

Modifies information about a lock member. This requires a Bluetooth connection between the app and the lock to sync data.

API description

This API method is available to the legacy standard locks.

- (void)updateMemberWithUserName:(NSString *)userName
                        memberId:(NSString *)memberId
                     allowUnlock:(BOOL)allowUnlock
                        timeType:(ThingMemberTimeType)timeType
                   effectiveDate:(NSDate *)effectiveDate
                     invalidDate:(NSDate *)invalidDate
                         success:(nullable ThingSuccessBOOL)success
                         failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
userName	The name of the member.
memberId	The member ID.
allowUnlock	Specifies whether the member can unlock over Bluetooth.
timeType	The validity period. ThingMemberTimeTypePermanent: Permanent. ThingMemberTimeTypePhase: Timed.
effectiveDate	The start date and time.
invalidDate	The end date and time.
success	The success callback.
failure	The failure callback.

API description

This API method is available to the locks of pro edition.

- (void)updateProLockMemberInfoWithRequestModel:(ThingSmartHomeMemberRequestModel *)memberRequestModel
                                        success:(ThingSuccessHandler)success
                                        failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
memberRequestModel	See Home Member Management.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

    [self.lock updateMemberWithUserName:@"new name" memberId:@"0000008byw" allowUnlock:YES timeType:ThingMemberTimeTypePermanent effectiveDate:[NSDate date] invalidDate:[[NSDate date] dateByAddingTimeInterval:60 * 60 * 8] success:^(BOOL result) {
        NSLog(@"Lock member updated");
    } failure:^(NSError *error) {
        NSLog(@"Failed to create lock member, error: %@", error);
    }];

Swift:

    self.lock?.updateMember(withUserName: "new name", memberId: "0000008byw", allowUnlock: true, timeType: .phase, effectiveDate: Date(), invalidDate: Date().addingTimeInterval(60 * 60 * 8), success: { (result) in
            print("Lock member information updated")
        }, failure: { (error) in
            if let e = error {
                print("Failed to update lock member information, error: \(e)")
            }
        })

Delete a lock member

API description

This API method is available to the legacy standard locks.

- (void)removeMemberWithMemberId:(NSString *)memberId
                         success:(nullable ThingSuccessBOOL)success
                         failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
memberId	The member ID.
success	The success callback.
failure	The failure callback.

API description

This API method is available to the locks of pro edition.

- (void)removeProLockMemberWithUserId:(NSString *)userId
                              isAdmin:(BOOL)isAdmin
                              success:(ThingSuccessHandler)success
                              failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
userId	The user ID.
isAdmin	Specifies whether the user is an admin.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

    [self.lock removeMemberWithMemberId:@"000000747d" success:^(BOOL result) {
        NSLog(@"Lock member deleted");
    } failure:^(NSError *error) {
        NSLog(@"Failed to delete lock member, error: %@", error);
    }];

Swift:

    self.lock?.removeMember(withMemberId: "", success: { (result) in
        print("Lock member deleted")
    }, failure: { (error) in
        if let e = error {
            print("Failed to delete lock member, error: \(e)")
        }
    })

Modify validity period of a member (legacy not supported)

Modifies the validity period of a lock member. This requires a Bluetooth connection between the app and the lock to sync data.

API description

This API method is available to the locks of pro edition.

- (void)updateProLockMemberTimeWithDevId:(NSString *)devId
                                memberId:(NSString *)memberId
                           offlineUnlock:(BOOL)offlineUnlock
                                 isAdmin:(BOOL)isAdmin
                           effectiveDate:(nullable NSDate *)effectiveDate
                             invalidDate:(nullable NSDate *)invalidDate
                                schedule:(ThingSmartBLELockTimeScheduleInfo *)scheduleInfo
                                 success:(ThingSuccessID)success
                                 failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
memberId	The member ID.
offlineUnlock	Indicates whether offline unlocking is supported.
isAdmin	Specifies whether the user is an admin.
effectiveDate	The start date and time.
invalidDate	The end date and time.
scheduleInfo	The validity information.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

  // Request parameter query. See the demo for details.
    [self.bleDevice updateProLockMemberTimeWithDevId:self.bleDevice.deviceModel.devId
                                            memberId:[self.dataSource[@"userId"] stringValue]
                                       offlineUnlock:NO
                                             isAdmin:isAdmin
                                       effectiveDate:[self.timeView getEffectiveData]
                                         invalidDate:[self.timeView getInvalidData]
                                            schedule:[self.timeView getScheduleInfo]
                                             success:^(id result) {
                NSLog(@"Validity period updated");
    } failure:^(NSError *error) {
                 NSLog(@"Failed to update validity period");
    }];

Get current user information

API description

This API method is available to the legacy standard locks.

- (void)getCurrentMemberDetailWithDevId:(NSString *)devId
                                    gid:(long long)gid
                                success:(nullable ThingSuccessDict)success
                                failure:(nullable ThingFailureError)failure;

API description

This API method is available to the locks of pro edition.

- (void)getProCurrentMemberDetailWithDevId:(NSString *)devId
                                   success:(nullable ThingSuccessDict)success
                                   failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.bleDevice getCurrentMemberDetailWithDevId:self.devId gid:self.bleDevice.deviceModel.homeId success:^(NSDictionary *dict) {
		NSLog(@"Current user information obtained");
} failure:^(NSError *error) {
		NSLog(@"Failed to obtain current user information");
}];

Bluetooth connection

To access the full features of a Bluetooth lock, the user must turn on Bluetooth.

Query Bluetooth connection status

To access the full features of a Bluetooth lock, the user must turn on Bluetooth. Typically, the SDK automatically connects to the device over Bluetooth. You can use the following method to check the connection status.

/// Check if the device and mobile phone are connected over Bluetooth. If the result is NO, call autoConnect to connect.
- (BOOL)isBLEConnected;

/// Check device connection status (check if the gateway is online).
- (BOOL)isOnline;

Connect to Bluetooth lock

If the lock is not connected to the app over Bluetooth, call this method to connect.

/// If the app and device are not connected or are disconnected during the operation, call this method to connect.
- (void)autoConnect;

Unlock and lock over Bluetooth

Unlock within short range

API description

- (void)bleUnlock:(NSString *)lockUserId
          success:(ThingSuccessHandler)success
          failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
status	Unlock or lock.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

    ThingSmartBLELockDevice *lock = [ThingSmartBLELockDevice deviceWithDeviceId:@"your_lock_device_id"];
    [lock bleCurrentMemberDetailWithDevId:self.devId gid:self.lock.deviceModel.homeId success:^(NSDictionary *dict) {
                NSString *bleUnlock = [dict objectForKey:@"lockUserId"];
                [self.bleLockDevice bleUnlock:bleUnlock success:^{
                    NSLog(@"Door is unlocked");
                } failure:^(NSError *error) {
                    NSLog(@"Failed to unlock the door");
                }];
            } failure:^(NSError *error) {
                NSLog(@"bleCurrentMemberDetailWithDevId failure!");
            }];

Swift:

lock.bleCurrentMemberDetail(withDevId: devId, gid: lock.deviceModel.homeId, success: { [self] dict in
    let bleUnlock = dict?["lockUserId"] as? String
    bleLockDevice.bleUnlock(bleUnlock, success: {
        print("Door is unlocked");
    }, failure: { error in
        print("Failed to unlock the door");
    })
}, failure: { error in
    print("bleCurrentMemberDetailWithDevId failure!")
});

Lock within short range

API description

- (void)bleManualLock:(ThingSuccessHandler)success
              failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
success	The success callback.
failure	The failure callback.

Example

Objective-C:

    ThingSmartBLELockDevice *lock = [ThingSmartBLELockDevice deviceWithDeviceId:@"your_lock_device_id"];
    [lock bleManualLock:^{
                NSLog(@"Door is locked");
            } failure:^(NSError *error) {
                NSLog(@"Failed to lock the door: %ld", error.code);
            }];

Swift:

    let lockDevice = ThingSmartBLELockDevice(deviceId: "your_lock_device_id")
    self.lock?.manualLock(withStatus: status, success: {
        print("Door is locked")
    }, failure: { (error) in
        if let e = error {
            print("Failed to lock the door, error: \(e)")
        }
    })

Lock and unlock remotely

API description

//Remote unlocking
- (void)remoteSwitchLock:(ThingSuccessBOOL)success
                 failure:(ThingFailureError)failure;
//Remote locking
- (void)manualLockWithStatus:(ThingSuccessHandler)success
                     failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
success	The success callback.
failure	The failure callback.

Example

Objective-C:

  ThingSmartBLELockDevice *lock = [ThingSmartBLELockDevice deviceWithDeviceId:@"your_lock_device_id"];
  [lock remoteSwitchLock:^{
              NSLog(@"Remote unlocking succeeds");
          } failure:^(NSError *error) {
              NSLog(@"Remote unlocking fails: %ld", error.code);
          }];

  [lock manualLockWithStatus:^{
              NSLog(@"Remote locking succeeds");
          } failure:^(NSError *error) {
              NSLog(@"Remote locking fails: %ld", error.code);
          }];

Lock records

Get alert records

API description

- (void)getAlarmRecordListWithOffset:(int)offset
                               limit:(int)limit
                             success:(nullable void(^)(NSArray<ThingSmartLockRecordModel *> *records))success
                             failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
offset	The total number of returned pages.
limit	The total number of returned entries.
success	The success callback. The record list is returned.
failure	The failure callback.

Data model of ThingSmartLockRecordModel

Field	Type	Description
userId	NSString	The member ID.
userName	NSString	The nickname of the user.
time	NSTimeInterval	The 13-digit timestamp when the record was generated.
devId	NSString	The device ID.
dpData	NSDictionary	The DP data.
tags	NSInteger	The flag of the record. 0: Other types. 1: Duress alarm.
dpsArray	NSArray<NSDictionary *>	An array of DPs.

Example

Objective-C:

    [self.lock getAlarmRecordListWithOffset:0 limit:50 success:^(NSArray<ThingSmartLockRecordModel *> * _Nonnull records) {
        NSLog(@"Alert records: %@", records);
    } failure:^(NSError *error) {
        NSLog(@"Failed to query alert records, error: %@", error);
    }];

Swift:

    self.lock?.getAlarmRecordList(withOffset: 0, limit: 50, success: { (records) in
        print("Alert records \(records)")
    }, failure: { (error) in
        if let e = error {
            print("Failed to query alert records, error: \(e)")
        }
    })

Get unlocking records

API description

- (void)getUnlockRecordListWithOffset:(int)offset
                                limit:(int)limit
                              success:(nullable void(^)(NSArray<ThingSmartBLELockRecordModel *> *records))success
                              failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
offset	The total number of returned pages.
limit	The total number of returned entries.
success	The success callback. The record list is returned.
failure	The failure callback.

Example

Objective-C:

    [self.lock getUnlockRecordListWithOffset:0 limit:50 success:^(NSArray<ThingSmartLockRecordModel *> * _Nonnull records) {
        NSLog(@"Unlocking records: %@", records);
    } failure:^(NSError *error) {
        NSLog(@"Failed to query unlocking records, error: %@", error);
    }];

Swift:

    self.lock?.getUnlockRecordList(withOffset: 0, limit: 50, success: { (records) in
        print("Unlocking records \(records)")
    }, failure: { (error) in
        if let e = error {
            print("Failed to query unlocking records, error: \(e)")
        }
    })

Get duress alarm records

API description

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

Parameter description

Parameters	Description
dpCodes	The DP code for duress alarms.
offset	The total number of returned pages.
limit	The total number of returned entries.
success	The success callback. The record list is returned.
failure	The failure callback.

Query records with filter (log component)

API description

- (void)getProUnlockRecordListWithDevId:(NSString *)devId
                          logCategories:(NSString *)logCategories
                                userIds:(NSString *)userIds
                    onlyShowMediaRecord:(BOOL)onlyShowMediaRecord
                              startTime:(NSInteger)startTime
                                endTime:(NSInteger)endTime
                             lastRowKey:(NSString *)lastRowKey
                                  limit:(NSInteger)limit
                                success:(ThingSuccessID)success
                                failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The total number of returned pages.
logCategories	The log category. operation: Operation records. unlock_record: Unlocking records. close_record: Locking records. alarm_record: Alert records.
userIds	The list of user IDs to be returned, separated with commas (,). Example: 12,13.
onlyShowMediaRecord	Indicates whether only log entries with image or video are returned. Default value: False, returning all log entries.
startTime	The start time, in milliseconds.
endTime	The end time, in milliseconds.
lastRowKey	The row key of the last entry returned on the previous page.
limit	The maximum number of entries returned on each page.
success	The success callback.
failure	The failure callback.

The return data:

Field	Type	Description
hasNext	Boolean	Indicates whether the entries are returned on pages.
lastRowKey	String	The row key of the last entry returned on the previous page.
records	List	The list of records. See the table below for information about a single record.

A single record

Field	Type	Required	Description
logId	Long	Yes	The log ID.
logCategory	String	Yes	The log type. operation: Operation records. unlock_record: Unlocking records. close_record: Locking records. alarm_record: Alert records.
logType	String	Yes	The log type. For more information, see Appendix.
recordType	Integer	No	Only unlocking records are returned. Unlocking Alert
unlockNameRosettaKey	String	No	The type of locking record. For more information, see Appendix.
currentUser	Boolean	No	Indicates whether the record belongs to the current user. If so, the value is true. This parameter is required for non-combined unlocking methods.
userId	String	No	The user ID, required only for unlocking records, duress alarms, and operation records.
userName	String	No	The username.
memberBindableFlag	Boolean	Yes	Indicates whether the record can be bound with the member.
unlockName	String	No	The name of the unlocking method, which can be empty.
time	Long	Yes	The time when the event occurs.
relateDevName	String	No	The name of the associated device.
relateOpMode	String	No	The details of the associated unlocking method.
data	String	Yes	The operation records. For more information, see Appendix.
unionUnlockInfo	UnionUnlockInfo	No	The information about combined unlocking methods.
mediaInfoList	List	No	The information about video and image. This parameter applies to smart video locks and low power Wi-Fi keep-alive locks with video or image features. For more information, see MediaInfoBean.

Example

Objective-C:

    [self.bleDevice getProUnlockRecordListWithDevId:self.bleDevice.deviceModel.devId
                                          logCategories:self.logCategories
                                                userIds:self.userIds
                                    onlyShowMediaRecord:NO
                                              startTime:self.startTime
                                                endTime:self.endTime
                                             lastRowKey:@""
                                                  limit:50
                                                success:^(id result) {
            NSLog(@"Log query succeeds");
        } failure:^(NSError *error) {
            NSLog(@"Log query fails");
        }];

Unlocking methods

Get the list of bound unlocking methods

API description

- (void)getProBoundUnlockOpModeListWithDevId:(NSString *)devId
                                      userId:(NSString *)userId
                                     success:(ThingSuccessID)success
                                     failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
userId	The member ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.bleDevice getProBoundUnlockOpModeListWithDevId:self.bleDevice.deviceModel.devId
                                                  userId:[self.dataSource[@"userId"] stringValue]
                                                 success:^(id result) {
                NSLog(@"List request succeeds");
    } failure:^(NSError *error) {
                NSLog(@"List request fails");
    }];

Determine unlocking methods to be assigned

API description

- (void)isProNeedAllocUnlockOpModeWithDevId:(NSString *)devId
                                    success:(ThingSuccessID)success
                                    failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.bleDevice isProNeedAllocUnlockOpModeWithDevId:self.bleDevice.deviceModel.devId
                                                success:^(id result) {
                NSLog(@"Method request succeeds");
    } failure:^(NSError *error) {
                NSLog(@"Method request fails");
    }];

Query unlocking methods not bound with member

API description

- (void)getProUnboundUnlockOpModeListWithDevId:(NSString *)devId
                                       success:(ThingSuccessID)success
                                       failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.bleDevice getProUnboundUnlockOpModeListWithDevId:self.bleDevice.deviceModel.devId
                                                   success:^(id result) {
                NSLog(@"List query succeeds");
    } failure:^(NSError *error) {
                NSLog(@"List query fails");
    }];

Assign unlocking method to user

API description

- (void)allocProUnlockOpModeWithDevId:(NSString *)devId
                               userId:(NSString *)userId
                            unlockIds:(NSString *)unlockIds
                              success:(ThingSuccessID)success
                              failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
userId	The member ID.
unlockIds	The ID of the unlocking method.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

//userId: The userId assigned to the member. unlockIds: The ID of the unlocking method.
    [self.bleDevice allocProUnlockOpModeWithDevId:self.bleDevice.deviceModel.devId
                                           userId:userId
                                        unlockIds:@[unlockId].thingsdk_JSONString
                                          success:^(id result) {
        NSLog(@"Assigned successfully");
    } failure:^(NSError *error) {
                 NSLog(@"Failed to assign");
    }];

Add unlocking method on the app

Adds a generic unlocking method. The app must be connected to the lock over Bluetooth during the operation.

API description

- (void)addUnlockOpmodeForMemberWithMemberId:(NSString *)memberId
                                     isAdmin:(BOOL)isAdmin
                                unlockDpCode:(NSString *)unlockDpCode
                                unlockOpType:(ThingUnlockOpType)unlockOpType
                                  unlockName:(NSString *)unlockName
                               effectiveDate:(nullable NSDate *)effectiveDate
                                 invalidDate:(nullable NSDate *)invalidDate
                                       times:(int)times
                                  dataLength:(int)dataLength
                                 dataContent:(NSString *)dataContent
                                     timeout:(NSTimeInterval)timeout
                               needHijacking:(BOOL)needHijacking
                                     success:(nullable ThingSuccessString)success
                                     failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
memberId	The member ID.
isAdmin	Specifies whether the user is an admin.
unlockDpCode	The identifier of the unlocking method. For more information, see List of Lock DPs. For example, unlock_card represents unlocking with card.
unlockOpType	The unlocking method. For more information, see the enum values of ThingUnlockOpType.
unlockName	The name of the unlocking method.
effectiveDate	The start date and time.
invalidDate	The end date and time.
times	The maximum number of times the unlocking method can be used.
dataLength	The data length. It must be the same as the length of data content.
dataContent	The payload.
timeout	The timeout value for a response. During the interaction with users, such as fingerprint operations, this parameter is not required.
needHijacking	Specifies whether to enable duress alarms.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

    [self.lock addUnlockOpmodeForMemberWithMemberId:@"00000074zg"
                                            isAdmin:NO
                                       unlockDpCode:@"unlock_password"
                                       unlockOpType:ThingUnlockOpTypePassword
                                         unlockName:@"Password: 774641"
                                      effectiveDate:nil
                                        invalidDate:nil
                                              times:10
                                         dataLength:6
                                        dataContent:@"774641"
                                            timeout:6
                                      needHijacking:YES
                                            success:^(NSString *result) {
        NSLog(@"Added successfully");
    } failure:^(NSError *error) {
        NSLog(@"Failed to add %@", error);
    }];

Swift:

    self.lock?.addUnlockOpmodeForMember(withMemberId: "00000074zg", isAdmin: false, unlockDpCode: "unlock_password", unlockOpType: ThingUnlockOpTypePassword, unlockName: "Password 774641", effectiveDate: nil, invalidDate: nil, times: 10, dataLength: 6, dataContent: "774641", timeout: 5, needHijacking: true, success: { (result) in
         print("Added successfully")
    }, failure: { (error) in
        if let e = error {
            print("Failed to add, error: \(e)")
        }
    })

Update unlocking method on the app

Modifies a generic unlocking method. The app must be connected to the lock over Bluetooth during the operation.

API description

- (void)modifyUnlockOpmodeForMemberWithMemberId:(NSString *)memberId
                                       opmodeId:(NSString *)opmodeId
                                        isAdmin:(BOOL)isAdmin
                                     firmwareId:(int)firmwareId
                                   unlockDpCode:(NSString *)unlockDpCode
                                   unlockOpType:(ThingUnlockOpType)unlockOpType
                                     unlockName:(NSString *)unlockName
                                  effectiveDate:(nullable NSDate *)effectiveDate
                                    invalidDate:(nullable NSDate *)invalidDate
                                          times:(int)times
                                     dataLength:(int)dataLength
                                    dataContent:(NSString *)dataContent
                                        timeout:(NSTimeInterval)timeout
                                  needHijacking:(BOOL)needHijacking
                                        success:(nullable ThingSuccessBOOL)success
                                        failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
memberId	The member ID.
opmodeId	The unlocking method ID. You can get the value from the list of unlocking methods.
isAdmin	Specifies whether the user is an admin.
firmwareId	The hardware ID.
unlockDpCode	The identifier of the unlocking method. For more information, see List of Lock DPs. For example, unlock_card represents unlocking with card.
unlockOpType	The unlocking method. For more information, see the enum values of ThingUnlockOpType.
unlockName	The name of the unlocking method.
effectiveDate	The start date and time.
invalidDate	The end date and time.
times	The maximum number of times the unlocking method can be used.
dataLength	The data length. It must be the same as the length of data content.
dataContent	The payload.
timeout	The timeout value for a response. During the interaction with users, such as fingerprint operations, this parameter is not required.
needHijacking	Specifies whether to enable duress alarms.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

    [self.lock modifyUnlockOpmodeForMemberWithMemberId:@"00000074zg"
                                              opmodeId:@"232323"
                                               isAdmin:NO
                                            firmwareId:15 //The opmodevalue from the unlocking method data.
                                          unlockDpCode:@"unlock_password"
                                          unlockOpType:ThingUnlockOpTypePassword
                                            unlockName:@"Password 774641"
                                         effectiveDate:nil
                                           invalidDate:nil
                                                 times:10
                                            dataLength:6
                                           dataContent:@"774641"
                                               timeout:6
                                         needHijacking:YES
                                               success:^(NSString *result) {
        NSLog(@"Updated successfully");
    } failure:^(NSError *error) {
        NSLog(@"Failed to update %@", error);
    }];

Swift:

    self.lock?.modifyUnlockOpmodeForMember(withMemberId: "00000074zg", opmodeId: "232323", isAdmin: false, firmwareId: 15, unlockDpCode: "unlock_password", unlockOpType: ThingUnlockOpTypePassword, unlockName: "Password 774641", effectiveDate: nil, invalidDate: nil, times: 10, dataLength: 6, dataContent: "774641", timeout: 5, needHijacking: true, success: { (result) in
        print("Updated successfully")
    }, failure: { (error) in
        if let e = error {
            print("Failed to update, error: \(e)")
        }
    })

Delete unlocking method on the app

API description

- (void)removeUnlockOpmodeForMemberWithOpmodeModel:(ThingSmartBLELockOpmodeModel *)opmodeModel
                                           isAdmin:(BOOL)isAdmin
                                      unlockDpCode:(NSString *)unlockDpCode
                                      unlockOpType:(ThingUnlockOpType)unlockOpType
                                           timeout:(NSTimeInterval)timeout
                                           success:(ThingSuccessHandler)success
                                           failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
opmodeModel	The model of the unlocking method.
isAdmin	Specifies whether the user is an admin.
unlockDpCode	The identifier of the unlocking method. For more information, see List of Lock DPs. For example, unlock_card represents unlocking with card.
unlockOpType	The unlocking method. For more information, see the enum values of ThingUnlockOpType.
timeout	The timeout value for a response. During the interaction with users, such as fingerprint operations, this parameter is not required.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

    [self.lock removeUnlockOpmodeForMemberWithOpmodeModel:model
                                                  isAdmin:NO
                                             unlockDpCode:@"unlock_password"
                                             unlockOpType:ThingUnlockOpTypePassword
                                                  timeout:10
                                                  success:^{
        NSLog(@"Deleted successfully");
    } failure:^(NSError *error) {
        NSLog(@"Failed to delete %@", error);
    }]

Swift:

    self.lock?.removeUnlockOpmodeForMember(with: model, isAdmin: false, unlockDpCode: "unlock_password", unlockOpType: ThingUnlockOpTypePassword, timeout: 10, success: {
        print("Deleted successfully")
    }, failure: { (error) in
        if let e = error {
            print("Failed to delete, error: \(e)")
        }
    })

Cancel enrolling fingerprint on the app

API description

- (void)cancelUnlockOpmodeForFingerWithAdmin:(BOOL)isAdmin
                                  lockUserId:(int)lockUserId
                                     success:(nullable ThingSuccessBOOL)success
                                     failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
isAdmin	Specifies whether the user is an admin.
lockUserId	The user ID stored on the lock.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.bleDevice cancelUnlockOpmodeForFingerWithAdmin:isAdmin
                                          lockUserId:self.lockUserId
                                             success:^(BOOL result) {
		NSLog(@"Canceled successfully");
} failure:^(NSError *error) {
		NSLog(@"Failed to cancel");
}];

Query details of an unlocking method

API description

- (void)getProUnlockOpModeDetailWithDevId:(NSString *)devId
                                 opModeId:(NSString *)opModeId
                                  success:(ThingSuccessID)success
                                  failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
opModeId	The ID of an unlocking method.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.bleDevice getProUnlockOpModeDetailWithDevId:devId
                                         opModeId:opModeId
                                          success:^(id result) {
		NSLog(@"Queried successfully");
} failure:^(NSError *error) {
		NSLog(@"Failed to query");
}];

Set or cancel duress code

API description

- (void)addHijackingConfigWithDevId:(NSString *)devId
                               dpId:(NSString *)dpId
                            dpValue:(NSString *)dpValue
                            success:(ThingSuccessBOOL)success
                            failure:(nullable ThingFailureError)failure;

- (void)removeHijackingConfigWithDevId:(NSString *)devId
                                  dpId:(NSString *)dpId
                               dpValue:(NSString *)dpValue
                               success:(ThingSuccessID)success
                               failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
dpId	The DP ID.
dpValue	The DP value.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.bleDevice addHijackingConfigWithDevId:self.bleDevice.deviceModel.devId
                                       dpId:self.model.opmode
                                    dpValue:[self.dataSource[@"unlockId"] stringValue]
                                    success:^(BOOL result) {
		NSLog(@"Duress added");	
} failure:^(NSError *error) {
		NSLog(@"Failed to add duress");
}];

[self.bleDevice removeHijackingConfigWithDevId:self.bleDevice.deviceModel.devId
                                          dpId:self.model.opmode
                                       dpValue:[self.dataSource[@"unlockId"] stringValue]
                                       success:^(id result) {
		NSLog(@"Duress canceled");	
} failure:^(NSError *error) {
		NSLog(@"Failed to cancel duress");	
}];

Turn on/off unlocking method notification

For more information, see Update unlocking method on the app.

Password management

Create offline password

API description

This API method is available to the legacy standard locks.

- (void)getOfflinePasswordWithDevId:(NSString *)devId
                            pwdType:(NSString *)pwdType
                           gmtStart:(NSInteger)gmtStart
                         gmtExpired:(NSInteger)gmtExpired
                            pwdName:(NSString *)pwdName
                            success:(ThingSuccessID)success
                            failure:(nullable ThingFailureError)failure;

API description

This API method is available to the locks of pro edition.

- (void)getProOfflinePasswordWithDevId:(NSString *)devId
                               pwdType:(NSString *)pwdType
                              gmtStart:(NSInteger)gmtStart
                            gmtExpired:(NSInteger)gmtExpired
                               pwdName:(NSString *)pwdName
                               success:(ThingSuccessID)success
                               failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
pwdType	The type of the password. 0: Unlimited times 1: One-time 9: Clearing code
gmtStart	The start date and time. Set it to 0 if the password is not time-limited.
gmtExpired	The end date and time. Set it to 0 if the password is not time-limited.
pwdName	The name of the password.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

//One-time offline password
[self.bleDevice getOfflinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                            pwdType:@"1"
                                           gmtStart:0
                                         gmtExpired:0
                                            pwdName:@"One-time offline password"
                                            success:^(id result) {
                                    NSLog(@"Success");
        } failure:^(NSError *error) {
                                    NSLog(@"Error");
        }];

//Time-limited password for legacy standard locks
[self.bleDevice getOfflinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                            pwdType:@"0"
                                           gmtStart:effectiveTime
                                         gmtExpired:invalidTime
                                            pwdName:@"Time-limited password for legacy standard locks"
                                            success:^(id result) {
                                    NSLog(@"Success");
        } failure:^(NSError *error) {
                                    NSLog(@"Error");
        }];

//The code to clear all passwords (for legacy standard locks)
[self.bleDevice getOfflinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                            pwdType:@"9"
                                           gmtStart:0
                                         gmtExpired:0
                                            pwdName:@"The code to clear all passwords (for legacy standard locks)"
                                            success:^(id result) {
                                    NSLog(@"Success");
        } failure:^(NSError *error) {
                                    NSLog(@"Error");
        }];

//Pro One-time password
[self.bleDevice getProOfflinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                               pwdType:@"1"
                                              gmtStart:0
                                            gmtExpired:0
                                               pwdName:@"Pro One-time password"
                                               success:^(id result) {
                                    NSLog(@"Success");
        } failure:^(NSError *error) {
                                    NSLog(@"Error");
        }];

// Time-limited password for pro locks
[self.bleDevice getProOfflinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                               pwdType:@"0"
                                              gmtStart:effectiveTime
                                            gmtExpired:invalidTime
                                               pwdName:@"Time-limited password for pro locks"
                                               success:^(id result) {
                                    NSLog(@"Success");
        } failure:^(NSError *error) {
                                    NSLog(@"Error");
        }];

// The clearing code for pro locks.
[self.bleDevice getProOfflinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                               pwdType:@"9"
                                              gmtStart:0
                                            gmtExpired:0
                                               pwdName:@"The clearing code for pro locks"
                                               success:^(id result) {
                                    NSLog(@"Success");
        } failure:^(NSError *error) {
                                    NSLog(@"Error");
        }];

Get clearing code of an offline password

API description

This API method is available to the legacy standard locks.

- (void)getSingleRevokeOfflinePasswordWithDevId:(NSString *)devId
                                          pwdId:(NSInteger )pwdId
                                        success:(ThingSuccessID)success
                                        failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
pwdId	The ID of the password.
success	The success callback.
failure	The failure callback.

API description

This API method is available to the locks of pro edition.

- (void)getProSingleRevokeOfflinePasswordWithDevId:(NSString *)devId
                                   unlockBindingId:(NSInteger )unlockBindingId
                                              name:(NSString *)name
                                           success:(ThingSuccessID)success
                                           failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
unlockBindingId	The authorization ID of the password.
name	The name of the clearing code.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

// Legacy standard locks
[self.bleDevice getSingleRevokeOfflinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                                      pwdId:@"pwdId"
                                                    success:^(id result) {
        if (result && [result isKindOfClass:[NSDictionary class]]){
            NSString *pwdName = [result[@"pwdName"] stringValue];
            NSString *pwdValue = [result[@"pwd"] stringValue];
        }} failure:^(NSError *error) {
                        NSLog(@"Error");
    }];

//Pro
[self.bleDevice getProSingleRevokeOfflinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                                   unlockBindingId:[dicValue[@"unlockBindingId"] integerValue]
                                                              name:@"Clearing code"
                                                           success:^(id result) {
            if (result && [result isKindOfClass:[NSDictionary class]]){
                NSString *pwdName = [result[@"pwdName"] stringValue];
                NSString *pwdValue = [result[@"pwd"] stringValue];
            }
        }failure:^(NSError *error) {
                        NSLog(@"Error");
        }];

Get valid time-limited offline password

Returns the password that can be deleted with clearing code.

API description

- (void)getSingleRevokePasswordListWithDevId:(NSString *)devId
                                     success:(ThingSuccessID)success
                                     failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
success	The success callback.
failure	The failure callback.

Repeatedly validate temporary online password

API description

This API method is available to the legacy standard locks.

- (void)validateCustomPasswordWithDevId:(NSString *)devId
                                   name:(NSString *)name
                          effectiveTime:(NSInteger)effectiveTime
                            invalidTime:(NSInteger)invalidTime
                               password:(NSString *)password
                               schedule:(ThingSmartBLELockScheduleList *)schedule
                                success:(ThingSuccessID)success
                                failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
name	The name of the password.
effectiveTime	The start date and time.
invalidTime	The end date and time.
password	The password.
schedule	The schedule.
success	The success callback.
failure	The failure callback.

API description

This API method is available to the locks of pro edition.

- (void)validateProCustomPasswordWithDevId:(NSString *)devId
                                      name:(NSString *)name
                           unlockBindingId:(NSInteger)unlockBindingId
                             effectiveTime:(NSInteger)effectiveTime
                               invalidTime:(NSInteger)invalidTime
                                  password:(NSString *)password
                                  schedule:(NSString *)schedule
                                   success:(ThingSuccessID)success
                                   failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
name	The name of the password.
unlockBindingId	The ID of the temporary password, which is required for the request to update the password.
effectiveTime	The start date and time.
invalidTime	The end date and time.
password	The password.
schedule	The schedule.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

// Legacy standard locks
    ThingSmartBLELockScheduleList *schedule = [[ThingSmartBLELockScheduleList alloc] init];//schedule, include your schedule data
    NSString *scheduleString = [schedule getJsonStringFromScheduleList];
    [self.lockDeviceService validateCustomPasswordWithDevId:devId
                                                       name:name
                                              effectiveTime:effectiveTime
                                                invalidTime:invalidTime
                                                   password:password
                                                   schedule:scheduleString
                                                    success:^(id result) {
                        NSLog(@"Verified");
    } failure:^(NSError *error) {
                        NSLog(@"Error");
        }];

//Pro
    ThingSmartBLELockScheduleList *schedule = [[ThingSmartBLELockScheduleList alloc] init];//schedule, include your schedule data
    NSString *scheduleString = [schedule getJsonStringFromScheduleList];
    [self.lockDeviceService validateProCustomPasswordWithDevId:devId
                                                          name:name
                                               unlockBindingId:0
                                                 effectiveTime:effectiveTime
                                                   invalidTime:invalidTime
                                                      password:password
                                                      schedule:scheduleString
                                                       success:^(id result) {
                        NSLog(@"Verified");
    } failure:^(NSError *error) {
                        NSLog(@"Error");
        }];

Create a temporary online password

API description

This API method is available to the legacy standard locks. Custom passwords are the equivalent to the periodic passwords for legacy locks.

- (void)getCustomOnlinePasswordWithDevId:(NSString *)devId
                                    name:(NSString *)name
                           effectiveTime:(NSInteger)effectiveTime
                             invalidTime:(NSInteger)invalidTime
                                password:(NSString *)password
                                schedule:(ThingSmartBLELockScheduleList *)schedule
                               availTime:(NSInteger)availTime
                                      sn:(NSInteger)sn
                                 success:(ThingSuccessID)success
                                 failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
name	The name of the password.
effectiveTime	The start date and time.
invalidTime	The end date and time.
password	The password.
schedule	The schedule.
availTime	The number of times the password can be used. 0: Permanent 1: One-time
sn	The ID of the temporary password.
success	The success callback.
failure	The failure callback.

API description

This API method is available to the locks of pro edition.

- (void)getProCustomOnlinePasswordWithDevId:(NSString *)devId
                                       name:(NSString *)name
                                   password:(NSString *)password
                              effectiveTime:(NSInteger)effectiveTime
                                invalidTime:(NSInteger)invalidTime
                                  availTime:(NSInteger)availTime
                                         sn:(NSInteger)sn
                                   schedule:(ThingSmartBLELockScheduleList *)schedule
                                    success:(ThingSuccessID)success
                                    failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
name	The name of the password.
password	The password.
effectiveTime	The start date and time.
invalidTime	The end date and time.
availTime	The number of times the password can be used.
sn	The ID of the temporary password.
schedule	The schedule.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

        // One-time password for legacy standard locks
        ThingSmartBLELockScheduleList *listModel = [[ThingSmartBLELockScheduleList alloc] init];
    [self.bleDevice getCustomOnlinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                                         name:name
                                                effectiveTime:effectiveTime
                                                  invalidTime:invalidTime
                                                     password:password
                                                     schedule:listModel
                                                    availTime:1
                                                           sn:0
                                                      success:^(id result) {
                        NSLog(@"Created successfully");
            } failure:^(NSError *error) {
                            NSLog(@"Failed to create");
            }];

         // Periodic password for legacy standard locks
            ThingSmartBLELockScheduleList *listModel = [self.cycleView getScheduleListModel];
            [self.bleDevice getCustomOnlinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                                         name:name
                                                effectiveTime:effectiveTime
                                                  invalidTime:invalidTime
                                                     password:password
                                                     schedule:listModel
                                                    availTime:0
                                                           sn:0
                                                      success:^(id result) {
                        NSLog(@"Created successfully");
            } failure:^(NSError *error) {
                                NSLog(@"Failed to create");
            }];

// Periodic password for pro locks.
    ThingSmartBLELockScheduleList *listModel = [self.cycleView getScheduleListModel];
            [self.bleDevice getProCustomOnlinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                                           name:name
                                                       password:password
                                                  effectiveTime:effectiveTime
                                                    invalidTime:invalidTime
                                                      availTime:0
                                                             sn:0
                                                       schedule:listModel
                                                        success:^(id result) {
                                NSLog(@"Created successfully");
            } failure:^(NSError *error) {
                                NSLog(@"Failed to create");
            }];

Modify temporary online password

API description

This API method is available to the legacy standard locks.

- (void)updateOnlinePasswordWithDevId:(NSString *)devId
                                 name:(NSString *)name
                             password:(NSString *)password
                                pwdId:(NSInteger )pwdId
                        effectiveTime:(NSInteger)effectiveTime
                          invalidTime:(NSInteger)invalidTime
                             schedule:(ThingSmartBLELockScheduleList *)schedule
                                   sn:(NSInteger)sn
                            availTime:(NSInteger)availTime
                              success:(ThingSuccessID)success
                              failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The product ID.
name	The name of the password.
password	The password.
pwdId	The ID of the password.
effectiveTime	The start date and time.
invalidTime	The end date and time.
schedule	The schedule.
sn	The hardware ID.
availTime	The number of times the password can be used.
success	The success callback.
failure	The failure callback.

API description

This API method is available to the locks of pro edition.

- (void)updateProOnlinePasswordWithDevId:(NSString *)devId
                                    name:(NSString *)name
                                password:(NSString *)password
                         unlockBindingId:(NSInteger )unlockBindingId
                           effectiveTime:(NSInteger)effectiveTime
                             invalidTime:(NSInteger)invalidTime
                                   phase:(NSInteger)phase
                                schedule:(ThingSmartBLELockScheduleList *)schedule
                                      sn:(NSInteger)sn
                                 success:(ThingSuccessID)success
                                 failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
productId	The product ID.
name	The name of the password.
password	The password.
unlockBindingId	The ID of the temporary password.
effectiveTime	The start date and time.
invalidTime	The end date and time.
phase	2: Normal 4: Frozen
schedule	The schedule.
sn	The hardware ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

// Legacy standard locks
ThingSmartBLELockScheduleList *listModel = [[ThingSmartBLELockScheduleList alloc] init];
            [self.bleDevice updateOnlinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                                     name:name
                                                 password:@""
                                                    pwdId:pwdId
                                            effectiveTime:effectiveTime
                                              invalidTime:invalidTime
                                                 schedule:listModel
                                                       sn:sn
                                                availTime:1
                                                  success:^(id result) {
                            NSLog(@"Updated successfully");
            } failure:^(NSError *error) {
                            NSLog(@"Failed to update");
            }];
//Pro
ThingSmartBLELockScheduleList *listModel = [[ThingSmartBLELockScheduleList alloc] init];
            [self.bleDevice updateProOnlinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                                        name:name
                                                    password:@""
                                             unlockBindingId:unlockBindingId
                                               effectiveTime:effectiveTime
                                                 invalidTime:invalidTime
                                                       phase:2
                                                    schedule:listModel
                                                          sn:1
                                                     success:^(id result) {
                            NSLog(@"Updated successfully");
            } failure:^(NSError *error) {
                            NSLog(@"Failed to update");
            }];

Delete an online temporary password

API description

This API method is available to the legacy standard locks.

- (void)deleteOnlinePasswordWithDevId:(NSString *)devId
                                pwdId:(NSInteger )pwdId
                                   sn:(NSInteger)sn
                              success:(ThingSuccessID)success
                              failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
productId	The product ID.
pwdId	The ID of the password.
sn	The hardware ID.
success	The success callback.
failure	The failure callback.

API description

This API method is available to the locks of pro edition.

- (void)deleteProOnlinePasswordWithDevId:(NSString *)devId
                         unlockBindingId:(NSInteger )unlockBindingId
                                      sn:(NSInteger)sn
                                 success:(ThingSuccessID)success
                                 failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
productId	The product ID.
unlockBindingId	The ID of the temporary password.
sn	The hardware ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

// Legacy standard locks
[self.bleDevice deleteOnlinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                                    pwdId:pwdId
                                                       sn:sn
                                                  success:^(id result) {
                            NSLog(@"Deleted successfully");
        } failure:^(NSError *error) {
                            NSLog(@"Failed to delete");
        }];
//Pro
[self.bleDevice deleteProOnlinePasswordWithDevId:self.bleDevice.deviceModel.devId
                                             unlockBindingId:unlockBindingId
                                                          sn:sn
                                                     success:^(id result) {
                            NSLog(@"Deleted successfully");
        } failure:^(NSError *error) {
                            NSLog(@"Failed to delete");
        }];

Get the list of offline passwords (for legacy)

This API method is available to the legacy standard locks.

API description

- (void)getOfflinePasswordListWithDevId:(NSString *)devId
                                pwdType:(NSString *)pwdType
                                 status:(NSInteger)status
                                 offset:(NSInteger)offset
                                  limit:(NSInteger)limit
                                success:(ThingSuccessID)success
                                failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
pwdType	The type of the password. 0: Time-limited password 1: One-time password 8: Code to delete a specific password 9: Clearing code
status	The status of the temporary password. 1: Valid 0: Invalid
offset	The page number.
limit	The maximum number of entries returned per page. Default value: 50.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

// Query one-time offline passwords for legacy standard locks
[self.bleDevice getOfflinePasswordListWithDevId:self.bleDevice.deviceModel.devId
                                                    pwdType:@"1"
                                                     status:1
                                                     offset:0
                                                      limit:20
                                                    success:^(id result) {
            NSLog(@"List query succeeds");
        } failure:^(NSError *error) {
            NSLog(@"List query fails");
        }];
// Query time-limited offline passwords for legacy standard locks.
[self.bleDevice getOfflinePasswordListWithDevId:self.bleDevice.deviceModel.devId
                                                    pwdType:@"0"
                                                     status:1
                                                     offset:0
                                                      limit:20
                                                    success:^(id result) {
            NSLog(@"List query succeeds");
        } failure:^(NSError *error) {
            NSLog(@"List query fails");
        }];

// Query the clearing code (empty all passwords) for legacy standard locks.
[self.bleDevice getOfflinePasswordListWithDevId:self.bleDevice.deviceModel.devId
                                                    pwdType:@"9"
                                                     status:1
                                                     offset:0
                                                      limit:40
                                                    success:^(id result) {
            NSLog(@"List query succeeds");
        } failure:^(NSError *error) {
            NSLog(@"List query fails");
        }];

// Query the clearing code (delete a password) for legacy standard locks.
[self.bleDevice getOfflinePasswordListWithDevId:self.bleDevice.deviceModel.devId
                                                    pwdType:@"9"
                                                     status:1
                                                     offset:0
                                                      limit:20
                                                    success:^(id result) {
            NSLog(@"List query succeeds");
        } failure:^(NSError *error) {
            NSLog(@"List query fails");
        }];

Get the list of temporary online passwords (for legacy)

This API method is available to the legacy standard locks.

API description

- (void)getOnlinePasswordListWithDevId:(NSString *)devId
                             availTime:(NSInteger)availTime
                               success:(ThingSuccessID)success
                               failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
availTime	The number of times the password can be used.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

// Query the list of online one-time passwords for legacy standard locks.
[self.bleDevice getOnlinePasswordListWithDevId:self.bleDevice.deviceModel.devId
                                                 availTime:1
                                                   success:^(id result) {
            NSLog(@"List query succeeds");
        } failure:^(NSError *error) {
            NSLog(@"List query fails");
        }];
// Query the list of online periodic passwords for legacy standard locks.
[self.bleDevice getOnlinePasswordListWithDevId:self.bleDevice.deviceModel.devId
                                                 availTime:0
                                                   success:^(id result) {
            NSLog(@"List query succeeds");
        } failure:^(NSError *error) {
            NSLog(@"List query fails");
        }];

Get the password list

This API method is available to the locks of pro edition.

API description

- (void)getProPasswordListWithDevId:(NSString *)devId
                          authTypes:(NSArray *)authTypes
                            success:(ThingSuccessID)success
                            failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
authTypes	The authorization type.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

// Query the list of online custom passwords.
[self.bleDevice getProPasswordListWithDevId:self.bleDevice.deviceModel.devId
                                              authTypes:@[@"LOCK_TEMP_PWD"]
                                                success:^(id result) {
            NSLog(@"List query succeeds");
        } failure:^(NSError *error) {
            NSLog(@"List query fails");
        }];
// Query the list of offline time-limited passwords, one-time passwords, and clearing code.
[self.bleDevice getProPasswordListWithDevId:self.bleDevice.deviceModel.devId
                                              authTypes:@[@"LOCK_OFFLINE_TEMP_PWD"]
                                                success:^(id result) {
            NSLog(@"List query succeeds");
        } failure:^(NSError *error) {
            NSLog(@"List query fails");
        }];

Create a dynamic password

API description

- (void)getLockDynamicPasswordWithSuccess:(nullable ThingSuccessString)success
                                  failure:(nullable ThingFailureError)failure;

Parameter description

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

Example

Objective-C:

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

Swift:

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

Get positional notation of password

Returns the positional notation and other configurations of a lock panel.

API description

- (void)getLockDeviceConfigWithProductId:(NSString *)productId
                                 options:(NSString *)options
                                 success:(ThingSuccessID)success
                                 failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
productId	The product ID.
options	The items to be queried, including uiContent, cloudDp, and powerCode.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

   [self.bleDevice getLockDeviceConfigWithProductId:self.bleLockDevice.deviceModel.productId
                                                     options:@"uiContent,cloudDp,powerCode"
                                                     success:^(id result) {
                                    NSLog(@"Success");
            } failure:^(NSError *error) {
                                    NSLog(@"Error");
            }];

Lock settings

Query on/off status of remote unlocking

API description

- (void)fetchRemoteUnlockTypeWithDevId:(NSString *)devId
                               success:(nullable ThingSuccessID)success
                               failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.bleDevice fetchRemoteUnlockTypeWithDevId:self.bleDevice.deviceModel.devId
                                           success:^(id result) {
        NSLog(@"Succeed %@", result);
    } failure:^(NSError *error) {
        NSLog(@"Fail %@", error);
    }];

Set on/off status of remote unlocking

API description

- (void)setRemoteUnlockTypeWithDevId:(NSString *)devId
                             propKvs:(NSString *)propKvs
                             success:(ThingSuccessID)success
                             failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
propKvs	The key-value pair. The key is UNLOCK_PHONE_REMOTE.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

NSString *dataStr = @"{\"UNLOCK_PHONE_REMOTE\":\"true\"}";
if (!value){
    dataStr = @"{\"UNLOCK_PHONE_REMOTE\":\"false\"}";
}
[self.bleDevice setRemoteUnlockTypeWithDevId:self.bleDevice.deviceModel.devId
                                     propKvs:dataStr
                                     success:^(id result) {
    NSLog(@"Set successfully %@", result);
} failure:^(NSError *error) {
    NSLog(@"Failed to set %@", error);
}];

Query on/off status of Google Voice password

API description

- (void)fetchRemoteVoiceUnlockWithDevId:(NSString *)devId
                                success:(ThingSuccessID)success
                                failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.bleDevice fetchRemoteVoiceUnlockWithDevId:self.bleDevice.deviceModel.devId
                                        success:^(id result) {
      NSLog(@"Query succeeds %@", result);
} failure:^(NSError *error) {
      NSLog(@"Query fails %@", error);
}];

Set Google Voice password

API description

- (void)setRemoteVoiceUnlockWithDevId:(NSString *)devId
                                 open:(BOOL)open
                                  pwd:(NSString *)pwd
                              success:(ThingSuccessID)success
                              failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
open	The on/off status.
pwd	The password.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.bleDevice setRemoteVoiceUnlockWithDevId:self.bleDevice.deviceModel.devId
                                             open:YES
                                              pwd:pwd
                                          success:^(id result) {
            NSLog(@"Set successfully %@", result);
} failure:^(NSError *error) {
            NSLog(@"Failed to set %@", error);
}];

Send locking setting DPs

Use the methods mentioned in Device Control.

Sync data

Sync random numbers, accessories, and records

Data is synced once after the app is launched and the device goes online. The offline password time, random numbers, and lock operation records will be synced. If data is not synced, unlocking is not allowed.

API description

- (void)publishSyncBatchDataSuccess:(ThingSuccessHandler)success
                            failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.bleDevice publishSyncBatchDataSuccess:^{
    NSLog(@"Data is sent");
} failure:^(NSError *error) {
    NSLog(@"Failed to send data");
}];

Query synced data content

Returns the payload of publishSyncBatchData, without any data exchange with the device.

API description

- (void)getSyncBatchDataWithDevId:(NSString *)devId
                          success:(ThingSuccessID)success
                          failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

[self.bleDevice getSyncBatchDataWithDevId:self.devId
                                  success:^(id result) {
    NSLog(@"Data query succeeds");
} failure:^(NSError *error) {
    NSLog(@"Data query fails");
}];

Sync unlocking methods

API description

- (void)syncDataWithDevId:(NSString *)devId
                    dpIds:(NSArray<NSString *> *)dpIds
                  success:(ThingSuccessID)success
                  failure:(nullable ThingFailureError)failure;

Parameter description

Parameters	Description
devId	The device ID.
dpIds	Returns the list of unlocking methods to be synced. The returned result is an array of numbers.
success	The success callback.
failure	The failure callback.

Example

Objective-C:

  [self.bleDevice syncDataWithDevId:self.bleDevice.deviceModel.devId
                              dpIds:@[@"12",@"13"]
                            success:^(id result) {
        NSLog(@"Sync succeeds");
  } failure:^(NSError *error) {
        NSLog(@"Sync fails");
  }];

Appendix

Types of locking records

Parse the returned operation records.

Type	Description
HISTORY_LOCK_UNDEFINED	Undefined locking type
HISTORY_LOCK_VOICE_REMOTE	Remote unlocking by voice
HISTORY_LOCK_APP_REMOTE	Remote unlocking via the app
HISTORY_LOCK_AUTO	Automatic locking
HISTORY_LOCK_LOCAL_MANUAL	Manual locking
HISTORY_LOCK_FITTINGS	Accessory-triggered locking
HISTORY_LOCK_App	Press and hold to lock via app
HISTORY_LOCK_GEO_FENCE	Geofence-triggered unlocking

Data formats of operation records

Parse the operation record data according to its type.

Feature	Data definition
Device binding	[<Operator name>, <Lock name>]
Temporary password	[<Temporary password name>, <start date>, <end date>, <Schedule (only one schedule allowed for standard locks) [<All-day access or not>, <Start time>, <End time>, <Working days>, <Time zone>]]
Validity period of user (multiple validity periods supported)	[<"Target user",Permanent or not>, <Start date>, <End date>, <Schedule (only one schedule allowed for standard locks) [All-day access or not>, <Start time>, <End time>, <Time zone]>] This definition does not apply to non-permanent users.
Add or delete an unlocking method	[<User ID>, <Username>, <Name of unlocking method>, <Type-unlock with card (standard DP)>]
Communication module insertion and ejection	[<Module type>]: 1 represents a Bluetooth LE and NB-IoT combo module.
Get an offline password	[<Offline password name,Start date and time,End date and time,Offline password type]>]. The offline password types include: 0: Time-limited password. 1: One-time password 8: Code to clear a specific password 9: Code to clear all used passwords
Rename an offline password	[<Old name>, <New name>, <Password type>]
Unlocking records	1: The ID of the unlocking method.

New version of log definitions

Type	Description
dev_bind	Device binding
member_schedule_update	Modify the validity period of a member
unlock_add	Add an unlocking method
unlock_del	Delete an unlocking method
temp_pwd_create	Add a temporary password
temp_pwd_del	Delete a temporary password
temp_pwd_meta_update	Modify the validity period of a temporary password
temp_pwd_name_update	Rename a temporary password
offline_pwd_achieve	Get a time-limited offline password
offline_pwd_clear_achieve	Get a code to clear all offline passwords
offline_pwd_clear_single_achieve	Get a code to clear a specific offline password
offline_pwd_name_update	Update the name of an offline temporary password
unlock_ble	Unlock over Bluetooth by button press
unlock_password	Unlock with password
unlock_temporary	Unlock with temporary password
unlock_dynamic	Unlock with dynamic password
unlock_offline_pd	Unlock with offline password
unlock_offline_clear	Report emptying all offline passwords
unlock_offline_clear_single	Report clearing a single offline password
unlock_fingerprint	Unlock with fingerprint
unlock_card	Unlock with card
unlock_key	Unlock with mechanical key
unlock_face	Unlock with face recognition
unlock_eye	Unlock with iris
unlock_hand	Unlock with palm print
unlock_finger_vein	Unlock with finger vein
unlock_double	Combined unlocking (without the user who unlocks the door)
unlock_double_kit	Combined unlocking (with the user who unlocks the door)
alarm_lock	Alert
hijack	Duress alarm
lock_record	Locking records
unlock_record_check	Accessory records
unlock_phone_remote	Record of remote unlocking via app
unlock_app	Record of unlocking via app (for legacy)
unlock_voice_remote	Record of unlocking via speaker
door_opened	Door opened
open_inside	Door opened from inside
timer_opened	Timer ON executed
timer_closed	Timer OFF executed
dev_communication_module_add	Module inserted or ejected

Standard DPs on lock

Type	Description
arming_switch	Arm away
unlock_switch	Multi-factor authentication
automatic_lock	Automatic locking
auto_lock_time	Delay for auto-locking
verify_lock_switch	Turn on/off locking check
do_not_disturb	Do not disturb (DND) mode
special_control	Special control
special_function	Special features
beep_volume	Prompt volume

Error codes

Error codes	Description
4000	Product definition error
4001	Username error
4002	Time error
4003	Device processing timeout
4004	Device disconnected

Sample

For more information, see Tuya iOS Cube App SDK Sample.