Wi-Fi 门锁

更新时间：2024-11-18 11:33:10下载pdf

使用说明

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

示例代码

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

// 初始化 SDK，仅需要调用一次
TuyaOptimusSdk.init(getApplicationContext());
// 获取 ITuyaLockManager
ITuyaLockManager tuyaLockManager = TuyaOptimusSdk.getManager(ITuyaLockManager.class);
// 创建 ITuyaWifiLock
ITuyaWifiLock tuyaLockDevice = tuyaLockManager.getWifiLock("your_lock_device_id");

名词解释

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

门锁成员

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

获取门锁成员

接口说明

public void getLockUsers(final ITuyaResultCallback<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：非家庭成员

示例代码

tuyaLockDevice.getLockUsers(new ITuyaResultCallback<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 ITuyaResultCallback<String> callback)

参数说明

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

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

UnlockRelationBean 字段说明

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

示例代码

ArrayList<UnlockRelation> unlockRelations = new ArrayList<>();
UnlockRelation unlockRelation = new UnlockRelation();
unlockRelation.unlockType = TuyaUnlockType.PASSWORD;
unlockRelation.passwordNumber = 1;
unlockRelations.add(unlockRelation);
File avatarFile = new File(getFilesDir(), "1.png");
tuyaLockDevice.addLockUser("Pan", avatarFile , unlockRelations, new ITuyaResultCallback<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 ITuyaResultCallback<Boolean> callback)

参数说明

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

示例代码

ArrayList<UnlockRelation> unlockRelations = new ArrayList<>();
UnlockRelation unlockRelation = new UnlockRelation();
unlockRelation.unlockType = TuyaUnlockType.PASSWORD;
unlockRelation.passwordNumber = 1;
unlockRelations.add(unlockRelation);
tuyaLockDevice.updateLockUser("0000005f1g", "pan", null, unlockRelations, new ITuyaResultCallback<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, ITuyaResultCallback<Boolean> callback)

参数说明

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

示例代码

ArrayList<UnlockRelation> unlockRelations = new ArrayList<>();
UnlockRelation unlockRelation = new UnlockRelation();
unlockRelation.unlockType = TuyaUnlockType.PASSWORD;
unlockRelation.passwordNumber = 1;
unlockRelations.add(unlockRelation);
tuyaLockDevice.updateFamilyUserUnlockMode("your_family_user_id", unlockRelations, new ITuyaResultCallback<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 ITuyaResultCallback<Boolean> callback)

参数说明

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

示例代码

tuyaLockDevice.deleteLockUser("0000004pnk", new ITuyaResultCallback<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");
    }
});

临时密码

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

Wi-Fi 门锁

获取临时密码

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

接口说明

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

TuyaSmartLockTempPwdModel 数据模型

字段	类型	描述
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; // 已过期

示例代码

tuyaLockDevice.getTempPasswords(new ITuyaResultCallback<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 ITuyaResultCallback<Boolean> callback)

TempPassword 参数说明

下面为该类的字段说明：

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

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

示例代码

TempPasswordBuilder tempPasswordBuilder = new TempPasswordBuilder()
        .name("Liam's password")
        .password("1231231")
        .effectiveTime(System.currentTimeMillis())
        .invalidTime(System.currentTimeMillis() + 24 * 60 * 60 * 1000);
tuyaLockDevice.createTempPassword(tempPasswordBuilder, new ITuyaResultCallback<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 ITuyaResultCallback<Boolean> callback)

参数说明

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

示例代码

tuyaLockDevice.deleteTempPassword(1111, new ITuyaResultCallback<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");
    }
});

动态密码

Wi-Fi 门锁

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

接口说明

public void getDynamicPassword(final ITuyaResultCallback<String> callback)

示例代码

tuyaLockDevice.getDynamicPassword(new ITuyaResultCallback<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 可以进行远程开门。

Wi-Fi 门锁

远程开门监听

接口说明

public void setRemoteUnlockListener(RemoteUnlockListener remoteUnlockListener)

参数说明

RemoteUnlockListener 接口中有一个 Receive 方法，如下所示：

void onReceive(String devId, int second);

方法参数

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

请求远程开锁

接口说明

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

参数说明

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

示例代码

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

	....

    // 注册远程开锁监听
    tuyaLockDevice.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) {
    tuyaLockDevice.replyRemoteUnlock(allow, new ITuyaResultCallback<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");
        }
    });
}

门锁记录

获取门锁记录

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

接口说明

public void getRecords(ArrayList<String> dpCodes, int offset, int limit, final ITuyaResultCallback<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>	该门锁记录的功能 ID 和 `value` 数据
unlockRelation	UnlockRelation	解锁类型和解锁密码编号的关系，如不是门锁记录，可为空
tags	int	门锁记录标位： 0：其他 1：劫持报警

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

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

示例代码

// 可传入开锁方式的相关设备功能 ID，即可获取门锁记录
ArrayList<String> dpCodes = new ArrayList<>();
dpCodes.add("alarm_lock");
dpCodes.add("hijack");
dpCodes.add("doorbell");
tuyaLockDevice.getRecords(dpCodes, 0, 10, new ITuyaResultCallback<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 page number
 * @param limit item count
 * @param callback callback
 */
void getUnlockRecords(int offset, int limit, final ITuyaResultCallback<Record> callback);

参数说明

参数	说明
offset	查询的页数
limit	查询的条数

示例代码

tuyaLockDevice.getUnlockRecords(0, 10, new ITuyaResultCallback<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 ITuyaResultCallback<Boolean> callback);

参数说明

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

移除劫持标记

接口说明

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

参数说明

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

获取门锁劫持记录

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

接口说明

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

参数说明

参数	说明
offset	查询的页数
limit	查询的条数

代码示例

tuyaLockDevice.getHijackRecords(0, 10, new ITuyaResultCallback<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