Bluetooth Smart Lock

Last Updated on : 2023-06-28 02:13:47download

Functional description

Class name	Description
`ThingOptimusSdk`	Provides access to the Smart Lock SDK initialization feature and returns the lock management class.
`IThingLockManager`	The lock management class that is used to get different types of lock classes.
`IThingBleLockV2`	The Bluetooth lock class that includes all methods of Bluetooth locks.

Example

The following code block shows how to create a Bluetooth lock class based on a device ID.

// Initialize the SDK for only once.
ThingOptimusSdk.init(getApplicationContext());
// Get the `IThingLockManager` class.
IThingLockManager thingLockManager = ThingOptimusSdk.getManager(IThingLockManager.class);
// Create the `IThingBleLockV2` class.
IThingBleLockV2 thingLockDevice = thingLockManager.getBleLockV2(your_device_id);

Glossary

Term	Description
Duress alarms	The duress alert 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 alerts to be sent to a list of contacts. 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 alerts to be sent to a list of contacts.
Lock members	Lock members are home members, the same as that defined in the Smart Life App SDK. The Smart Lock SDK can be used to bind a lock password ID with a home member account. For more information, see Home Management.
lockUserId	A lockUserId is a member ID that the cloud assigns to a lock when you create a lock member. Each `lockUserId` indicates the member ID that is recorded in the firmware.
userId	A userId is the ID that the cloud assigns to a lock member when you create the member. Each `userId` is a unique ID of each user and is recorded in a database.
dpCode	An identifier of a data point (DP) for a device. Each DP is assigned a name and an identifier indicated by `dpCode`. For more information, see List of Lock DPs.
unlockId	An `unlockId` is the unlocking method ID that consists of an unlocking DP ID plus a lock ID. Example: `12-02`.

After the Smart Lock SDK is integrated, you must execute the unlocking methods mentioned in Sync data before the SDK can be used.

Lock members

This section describes the operations regarding home members.

Get a list of lock members

API description

/**
* Get a list of home members
*
* @param callback The callback.
*/
void getProLockMemberList(IThingResultCallback<ArrayList<MemberInfoBean>> callback);

Data model of MemberInfoBean

Field	Type	Description
userId	String	The user ID.
avatarUrl	String	The avatar URL of the user.
lockUserId	Integer	The user ID that is associated with the lock.
nickName	String	The nickname.
userType	Integer	The type of user. Valid values: `10`: administrator. `20`: common user. `50`: home owner.
backHomeNotifyAttr	Integer	Indicates whether to enable notifications of home member arrival. Valid values: `0`: no. `1`: yes.
userContact	String	The contact information of the member.
offlineUnlock	Boolean	Indicates whether to support offline unlocking. Valid values: `true`: yes `false`: no
unlockDetail	List	The list of unlocking methods that the user can use. For more information, see `Data model of UnlockDetail`.
timeScheduleInfo	TimeScheduleInfo	The validity period of the user.

Data model of TimeScheduleInfo

Field	Type	Description
permanent	Boolean	Indicates whether the user is a permanent user.
timeSetShifted	Boolean	Indicates whether the validity period of the non-permanent administrator has an offset.
userTimeSet	String	The hexadecimal validity period of the user.
effectiveTime	Integer	The 10-digit time when the validity period starts.
expiredTime	Integer	The 10-digit time when the validity period ends.
scheduleDetails	List	Indicates whether the validity period recurs weekly and the recurring interval. For more information, see `Data model of ScheduleBean`.

Data model of ScheduleBean

Field	Type	Description
workingDay	Integer	The working days. For more information, see Things to note.
allDay	Boolean	Indicates whether the setting is valid all the day.
effectiveTime	Integer	The start time in minutes. Example: To make the setting take effect at 8 o’clock in the morning on the current day, the value is 480= 8 × 60.
invalidTime	Integer	The end time in minutes. Example: To make the setting expire at 20 o’clock in the afternoon on the current day, the value is 1200= 20 × 60.
timeZoneId	String	The time zone information.

Data model of UnlockDetail

Field	Type	Description
dpId	Integer	The DP ID of the feature.
count	Integer	The number of unlocking methods.
unlockList	List	The list of unlocking methods. For more information, see `Data model of UnlockInfoBean`.

Data model of UnlockInfoBean

Field	Type	Description
unlockId	String	The ID of an unlocking method.
opModeId	Long	The ID of an unlocking method in the cloud.
unlockName	String	The name of an unlocking method.
unlockAttr	Integer	The attribute of an unlocking method. Valid values: `1`: with duress alarm `0`: no duress alarm
adminFlag	Boolean	Indicates whether the administrator’s fingerprint is used.
photoUnlock	Boolean	Indicates whether to capture when unlocking. This field is supported by camera locks only.

Example

thingLockDevice.getProLockMemberList(new IThingResultCallback<ArrayList<MemberInfoBean>>() {
    @Override
    public void onSuccess(ArrayList<MemberInfoBean> result) {
        Log.i(Constant.TAG, "getProLockMemberList success: lockUserBean = " + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "getProLockMemberList failed: code = " + code + " message = " + message);
    }
});

Create a lock member

Creates a home member as a lock member. An account of the app must be created for the home member.

API description

/**
* Adds a home member.
*
* @param memberWrapperBean The request parameter.
* @param callback          The callback.
*/
void createProLockMember(MemberWrapperBean memberWrapperBean,IThingDataCallback<MemberBean> callback);

Data model of MemberWrapperBean

For more information, see Member Information Management.

Example

MemberWrapperBean.Builder memberWrapperBean = new MemberWrapperBean.Builder();
memberWrapperBean.setNickName();// The nickname of the member.
memberWrapperBean.setCountryCode();// The country code.
memberWrapperBean.setAccount();// The app account.
memberWrapperBean.setRole();// The role of the member. For more information about the definitions, see MemberRole in Member Information Management.
memberWrapperBean.setHomeId();// The ID of the home to which the current device belongs.
memberWrapperBean.setAutoAccept(false);// true: The invitee automatically accepts the invitation to join the home.
thingLockDevice.createProLockMember(memberWrapperBean.build(), new IThingDataCallback<MemberBean>() {
    @Override
    public void onSuccess(MemberBean result) {
        Log.i(Constant.TAG, "add lock user success");
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "add lock user failed: code = " + code + " message = " + message);
    }
});

Delete a lock member

Delete a home member and all unlocking methods that are associated with this member from the device.

API description

/**
* Deletes a member.
*
* @param memberInfoBean The information about the member.
* @param callback       The callback.
*/
void removeProLockMember(MemberInfoBean memberInfoBean, IResultCallback callback);

Example

The request parameter memberInfoBean is the data model returned by getProLockMemberList that is used to get a member list.

thingLockDevice.removeProLockMember(memberInfoBean, new IResultCallback() {
    @Override
    public void onError(String code, String error) {
        Log.e(Constant.TAG, "removeProLockMember failed: code = " + code + " message = " + error);
    }

    @Override
    public void onSuccess() {
        Log.i(Constant.TAG, "removeProLockMember success");
    }
});

Modify information about a member

Modifies only the nickname and role of a member.

API description

/**
* Edits the information about a member.
*
* @param memberWrapperBean The request parameter.
* @param callback          The callback.
*/
void updateProLockMemberInfo(MemberWrapperBean memberWrapperBean, IResultCallback callback);

Data model of MemberWrapperBean

For more information, see Member Information Management.

Example

MemberWrapperBean.Builder memberWrapperBean = new MemberWrapperBean.Builder();
memberWrapperBean.setNickName();// The nickname of the member.
memberWrapperBean.setRole();// The role of the member. For more information about the definitions, see MemberRole in Member Information Management.
memberWrapperBean.setMemberId();// The userId returned in the member list.
thingLockDevice.updateProLockMemberInfo(memberWrapperBean.build(), new IResultCallback() {
    @Override
    public void onError(String code, String error) {
        Log.e(Constant.TAG, "updateProLockMemberInfo failed: code = " + code + " message = " + error);
    }

    @Override
    public void onSuccess() {
        Log.i(Constant.TAG, "updateProLockMemberInfo success");
    }
});

Modify validity period of a member (unavailable to legacy versions)

Modifies the validity period of a lock member. This feature requires communication between your app and a Bluetooth lock. Your app must be connected to the lock over Bluetooth during the operation.

API description

The request parameter memberInfoBean is the data model returned by getProLockMemberList that is used to get a member list.

/**
* Modifies the validity period of a member.
*
* @param memberInfoBean The information about the member.
* @param callback       The callback.
*/
void updateProLockMemberTime(MemberInfoBean memberInfoBean, IThingResultCallback<Boolean> callback);

Example

thingLockDevice.updateProLockMemberTime(memberInfoBean, new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        Log.i(Constant.TAG, "updateProLockMemberTime success");
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "updateProLockMemberTime failed: code = " + code + " message = " + message);
    }
});

Things to note

The weekly recurring field workingDay consists of seven bits, and each bit is 1 or 0. A value of 1 represents ON and a value of 0 represents OFF. The following examples show the conversion from binary to decimal for different settings in the field.

Saturday	Friday	Thursday	Wednesday	Tuesday	Monday	Sunday	Binary	Calculation result (decimal)
1	1	1	1	1	1	1	1111111	127
0	0	0	0	0	0	0	0000000	0
0	1	1	1	1	0	0	0111100	60

The SDK provides a simple calculation method. For more information about ScheduleBean, see its data model.

// Adds a day.
scheduleBean.dayOfWeeks.add(ScheduleBean.DayOfWeek.MONDAY);
// Removes a day.
scheduleBean.dayOfWeeks.remove(ScheduleBean.DayOfWeek.FRIDAY);
// Parses and displays data.
scheduleBean.dayOfWeeks = LockUtil.parseWorkingDay(scheduleBean.workingDay);
// Encapsulates the list of selected days.
scheduleBean.workingDay = Integer.parseInt(LockUtil.convertWorkingDay(scheduleBean.dayOfWeeks);

Get current user information

API description

/**
* Returns information about the current user.
*
* @param callback The callback.
*/
void getCurrentMemberDetail(IThingResultCallback<BLELockUser> callback);
/**
* Returns information about the pro edition of smart locks used by the current user.
*
* @param callback The callback.
*/
void getProCurrentMemberDetail(IThingResultCallback<BLELockUserV3> callback);

Example

thingLockDevice.getCurrentMemberDetail(new IThingResultCallback<BLELockUser>() {
    @Override
    public void onSuccess(BLELockUser result) {
        Log.i(Constant.TAG, "getCurrentMemberDetail:" + result);
    }

    @Override
    public void onError(String code, String error) {
        Log.e(Constant.TAG, "getCurrentMemberDetail onError code:" + code + ", error:" + error);
    }
});
// The pro edition.
thingLockDevice.getProCurrentMemberDetail(new IThingResultCallback<BLELockUserV3>() {
    @Override
    public void onSuccess(BLELockUserV3 result) {
        Log.i(Constant.TAG, "getProCurrentMemberDetail:" + result);
    }

    @Override
    public void onError(String code, String error) {
        Log.e(Constant.TAG, "getCurrentMemberDetail onError code:" + code + ", error:" + error);
    }
});

Bluetooth connection

To use certain features of a Bluetooth lock, users must enable the Bluetooth feature on your app.

Query Bluetooth connection status

The SDK can be used to enable an automatic connection with the lock over Bluetooth. The following API methods can be called to create a connection and query the connection status.

API description

/**
* @return Returns the Bluetooth connection status.
*/
boolean isBLEConnected();
/**
* @return Indicates whether the device is online.
*/
boolean isOnline();

Example

boolean isBLEConnected = thingLockDevice.isBLEConnected();
boolean isOnline = thingLockDevice.isOnline();
if (!isBLEConnected && isOnline) {
    device_state_view.setText("Connected to the gateway");
} else if (isBLEConnected && isOnline) {
    device_state_view.setText("Connected over Bluetooth");
} else {
    device_state_view.setText("Offline");
}

Bluetooth connection to lock

If the system returns that a Bluetooth lock is not connected to your app, call this API method to connect to the Bluetooth lock.

API description

The timeout period of each Bluetooth connection is 30 seconds. If a connection request timed out, a callback is invoked by onError. The callback is invoked only once for ConnectV2Listener that is encapsulated on top of connectBleDevice.

/**
* Triggers a Bluetooth connection.
*
* @param connectListener The callback.
*/
void autoConnect(ConnectV2Listener connectListener);

Example

thingLockDevice.autoConnect(new ConnectV2Listener() {
    @Override
    public void onStatusChanged(boolean online) {
        Log.e(Constant.TAG, "device online:" + online);
    }

    @Override
    public void onError(String code, String error) {
        Log.e(Constant.TAG, "autoConnect onError code:" + code + ", error:" + error);
    }
});

Unlock and lock over Bluetooth

Short-range unlocking

API description

The timeout period of each unlocking request is 30 seconds. If an unlocking request timed out, a callback is invoked by onError. The callback is invoked only once for IResultCallback.

/**
* Unlocks the door over Bluetooth.
*
* @param lockUserId The member ID that the cloud assigns to a lock when you create a lock member.
* @param callback   The callback.
*/
void bleUnlock(String lockUserId, IResultCallback callback);

Example

// Returns the member ID that the cloud assigns to a lock when you create a lock member.
thingLockDevice.getCurrentMemberDetail(new IThingResultCallback<BLELockUser>() {
    @Override
    public void onSuccess(BLELockUser result) {
        Log.i(Constant.TAG, "getCurrentMemberDetail:" +result);
        // Runs the unlocking task.
        thingLockDevice.bleUnlock(result.lockUserId, new IResultCallback() {
            @Override
            public void onError(String code, String error) {
                Log.e(Constant.TAG, "bleUnlock onError code:" + code + ", error:" + error);
            }

            @Override
            public void onSuccess() {
                Log.i(Constant.TAG, "bleUnlock onSuccess");
            }
        });
    }

    @Override
    public void onError(String code, String error) {
        Log.e(Constant.TAG, "getCurrentMemberDetail onError code:" + code + ", error:" + error);
    }
});

Short-range locking over Bluetooth

API description

You can call this method to lock a door over Bluetooth after your app is connected to the Bluetooth lock.

The timeout period of each locking request is 30 seconds. If an unlocking request timed out, a callback is invoked by onError. The callback is invoked only once for IResultCallback.

/**
* Locks the door over Bluetooth.
*
* @param callback The callback.
*/
void bleManualLock(IResultCallback callback);

Example

thingLockDevice.bleManualLock(new IResultCallback() {
    @Override
    public void onError(String code, String error) {
        Log.e(Constant.TAG, "bleManualLock onError code:" + code + ", error:" + error);
    }

    @Override
    public void onSuccess() {
        Log.i(Constant.TAG, "bleManualLock onSuccess");
    }
});

Remote locking and unlocking over Bluetooth

For more information about the query and settings of locking and unlocking, see Lock settings.

API description

The timeout period of each request is 30 seconds. If an unlocking request timed out, a callback is invoked by onError. The callback is invoked only once for IResultCallback.

/**
* Remotely locks or unlocks the door.
*
* @param open     Locks or unlocks the door.
* @param callback The callback.
*/
void remoteSwitchLock(boolean open, IResultCallback callback);

Example

thingLockDevice.remoteSwitchLock(true/false, new IResultCallback() {
    @Override
    public void onError(String code, String error) {
        Log.e(Constant.TAG, "remoteSwitchLock onError code:" + code + ", error:" + error);
    }

    @Override
    public void onSuccess() {
        Log.i(Constant.TAG, "remoteSwitchLock onSuccess");
    }
});

Lock usage records

Get alert records

This method is available to legacy versions only. For the pro edition of smart locks, we recommend that you call the method in Filterable records (log component).

API description

/**
* get alarm records in old version
*
* @param offset   page number
* @param limit    item count
* @param callback callback
*/
void getAlarmRecordList(int offset, int limit, IThingResultCallback<Record> callback);

Parameters

Parameter	Description
offset	The page number starting from which records are returned.
limit	The maximum number of records to be returned in each call.

Data model of Record

Field	Type	Description
totalCount	Integer	The total number of records to be returned in each call.
hasNext	Boolean	Specifies whether to return the next page.
datas	List	The record content. For more information, see `DataBean`.

Data model of DataBean

Field	Type	Description
userId	String	The user ID.
userName	String	The nickname of a specified user.
unlockType	String	The type of unlocking.
devId	String	The device ID.
createTime	Long	The timestamp when the record was created.
tags	Integer	The flag of the record. Valid values: `0`: other types of alarms `1`: duress alarm
unlockRelation	UnlockRelation	The instance that specifies the relationship between an unlocking type and an unlocking password number. Ignore this parameter for non-unlocking records.

Example

thingLockDevice.getAlarmRecordList(0, 10, new IThingResultCallback<Record>() {
    @Override
    public void onSuccess(Record result) {
        Log.i(Constant.TAG, "get alarm records success: recordBean = " + result);
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        Log.e(Constant.TAG, "get alarm records failed: code = " + errorCode + " message = " + errorMessage);
    }
});

Get unlocking records

This method is available to legacy versions only. For the pro edition of smart locks, we recommend that you call the method in Filterable records (log component).

API description

For more information, see the alert records.

/**
* get unlock records in old version
*
* @param offset   page number
* @param limit    item count
* @param callback callback
*/
void getUnlockRecordList(int offset, int limit, IThingResultCallback<Record> callback);

Example

thingLockDevice.getUnlockRecordList(0, 10, new IThingResultCallback<Record>() {
    @Override
    public void onSuccess(Record result) {
        Log.i(Constant.TAG, "getUnlockRecordList success: recordBean = " + result);
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        Log.e(Constant.TAG, "getUnlockRecordList failed: code = " + errorCode + " message = " + errorMessage);
    }
});

Get alert records

This method is available to legacy versions only. For the pro edition of smart locks, we recommend that you call the method in Filterable records (log component).

API description

For more information, see the alert records.

/**
* Returns the duress flag for legacy versions.
*
* @param offset page number
* @param limit item count
* @param callback callback
*/
void getHijackRecords(int offset, int limit, IThingResultCallback<Record> callback);

Example

thingLockDevice.getHijackRecords(0, 10, new IThingResultCallback<Record>() {
    @Override
    public void onSuccess(Record result) {
        Log.i(Constant.TAG, "getHijackRecords success: recordBean = " + result);
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        Log.e(Constant.TAG, "getHijackRecords failed: code = " + errorCode + " message = " + errorMessage);
    }
});

Filterable records (log component)

Returns the usage records that can be filtered by users. This method is available to the pro edition of smart locks.

API description

/**
* Returns the usage records respecting the pro edition.
*
* @param request The request parameter.
* @param callback The listener.
*/
void getProUnlockRecordList(RecordRequest request, IThingResultCallback<ProRecord> callback);

Data model of RecordRequest

Field	Type	Description
logCategories	String	The type of log. Valid values: `operation`: operation log `unlock_record`: unlocking log `close_record`: locking log `alarm_record`: alarm log The values are separated with commas (,) and encapsulated as a list of enum values in the Smart Lock SDK.
userIds	String	The list of user IDs to be returned, separated with commas (,). Example: `12,13`.
onlyShowMediaRecord	Boolean	Indicates whether only log entries with images or video files are returned. Default value: `false`, used to return all log entries.
startTime	Long	The start time of the period to be queried. Unit: milliseconds.
endTime	Long	The end time of the period to be queried. Unit: milliseconds.
lastRowKey	String	The row key of the last entry on each page. The value is empty for the first page.
limit	Integer	The maximum number of entries to be returned per page.

Data model of ProRecord

Field	Type	Description
hasNext	Boolean	Indicates whether the entries are returned on pages.
lastRowKey	String	The row key of the last entry on each page.
records	List	The list of records. For more information about a single record, see `DataBean`.

Data model of DataBean

Field	Type	Required	Description
logId	Long	Yes	The log ID.
logCategory	String	Yes	The type of log. Valid values: `operation`: operation log `unlock_record`: unlocking log `close_record`: locking log `alarm_record`: alarm log
logType	String	Yes	The type of log. For more information, see Appendix.
recordType	Integer	No	Only unlocking records are returned. Valid values: Unlocking Alarm
unlockNameRosettaKey	String	No	The type of locking record. For more information, see Appendix.
currentUser	Boolean	No	Indicates whether the record is generated by the current user. If so, the value is `true`. This parameter is required by non-combined unlocking methods.
userId	String	No	The user ID, required only by unlocking records, duress alarms, and operation records.
userName	String	No	The username.
memberBindableFlag	Boolean	Yes	Indicates whether a record can be bound with a member.
unlockName	String	No	The name of an unlocking method. The value can be empty.
time	Long	Yes	The time when an 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 record. For more information, see Appendix.
unionUnlockInfo	UnionUnlockInfo	No	The information about a combined unlocking method.
mediaInfoList	List	No	The information about video files and images. This parameter applies to smart video locks, Wi-Fi low-power locks, and keepalive locks when these locks can generate video files and images. For more information, see `MediaInfoBean`.

Data model of UnionUnlockInfo

Field	Type	Required	Description
userName	String	No	The username triggered by the combined unlocking method. The value can be empty.
opMode	String	No	The type of unlocking method that is used for combined unlocking.
unlockName	String	No	The name of the unlocking method that is used for combined unlocking. The value can be empty.
currentUser	Boolean	No	Indicates whether the combined unlocking method is used by the current user.
sn	Integer	No	The hardware SN of the device that is bound with the combined unlocking method.

Data model of MediaInfoBean

Field	Type	Required	Description
fileUrl	String	No	The URL of a cover image.
fileKey	String	No	The secret key that is used to decrypt a cover image.
mediaPath	String	No	The relative address of a video file.
mediaBucket	String	No	The bucket where a video file is located.
mediaKey	String	No	The secret key that is used to decrypt a video file.

Example

ArrayList<RecordRequest.LogRecord> logRecords = new ArrayList<>();
logRecords.add(RecordRequest.LogRecord.UNLOCK_RECORD);
logRecords.add(RecordRequest.LogRecord.CLOSE_RECORD);
logRecords.add(RecordRequest.LogRecord.ALARM_RECORD);
logRecords.add(RecordRequest.LogRecord.OPERATION);
RecordRequest request = new RecordRequest();
request.setLogCategories(logRecords);
request.setLimit(10);
thingLockDevice.getProUnlockRecordList(request, new IThingResultCallback<ProRecord>() {
    @Override
    public void onSuccess(ProRecord result) {
        Log.i(Constant.TAG, "get ProUnlock RecordList success: recordBean = " + result);
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        Log.e(Constant.TAG, "get ProUnlock RecordList failed: code = " + errorCode + " message = " + errorMessage);
    }
});

Unlocking methods

Get a list of linked unlocking methods

API description

/**
* Returns a list of linked unlocking methods.
*
* @param userId   The user ID.
* @param callback The callback.
*/
void getProBoundUnlockOpModeList(String userId, IThingResultCallback<MemberInfoBean> callback);

Example

Returns the member data model MemberInfoBean, as mentioned in the method for getting the member list.

thingLockDevice.getProBoundUnlockOpModeList(userId, new IThingResultCallback<MemberInfoBean>() {
    @Override
    public void onSuccess(MemberInfoBean result) {
        Log.i(Constant.TAG, "getProBoundUnlockOpModeList:" + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "getProBoundUnlockOpModeList failed: code = " + code + " message = " + message);
    }
});

Determine unassigned unlocking methods

API description

/**
* Determines whether there are unlocking methods to be assigned.
*
* @param callback The callback.
*/
void isProNeedAllocUnlockOpMode(IThingResultCallback<Boolean> callback);

Example

thingLockDevice.isProNeedAllocUnlockOpMode(new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        Log.i(Constant.TAG, "isProNeedAllocUnlockOpMode:" + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "isProNeedAllocUnlockOpMode failed: code = " + code + " message = " + message);
    }
});

Get a list of unlinked unlocking methods

API description

/**
* Returns a list of unlinked unlocking methods.
*
* @param callback The callback.
*/
void getProUnboundUnlockOpModeList(IThingResultCallback<ArrayList<AllocOpModeBean>> callback);

Example

thingLockDevice.getProUnboundUnlockOpModeList(new IThingResultCallback<ArrayList<AllocOpModeBean>>() {
    @Override
    public void onSuccess(ArrayList<AllocOpModeBean> result) {
        Log.i(Constant.TAG, "getProUnboundUnlockOpModeList:" + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "getProUnboundUnlockOpModeList failed: code = " + code + " message = " + message);
    }
});

Data model of AllocOpModeBean

Field	Type	Description
opMode	String	The unlocking method. Valid values: `1`: fingerprint `2`: password `3`: card
unlockList	List	The details of the unassigned unlocking method. For more information, see the settings of `UnlockInfoBean`.

Assign unlocking method to user

API description

/**
* Assigns an unlocking method to a user.
*
* @param userId   The user ID.
* @param unlockIds The DP of the unlocking method.
* @param callback The callback.
*/
void allocProUnlockOpMode(String userId, List<String> unlockIds, IThingResultCallback<Boolean> callback);

Request parameters

Field	Type	Description
userId	String	The user ID.
unlockIds	List	A list of unlocking methods.

Example

thingLockDevice.allocProUnlockOpMode(userId, unlockIds, new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        Log.i(Constant.TAG, "allocProUnlockOpMode onSuccess: " + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "allocProUnlockOpMode failed: code = " + code + " message = " + message);
    }
});

Add unlocking method on the app

API description

/**
* Legacy all-in-one lock: add an unlocking method.
*
* @param opModeAddRequest The request parameter.
* @param callback         The callback.
*/
void addUnlockOpModeForMember(OpModeRequest opModeAddRequest, IThingResultCallback<AddOpmodeResult> callback);
/**
* Pro edition: add an unlocking method.
*
* @param opModeAddRequest The request parameter.
* @param callback         The callback.
*/
void addProUnlockOpModeForMember(OpModeRequest opModeAddRequest, IThingResultCallback<AddOpmodeResult> callback);

Data model of OpModeRequest

Field	Type	Description
userId	String	The user ID.
unlockId	String	The unlocking method ID. Set the value in the format of `<DP>-<Lock ID>`, such as `1-01`.
unlockName	String	The name of an unlocking method. The value can be empty for the pro edition, but it is required for legacy versions.
opModeId	Long	The ID of an unlocking method in the cloud. The value is used for updates.
unlockAttr	Integer	Specifies whether to enable the unlocking notifications in emergency conditions like duress. Valid values: `0`: no. `1`: yes.
password	String	The unlocking password.
notifyInfo	NotifyInfoBean	The information about the notification, dedicated for the pro edition.
times	Integer	The number of times the notification is sent. Value range: `0` to `255`.
lockUserId	Integer	The user ID on the lock.
unlockType	String	The `DP code` of the unlocking method.
userType	Integer	The type of user. Valid values: `10`: administrator. `20`: common user. `50`: home owner.

Data model of NotifyInfoBean

Field	Type	Description
appSend	Boolean	Specifies whether to send a notification to the app, dedicated for the pro edition.

Example

Different from legacy versions, the pro edition has new features and API versions are updated.

OpModeRequest request = new OpModeRequest()
request.setUserType();// The type of user.
request.setUserId();// The user ID.
request.setLockUserId();// The lock ID of the user.
request.setUnlockName();// The name of the unlocking method.
request.setUnlockAttr(0);// Determines the emergency condition that is called duress for legacy versions.
request.setPassword();// The password must be entered for the unlocking method with password.
// Example for legacy versions
thingLockDevice.addUnlockOpModeForMember(request, new IThingResultCallback<AddOpmodeResult>() {
    @Override
    public void onSuccess(AddOpmodeResult result) {
        Log.i(Constant.TAG, "addUnlockOpModeForMember onSuccess");
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "addUnlockOpModeForMember onError:" + code + ", message: " + message);
    }
});
// Example for the pro edition
thingLockDevice.addProUnlockOpModeForMember(request, new IThingResultCallback<AddOpmodeResult>() {
    @Override
    public void onSuccess(AddOpmodeResult result) {
        Log.i(Constant.TAG, "addProUnlockOpModeForMember onSuccess");
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "addProUnlockOpModeForMember onError:" + code + ", message: " + message);
    }
});

Data model of AddOpmodeResult

Field	Type	Description
opModeId	Long	The ID of an unlocking method in the cloud. The value is used for updates.
unlockName	String	The name of an unlocking method. The value can be empty.

Delete unlocking method on the app

API description

/**
* Legacy versions: delete an unlocking method.
*
* @param unlockMode The request parameter.
* @param callback   The callback.
*/
void removeUnlockOpModeForMember(OpModeRemoveRequest unlockMode, IThingResultCallback<Boolean> callback);
/**
* Pro edition: delete an unlocking method.
*
* @param unlockMode The request parameter.
* @param callback   The callback.
*/
void removeProUnlockOpModeForMember(OpModeRemoveRequest unlockMode, IThingResultCallback<Boolean> callback);

Data model of OpModeRemoveRequest

Field	Type	Description
userId	String	The user ID.
lockUserId	String	The member ID that the cloud assigns to a lock when you create a lock member.
userType	Integer	The type of user.
unlockId	String	The ID of an unlocking method.
opModeId	String	The number of a specified unlocking method in the cloud.

Example

OpModeRemoveRequest removeRequest = new OpModeRemoveRequest();
removeRequest.setUserId(memberInfo.getUserId());
removeRequest.setLockUserId(memberInfo.getLockUserId());
removeRequest.setUnlockId(infoBean.getUnlockId());
removeRequest.setOpModeId(infoBean.getOpModeId());
removeRequest.setUserType(memberInfo.getUserType());
// Legacy versions.
thingLockDevice.removeUnlockOpModeForMember(removeRequest, new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        Log.i(Constant.TAG, "removeUnlockOpModeForMember onSuccess");
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        Log.e(Constant.TAG, "removeUnlockOpModeForMember onError:" + code + ", message: " + message);
    }
});
// The pro edition.
thingLockDevice.removeProUnlockOpModeForMember(removeRequest, new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        Log.i(Constant.TAG, "removeProUnlockOpModeForMember onSuccess");
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "removeProUnlockOpModeForMember onError:" + code + ", message: " + message);
    }
});

Update unlocking method on the app

API description

For more information about the data model of OpModeRequest as the request parameter, see Add unlocking method on the app.

/**
* Updates an unlocking method.
*
* @param opModeUpdateRequest The request parameter.
* @param callback            The callback.
*/
void modifyUnlockOpModeForMember(OpModeRequest opModeUpdateRequest, IThingResultCallback<Boolean> callback);
/**
* Pro edition: update an unlocking method.
*
* @param opModeUpdateRequest The request parameter.
* @param callback            The callback.
*/
void modifyProUnlockOpModeForMember(OpModeRequest opModeUpdateRequest, IThingResultCallback<Boolean> callback);

Example

NotifyInfoBean notifyInfoBean = new NotifyInfoBean();
notifyInfoBean.setAppSend(true);
OpModeRequest request = new OpModeRequest();
request.setUserType();// The type of user.
request.setUserId();  // The user ID.
request.setLockUserId();// The lock ID of the user.
request.setUnlockName();// The name of the unlocking method.
request.setUnlockAttr(0);// Determines the emergency condition.
request.setPassword();  // The password must be entered for the unlocking method with password.
request.setOpModeId();  // The lock ID stored in the cloud.
request.setUnlockId();  // The unlocking method ID.
// Legacy versions.
thingLockDevice.modifyUnlockOpModeForMember(request, new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        Log.i(Constant.TAG, "modifyUnlockOpModeForMember onSuccess");
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "modifyUnlockOpModeForMember onError:" + code + ", message: " + message);
    }
});
// Pro edition: update an unlocking method.
request.setNotifyInfo(notifyInfoBean);// Sets the switch of the notification method.
thingLockDevice.modifyProUnlockOpModeForMember(request, new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        Log.i(Constant.TAG, "modifyProUnlockOpModeForMember onSuccess");
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "modifyProUnlockOpModeForMember onError:" + code + ", message: " + message);
    }
});

Cancel enrollment of fingerprint unlocking method on the app

This method applies to the unlocking method with fingerprint.

API description

/**
* Cancels enrollment of an unlocking method with fingerprint.
*
* @param lockUserId The lock ID of the member.
* @param userType   The type of member.
* @param callback   The callback.
*/
void cancelUnlockOpModeForFinger(int lockUserId, int userType, IResultCallback callback);

Example

After enrollment is canceled, the error message addUnlockOpModeForMember.onError that is returned for the request of adding an unlocking method includes the code parameter. For more information about the values of code, see Appendix.

thingLockDevice.cancelUnlockOpModeForFinger(request.getLockUserId(), request.getUserType(), new IResultCallback() {
    @Override
    public void onError(String code, String message) {
         Log.e(Constant.TAG, "cancelUnlockOpModeForFinger onError:" + code + ", message: " + message);
    }

    @Override
    public void onSuccess() {
    }
});

Query details of an unlocking method

This method is suitable for users to view or edit the details of an unlocking method.

API description

/**
* Returns the details of an unlocking method.
*
* @param opModeId The lock ID that is stored in the cloud.
* @param callback The callback.
*/
void getProUnlockOpModeDetail(long opModeId, IThingResultCallback<OpModeDetailBean> callback);

Request parameters

Field	Type	Description
opModeId	Long	The lock ID that is stored in the cloud.

Data model of OpModeDetailBean

Field	Type	Description
phase	Integer	The status of the user. Valid values: `0`: frozen `1`: normal `5`: expired `6`: ineffective `7`: deleted
unlockAttr	Integer	The attribute of an unlocking method. Valid values: `1`: emergency `0`: not emergency
unlockName	String	The name of an unlocking method.
userId	String	The user ID.
opModeValue	String	The hexadecimal value of the unlocking method.
opMode	String	The type of unlocking method. This parameter matches `dpId`.
unlockId	String	The ID of an unlocking method.
lockUserId	Integer	The user ID on the lock.
opModeId	Long	The ID of an unlocking method in the cloud.
userTimeSet	String	The validity period of the user.
userType	Integer	The type of user.
sourceAttribute	Integer	The source of the unlocking method. Valid values: `1`: enroll on the app `2`: enroll on an offline lock `3`: enroll by the lock super administrator
notifyInfo	NotifyInfoBean	The information about the notification. The value is returned only when the unlocking method attribute is set to `1` for the pro edition.

Example

thingLockDevice.getProUnlockOpModeDetail(opModeId, new IThingResultCallback<OpModeDetailBean>() {
    @Override
    public void onSuccess(OpModeDetailBean result) {
        Log.i(Constant.TAG, "getUnlockOpModeDetail: " + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "getUnlockOpModeDetail onError:" + code + ", message: " + message);
    }
});

Set or cancel unlocking method under duress

By default, this feature is built into the methods of adding and updating an unlocking method. This section describes how to use this feature in detail.

API description

/**
* Adds a duress alarm flag.
*
* @param dpId      The DP ID.
* @param unlockId The unlocking method ID in the format of dpId + Lock ID.
* @param callback The callback.
*/
void addHijackingConfig(String dpId, String unlockId, IThingResultCallback<Boolean> callback);

/**
* Removes a duress alarm flag.
*
* @param dpId      The DP ID.
* @param unlockId The unlocking method ID in the format of dpId + Lock ID.
* @param callback The callback.
*/
void removeHijackingConfig(String dpId, String unlockId, IThingResultCallback<Boolean> callback);

Sync unlocking methods on the app

API description

/**
* Syncs unlocking methods.
*
* @param dpIds    The unlocking method DP to be synced.
* @param callback The callback.
*/
void syncData(List<String> dpIds, IResultCallback callback);

Example

ArrayList<String> dpIds = new ArrayList<>();
dpIds.add(unlockType);
thingLockDevice.syncData(dpIds, new IResultCallback() {
    @Override
    public void onError(String code, String error) {
        Log.e(Constant.TAG, "syncData onError:" + code + ", message: " + message);
    }

    @Override
    public void onSuccess() {
        Log.i(Constant.TAG, "syncData onSuccess");
    }
});

Enable or disable unlocking method notification

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

Password management

Create offline password (one-time, multi-time, clearing code)

API description

/**
* Returns an offline password.
*
* @param pwdType    The type of password.
* @param gmtStart   The start time.
* @param gmtExpired The end time.
* @param pwdName    The password name.
* @param callback   The callback.
*/
void getOfflinePassword(OfflineTempPasswordType pwdType, long gmtStart, long gmtExpired,
                    String pwdName,
                    IThingResultCallback<OfflineTempPassword> callback);

/**
* Pro edition: get an offline password.
*
* @param pwdType    The type of password.
* @param gmtStart   The start time.
* @param gmtExpired The end time.
* @param pwdName    The password name.
* @param callback   The callback.
*/
void getProOfflinePassword(OfflineTempPasswordType pwdType, long gmtStart, long gmtExpired,
                        String pwdName,
                        IThingResultCallback<OfflineTempPassword> callback);

Request parameters

Field	Type	Description
pwdType	OfflineTempPasswordType	The type of password. Valid values: `0`: a password that can be used as many times as needed before it expires `1`: a one-time password `9`: a clearing code
gmtStart	Long	The time when the password becomes effective. The value is `0` except for a password that can be used as many times as needed before it expires.
gmtExpired	Long	The time when the password expires. The value is `0` except for a password that can be used as many times as needed before it expires.
pwdName	String	The name of the password.

Example

// Legacy versions.
thingLockDevice.getOfflinePassword(pwdType, gmtStart, gmtExpired, name, new IThingResultCallback<OfflineTempPassword>() {
    @Override
    public void onSuccess(OfflineTempPassword result) {
        Log.i(Constant.TAG, "getOfflinePassword success :" + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "getOfflinePassword failed: code = " + code + " message = " + message);
    }
});
// The pro edition.
thingLockDevice.getProOfflinePassword(pwdType, gmtStart, gmtExpired, name, new IThingResultCallback<OfflineTempPassword>() {
    @Override
    public void onSuccess(OfflineTempPassword result) {
        Log.i(Constant.TAG, "getProOfflinePassword success :" + result);
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        Log.e(Constant.TAG, "getProOfflinePassword failed: code = " + code + " message = " + message);
    }
});

Data model of OfflineTempPassword

Field	Type	Description
unlockBindingId	String	The authorization ID of the unlocking method, dedicated for the pro edition.
pwd	String	The temporary password.
pwdId	String	The password ID.
pwdName	String	The name of the password, dedicated for the pro edition.
gmtStart	Long	The 10-digit time when the temporary password takes effect. Unit: seconds.
gmtExpired	Long	The 10-digit time when the temporary password expires. Unit: seconds.

Get clearing code of an offline password

API description

/**
* Returns the clearing code of an offline password.
*
* @param revokeRequest The request parameter.
* @param callback      The callback.
*/
void getSingleRevokeOfflinePassword(OfflinePasswordRevokeRequest revokeRequest, IThingResultCallback<String> callback);

Data model of OfflinePasswordRevokeRequest

Field	Type	Description
passwordId	String	The ID of the offline password. Valid values: `unlockBindingId` used by the pro edition `pwdId` used by legacy versions
name	String	The name of the password to be cleared, dedicated for the pro edition.

Get effective offline password (unlimited use, clearable)

API description

/**
*
* @param callback callback
*/
void getSingleRevokePasswordList(IThingResultCallback<ArrayList<OfflineTempPassword>> callback);

Example

thingLockDevice.getSingleRevokePasswordList(new IThingResultCallback<ArrayList<OfflineTempPassword>>() {
    @Override
    public void onSuccess(ArrayList<OfflineTempPassword> result) {
        Log.i(Constant.TAG, "getSingleRevokePasswordList success: " + result);
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        Log.e(Constant.TAG, "getSingleRevokePasswordList failed: code = " + errorCode + " message = " + errorMessage);
    }
});

Example

OfflinePasswordRevokeRequest revokeRequest = new OfflinePasswordRevokeRequest();
revokeRequest.setPasswordId();
revokeRequest.setName();// Dedicated for the pro edition.
thingLockDevice.getSingleRevokeOfflinePassword(revokeRequest, new IThingResultCallback<String>() {
    @Override
    public void onSuccess(String result) {
        Log.i(Constant.TAG, "getSingleRevokeOfflinePassword success :" + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "getSingleRevokeOfflinePassword failed: code = " + code + " message = " + message);
    }
});

Repeatedly validate temporary online password

By default, this feature is built into the methods of adding and updating a temporary online password. This section describes how to use this feature in detail.

API description

/**
* Repeatedly validates the content of an online password.
*
* @param request The request parameter.
* @param callback The callback.
*/
void validateCustomPassword(PasswordRequest request, IThingResultCallback<Boolean> callback);

Data model of PasswordRequest

Field	Type	Description
id	String	The password ID. For the pro edition, `unlockBindingId` is used as the request parameter.
password	String	The temporary password.
sn	Integer	The serial number of the password. The value is reported by the device when the password is created.
effectiveTime	Long	The time when the password takes effect.
invalidTime	Long	The time when the password expires.
availTime	Integer	The number of times the password can be used. Valid values: `0`: permanently valid `1`: one-time, unavailable to the pro edition
name	String	The name of the password.
schedule	ScheduleBean	For more information, see `Data model of ScheduleBean`.

Example

thingLockDevice.validateCustomPassword(PasswordRequest, new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        Log.i(Constant.TAG, "validateCustomPassword success :" + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "validateCustomPassword failed: code = " + code + " message = " + message);
    }
});

Create a temporary online password

The types of temporary online passwords include one-time and recurring. For the pro edition, the one-time temporary online password is unavailable.

API description

For more information, see Data model of PasswordRequest.

/**
* Creates an online password. A one-time or periodic password is supported.
* Pro edition: create a custom password, not one-time.
*
* @param request The request parameter.
* @param callback The callback.
*/
void getCustomOnlinePassword(PasswordRequest request, IThingResultCallback<String> callback);

Example

thingLockDevice.getCustomOnlinePassword(PasswordRequest, new IThingResultCallback<String>() {
    @Override
    public void onSuccess(String result) {
        Log.i(Constant.TAG, "getCustomOnlinePassword success :" + result);
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        Log.e(Constant.TAG, "getCustomOnlinePassword failed: code = " + code + " message = " + message);
    }
});

Modify details or validity period of temporary online password

API description

/**
* Modifies the details or validity period of a temporary online password.
*
* @param request The request parameter.
* @param callback The listener.
*/
void updateOnlinePassword(PasswordRequest request, IThingResultCallback<String> callback);

Example

thingLockDevice.updateOnlinePassword(passwordRequest, new IThingResultCallback<String>() {
    @Override
    public void onSuccess(String result) {
        Log.i(Constant.TAG, "updateOnlinePassword success :" + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "updateOnlinePassword failed: code = " + code + " message = " + message);
    }
});

Delete temporary online password

API description

/**
* Deletes a temporary online password. The password record is deleted and no longer displayed to users.
*
* @param deleteRequest      The input parameter.
* @param callback           The callback.
*/
void deleteOnlinePassword(OnlinePasswordDeleteRequest deleteRequest, IThingResultCallback<String> callback);

Data model of OnlinePasswordDeleteRequest

Field	Type	Description
passwordId	String	The ID of the offline password. Valid values: `unlockBindingId` used as the request parameter by the pro edition `pwdId` or ID used as the request parameter by legacy versions
sn	Integer	The serial number of the password.

Example

OnlinePasswordDeleteRequest deleteRequest = new OnlinePasswordDeleteRequest();
deleteRequest.setSn(passwordItem.getSn());
deleteRequest.setPasswordId(passwordItem.getUnlockBindingId());
thingLockDevice.deleteOnlinePassword(deleteRequest, new IThingResultCallback<String>() {
    @Override
    public void onSuccess(String result) {
        Log.i(Constant.TAG, "deleteProOnlineTempPassword success: " + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "deleteProOnlineTempPassword failed: code = " + code + " message = " + message);
    }
});

Get a list of offline passwords (legacy versions)

For the pro edition, use the new method for getting a password list.

API description

/**
* Legacy all-in-one lock: get a list of offline passwords.
*
* @param offlineType           The type of password: a one-time password, a periodic password, and a clearing code used to delete all offline passwords.
* @param offset                The number of the entry starting from which entries are returned.
* @param limit                 The maximum number of entries returned on each page.
* @param offlinePasswordStatus The password status: valid, invalid, and used.
* @param callback              The listener.
*/
void getOfflinePasswordList(OfflineTempPasswordType offlineType, int offset, int limit,
                        OfflineTempPasswordStatus offlinePasswordStatus,
                        IThingResultCallback<ArrayList<OfflineTempPasswordItem>> callback);

Request parameters

Field	Type	Description
offlineType	OfflineTempPasswordType	The type of password. Valid values: `MULTIPLE`: a password that can be used as many times as needed before it expires `SINGLE`: a one-time password `CLEAR_ALL`: a clearing code used to delete all offline passwords
offset	Integer	The number of the entry starting from which entries are returned.
limit	Integer	The maximum number of entries returned on each page.
offlinePasswordStatus	OfflineTempPasswordStatus	The status of a specified temporary password. Valid values: `TO_BE_USED`: valid `USED`: used `EXPIRED`: expired

Example

thingLockDevice.getOfflinePasswordList(OfflineTempPasswordType.MULTIPLE, 0, 10, OfflineTempPasswordStatus.TO_BE_USED, new IThingResultCallback<ArrayList<OfflineTempPasswordItem>>() {
    @Override
    public void onSuccess(ArrayList<OfflineTempPasswordItem> result) {
        Log.i(Constant.TAG, "getOfflineTempPasswordList success: " + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "getOfflineTempPasswordList failed: code = " + code + " message = " + message);
    }
});

Data model of OfflineTempPasswordItem

Field	Type	Description
pwdId	Integer	The password ID.
pwdType	String	The type of password.
pwdName	String	The name of the password.
gmtStart	Long	The time when the password takes effect.
gmtExpired	Long	The time when a password expires.
hasClearPwd	Boolean	Indicates whether a clearing code has been set. The value is returned only when `pwdType` is 0. This type of password can be used as many times as needed before it expires.
revokedPwdName	String	The name of the clearing code. The value is returned only when `pwdType` is 8. This type of password is used to clear a single password.
status	Integer	The status. The following states are supported: Sent, effective Sent successfully Expired

Get a list of temporary online passwords (legacy versions)

For the pro edition, use the new method for getting a password list.

API description

/**
* Legacy all-in-one lock: get a list of online passwords.
*
* @param availTimes Indicates a one-time password or a periodic password. Valid values: `0` to represent a periodic password and `1` to represent a one-time password.
* @param callback   The callback.
*/
void getOnlinePasswordList(int availTimes, IThingResultCallback<ArrayList<TempPasswordBeanV3>> callback);

Request parameters

Field	Type	Description
availTimes	Integer	`0`: a periodic password `1`: a one-time password

Example

thingLockDevice.getOnlinePasswordList(availTimes, new IThingResultCallback<ArrayList<TempPasswordBeanV3>>() {
    @Override
    public void onSuccess(ArrayList<TempPasswordBeanV3> result) {
        Log.i(Constant.TAG, "getOnlinePasswordList success: " + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "getOnlinePasswordList failed: code = " + code + " message = " + message);
    }
});

Data model of TempPasswordBeanV3

Field	Type	Description
id	Integer	The password ID.
effective	Integer	The status. The following states are supported: To be effective To be sent In use To be deleted Expired
effectiveTime	Long	The time when the password takes effect.
invalidTime	Long	The time when the password expires.
availTime	Integer	The number of times the password can be used. Valid values: `0`: valid permanently `1`: a one-time password
name	String	The name of the password.
sn	Integer	The serial number of the temporary password recorded in the device.
scheduleDetails	ScheduleBean	Indicates whether the weekly schedule expires. For more information, see `Data model of ScheduleBean`.

Get a password list

API description

/**
* The list of passwords for the pro edition.
* The authorization type. Valid values:
* LOCK_BLUE_PASSWORD: unlock with the app
* LOCK_OFFLINE_TEMP_PWD: offline password
* LOCK_TEMP_PWD: online password
*
* @param authTypes The type of authorization.
* @param callback The callback.
*/
void getProPasswordList(List<ProPasswordListTypeEnum> authTypes, IThingResultCallback<ArrayList<ProTempPasswordItem>> callback);

Request parameters

Field	Type	Description
authTypes	List	Enum values of `ProPasswordListTypeEnum`: `LOCK_BLUE_PASSWORD`: unlock with the app `LOCK_OFFLINE_TEMP_PWD`: offline password `LOCK_TEMP_PWD`: online password

Example

List<ProPasswordListTypeEnum> authTypes = new ArrayList<>();
authTypes.add(ProPasswordListTypeEnum.LOCK_BLUE_PASSWORD);
authTypes.add(ProPasswordListTypeEnum.LOCK_OFFLINE_TEMP_PWD);
authTypes.add(ProPasswordListTypeEnum.LOCK_TEMP_PWD);
thingLockDevice.getProPasswordList(authTypes, new IThingResultCallback<ArrayList<ProTempPasswordItem>>() {
    @Override
    public void onSuccess(ArrayList<ProTempPasswordItem> result) {
        Log.i(Constant.TAG, "getProPasswordList success: " + result);
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        Log.e(Constant.TAG, "getProPasswordList failed: code = " + errorCode + " message = " + errorMessage);
    }
});

Data model of ProTempPasswordItem

Field	Type	Description
unlockBindingId	Long	The serial number of the password.
effectiveTime	Long	The time when the password takes effect.
invalidTime	Long	The time when the password expires.
name	String	The name of the password.
userName	String	The associated username. The value is required when a Bluetooth unlocking password is shared, and optional in other cases.
scheduleDetails	List	The details of the weekly schedule. For more information, see `Data model of ScheduleBean`.
opModeType	Integer	The type of unlocking method. Valid values: A temporary password with a validity period A common permanent password An offline temporary password A virtual key A fingerprint A card An authorized Bluetooth unlocking method with the app
opModeSubType	Integer	For more information, see opModeSubType.
sn	Integer	The serial number recorded in the device.
lockUserId	Integer	The member ID that the cloud assigns to a lock when you create a lock member.
account	String	The contact information of the member.
countryCode	String	The country code.
timeSetType	Integer	The type of validity period. Valid values: `10`: valid permanently `20`: valid within a period `30`: valid cyclically
opModeInfo	OPModeInfo	The information about the unlocking method.

Types of unlocking methods indicated by opModeSubType

Type	Description
An offline temporary password	`0`: a password that can be used as many times as needed before it expires `1`: a one-time password `8`: a code for clearing a single password `9`: a code for clearing all passwords
An online temporary password	`0`: a password with a validity period `1`: a password that can be used only once
An authorized Bluetooth unlocking method with the app	`0`: can be used as many times as needed before the authorization expires `1`: can be used only once

Data model of OPModeInfo

Field	Type	Description
hasClearPwd	Boolean	Indicates whether a clearing code is set. The value is required for an offline password.
revokedPwdName	String	The name of the clearing code.
revokedPwdEffectiveTime	String	The start time of the validity period of the clearing code.
revokedPwdInvalidTime	String	The time when the clearing code expires.

Create a dynamic password

API description

/**
* Returns a dynamic password.
*
* @param callback The callback.
*/
void getLockDynamicPassword(IThingResultCallback<DynamicPasswordBean> callback);

Data model of DynamicPasswordBean

Field	Type	Description
dynamicPassword	String	The dynamic clear-text password.

Example

thingLockDevice.getLockDynamicPassword(new IThingResultCallback<DynamicPasswordBean>() {
    @Override
    public void onSuccess(DynamicPasswordBean result) {
        Log.i(Constant.TAG, "getLockDynamicPassword onSuccess");
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "getLockDynamicPassword onError:" + code + ", message: " + message);
    }
});

Get number system type of password

Returns the configurations of the number system with the help of the panel cloud capability API. The password returned from the cloud must be converted between number systems.

Field name	Description	Default value
digitalBase	The number system supported by the password.	`10`
isHideZero	Indicates whether the least-significant bit (LSB) is `0` or `1`. Valid values: `true`: 1 `false`: 0	`false`

API description

/**
* Returns the type of number system used by the password.
*
* @param callback The callback.
*/
void getLockDeviceConfig(IThingResultCallback<String> callback);

Example

thingLockDevice.getLockDeviceConfig(new IThingResultCallback<String>() {
    @Override
    public void onSuccess(String result) {
        Log.i(Constant.TAG, "getLockDeviceConfig success :" + result);
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        Log.e(Constant.TAG, "getLockDeviceConfig failed: code = " + errorCode + " message = " + errorMessage);
    }
});

Lock settings

Get status of remote unlocking switch

API description

/**
* Determines whether remote unlocking is enabled.
*
* @param callback The callback.
*/
void fetchRemoteUnlockType(IThingResultCallback<Boolean> callback);

Example

thingLockDevice.fetchRemoteUnlockType(new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        Log.i(Constant.TAG, "get remote unlock available success:" + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "get remote unlock available failed: code = " + code + " message = " + message);
    }
});

Set status of remote unlocking switch

API description

/**
* Sets the status of the remote unlocking switch.
*
* @param isOpen   The setting of the switch.
* @param callback The callback.
*/
void setRemoteUnlockType(boolean isOpen, IResultCallback callback);

Example

thingLockDevice.setRemoteUnlockType(isOpen, new IResultCallback() {
    @Override
    public void onError(String code, String error) {
        Log.e(Constant.TAG, "setRemoteUnlockType failed: code = " + code + " message = " + error);
    }

    @Override
    public void onSuccess() {
        Log.i(Constant.TAG, "setRemoteUnlockType success");
    }
});

Get status of Google Voice password switch

API description

/**
* Determines whether Google Voice password is enabled.
*
* @param callback The callback.
*/
void fetchRemoteVoiceUnlock(IThingResultCallback<Boolean> callback);

Example

thingLockDevice.fetchRemoteVoiceUnlock(new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        Log.i(Constant.TAG, "fetchRemoteVoiceUnlock success:" + result);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "fetchRemoteVoiceUnlock failed: code = " + code + " message = " + message);
    }
});

Set Google Voice password

API description

/**
* Sets or cancels a Google Voice password.
*
* @param isOpen   Sets or cancels a Google Voice password.
* @param password The password.
* @param callback The callback.
*/
void setRemoteVoiceUnlock(boolean isOpen, String password, IThingResultCallback<Boolean> callback);

Example

thingLockDevice.setRemoteVoiceUnlock(isOpen, password, new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        Log.i(Constant.TAG, "setRemoteVoiceUnlock success:" + result);
    }

    @Override
    public void onError(String code, String error) {
        Log.e(Constant.TAG, "setRemoteVoiceUnlock failed: code = " + code + " message = " + error);
    }
});

Send locking setting DPs

Use the methods mentioned in Device Control.

Example

The following example shows how to enable the delayed locking feature with a delay of 10 seconds.

String automaticLock_dpId = LockUtil.convertCode2Id(deviceId, "automatic_lock");
String autoLockTime_dpId = LockUtil.convertCode2Id(deviceId, "auto_lock_time");
Map<String, Object> data = new HashMap<>();
dpMap.put(automaticLock_dpId, true);
dpMap.put(autoLockTime_dpId, 10);
IThingDevice iThingDevice = ThingHomeSdk.newDeviceInstance(mDevId);
iThingDevice.publishDps(dpMap, new IResultCallback() {
    @Override
    public void onError(String code, String error) {

    }

    @Override
    public void onSuccess() {

    }
});

Sync data

Sync random numbers, accessories, and records

After the app is started and the device goes online, the data such as offline password time, unlocking random numbers, and lock operation records is synced once. If data is not synced, unlocking is not allowed.

API description

void publishSyncBatchData();

Example

thingLockDevice.publishSyncBatchData();

Get synced data content

Returns the content of the data stored in the cloud by publishSyncBatchData. This data retrieval process does not require interaction with the device.

API description

void getSyncBatchData(IThingResultCallback<SyncBatchBean> callback);

Example

thingLockDevice.getSyncBatchData(new IThingResultCallback<SyncBatchBean>() {
    @Override
    public void onSuccess(SyncBatchBean result) {

    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "getSyncBatchData failed: code = " + code + " message = " + message);
    }
});

Sync unlocking methods

By default, this logic is built into the method of adding an unlocking method. This section describes how to use this feature in detail.

API description

/**
* Syncs unlocking methods.
*
* @param dpIds    The unlocking method DP to be synced.
* @param callback The callback.
*/
void syncData(List<String> dpIds, IResultCallback callback);

Example

ArrayList<String> dpIds = new ArrayList<>();
dpIds.add(dpId);
thingLockDevice.syncData(dpIds, new IResultCallback() {
    @Override
    public void onError(String code, String error) {

    }

    @Override
    public void onSuccess() {

    }
});

Appendix

Types of locking records

The operation records returned by DataBean.unlockNameRosettaKey can be parsed into the following types.

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

Data formats of operation records

The operation records returned by DataBean.data can be parsed into the following features and definitions.

Feature	Data definition
Device binding	`[<Operator name>, <Lock name>]`
Temporary password	`[<Temporary password name>, <Time of taking effect>, <Time of expiration>, <Schedules (only one schedule for the one-in-one lock) [<Whether effective all day>, <Time of taking effect in minutes>, <Time of expiration in minutes>, <Working days>, <Time zone>]]`
Validity period of user (multiple validity periods supported)	`[<"User whose validity period is modified",Permanent or not>, <Time of taking effect>, <Time of expiration>, <Schedules (only one schedule for the one-in-one lock) [Whether effective all day>, <Time of taking effect in minutes>, <Time of expiration in minutes>, <Time zone]>]`
Add or delete an unlocking method	`[<User ID>, <Username>, <Unlocking name on the device>, <Type—unlock with card (standard DP)>]`
Insert a module or take it out of the lock	`[<Module type>]`: `1` represents a Bluetooth LE and NB-IoT combo module.
Get an offline password	`[<Offline password name,Time of taking effect,Time of expiration,Offline password type]>]`. The offline password types include: `0`: a password that can be used as many times as needed before it expires `1`: a one-time password `8`: a code for clearing a single password `9`: a code for clearing all used passwords
Rename an offline password	`[<Old name>, <New name>, <Password type>]`
Unlocking record	`"1"`: unlocking method ID

Definitions of log types for pro edition

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 an offline password that can be used as many times as needed before it expires
offline_pwd_clear_achieve	Get a code for clearing of all offline passwords
offline_pwd_clear_single_achieve	Get a code for clearing of a single offline password
offline_pwd_name_update	Update the name of an offline temporary password
unlock_ble	Unlock over Bluetooth by pressing a key
unlock_password	Unlock with a normal password
unlock_temporary	Unlock with a temporary password
unlock_dynamic	Unlock with a dynamic password
unlock_offline_pd	Unlock with an offline password
unlock_offline_clear	Report the clearing of all offline passwords
unlock_offline_clear_single	Report the clearing of a single offline password
unlock_fingerprint	Unlock with a fingerprint
unlock_card	Unlock with a card
unlock_key	Unlock with a mechanical key
unlock_face	Unlock with face recognition
unlock_eye	Unlock with iris
unlock_hand	Unlock with a palm print
unlock_finger_vein	Unlock with a 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 record
unlock_record_check	Accessory record
unlock_phone_remote	Record of remote unlocking on the app
unlock_app	Record of unlocking on the app for legacy versions
unlock_voice_remote	Record of unlocking by talking to a speaker
door_opened	Door opened
open_inside	Unlock from the inside of the door
timer_opened	The timer ON command already executed
timer_closed	The timer OFF command already executed
dev_communication_module_add	Insert a module or take it out of the lock

Standard DPs on lock

Type	Description
arming_switch	Arm away
unlock_switch	Switch between single unlocking and combined unlocking
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	Local voice guidance volume

Error codes

The following list of error codes is subject to the basic error codes for Smart Lock SDK.

Error code	Description
10203	The device is offline.
10204	The operation timed out.
13001	The password verification is not passed.
13002	Incorrect data check.
13003	The data does not exist.
13004	The DP does not exist.
13005	The unlocking fingerprint is incomplete.
13006	The device reports the failure of the unlocking method enrollment.
13007	The device reports the `userId` of the unlocking method enrollment does not exist.
13008	Add, modify, and delete an unlocking method: The lock fails to return a response.
13009	The device reports the failure of updating a temporary online password.
13010	The device reports the failure of deleting a temporary online password.
13011	The device reports the failure of creating a temporary online password.
13012	The device reports all hardware IDs are assigned in the operation of creating a temporary online password.
130013	The user cancels fingerprint enrollment.

Prev DocWi-Fi Smart Lock

Next DocWi-Fi Smart Lock Audio and Video Capabilities