Wi-Fi 门锁

更新时间:2024-06-17 09:43:13下载pdf

使用说明

类名 说明
ThingOptimusSdk 初始化 SDK 入口,用来获取门锁管理类
IThingLockManager 门锁管理类,可以获取不同类型的门锁类
IThingWifiLock Wi-Fi 门锁类,所有 Wi-Fi 门锁相关方法都在其中

示例代码

通过设备 ID 创建 Wi-Fi 门锁类。

// 初始化 SDK,仅需要调用一次
ThingOptimusSdk.init(getApplicationContext());
// 获取 IThingLockManager
IThingLockManager thingLockManager = ThingOptimusSdk.getManager(IThingLockManager.class);
// 创建 IThingWifiLock
IThingWifiLock thingLockDevice = thingLockManager.getWifiLock("your_lock_device_id");

名词解释

名词列表 说明
门锁劫持 指将特定的指纹、密码等,设置为劫持密码,当用户被劫持,并使用该密码开锁时,门会打开。同时,门锁将开门报警信息发送至家人手机或物业管理系统。
门锁成员 门锁成员分为 家庭成员非家庭成员
  • 家庭成员:涂鸦智能生活 App SDK 中的家庭成员概念。门锁 SDK 将对应的门锁密码编号与该账号关联起来。相关管理操作,请参考 家庭管理
  • 非家庭成员:即为门锁设备单独的成员,仅跟随设备关联。用户可以创建并分配,门锁 SDK 将对应的门锁密码编号与该成员关联起来。
dpCode 设备功能的标识符。每个设备功能都有名称和编号,请参考下文 门锁功能列表

门锁成员

本小节主要介绍门锁成员中 非家庭成员 的管理操作。

获取门锁成员

接口说明

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

WifiLockUser 字段说明

字段 类型 描述
userId String 成员 ID
userName String 用户昵称
avatarUrl String 头像地址
contact String 联系方式
unlockRelations List 开锁方式及密码编号
devId String 门锁设备 ID
ownerId String 所属家庭 ID
userType int 门锁成员类型
  • 1:家庭成员
  • 2:非家庭成员

示例代码

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);
    }
});

创建门锁成员

创建非家庭成员,以供后续开锁记录关联操作。

接口说明

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

参数说明

参数 能否为空 说明
userName 成员名称
avatarFile 成员头像,不传则为默认头像
unlockRelations 成员解锁方式与密码编号的关联关系

UnlockRelation 可以从 获取开锁记录 接口中获取。当门锁使用密码或其他解锁方式后,能够获取解锁记录,然后您可以将解锁记录中的解锁方式分配给某个用户。

UnlockRelationBean 字段说明

字段 类型 描述
ThingUnlockType 枚举 解锁方式
passwordNumber int 关联的密码编号,范围为 0~999

示例代码

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);
    }
});

更新门锁成员

接口说明

更新门锁成员信息,包括用户名、头像、解锁密码对应关系等。

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

参数说明

参数 能否为空 说明
userId 成员用户 ID,必填
userName 成员用户名称,可选,不传则不修改
avatarFile 成员用户头像,可选,不传则为默认头像
unlockRelations 成员解锁方式与密码序列号的关联关系,必填,不修改则填原本的值

示例代码

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");
    }
});

更新家庭成员解锁方式

接口说明

更新家庭成员的解锁方式。此接口仅支持修改分配给家庭成员的解锁方式,不支持修改用户名和头像。

如需修改家庭成员的用户名和头像等,只能通过 家庭成员管理 相关接口处理。

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

参数说明

参数 能否为空 说明
userId 成员用户 ID,必填
unlockRelations 成员解锁方式与密码序列号的关联关系

示例代码

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");
    }
});

删除门锁成员

接口说明

删除门锁成员信息。删除成员后,并不会删除已有的密码。

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

参数说明

参数 说明
userId 门锁成员用户 ID

示例代码

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");
    }
});

临时密码

创建临时密码,并在门锁上进行输入后即可开锁。

门锁用户App云端输入 7 位纯数字临时密码创建临时密码返回创建结果在门锁上输入密码,让设备触发更新密码列表更新密码列表输入密码执行门锁用户App云端临时密码开门

获取临时密码

获取临时密码列表的同时,可以查看临时密码的使用状态情况。

接口说明

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

ThingSmartLockTempPwdModel 数据模型

字段 类型 描述
phone String 手机号
name String 临时密码名称
countryCode String 国家码
invalidTime long 失效时间戳,单位 ms
effectiveTime long 生效时间戳,单位 ms
createTime long 创建时间戳,单位 ms
id int 密码唯一 ID
sequenceNumber int 密码编号,关联账号使用
status int 密码状态

其中,密码状态(status)包含以下类型:

int REMOVED = 0; // 已删除
int INVALID = 1; // 失效
int TO_BE_PUBILSH = 2; // 待下发
int WORKING = 3; // 使用中
int TO_BE_DELETED = 4; // 待删除
int EXPIRED = 5; // 已过期

示例代码

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); 
    }
});

创建临时密码

临时密码可以自定义密码的有效期间。当创建临时密码后,需要在门锁设备上进行同步。

接口说明

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

TempPassword 参数说明

下面为该类的字段说明:

参数 能否为空 说明
name 密码名称
password 7 位纯数字的临时密码
effectiveDate 密码生效时间戳,单位 ms
invalidDate 密码失效时间,单位 ms
countryCode 国家或地区的编码,例如 86 表示中国大陆地区
phone 手机号码,当创建成功时,会通知给该手机用户。phonecountryCode 为选填参数,填写该参数前请确保您已经开通了短信服务,否则不会生效。

TempPassword 通过 TempPassword.Builder 创建。详情请参考以下示例代码。

示例代码

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");
    }
});

删除临时密码

删除临时密码后,需要门锁设备进行更新。

接口说明

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

参数说明

参数 说明
passwordId 门锁临时密码唯一 ID

示例代码

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");
    }
});

动态密码

门锁用户App云端请求获取动态密码返回动态密码结果传达密码得到动态密码输入动态密码执行门锁用户App云端动态密码开门

获取动态密码。在门锁上输入动态密码后即可开锁,动态密码有效时间为 5 分钟。

接口说明

public void getDynamicPassword(final IThingResultCallback<String> callback)

示例代码

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);
    }
});

远程开门

在门锁上触发远程开门请求后,使用 SDK 可以进行远程开门。

用户门锁App操作门锁(4+发起远程开门请求收到门锁请求,通知门锁主人决定确认是否开门发送开门结果处理结果用户门锁App门锁远程开门流程

远程开门监听

接口说明

public void setRemoteUnlockListener(RemoteUnlockListener remoteUnlockListener)

参数说明

RemoteUnlockListener 接口中有一个 Receive 方法,如下所示:

void onReceive(String devId, int second);

方法参数

字段 类型 描述
devId String 设备 ID
second int 最短的响应时间,单位为秒

请求远程开锁

接口说明

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

参数说明

字段 类型 描述
allow boolean 是否允许开锁

示例代码

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

	....

    // 注册远程开锁监听
    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();
            }
        }
    });
}

/**
 * 创建远程开锁确认弹框
 */
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();
}

/**
 * 请求远程开锁接口
 *
 * @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");
        }
    });
}

门锁设置

查询谷歌语音密码开关

接口说明

/**
* 谷歌语音密码开启查询
*
* @param callback 回调
*/
void fetchRemoteVoiceUnlock(IThingResultCallback<Boolean> callback);

示例代码

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);
    }
});

设置谷歌语音密码

接口说明

/**
* 设置或取消谷歌语音密码
*
* @param isOpen   开关设置
* @param password 语音密码
* @param callback 回调
*/
void setRemoteVoiceUnlock(boolean isOpen, String password, IThingResultCallback<Boolean> callback);

示例代码

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);
    }
});

门锁记录

获取门锁记录

本接口可根据传入的设备功能 ID 获取对应的门锁记录。

接口说明

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

参数说明

参数 说明
dpCodes 需要查询的记录的设备功能,具体可以参考对应设备的 门锁功能列表
offset 查询的偏移量
limit 查询的条数

返回值说明

Record 字段:

字段 类型 描述
totalCount int 总条目
hasNext boolean 是否有下一页
datas List 记录数据内容

DataBean 字段:

字段 类型 描述
userId String 成员 ID
avatarUrl String 头像 URL
userName String 用户昵称
createTime long 该门锁记录的时间戳,单位 ms
devId String 设备 ID
dpCodesMap HashMap<String, Object> 该门锁记录的 功能 IDvalue 数据
unlockRelation UnlockRelation 解锁类型和解锁密码编号的关系,如不是门锁记录,可为空
tags int 门锁记录标位:
  • 0:其他
  • 1:劫持报警

您可以通过查询门锁记录,获得 unlockRelation,然后分配给 创建的用户

例如您在门锁上创建了一个密码,然后使用了该密码开锁,这样就产生了一条开锁记录,获得了开锁方式的返回值。App 端查询到这条开锁记录,就可以将密码分配给您想分配的用户。

示例代码

// 可传入开锁方式的相关设备功能 ID,即可获取门锁记录
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 unlock records
 * @param unlockTypes unlock type list 
 * @param offset offset number
 * @param limit item count
 * @param callback callback
 */
void getUnlockRecords(int offset, int limit, final IThingResultCallback<Record> callback);

参数说明

参数 说明
offset 查询的偏移量
limit 查询的条数

示例代码

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);
    }
});

门锁劫持

指将特定的指纹、密码等,设置为劫持密码,当用户被劫持,并使用该密码开锁时,门会打开。同时,门锁将开门报警信息发送至家人手机或物业管理系统。

添加劫持标记

为开锁方式添加劫持标记后,即可将其设置成劫持密码。

接口说明

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

参数说明

参数 说明
unlockRelation 解锁方式和解锁密码编号对象
callback 设置结果的回调

移除劫持标记

接口说明

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

参数说明

参数 说明
unlockRelation 解锁方式和解锁密码编号对象
callback 设置结果的回调

获取门锁劫持记录

可根据传入的解锁功能定义点进行查询门锁劫持开门记录。

接口说明

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

参数说明

参数 说明
offset 查询的偏移量
limit 查询的条数

代码示例

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);
    }
});

门锁功能列表

功能名称 功能标识符(dpCode)
指纹解锁 unlock_fingerprint
普通密码解锁 unlock_password
临时密码解锁 unlock_temporary
动态密码解锁 unlock_dynamic
卡片解锁 unlock_card
人脸识别解锁 unlock_face
钥匙解锁 unlock_key
告警 alarm_lock
远程开门请求倒计时 unlock_request
远程开门请求回复 reply_unlock_request
电池电量状态 battery_state
剩余电量 residual_electricity
反锁状态 reverse_lock
童锁状态 child_lock
App 远程解锁 wifi 门锁 unlock_app
劫持告警 hijack
从门内侧打开门锁 open_inside
开合状态 closed_opened
门铃呼叫 doorbell
短信通知 message
上提反锁 anti_lock_outside
虹膜解锁 unlock_eye
掌纹解锁 unlock_hand
指静脉解锁 unlock_finger_vein
同步所有指纹编号 update_all_finger
同步所有密码编号 update_all_password
同步所有卡编号 update_all_card
同步所有人脸编号 update_all_face
同步所有虹膜编号 update_all_eye
同步所有掌纹编号 update_all_hand
同步所有指静脉编号 update_all_fin_vein
离线密码解锁上报 unlock_offline_pd
离线密码清空上报 unlock_offline_clear
单条离线密码清空上报 unlock_offline_clear_single