Wi-Fi Smart Lock

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

Description of classes

Class name Description
ThingOptimusSdk Provides access to the SDK initialization feature and returns the lock management class.
IThingLockManager The lock management class that is used to get different types of lock classes.
IThingWifiLock The Wi-Fi lock class that includes all methods of Wi-Fi locks.

Example

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

// Initialize the SDK for only once.
ThingOptimusSdk.init(getApplicationContext());
// Get the `thingLockManager` class.
IThingLockManager thingLockManager = ThingOptimusSdk.getManager(IThingLockManager.class);
// Create `IThingWifiLock`.
IThingWifiLock thingLockDevice = thingLockManager.getWifiLock("your_lock_device_id");

Terms

Term Description
Duress alarms The duress alarm feature allows users to enroll a password or fingerprint as a duress code. If they are coerced by hostile persons, unlocking with the duress code can trigger alarms to be sent to a list of contacts.
Lock members Lock members are classified into home members and non-home members.
  • Home member: the same as that defined in the Smart Life App SDK. The Smart Lock SDK can be used to associate a lock password ID with a home member account. For more information, see Home Management.
  • Non-home members: an individual member of a smart lock, only associated with the device. This member can be created and assigned. The Smart Lock SDK can be used to associate a lock password ID with this member.
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.

Lock members

This section describes the operations regarding non-home members.

Query a list of lock members

API description

public void getLockUsers(final IThingResultCallback<List<WifiLockUser>> callback)

Fields of WifiLockUser

Field Type Description
userId String The member ID.
userName String The nickname of the user.
avatarUrl String The URL of the avatar.
contact String The contact method.
unlockRelations List The unlocking method and password serial number.
devId String The device ID.
ownerId String The home ID.
userType int The type of lock member. Valid values:
  • 1: home member
  • 2: non-home member

Example

thingLockDevice.getLockUsers(new IThingResultCallback<List<WifiLockUser>>() {
    @Override
    public void onError(String code, String message) {
        Log.e(TAG, "get lock users failed: code = " + code + "  message = " + message);
    }

    @Override
    public void onSuccess(List<WifiLockUser> wifiLockUser) {
        Log.i(TAG, "get lock users success: wifiLockUser = " + wifiLockUser);
    }
});

Create a lock member

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

API description

public void addLockUser(final String userName, File avatarFile, final List<UnlockRelation> unlockRelations, final IThingResultCallback<String> callback)

Parameters

Parameter Optional Description
userName No The name of the member.
avatarFile Yes The avatar of the member. If it is not set, the default avatar is used.
unlockRelations No The mapping between the unlocking method and the password serial number.

You can call getRecords to get the value of UnlockRelation. After unlocking with a password or another method, an unlocking record can be obtained. The unlocking method in the unlocking record can be assigned to a user.

Fields of UnlockRelationBean

Field Type Description
ThingUnlockType Enum The unlocking method.
passwordNumber int The associated password serial number. Valid values: 0 to 999.

Example

ArrayList<UnlockRelation> unlockRelations = new ArrayList<>();
UnlockRelation unlockRelation = new UnlockRelation();
unlockRelation.unlockType = ThingUnlockType.PASSWORD;
unlockRelation.passwordNumber = 1;
unlockRelations.add(unlockRelation);
File avatarFile = new File(getFilesDir(), "1.png");
thingLockDevice.addLockUser("Pan", avatarFile , unlockRelations, new IThingResultCallback<String>() {
    @Override
    public void onError(String code, String message) {
        Log.e(TAG, "add lock user failed: code = " + code + "  message = " + message);
    }

    @Override
    public void onSuccess(String userId) {
        Log.i(TAG, "add lock user success: " + userId);
    }
});

Modify a lock member

API description

Modifies the information about a lock member, including the user name, avatar, and mapping with the unlocking password.

public void updateLockUser(final String userId, final String userName, File avatarFile, final List<UnlockRelation> unlockRelations, final IThingResultCallback<Boolean> callback)

Parameters

Parameter Optional Description
userId No The member ID, required.
userName Yes The username of the member. This parameter is optional and not changed if not set.
avatarFile Yes The avatar of the member. If it is not set, the default avatar is used.
unlockRelations No The mapping between the unlocking method and the password serial number. This parameter is required and not changed if not set.

Example

ArrayList<UnlockRelation> unlockRelations = new ArrayList<>();
UnlockRelation unlockRelation = new UnlockRelation();
unlockRelation.unlockType = ThingUnlockType.PASSWORD;
unlockRelation.passwordNumber = 1;
unlockRelations.add(unlockRelation);
thingLockDevice.updateLockUser("0000005f1g", "pan", null, unlockRelations, new IThingResultCallback<Boolean>() {
    @Override
    public void onError(String code, String message) {
        Log.e(TAG, "update lock user failed: code = " + code + "  message = " + message);
    }

    @Override
    public void onSuccess(Boolean aBoolean) {
        Log.i(TAG, "update lock user success");
    }
});

Modify an unlocking method

API description

Modifies only an unlocking method that is assigned to a home member. The username and avatar of the member are not modified in this call.

The username, avatar, and other information about a member can be modified only in the API requests mentioned in Home Management.

public void updateFamilyUserUnlockMode(String userId, List<UnlockRelation> unlockRelations, IThingResultCallback<Boolean> callback)

Parameters

Parameter Optional Description
userId No The member ID, required.
unlockRelations No The mapping between the unlocking method and the password serial number.

Example

ArrayList<UnlockRelation> unlockRelations = new ArrayList<>();
UnlockRelation unlockRelation = new UnlockRelation();
unlockRelation.unlockType = ThingUnlockType.PASSWORD;
unlockRelation.passwordNumber = 1;
unlockRelations.add(unlockRelation);
thingLockDevice.updateFamilyUserUnlockMode("your_family_user_id", unlockRelations, new IThingResultCallback<Boolean>() {
    @Override
    public void onError(String code, String message) {
        Log.e(TAG, "update family user failed: code = " + code + "  message = " + message);
    }

    @Override
    public void onSuccess(Boolean aBoolean) {
        Log.i(TAG, "update family user success");
    }
});

Delete a lock member

API description

Deletes the information about a lock member. After the member is deleted, the existing password is not deleted.

public void deleteLockUser(String userId, final IThingResultCallback<Boolean> callback)

Parameters

Parameter Description
userId The member ID.

Example

thingLockDevice.deleteLockUser("0000004pnk", new IThingResultCallback<Boolean>() {
    @Override
    public void onError(String code, String message) {
        Log.e(TAG, "delete lock user failed: code = " + code + "  message = " + message);
    }

    @Override
    public void onSuccess(Boolean result) {
        Log.i(TAG, "delete lock user failed success");
    }
});

Temporary passwords

Creates a temporary password. Users can enter this password to unlock a door.

Wi-Fi Smart Lock

Query temporary password list

Returns a list of temporary passwords. The usage status of each temporary password is also displayed.

API description

public void getTempPasswords(final IThingResultCallback<List<TempPassword>> callback)

Data model of ThingSmartLockTempPwdModel

Field Type Description
phone String The mobile phone number.
name String The name of the temporary password.
countryCode String The country or region code.
invalidTime long The timestamp in milliseconds when the temporary password expires.
effectiveTime long The timestamp in milliseconds when the temporary password takes effect.
createTime long The timestamp in milliseconds when the temporary password was created.
id int The unique ID of the temporary password.
sequenceNumber int The serial number of the password, associated with a user account.
status int The status of the temporary password.

Valid values of status include:

int REMOVED = 0; // Deleted
int INVALID = 1; // Invalid
int TO_BE_PUBILSH = 2; // To be sent
int WORKING = 3; // Being used
int TO_BE_DELETED = 4; // To be deleted
int EXPIRED = 5; // Expired

Example

thingLockDevice.getTempPasswords(new IThingResultCallback<List<TempPassword>>() {
    @Override
    public void onError(String code, String message) {
        Log.e(TAG, "get lock temp passwords failed: code = " + code + "  message = " + message);
    }

    @Override
    public void onSuccess(List<TempPassword> tempPasswords) {
        Log.i(TAG, "get lock temp passwords success: tempPasswords" + tempPasswords); 
    }
});

Create a temporary password

The validity period of a temporary password can be customized. This setting must be synced with the lock after the temporary password is created.

API description

public void createTempPassword(TempPassword tempPassword, final IThingResultCallback<Boolean> callback)

Parameters of TempPassword

The following table describes the parameters of this class.

Parameter Optional Description
name No The name of the password.
password No The 7-digit numeric temporary password.
effectiveDate No The timestamp in milliseconds when the temporary password takes effect.
invalidDate No The timestamp in milliseconds when the temporary password expires.
countryCode Yes The country or region code. For example, 86 means mainland China.
phone Yes The mobile phone number. After the password is created, a notification will be sent to this mobile phone number. phone and countryCode are optional. Before phone is set, the mobile phone’s SMS service must be enabled. Otherwise, this setting will not take effect

TempPassword is created by TempPassword.Builder. For more information, see the following example.

Example

TempPasswordBuilder tempPasswordBuilder = new TempPasswordBuilder()
        .name("Liam's password")
        .password("1231231")
        .effectiveTime(System.currentTimeMillis())
        .invalidTime(System.currentTimeMillis() + 24 * 60 * 60 * 1000);
thingLockDevice.createTempPassword(tempPasswordBuilder, new IThingResultCallback<Boolean>() {
    @Override
    public void onError(String code, String message) {
        Log.e(TAG, "create lock temp password: code = " + code + "  message = " + message);
    }

    @Override
    public void onSuccess(Boolean result) {
        Log.i(TAG, "add lock user success");
    }
});

Delete a temporary password

Deletes a temporary password. This setting must be synced with the lock after the temporary password is deleted.

API description

public void deleteTempPassword(int passwordId, final IThingResultCallback<Boolean> callback)

Parameters

Parameter Description
passwordId The unique ID of the temporary password.

Example

thingLockDevice.deleteTempPassword(1111, new IThingResultCallback<Boolean>() {
    @Override
    public void onError(String code, String message) {
        Log.e(TAG, "delete lock temp password failed: code = " + code + "  message = " + message);
    }

    @Override
    public void onSuccess(Boolean result) {
        Log.i(TAG, "delete lock temp password success");
    }
});

Dynamic passwords

Wi-Fi Smart Lock

Returns a dynamic password. Users can enter the dynamic password to unlock a door. The dynamic password is valid for five minutes.

API description

public void getDynamicPassword(final IThingResultCallback<String> callback)

Example

thingLockDevice.getDynamicPassword(new IThingResultCallback<String>() {
    @Override
    public void onError(String code, String message) {
        Log.e(TAG, "get lock dynamic password failed: code = " + code + "  message = " + message);
    }

    @Override
    public void onSuccess(String dynamicPassword) {
        Log.i(TAG, "get lock dynamic password success: dynamicPassword = " + dynamicPassword);
    }
});

Remote unlocking

Users can trigger a remote unlocking request on a lock. Then, the SDK can be used to implement remote locking.

Wi-Fi Smart Lock

Listen for remote unlocking requests

API description

public void setRemoteUnlockListener(RemoteUnlockListener remoteUnlockListener)

Parameters

RemoteUnlockListener provides the following Receive method:

void onReceive(String devId, int second);

Parameters

Field Type Description
devId String The device ID.
second int The minimum response time. Unit: seconds.

Request remote unlocking

API description

public void replyRemoteUnlock(boolean allow, final IThingResultCallback<Boolean> callback)

Parameters

Field Type Description
allow Boolean Specifies whether to allow unlocking the door.

Example

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_lock_device);

	....

    // Registers a listener for remote unlocking requests
    thingLockDevice.setRemoteUnlockListener(new RemoteUnlockListener() {
        @Override
        public void onReceive(String devId, int second) {
            if (second != 0 && !dialogShowing) {
                dialogShowing = true;
                Log.i(TAG, "remote unlock request onReceive");
                onCreateDialog();
            }
        }
    });
}

/**
 * Creates a dialog box that confirms whether to remotely unlock a door.
 */
public void onCreateDialog() {
    // Use the Builder class for convenient dialog construction
    AlertDialog.Builder builder = new AlertDialog.Builder(this);
    builder.setMessage("Whether to allow remote unlocking?")
            .setPositiveButton("YES", new DialogInterface.OnClickListener() {
                public void onClick(DialogInterface dialog, int id) {
                    replyRemoteUnlockRequest(true);
                    Log.i(TAG, "remote unlock request access");
                    dialog.dismiss();
                    dialogShowing = false;
                }
            })
            .setNegativeButton("NO", new DialogInterface.OnClickListener() {
                public void onClick(DialogInterface dialog, int id) {
                    replyRemoteUnlockRequest(false);
                    dialog.dismiss();
                    Log.i(TAG, "remote unlock request deny");
                    dialogShowing = false;
                }
            }).setCancelable(false);
    AlertDialog alertDialog = builder.create();
    alertDialog.setCanceledOnTouchOutside(false);
    alertDialog.show();
}

/**
 * Requests to remotely unlock a door.
 *
 * @param allow
 */
private void replyRemoteUnlockRequest(boolean allow) {
    thingLockDevice.replyRemoteUnlock(allow, new IThingResultCallback<Boolean>() {
        @Override
        public void onError(String code, String message) {
            Log.e(TAG, "reply remote unlock failed: code = " + code + "  message = " + message);
        }

        @Override
        public void onSuccess(Boolean result) {
            Log.i(TAG, "reply remote unlock success");
        }
    });
}

Lock usage records

Query lock usage records

Returns lock usage records based on the specified data point (DP) ID.

API description

public void getRecords(ArrayList<String> dpCodes, int offset, int limit, final IThingResultCallback<Record> callback)

Parameters

Parameter Description
dpCodes The list of data points (DPs) of the target device. For more information, see List of lock DPs.
offset The page number starting from which entries are returned.
limit The total number of returned entries in each call.

Return values

Fields of Record

Field Type Description
totalCount int The total number of returned entries in each call.
hasNext Boolean Indicates whether the next page is included.
datas List The data that is included in a record.

Fields of DataBean

Field Type Description
userId String The member ID.
avatarUrl String The avatar URL of the user.
userName String The nickname of the user.
createTime long The timestamp in milliseconds when the lock usage record was created.
devId String The device ID.
dpCodesMap HashMap<String, Object> The ID and current value of the DP.
unlockRelation UnlockRelation The mapping between an unlocking method and an unlocking password serial number. Ignore this parameter for non-unlocking records.
tags int The flag of the record. Valid values:
  • 0: other types of alarms
  • 1: duress alarm

You can query lock usage records to get the value of unlockRelation and assign the value to a created user.

For example, a password is created on a lock and used to unlock the door. This way, an unlocking record is generated and the unlocking method is returned. Users can query this unlocking record on the app and assign the associated password to a user as needed.

Example

// Sends the DP ID of the unlocking method to get the unlocking records.
ArrayList<String> dpCodes = new ArrayList<>();
dpCodes.add("alarm_lock");
dpCodes.add("hijack");
dpCodes.add("doorbell");
thingLockDevice.getRecords(dpCodes, 0, 10, new IThingResultCallback<Record>() {
    @Override
    public void onError(String code, String message) {
        Log.e(TAG, "get unlock records failed: code = " + code + "  message = " + message);
    }

    @Override
    public void onSuccess(Record recordBean) {
        Log.i(TAG, "get unlock records success: recordBean = " + recordBean);
    }
});

Get unlocking records

Unlocking records include the following events: unlock with a fingerprint, unlock with a normal password, unlock with a temporary password, unlock with a dynamic password, unlock with a card, unlock with biometric recognition, and unlock with a mechanical key.

API description

/**
 * get unlock records
 * @param unlockTypes unlock type list 
 * @param offset page number
 * @param limit item count
 * @param callback callback
 */
void getUnlockRecords(int offset, int limit, final IThingResultCallback<Record> callback);

Parameters

Parameter Description
offset The page number starting from which entries are returned.
limit The total number of returned entries in each call.

Example

thingLockDevice.getUnlockRecords(0, 10, new IThingResultCallback<Record>() {
    @Override
    public void onError(String code, String message) {
        Log.e(TAG, "get unlock records failed: code = " + code + "  message = " + message);
    }

    @Override
    public void onSuccess(Record recordBean) {
        Log.i(TAG, "get unlock records success: recordBean = " + recordBean);
    }
});

Duress alarms

The duress alarm feature allows users to enroll a password or fingerprint as a duress code. If they are coerced by hostile persons, unlocking with the duress code can trigger alarms to be sent to a list of contacts.

Add a duress alarm flag

Adds a duress alarm flag to an unlocking method. The associated password or fingerprint will be specified as a duress code.

API description

/**
 * Set the hijacking flag for the unlock method.
 *
 * @param unlockRelation UnlockRelation
 * @param callback callback
 */
void setHijackingConfig(UnlockRelation unlockRelation, final IThingResultCallback<Boolean> callback);

Parameters

Parameter Description
unlockRelation The mapping between an unlocking method and an unlocking password serial number.
callback The callback.

Remove a duress alarm flag

API description

/**
 * Remove the hijacking flag for the unlock method.
 *
 * @param unlockRelation UnlockRelation
 * @param callback callback
 */
void removeHijackingConfig(UnlockRelation unlockRelation, final IThingResultCallback<Boolean> callback);

Parameters

Parameter Description
unlockRelation The mapping between an unlocking method and an unlocking password serial number.
callback The callback.

Query duress alarm records

Returns the duress alarm records based on the specified unlocking DP data.

API description

public void getHijackRecords(int offset, int limit, final IThingResultCallback<RecordBean> callback)

Parameters

Parameter Description
offset The page number starting from which entries are returned.
limit The total number of returned entries in each call.

Example

thingLockDevice.getHijackRecords(0, 10, new IThingResultCallback<Record>() {
    @Override
    public void onError(String code, String message) {
        Log.e(TAG, "get lock hijack records failed: code = " + code + "  message = " + message);
    }

    @Override
    public void onSuccess(Record hijackingRecordBean) {
        Log.i(TAG, "get lock hijack records success: hijackingRecordBean = " + hijackingRecordBean);
    }
});

List of lock DPs

DP name DP identifier (dpCode)
Unlock with a fingerprint unlock_fingerprint
Unlock with a normal password unlock_password
Unlock with a temporary password unlock_temporary
Unlock with a dynamic password unlock_dynamic
Unlock with a card unlock_card
Unlock with biometric recognition unlock_face
Unlock with a mechanical key unlock_key
Alerts alarm_lock
Countdown of remote unlocking unlock_request
Reply to a remote unlocking request reply_unlock_request
Battery capacity status battery_state
Remaining battery capacity residual_electricity
Double locking status reverse_lock
Child lock status child_lock
Remote unlocking with app unlock_app
Duress alarm hijack
Unlock from the inside of the door open_inside
Open and closed status of the door closed_opened
Doorbell call doorbell
SMS notification message
Double lock by lifting up anti_lock_outside
Unlock with irises unlock_eye
Unlock with palm prints unlock_hand
Unlock with finger veins unlock_finger_vein
Synchronize all fingerprint numbers update_all_finger
Synchronize all password numbers update_all_password
Synchronize all card numbers update_all_card
Synchronize all face numbers update_all_face
Synchronize all iris numbers update_all_eye
Synchronize all palm print numbers update_all_hand
Synchronize all finger vein numbers update_all_fin_vein
Report offline password unlocking unlock_offline_pd
Report the clearing of offline passwords unlock_offline_clear
Report the clearing of a single offline password unlock_offline_clear_single