Bluetooth Lock

Last Updated on : 2024-03-04 03:06:15download

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 Smart Life App SDK. The Smart Lock SDK can be used to associate a lock password ID with a home member account. For more information, see Home Management.
  • Non-home members: an individual member 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.

AppCloudEnter information about member.Make API request to create user.Generate lock user ID and hardware member ID and Return the result.Process response and display processing result.AppCloudProcedure to create a lock member

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.

This API method only creates non-home members. For more information about home member management, see Home Management.

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.

CloudAppLockEnter new information about member.Create Bluetooth connection.Send command to update user information.Return the result.Make API request to update user.Return the result.Process response and display processing result.CloudAppLockProcedure to update a lock member

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

A Bluetooth connection between the app and the lock is required to delete all unlocking methods and passwords associated with the target member.

CloudAppLockConfirm to delete member.Create Bluetooth connection.Send command to delete user information.Return the result.Make API request to delete user.Return the result.Process response and display processing result.CloudAppLockProcedure to 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.

LockAppCloudDevice stays onlineUser submits the updated validity periodSend command to update validity period.Return the result.Update validity period in cloud.Return the result.Process response and display processing resultLockAppCloudModify validity period of a member

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

UserAppLockEnable Bluetooth and connect to lockTap unlock.Send command to unlock over Bluetooth.Receive command and unlock over Bluetooth.Return the result.Process response and display processing result.UserAppLockProcedure to unlock over Bluetooth

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

UserAppLockEnable Bluetooth and connect to lockTap lock.Send command to lock over Bluetooth.Receive command and lock over Bluetooth.Return the result.Process response and display processing result.UserAppLockProcedure to lock over Bluetooth

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

LockGatewayCloudAppUserConnect to gateway.Tap lock or unlock.Send request for locking or unlocking.Send command to lock or unlock.Receive command and lock or unlock.Return the result.Return the result.Return the result.Process response and display processing resultLockGatewayCloudAppUserLock 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.

CloudAppLockConfirm information about generic unlocking method.Create Bluetooth connection.Send command to add unlocking method.Return the result.Make API request to set duress alarms.Return the result.Process response and display processing result.CloudAppLockProcedure of adding generic unlocking method

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.

CloudAppLockConfirm new information about generic unlocking method.Create Bluetooth connection.Send command to update unlocking method.Return the result.Make API request to set duress alarms.Return the result.Process response and display processing result.CloudAppLockProcedure to modify generic unlocking method

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 Smart Life App SDK Sample.