Zigbee Lock

Last Updated on : 2024-05-20 10:07:01download

This topic describes various features of Zigbee door locks, including home members, unlocking methods, temporary passwords, history, remote operation, and settings.

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.
`IThingZigBeeLock`	The Zigbee lock class that includes all methods of Zigbee locks.

Sample code

The following code block shows how to create a Zigbee 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 IThingZigBeeLock class.
IThingZigBeeLock thingLockDevice = ThingLockManager.getZigBeeLock("your_device_id");

Terms

Term	Description
Duress alarm	The duress alarm feature allows users to enroll a password or fingerprint as a duress code. If they are coerced by hostile persons, unlocking with the duress code can trigger alarms that will be sent to a list of contacts.
Lock member	Lock members are home members, the same as that defined in the Smart Life App SDK. The Smart Lock SDK can be used to bind a lock password ID with a home member account. For more information, see Home Management.
lockUserId	A `lockUserId` is a member ID that the cloud assigns to a lock when you create a lock member. Each `lockUserId` indicates the member ID that is recorded in the firmware.
userId	A `userId` is the ID that the cloud assigns to a lock member when you create a lock member. Each `userId` is a unique ID of each user and is recorded in a database.
dpCode	The identifier of a data point (DP) for a device. Each DP is assigned a name and an identifier indicated by `dpCode`.
unlockId	An `unlockId` is the unlocking method ID that consists of an unlocking DP ID plus a lock ID. For example, `12-c`, where `c` is the hexadecimal converted from the decimal.
opmodeId	The ID of an unlocking method in the cloud.

Home members

This section describes the operations regarding home members.

Get member list

API description

/**
* Get the list of home members.
*
* @param callback The callback.
*/
void getMemberList(IThingDataCallback<ArrayList<MemberInfoBean>> callback);

Data model of MemberInfoBean

Field	Type	Description
userId	String	User IDs
avatarUrl	String	The URL address of a specified avatar.
lockUserId	Integer	The user ID in the lock firmware.
nickName	String	The nickname.
userType	Integer	The type of user. Valid values: `10`: administrator `20`: common user `50`: home owner
userContact	String	The contact information of the user.
unlockDetail	List	The list of unlocking methods that the user can use. For more information, see the data model of `UnlockDetail`.

Data model of UnlockDetail

Field	Type	Description
dpId	Integer	The DP ID of the unlocking method.
count	Integer	The number of unlocking methods.
unlockList	List	The list of unlocking methods. For more information, see the 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 a specified unlocking method.
unlockAttr	Integer	The attribute of an unlocking method. Valid values: `1`: duress alarm `0`: not duress alarm
admin	Boolean	Indicates whether the administrator’s fingerprint is used.

Sample code

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

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

Get member details

Get details of the current user or a specified user.

API description

/**
* Query the details of the current home member.
*
* @param callback The callback.
*/
void getMemberInfo(IThingDataCallback<MemberInfoBean> callback);
/**
* Query the details of a specified home member.
*
* @param callback The callback.
*/
void getMemberInfo(String userId, IThingDataCallback<MemberInfoBean> callback);

Sample code

// Query the details of the current home member.
zigBeeLock.getMemberInfo(new IThingDataCallback<MemberInfoBean>() {
    @Override
    public void onSuccess(MemberInfoBean bean) {
        Log.i(Constant.TAG, "getMemberInfo success:" + bean);
    }

    @Override
    public void onError(String code, String message) {
        Log.e(Constant.TAG, "getMemberInfo failed: code = " + code + " message = " + message);
    }
});
// Query the details of a specified home member.
zigBeeLock.getMemberInfo("userId", new IThingDataCallback<MemberInfoBean>() {
    @Override
    public void onSuccess(MemberInfoBean bean) {
        Log.i(Constant.TAG, "getMemberInfo success:" + bean);
    }

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

Add a member

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

API description

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

Data model of MemberWrapperBean

For more information, see Member Information Management.

Sample code

MemberWrapperBean.Builder memberWrapperBean = new MemberWrapperBean.Builder();
memberWrapperBean.setNickName();// The nickname of the member.
memberWrapperBean.setCountryCode();// The country or region code.
memberWrapperBean.setAccount();// The app account.
memberWrapperBean.setRole();// The role of the member.
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.
zigBeeLock.addMember(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 specified home member and all unlocking methods that are associated with this member from the device.

API description

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

Sample code

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

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

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

Modify information about a member

Modify only the nickname and role of a specified member.

API description

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

Data model of MemberWrapperBean

For more information, see Member Information Management.

Sample code

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.
zigBeeLock.updateMember(memberWrapperBean.build(), new IResultCallback() {
    @Override
    public void onError(String code, String error) {
        Log.e(Constant.TAG, "updateMember failed: code = " + code + " message = " + error);
    }

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

Get unlocking methods

Get the list of bound unlocking methods.

API description

/**
* Get the details of unlocking methods of a specified user.
*
* @param userId   The user ID.
* @param callback The callback.
*/
void getMemberOpmodeList(String userId, IThingResultCallback<ArrayList<OpModeBean>> callback);

Sample code

zigBeeLock.getMemberOpmodeList("userId", new IThingResultCallback<ArrayList<OpModeBean>>() {
    @Override
    public void onSuccess(ArrayList<OpModeBean> result) {
        Log.i(Constant.TAG, "getMemberOpmodeList onSuccess:" + result);
    }

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

Data model of OpModeBean

Field	Type	Description
opmode	String	The unlocking method. Valid values: `1`: fingerprint `2`: password `3`: card
opmodeValue	String	The number of a specified unlocking method in the cloud, equivalent to SN.
unlockId	String	The ID of an unlocking method.
lockUserId	Int	The lock member ID.
opmodeId	Long	The ID of an unlocking method in the cloud.
unlockAttr	Int	The attribute of an unlocking method. Valid values: `1`: duress alarm `0`: not duress alarm
unlockName	String	The name of a specified unlocking method.
userName	String	The nickname of the user.
userId	String	The user ID.

Get the list of unbound unlocking methods

API description

/**
* Get the list of unassigned unlocking methods.
*
* @param callback The callback.
*/
void getUnAllocOpMode(IThingDataCallback<ArrayList<UnAllocOpModeBean>> callback);

Sample code

zigBeeLock.getUnAllocOpMode(new IThingDataCallback<ArrayList<UnAllocOpModeBean>>() {
    @Override
    public void onSuccess(ArrayList<UnAllocOpModeBean> result) {
        Log.i(Constant.TAG, "getUnAllocOpMode onSuccess:" + result);
    }

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

Data model of UnAllocOpModeBean

Field	Type	Description
opmode	String	Get unlocking methods `1`: fingerprint `2`: password `3`: card
unlockInfo	List	The details of the unassigned unlocking method. For more information, see the settings of `UnAllocLockBean`.

Data model of UnAllocLockBean

Field	Type	Description
devId	String	The device ID.
unlockSn	Int	The ID of the current unlocking method in the lock.
unlockId	String	The ID of an unlocking method.
opmodeId	Long	The ID of an unlocking method in the cloud.
unlockName	String	The name of a specified unlocking method.

Assign unlocking method

API description

/**
* Assign an unlocking method to a specific user.
*
* @param userId   The user ID.
* @param unlockIds The unlocking method.
* @param callback The callback.
*/
void allocUnlockOpMode(String userId, List<String> unlockIds, IThingResultCallback<Boolean> callback);

Request parameters

Field	Type	Description
userId	String	User IDs
unlockIds	List	The list of unlocking methods.

Sample code

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

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

Bind unlocking method/history with a user

API description

/**
* Bind an unlocking method or history with a specific user.
*
* @param userId   The user ID.
* @param unlockIds The unlocking method.
* @param callback The callback.
*/
void bindOpModeToMember(String userId, List<String> unlockIds, IThingResultCallback<Boolean> callback);

Request parameters

Field	Type	Description
userId	String	User IDs
unlockIds	List	The list of unlocking methods.

Sample code

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

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

Add unlocking method

API description

/**
* Add an unlocking method
*
* @param opModeAddRequest The request parameter.
* @param callback         The callback.
*/
void addUnlockOpmodeForMember(OpModeAddRequest opModeAddRequest, IThingResultCallback<OpModeAddBean> callback);

/**
* Add an unlocking method (sending with password)
*
* @param opModeAddRequest The request parameter.
* @param callback         The callback.
*/
void addPasswordOpmodeForMember(OpModeAddRequest opModeAddRequest, IThingResultCallback<OpModeAddBean> callback);

Data model of OpModeAddRequest

Field	Type	Description
userId	String	User IDs
lockUserId	Integer	The user ID in the lock firmware.
unlockName	String	The name of a specified unlocking method.
unlockAttr	Integer	Specifies whether to enable the unlocking notifications in emergency conditions like duress. Valid values: `0`: no. `1`: yes.
password	String	The password, required when a command is sent with password.
unlockType	String	The `DP code` of the unlocking method type.
userType	Integer	The type of user. Valid values: `10`: administrator `20`: common user `50`: home owner

Data model of OpModeAddBean

Field	Type	Description
opModeId	long	The ID of a specified unlocking method in the cloud.
unlockName	String	The name of a specified unlocking method.

Sample code for getting cloud capabilities

Determine which of the two APIs to use depending on the return tyabitmqxx value. If the return value is empty, the value defaults to false.

Field	Description
true	Use `addUnlockOpmodeForMember`
false	Use `addPasswordOpmodeForMember`

private boolean tyabitmqxx = false;
zigBeeLock.getLockDeviceConfig(new IThingResultCallback<JSONObject>() {
    @Override
    public void onSuccess(JSONObject result) {
        JSONObject powerCode = result.getJSONObject("powerCode");
        if (powerCode != null) {
            if (powerCode.containsKey("tyabitmqxx")) {
                tyabitmqxx = powerCode.getBooleanValue("tyabitmqxx");
            } else {
                tyabitmqxx = true;
            }
        }
        //Special note: whether the input box is displayed in the UI is determined by tyabitmqxx=false
    }

    @Override
    public void onError(String errorCode, String errorMessage) {

    }
});

Sample code for adding an unlocking method

private void addUnlockMode() {
    if (!tyabitmqxx) {
        // Add an unlocking method.
        zigBeeLock.addPasswordOpmodeForMember(request, new IThingResultCallback<OpModeAddBean>() {
            @Override
            public void onSuccess(OpModeAddBean result) {
                Log.i(Constant.TAG, "addPasswordOpmodeForMember onSuccess:" + result);
            }

            @Override
            public void onError(String errorCode, String errorMessage) {
                Log.e(Constant.TAG, "addProUnlockOpModeForMember:" + errorMessage);
            }
        });
        return;
    }
    // Add an unlocking method with password
    zigBeeLock.addUnlockOpmodeForMember(request, new IThingResultCallback<OpModeAddBean>() {
        @Override
        public void onSuccess(OpModeAddBean result) {
            Log.i(Constant.TAG, "addUnlockOpmodeForMember onSuccess:" + result);
        }

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

Update unlocking method

This method can only be used to update the unlocking method name and enable or disable the duress feature.

API description

/**
* Update the unlocking method.
*
* @param userId   The user ID.
* @param unlockName The name of a specified unlocking method.
* @param opModeId The ID of a specified unlocking method that is stored in the cloud.
* @param unlockAttr Specifies whether to enable the duress feature. 0: disable, 1: enable.
* @param unlockId  The lock ID.
* @param callback   The callback.
*/
void modifyUnlockOpmodeForMember(String userId, String unlockName, long opModeId, int unlockAttr, String unlockId, IThingResultCallback<Boolean> callback);

Sample code

zigBeeLock.modifyUnlockOpmodeForMember(
    "userId",
    "unlockName",
    "opmodeId",
    "unlockAttr",
    "unlockId",
    new IThingResultCallback<Boolean>() {
        @Override
        public void onSuccess(Boolean result) {
        }

        @Override
        public void onError(String errorCode, String errorMessage) {
        }
    });

Delete unlocking method

API description

/**
* Delete an unlocking method.
*
* @param removeRequest The request parameter.
* @param callback      The callback.
*/
void removeUnlockOpmodeForMember(OpModeRemoveRequest removeRequest, IThingResultCallback<Boolean> callback);

Data model of OpModeRemoveRequest

Field	Type	Description
userId	String	User IDs
lockUserId	String	The user ID in the lock firmware.
userType	Integer	The type of user. Valid values:
unlockId	String	The ID of an unlocking method.
opModeId	String	The number of a specified unlocking method in the cloud.

Sample code

OpModeRemoveRequest removeRequest = new OpModeRemoveRequest();
removeRequest.setUserId(infoBean.getUserId());
removeRequest.setLockUserId(infoBean.getLockUserId());
removeRequest.setUnlockId(infoBean.getUnlockId());
removeRequest.setOpModeId(infoBean.getOpmodeId());
removeRequest.setUserType(infoBean.getUserType());
zigBeeLock.removeUnlockOpmodeForMember(removeRequest, new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        Log.i(Constant.TAG, "removeUnlockOpmodeForMember onSuccess:" + result);
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        Log.e(Constant.TAG, "removeUnlockOpmodeForMember:" + errorMessage);
    }
});

Cancel unlocking method enrollment

API description

/**
* Cancel the enrollment of an unlocking method.
*
* @param unlockType   The DP code of a specified unlocking method.
* @param lockUserId The user ID.
* @param userType   The permission of a specified member.
* @param callback   The callback.
*/
void cancelUnlockOpMode(String dpCode, int lockUserId, int userType, IResultCallback callback);

Sample code

private void cancelUnlock() {
    zigBeeLock.cancelUnlockOpMode(request.getUnlockType(), request.getLockUserId(), request.getUserType(), new IResultCallback() {
        @Override
        public void onError(String code, String error) {

        }

        @Override
        public void onSuccess() {

        }
    });
}

Set the duress alarm feature

This API call has been built into the method of adding or updating a member’s unlocking methods.

API description

/**
* Set the duress alarm feature.
*
* @param dpId      The DP ID.
* @param unlockId  The DP value.
* @param callback The callback.
*/
void addHijackingConfig(String dpId, String unlockId, IThingResultCallback<Boolean> callback);

Remove the duress alarm feature

This API call has been built into the method of adding or updating a member’s unlocking methods.

API description

/**
* Remove the duress alarm feature.
*
* @param dpId      The DP ID.
* @param unlockId  The DP value.
* @param callback The callback.
*/
void removeHijacking(String dpId, String unlockId, IThingResultCallback<Boolean> callback);

Temporary password

Get the list of temporary passwords

API description

/**
* Get the list of temporary passwords.
*
* @param limit    The maximum number of entries returned on each page.
* @param offset    The number of the entry starting from which entries are returned.
* @param callback The callback.
*/
void getPasswordList(int offset, int limit, IThingResultCallback<PasswordBean> callback);

Sample code

zigBeeLock.getPasswordList(0, 50, new IThingResultCallback<PasswordBean>() {
    @Override
    public void onSuccess(PasswordBean result) {
        Log.i(Constant.TAG, "getPasswordList success: " + result);
    }

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

Data model of PasswordBean

Field	Type	Description
hasNext	Boolean	Specifies whether there is a next page.
totalCount	Integer	The number of entries to be returned.
datas	List	The list of data. For more information, see `DataBean`.

Data model of DataBean

Field	Type	Description
effectiveTime	long	The effective time.
invalidTime	long	The end time.
password	String	The clear-text password.
phase	Integer	The status and phase. Valid values: `1`: processing `2`: normal `3`: frozen
oneTime	Integer	The type of password. Valid values: `1`: a one-time password `0`: a periodic password
ifEffective	Boolean	Specifies whether the password is valid.
operate	Integer	Recent operations. Valid values: `125`: delete `126`: modify `127`: freeze `128`: unfreeze
name	String	The password name.
deliveryStatus	Integer	The status. Valid values: `1`: not confirmed `2`: confirmed
modifyData	List	The list of data. For more information, see `ModifyDataBean`.

Data model of ModifyDataBean

Field	Type	Description
effectiveTime	long	The effective time.
invalidTime	long	The end time.
ifEffective	Boolean	Specifies whether the password is valid.
name	String	The password name.
scheduleList	List	The list of a specified schedule. For more information, see `ScheduleBean`.

Get the status of temporary passwords

Based on the data returned by the list, the corresponding status is displayed in the UI.

Get the list of invalid temporary passwords

API description

/**
* Get the list of invalid temporary passwords.
*
* @param limit    The maximum number of entries returned on each page.
* @param offset    The number of the entry starting from which entries are returned.
* @param callback The callback.
*/
void getInvalidPasswordList(int offset, int limit, IThingResultCallback<PasswordBean> callback);

Sample code

zigBeeLock.getInvalidPasswordList(0, 100, new IThingResultCallback<PasswordBean>() {
    @Override
    public void onSuccess(PasswordBean result) {
        Log.i(Constant.TAG, "getInvalidPasswordList success: " + result);
    }

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

Clear invalid passwords

API description

/**
* Clear invalid passwords.
*
* @param callback The callback.
*/
void removeInvalidPassword(IThingResultCallback<String> callback);

Sample code

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

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

Get dynamic password

API description

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

Data model of DynamicPasswordBean

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

Sample code

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

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

Add temporary periodic password

API description

/**
* Add a temporary periodic password.
*
* @param request The request parameter.
* @param callback The callback.
*/
void addTemporaryPassword(PasswordRequest request, IThingResultCallback<String> callback);

Data model of PasswordRequest

Field	Type	Description
id	Long	The ID in the cloud.
name	String	The password name.
password	String	The password content.
sn	Int	The serial number of the temporary password in the lock.
effectiveTime	Long	The effective time.
invalidTime	Long	The end time.
availTime	Int	The number of times the password can be used. Valid values: `0`: a permanent password `1`: a one-time password
schedule	List	The list of a specified schedule. For more information, see `ScheduleBean`.

Data model of ScheduleBean

Field	Type	Description
workingDay	Integer	Indicates whether the password is valid on a working day. For more information, see the description of `workingDay`.
allDay	Boolean	Indicates whether the password 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 800.
invalidTime	Integer	The end time in minutes. Example: To make the setting expire at 18 o’clock in the afternoon on the current day, the value is 1800.
timeZoneId	String	The time zone information (optional).

Description of workingDay

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

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

Sample code

PasswordRequest passwordRequest = new PasswordRequest();
passwordRequest.setName("nickname");
passwordRequest.setPassword("password");
passwordRequest.setSchedule("schedule");
passwordRequest.setEffectiveTime("effective time");
passwordRequest.setInvalidTime("expiration time");
passwordRequest.setAvailTime(0);
zigBeeLock.addTemporaryPassword(passwordRequest, new IThingResultCallback<String>() {
    @Override
    public void onSuccess(String result) {
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
    }
});

Add temporary one-time password

Before use, you need to check whether the DP code single_use_password exists on the device to determine whether a temporary one-time password can be added.

API description

/**
* Add a temporary one-time password.
*
* @param request The request parameter.
* @param callback The callback.
*/
void addTemporaryPassword(PasswordRequest request, IThingResultCallback<String> callback);

Sample code

PasswordRequest passwordRequest = new PasswordRequest();
passwordRequest.setName("nickname");
passwordRequest.setPassword("password");// It can be empty, generated in the cloud.
passwordRequest.setAvailTime(1);
zigBeeLock.addTemporaryPassword(passwordRequest, new IThingResultCallback<String>() {
    @Override
    public void onSuccess(String result) {
        // If the password is not passed, the cloud will generate a random password. You need to parse and display the returned data content.
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
    }
});

Rename temporary password

API description

/**
* Rename the password
*
* @param unlockName The name of a specified password.
* @param opModeId The password ID in the cloud (DataBean.id of the temporary password list).
* @param callback   The callback.
*/
void updateTemporaryPassword(String unlockName, long opModeId, IThingResultCallback<Boolean> callback);

Sample code

zigBeeLock.updateTemporaryPassword("name", "id", new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
    }
});

Modify temporary password

Modify a periodic temporary password.

API description

/**
* Edit a specified password.
*
* @param request The request parameter.
* @param callback The callback.
*/
void modifyTemporaryPassword(PasswordRequest request, IThingResultCallback<String> callback);

Sample code

PasswordRequest passwordRequest = new PasswordRequest();
passwordRequest.setId("id");
passwordRequest.setName("nickname");
passwordRequest.setSchedule("schedule");
passwordRequest.setEffectiveTime("effective time");
passwordRequest.setInvalidTime("expiration time");
passwordRequest.setAvailTime(0);
zigBeeLock.modifyTemporaryPassword(passwordRequest, new IThingResultCallback<String>() {
    @Override
    public void onSuccess(String result) {
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
    }
});

Delete a temporary password

API description

/**
* Delete a temporary password.
*
* @param removeRequest The request parameter.
* @param callback      The callback.
*/
void removeTemporaryPassword(PasswordRemoveRequest removeRequest, IThingResultCallback<String> callback);

Sample code

PasswordRemoveRequest removeRequest = new PasswordRemoveRequest();
removeRequest.setId(dataBean.id);//The password ID.
removeRequest.setAvailTime(dataBean.oneTime);//One-time or periodic password
removeRequest.setName(dataBean.name);//Nickname
removeRequest.setEffectiveTime(dataBean.effectiveTime);//Effective time
removeRequest.setInvalidTime(dataBean.invalidTime);//Expiration time
zigBeeLock.removeTemporaryPassword(removeRequest, new IThingResultCallback<String>() {
    @Override
    public void onSuccess(String result) {
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
    }
});

Freeze temporary password

API description

/**
* Freeze a temporary password
*
* @param request The request parameter.
* @param callback The callback.
*/
void freezeTemporaryPassword(PasswordRequest request, IThingResultCallback<String> callback);

Sample code

PasswordRequest passwordRequest = new PasswordRequest();
passwordRequest.setPassword(dataBean.password);
passwordRequest.setName(dataBean.name);
passwordRequest.setEffectiveTime(dataBean.effectiveTime);
passwordRequest.setInvalidTime(dataBean.invalidTime);
passwordRequest.setAvailTime(dataBean.oneTime);
passwordRequest.setId(dataBean.id);
zigBeeLock.freezeTemporaryPassword(passwordRequest, new IThingResultCallback<String>() {
    @Override
    public void onSuccess(String result) {
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
    }
});

Unfreeze temporary password

API description

/**
* Unfreeze a temporary password.
*
* @param request The request parameter.
* @param callback The callback.
*/
void unfreezeTemporaryPassword(PasswordRequest request, IThingResultCallback<String> callback);

Sample code

PasswordRequest passwordRequest = new PasswordRequest();
passwordRequest.setPassword(dataBean.password);
passwordRequest.setName(dataBean.name);
passwordRequest.setEffectiveTime(dataBean.effectiveTime);
passwordRequest.setInvalidTime(dataBean.invalidTime);
passwordRequest.setAvailTime(dataBean.oneTime);
passwordRequest.setId(dataBean.id);
zigBeeLock.unfreezeTemporaryPassword(passwordRequest, new IThingResultCallback<String>() {
    @Override
    public void onSuccess(String result) {
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
    }
});

History

Number of unread alerts

API description

/**
* The number of unread alerts.
*
* @param callback The callback.
*/
void getUnreadAlarmNumber(IThingResultCallback<String> callback);

Sample code

zigBeeLock.getUnreadAlarmNumber(new IThingResultCallback<String>() {
    @Override
    public void onSuccess(String result) {
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
    }
});

Alert history (doorbell + alert + duress)

API description

/**
* Alert and doorbell history
*
* @param devId    The device ID.
* @param dpIds     The DP IDs of alert types.
* @param offset    The number of the entry starting from which entries are returned.
* @param limit    The maximum number of entries returned on each page.
* @param callback The callback.
*/
void getAlarmRecordList(String devId, List<String> dpIds, int offset, int limit, final IThingResultCallback<RecordBean> callback);

Sample code

List<String> dpIds = new ArrayList<>();
dpIds.add(zigBeeLock.convertCode2Id(ZigBeeDatePoint.HI_JACK));
dpIds.add(zigBeeLock.convertCode2Id(ZigBeeDatePoint.ALARM_LOCK));
dpIds.add(zigBeeLock.convertCode2Id(ZigBeeDatePoint.DOORBELL));
zigBeeLock.getAlarmRecordList(mDevId, dpIds, 0, 30, new IThingResultCallback<RecordBean>() {
    @Override
    public void onSuccess(RecordBean result) {
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
    }
});

Unlocking history

API description

/**
* Unlocking history.
*
* @param devId    The device ID.
* @param dpIds     The DP IDs of unlocking methods.
* @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 callback The callback.
*/
void getUnlockRecordList(String devId, List<String> dpIds, int offset, int limit, final IThingResultCallback<RecordBean> callback);

Sample code

List<String> dpIds = new ArrayList<>();
dpIds.add(zigBeeLock.convertCode2Id(ZigBeeDatePoint.UNLOCK_CARD));
dpIds.add(zigBeeLock.convertCode2Id(ZigBeeDatePoint.UNLOCK_PASSWORD));
dpIds.add(zigBeeLock.convertCode2Id(ZigBeeDatePoint.UNLOCK_DYNAMIC));
dpIds.add(zigBeeLock.convertCode2Id(ZigBeeDatePoint.UNLOCK_FINGERPRINT));
dpIds.add(zigBeeLock.convertCode2Id(ZigBeeDatePoint.UNLOCK_TEMPORARY));
dpIds.add(zigBeeLock.convertCode2Id(ZigBeeDatePoint.UNLOCK_KEY));
dpIds.add(zigBeeLock.convertCode2Id(ZigBeeDatePoint.UNLOCK_REMOTE));
dpIds.add(zigBeeLock.convertCode2Id(ZigBeeDatePoint.OPEN_INSIDE));
zigBeeLock.getUnlockRecordList(mDevId, dpIds, 0, 30, new IThingResultCallback<RecordBean>() {
    @Override
    public void onSuccess(RecordBean result) {
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
    }
});

Remote features

Remote unlocking

You need to listen to the door status related DPs supported by the device to show whether the door is opened correctly. The API only returns successful execution.

API description

/**
* Remote unlocking.
*
* @param callback The callback.
*/
void remoteUnlock(IResultCallback callback);

Sample code

zigBeeLock.remoteUnlock(new IResultCallback() {
    @Override
    public void onError(String code, String error) {
    }

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

Remote locking

API description

/**
* Remote locking.
*
* @param callback The callback.
*/
void remoteLock(IResultCallback callback);

Sample code

zigBeeLock.remoteLock(new IResultCallback() {
    @Override
    public void onError(String code, String error) {
    }

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

Query on/off status of remote unlocking

API description

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

Sample code

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

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

Set on/off status of remote unlocking

API description

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

Sample code

zigBeeLock.setRemoteUnlockType(isOpen, new IResultCallback() {
    @Override
    public void onError(String code, String error) {
    }

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

Get remote unlocking permission

Prerequisite: The device needs to support two remote DP codes, remote_no_dp_key and remote_unlock, where remote_unlock is the prerequisite for remote unlocking with password. If remote_unlock is not supported, password-related features need to be hidden.

API description

/**
* Get remote unlocking permission
*
* @param callback The callback.
*/
void getRemoteUnlockPermissionValue(IThingResultCallback<RemotePermissionEnum> callback);

Sample code

zigBeeLock.getRemoteUnlockPermissionValue(new IThingResultCallback<RemotePermissionEnum>() {
    @Override
    public void onSuccess(RemotePermissionEnum result) {
    }
}

RemotePermissionEnum enumeration

Type	Description
REMOTE_NOT_DP_KEY_ALL	Unlock without password for everyone
REMOTE_NOT_DP_KEY_ADMIN	Unlock without password for admin
REMOTE_UNLOCK_ALL	Unlock with password for everyone
REMOTE_UNLOCK_ADMIN	Unlock with password for admin

Remote unlocking with password

Note that the password for remote unlocking is the password specified for the member’s unlocking method, not a temporary password.

Sample code

zigBeeLock.remoteUnlock(password, new IResultCallback() {
    @Override
    public void onError(String code, String error) {
    }

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

Set remote unlocking permission

API description

/**
* Set remote unlocking permission.
*
* @param permissionEnum Permission enumeration.
* @param callback       The callback.
*/
void setRemoteUnlockPermissionValue(RemotePermissionEnum permissionEnum, IResultCallback callback);

Sample code

zigBeeLock.setRemoteUnlockPermissionValue(RemotePermissionEnum.REMOTE_NOT_DP_KEY_ADMIN, new IResultCallback() {
    @Override
    public void onError(String code, String error) {
    }

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

Check if the speaker password is enabled

API description

/**
* Check if the speaker password is enabled.
*
* @param callback The callback.
*/
void fetchRemoteVoiceUnlock(IThingResultCallback<Boolean> callback);

Sample code

zigBeeLock.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 or cancel a speaker password

API description

/**
* Set or cancel a voice password.
*
* @param isOpen   Specifies whether this feature is enabled.
* @param password      The password.
* @param callback The callback.
*/
void setRemoteVoiceUnlock(boolean isOpen, String password, IThingResultCallback<Boolean> callback);

Sample code

zigBeeLock.setRemoteVoiceUnlock(isOpen, password, new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
    }

    @Override
    public void onError(String code, String error) {
    }
});

Additional features

Get the device’s activation time up to now

Get the device’s activation time up to now. For example, how many days it has protected the user.

API description

/**
* Get the device's activation time up to now.
*
* @param callback The callback.
*/
void getSecurityGuardDays(IThingResultCallback<String> callback);

Sample code

zigBeeLock.getSecurityGuardDays(new IThingResultCallback<String>() {
    @Override
    public void onSuccess(String result) {
    }

    @Override
    public void onError(String errorCode, String errorMessage) {

    }
});

Get cloud capabilities

Get the panel cloud capabilities of the device.

API description

/**
* Get cloud capabilities.
*
* @param callback The callback.
*/
void getLockDeviceConfig(IThingResultCallback<JSONObject> callback);

Sample code

zigBeeLock.getLockDeviceConfig(new IThingResultCallback<JSONObject>() {
    @Override
    public void onSuccess(JSONObject result) {
        JSONObject powerCode = result.getJSONObject("powerCode");
    }

    @Override
    public void onError(String errorCode, String errorMessage) {

    }
});

Miscellaneous

Error codes

Error code	Description
-10002	A device goes offline.
-10003	The request timed out.
-10004	Incorrect data check.
-10005	The data does not exist.
-10006	The DP does not exist.
-11001	The user canceled unlocking method enrollment.
-11002	The fingerprint is incomplete.
-11003	The device reports the failure of the unlocking method enrollment.
-11004	Failed to delete the specified unlocking method.
-11005	The unlocking method cannot be deleted.
-11007	Add an unlocking method — repeated enrollment.
-11008	Add an unlocking method — all hardware numbers have been assigned.
-11009	Add an unlocking method — the password being added is not a number.
-11010	Add an unlocking method — the password length is incorrect.
-11011	Add an unlocking method — the unlocking method is not supported.
-11012	Add an unlocking method — a fingerprint is being enrolled.
-11013	Add an unlocking method — the number is incorrect.
-11014	The password is empty.

DPs of unlocking history

DP	Functional description
unlock_fingerprint	Unlock with fingerprint
unlock_password	Unlock with password
unlock_temporary	Unlock with temporary password
unlock_dynamic	Unlock with dynamic password
unlock_card	Unlock with card
unlock_face	Unlock with face recognition
unlock_key	Unlock with mechanical key
unlock_remote	Remote unlocking
open_inside	Unlock from the inside of the door

Prev DocWi-Fi Smart Lock Audio and Video Capabilities

Next DocSmart Lock Basic API