功能实现说明

本文介绍 Wi-Fi 门锁的功能点设置及相关数据交互说明，该文档适用于 MCU 对接模式，适用于硬件开发阶段。

版本	修订说明	修订日期	备注
V1.0.1	修改部分文案	2020.8.13	修改部分文案内容

数据交互流程

Wi-Fi门锁数据交互总体流程一般包括如下：

• 本地比较开锁
• 判断模组联网状态
• 临时密码列表同步及比较开锁（如有该功能需加该流程）
• 非记录型数据上报（包括时间同步、电量上报）
• 记录型数据上报（各种开门+告警记录上报）

注意：门锁功能逻辑复杂，请您务必认真查看、理解并依照流程图进行程序设计，以保证开发效率和开发质量。

配网

使用场景

初次配网或操作移除网络后的配网，属于模组自带功能，不需要手动设置DP
流程参考如下：

正常完成配网后给模组上电上传数据，只需要给模组上电，等待模组返回连接服务器的网络状态即可，当前Wi-Fi门锁具有两种配网模式：

• EZ模式（smartconfig）：普通路由配网
• AP模式：设备热点配网

具体配网方式的区别，请参考 公版 App 使用手册。

相关MCU指令：查询产品信息——报告设备联网状态 —— 重置 Wi-Fi / 重置 Wi-Fi-选择配置模式

电量显示功能

使用场景

显示设备当前电量情况。

涉及DP

• 电量状态，显示电量的高、中、低等状态
• 剩余电量，显示具体的数值

注：两个DP点二选一即可，都标示当前设备可用电量的状态，根据设备实际情况选择上报的类型

DP说明

• 电量状态：显示当前剩余电量挡位，分为高、中、低三档

• 剩余电量：显示当前剩余电量百分比，取值范围0~100

  上报逻辑，以下情况要求上报：

  • 设备首次配网/重新配网需上报电量
  • 设备重启（更换电池）
  • 电量发生变化
  • 定期上报，如10天上更新上报一次

相关MCU指令：实时状态上报

开门日志功能

使用场景

App上可查看门锁的历史开门记录

涉及DP

• 指纹编号
• 卡片编号
• 人脸编号
• 普通密码编号
• 临时密码编号
• 动态密码编号
• 钥匙编号
• 远程解锁
• 从内侧开门

注：需要联系项目经理开通权限，APP才能显示记录数据，且无条数限制

DP说明

• 指纹编号、卡片编号、人脸编号、普通密码编号：DP值用于区分人员（取值范围0~999）， 上报时面板显示对应人员解锁信息。如上报指纹编号DP值为25，面板显示“25 指纹解锁”
• 钥匙编号、远程解锁临时密码编号、动态密码编号、从内侧开门：DP值无特殊含义（取值范围0~999），只为与上面对的数据格式保持统一，上报时面板只显示解锁方式，不做人员区别。如上报钥匙编号DP值为25，面板显示“钥匙解锁”

实现流程

基本思路：

门锁被打开时，上报对应开门方式的DP点，如下表。开门日志显示的记录数据需要在没有网络的情况下，和实际发生的事件一致，因此推荐使用记录型状态上报。在断网时模组保存无法上报成功的数据，来当下次有数据上报的时候再重新上报，记录型数据携带时间为设备本地时间。

开门方式	上报DP点	DP值
指纹开门	指纹编号	与实际对应
普通密码开开门	普通密码编号	与实际对应
临时密码开门	临时密码编号	任意值均可
动态密码开门	动态密码编号	任意值均可
刷卡开门	卡片编号	与实际对应
人脸识别开门	人脸编号	与实际对应
钥匙开门	钥匙编号	任意值均可
APP远程开门	远程解锁	任意值均可
从家里开门	从内测开门	任意值均可

实现流程：

相关MCU指令：记录型状态上报

备注：相关的编号是由MCU生成的，尤其是临时密码的编号，MCU的编号跟临时密码的编号是独立的

成员管理功能

使用场景

APP上添加成员，并绑定指纹编号、普通密码编号、卡片编号、人脸编号，上报编号时APP将编号信息转换为对应的成员名称来显示。如：添加成员“女儿”，绑定卡片编号3，当设备上报卡片编号3的开门信息时，APP显示“女儿 卡片解锁”（不绑定成员则显示“3 卡片解锁”）。

实现流程

相关MCU指令：纯app功能，不涉及通信协议

报警功能

使用场景

门锁报警被触发时，App上能及时提示报警，且能查看报警记录

涉及DP

• 报警
• 劫持报警
• 门铃呼叫

注：需要联系涂鸦项目经理开通权限，APP才能显示记录数据，且无条数限制

DP说明

• 报警：报警支持的内容包括指纹试错报警、密码试错报警、卡试错报警、人脸试错报警、假锁（锁舌卡住）、高温报警、超时未关门、电子锁舌未弹出、防撬报警、钥匙插入、低电报警、电量耗尽报警、震动报警

• 劫持报警：有劫持报警功能时选择（DP值无需关心，可以不上报），具体功能由云端实现，设备硬件不需要支持。例如用户通过app将指纹3标记为劫持报警，若服务器收到指纹3的开锁记录，会触发劫持报警

• 门铃呼叫：门锁硬件上如带有门铃功能时选择，上报DP值为0或1，APP上都会显示门铃报警记录

实现流程

基本思路：

触发报警时，MCU上报对应报警DP值。

注：用记录型状态上报，要采用设备端时间，且要注意时间的准确性。若设备时间比实际时间滞后，上报时app报警图标无闪烁提醒，点击进去可以查看到该条报警记录；若以服务端时间为准，设备断网后重新联网，这时显示记录时间和实际发生的事件不符合。

报警、门铃报警：

劫持报警：

相关MCU指令：记录型状态上报

远程开门功能

使用场景

访客在门锁硬件上输入特定的开门密码（厂家自行决定触发方式，可以是指定的物理按钮，或者特殊的开门码，例如888#）触发门锁远程开门功能，主人能在特定时间内，通过APP对该开门请求进行响应，可以同意开门，或拒绝开门

涉及DP

• DP 9：远程开门请求倒计时
• DP 15：APP 远程解锁
• DP 49：设置远程开门秘钥
• DP 50：新免密远程开门 - 带秘钥

DP说明

• 远程开门请求：有远程开门需求时门锁主动上报，DP值表示远程开门有效的剩余时间，取值范围0~90，上报1-90时开启远程开门入口，0时关闭入口。当远程开门请求被触发时，设备上报该DP并附有效剩余时间（非零），APP面板开启远程开门入口，随后设备开始有效剩余时间倒计时并上报，远程开门入口闪烁，直到有效剩余时间上报为0时，关闭远程开门入口。

  MCU上报的数据倒计时，需要按照倒序上报。例如 90 89 88 87这样倒序上报，可以1s上报一次，也可以2s上报一次APP响应之后。无论倒计时一直计数到0，或是app下发了指令同意或者拒绝开门，MCU收到后都必须上报0，否则云端的状态无法“复位“

实现流程

基本思路：

设备端发起远程开门请求，APP上确认是否同意请求并回复设备。设备根据回复信息控制门锁状态，同时上报关闭开门请求。若设备等待开门请求回复超时（即有效剩余时间倒计时为0），也上报关闭开门请求。

实现流程：

相关MCU指令：实时状态上报——模组命令下发

临时密码功能

使用场景

用户在APP上设置临时密码，有效时间内访客在门锁上输入对应的临时密码即可开门。（该功能需要门锁本地有时钟芯片，且建议临时密码获取后保存在本地）

临时密码状态说明

• 未生效：密码未到生效时间
• 待下发：密码已生效，但没有下发到设备
• 使用中：密码已生效且已下发到设备
• 待删除：APP端删除，但还未将删除状态下发设备（设备未重新申请临时密码）
• 已失效：超过失效时间，或APP端删除且将删除状态下发设备

转换关系如下：

实现流程

开发流程与MCU侧的建议方案：

请参考下图。其中当MCU发起向服务器同步临时密码列表时，可能因为网络等原因导致同步失败。同步失败，本次更新失败，密码列表维持更新前不变

多组临时密码获取流程：

密码每次服务端都是全量下发，门锁需要每次根据服务端返回的所有密码和状态进行更新。

相关MCU指令：请求云端临时密码（支持多组）

动态密码功能

使用场景

主人在APP上生成动态密码，有效时间内访客在门锁上输入对应的动态密码即可开门。

实现流程

基本思路：

APP上获取动态密码，设备端输入动态密码并上报（动态密码上报指令中的时间戳，必须使用格林时间而非本地时间），模组返回校验结果，设备根据回复结果控制门锁状态。动态密码5分钟内有效，超时重新获取。

动态密码是不依赖网络实现的临时性密码，该方案依靠算法实现。APP向涂鸦的服务器请求某个门锁当前的动态密码，当门锁收到某个疑似为动态密码的密码时，将该密码提交给涂鸦的模组，同时把当前的时间、管理员密码，一并给到模组。模组收到当前时间、管理员密码，结合模组自己保存的初始秘钥进行运算，将运算后得到的密码与用户输入的密码进行比对。如果比对通过，模组告诉 MCU 开门，比对失败，拒绝开门。

注：APP上获取动态密码，目前Wi-Fi的公版面板没有加入管理员密码的混算，但嵌入式和服务器上已支持。

实现流程：

相关MCU指令：动态密码校验

临时密码短信通知

使用场景

该功能与临时密码功能所对应，在需要临时密码的场景下，通过涂鸦app（或OEM的app）在创建临时密码的同时，可以给指定的手机号发送短信，短信内容中包含设备的名称，密码的内容（7位数字），以及生效时间和结束时间

短信支持中国大陆地区，以及海外，在app创建临时密码的时候，可以选择国家/地区码

涉及DP

• 短信通知

DP说明

该DP是非必选DP，使用该功能需要付费

勾选该DP后，需在涂鸦开发者平台的增值服务市场自助开通

操作流程：打开增值服务市场页——选择所有增值服务——选择通知服务——找到“门锁短信通知”并开通

纯APP功能，无需协议

开锁方式同步

使用场景

当门锁本地的开锁方式发生变化，新增或删除，将门锁本地所有的解锁id同步到云端。

涉及DP

• 同步所有指静脉编号
• 同步所有掌纹编号
• 同步所有虹膜编号
• 同步所有人脸编号
• 同步所有卡编号
• 同步所有密码编号
• 同步所有指纹编号

DP说明

将开锁方式分成125份，每份8个与一个字节8位对应, 则刚好可以存储1000个密码, 且满足DP数据上报最大长度255的限制

byte[0] 分片位置 byte[1] 该分片上的开锁方式。开锁方式字节数据上对应标位的比特为1，则表明该密码存在

例如：00000001 00010011 表明第一个分片上0,1,4号开锁方式存在

01000001 00100101 表明第65个分片(2^6+1)上0,2,5位置，如位置5实际密码编号64*8+5为517

00000010 00000000 空分片需要硬件处理，不必上传, 减少实际长度

注意：分片是从1开始，不是从0开始（例：密码8应该属于第2分片了，一个分片只有8个密码，对应0-7值）

实现流程

注意：每次向上同步的时候，需要把更新后本地所具备的所有id都同步到云端。

相关MCU指令：实时状态上报

离线临时密码功能（Pro版功能）

使用场景

在Wi-Fi断开或Wi-Fi环境较差情况下（即门锁断开网络连接的情况下）使用。

离线临时密码使用规则说明

一次性密码

创建后6小时内，可以使用1次，使用后失效；每个整点60分钟内，只有10组可用的单次密码。

不限次数密码

有效期内可多次使用，有效期最长只能设置1年区间；生效后24小时内，必须要使用1次，否则将自动失效；同一设备在相同生效、失效时间段内只能获取1次密码。

清空所有密码

只可清空所有在门锁上至少被使用过一次的离线不限次数密码；不能清空一次性密码、没有在门锁上使用过的不限次数密码；点击创建后，需要在24小时内使用；每个整点60分钟内，只有10组可用的清空码（清空所有）。

清空单个密码

只可清空单条在门锁上至少被使用过一次的离线不限次数密码；不能清空一次性密码、没有在门锁上使用过的不限次数密码；点击创建后，该清空码的失效时间与被清空的那条密码的失效时间相同。

实现流程

基本思路

APP上获取离线临时密码，设备端输入离线临时密码并上报（离线临时密码上报指令中的时间戳，必须使用格林时间而非本地时间），模组返回校验结果，设备根据回复结果控制门锁状态。

实现流程

在线循环密码功能（Pro版功能）

使用场景

用户在APP上设置在线循环密码，有效时间内访客在门锁上输入对应密码即可开门，可实现日程化的密码失效。

在线循环密码状态说明

• 未生效：密码未到生效时间

• 待下发：密码已生效，但没有下发到设备

• 使用中：密码已生效且已下发到设备

• 待删除：APP端删除，但还未将删除状态下发设备（设备未重新申请临时密码）

• 已失效：超过失效时间，或APP端删除且将删除状态下发设备

转换关系如下：

实现流程

基本思路

在APP上创建在线密码，设置生效失效时间，可选择是否重复，若选择需要设置重复周期。在线循环密码在APP设计上为了和其他密码区分开使用7位有效数据，当门锁主板检测到用户使用的是多组临时密码需要去调用此接口去云端拉取相关数据，密码每次服务端都是全量下发，门锁需要根据服务端返回的所有密码和状态进行更新。

实现流程

相关MCU指令：请求云端临时密码（带schedule列表）

从APP端录入解锁方式（Pro版功能）

使用场景

通过APP发起添加解锁方式，指纹、门卡及密码。

涉及DP

• 查询创建类型
• 创建类型回复
• 门锁录入完成
• 远程创建成功
• 门锁允许远程删除
• 远程删除指纹
• 远程删除回复
• 远程删除密码
• 取消远程创建
• 远程删除门卡

DP说明

• 门锁录入完成、远程删除指纹、远程删除密码、远程删除门卡：DP值用于区分人员（取值范围0-999）。
• 查询创建类型、远程创建成功、门锁允许远程删除、远程删除回复、取消远程创建，bool型，MCU上报。
• 创建类型回复：模组根据APP端操作下发相应类型（指纹、门卡、密码）。

实现流程

流程

从APP端删除解锁方式（Pro版功能）

使用场景

通过APP发起删除解锁方式，指纹、门卡及密码。

涉及DP

• 门锁允许远程删除
• 远程删除指纹
• 远程删除回复
• 远程删除密码
• 远程删除门卡

DP说明

• 远程删除指纹、远程删除密码、远程删除门卡：DP值用于区分人员（取值范围0-999）。
• 门锁允许远程删除、远程删除回复：bool型，MCU上报。

实现流程

流程

本地退网

使用场景

门锁本地退网

逻辑说明

通过门锁按键，让门锁退网（重置Wi-Fi，03/04命令字），APP显示门锁移除成功，但不影响门锁本地的功能和临时密码的使用。

设备移除后重新配网，APP上报警、成员、开门记录、临时密码都还在，且功能正常使用。

实现流程

APP退网

使用场景

通过APP退网

逻辑说明

在APP上点击“移除设备”，门锁移除成功，但不影响门锁本地的功能和临时密码的使用。

设备移除后重新配网，APP上报警、成员、开门记录、临时密码都还在，且功能正常使用。

实现流程

本地恢复出厂设置

使用场景

门锁本地恢复出厂设置

逻辑说明

设备能联网的情况：

门锁本地恢复出厂设置，在没有重新配网之前，门锁本地数据卡、指纹、普通密码、人脸、临时密码等被清空，APP端设备可以被移除（非必须，如果可以成功移除，则是模组先给APP发送Wi-Fi重置协议，再进入本地恢复出厂设置），原离线密码失效。

重新配网之后，如果device id不变（老的基线，乐鑫8266），重新添加门锁设备后APP端数据未被清空（开门记录、临时密码等记录还在），原临时密码还可以使用，原离线密码失效；如果device id改变，重新添加门锁设备后APP端数据被清空，原临时密码不可用，离线密码失效。

设备无法联网的情况：

门锁本地恢复出厂设置，在没有重新配网之前，本地数据被清空，APP内门锁未被移除，但是APP已收不到该设备新的数据，且无法对该门锁进行操作，原离线密码失效。

重新配网之后，如果device id不变（老的基线，乐鑫8266），重新添加后会覆盖原锁，记录都在，原临时密码还可以使用，原离线密码失效；如果device id改变，重新添加门锁设备后APP端数据被清空，原临时密码不可用，离线密码失效。

实现流程

APP恢复出厂设置

使用场景

通过APP恢复出厂设置

逻辑说明

设备能联网的情况：

APP点击“恢复出厂设置”，在没有重新配网之前，门锁本地信息卡、指纹、普通密码、人脸等不会被删除，临时密码仍可正常使用，离线密码最多只能使用一次。

重新配网之后，如果厂家做了重新配网的时候做临时密码列表的一次同步（此时为空列表），那么重新添加后APP端内数据清空，临时密码不能使用，原离线密码不可用；如果厂家没有做上述同步机制，那么重新添加后APP端内数据清空，临时密码最多可以使用一次，原离线密码不可用。

设备无法联网的情况：

APP点击“恢复出厂设置”，没有重新配网之前APP内门锁被移除，临时密码仍可使用，离线密码仍可使用。

重新配网之后，如果厂家做了重新配网后做临时密码列表的一次同步（此时为空列表），那么重新添加后APP端内数据清空，临时密码不能使用，原离线密码不可用；如果厂家没有做上述同步机制，那么重新添加后APP端内数据清空，临时密码最多可以使用一次，原离线密码不可用。

实现流程

Alexa App场景联动

使用场景

非保活Wi-Fi门锁实现与Alexa生态设备的场景联动，例如当门打开后Alexa生态中的灯或其他设备自动开启。

涉及DP

落锁状态：lock_motor_state，布尔型，支持上报/下发，【true 开锁】/【false 关锁】

逻辑说明

• PID设置时勾选DP点：lock_motor_state 。该DP是 Alexa 用来判断门锁开关状态的，所以必须要上报准确
• 确保从门外开锁时，MCU端必须上报 lock_motor_state 这个dp，上报状态为【true 开锁】/【false 关锁】；确保门锁（或自动落锁）关锁后，能上报 lock_motor_state 这个DP，上报状态为【false 关锁】
• 非保活Wi-Fi门锁只支持Alexa Routines功能，即门锁设备只能作为触发条件，不能作为执行条件
• 部分门锁支持区分从门外开锁和从门内开锁，Alexa Routines支持的场景联动，一般场景为当家人回家-门锁开时 ，联动开灯或者开空调，所以一般情况下是外开门才会触发联动。 对于从门内开锁的场景，建议不要上报lock_motor_state

拍照锁

使用场景

主要应用于人脸识别锁的图片传输功能需求。上传图片后，可从 App 端查看开门者人脸信息。

涉及 DP

• DP 212 主动消息推送：MCU 无需处理。

解锁 DP（开门/告警的 DPID）	解锁时间（秒）	事件图片/视频个数（产品定义不能超过 10 个）	事件图片/视频id（2*n）	事件上报时间（秒）
1 字节	4 字节	1 字节	2 字节 * n	4 字节

说明：
解锁 DP：即开门记录/告警 DP；
解锁时间：即上报解锁记录 DP 的时间，需要和解锁 DP 上报的时间保持一致；
事件个数：当前触发的事件上报了多少张图片（默认只支持 1 张）；
图片 id：事件触发拍照图片 id 的编码（根据实际 MCU 定义的图片 id 生成规则，0x62 中也会返回这个图片 id）；
事件上报时间：图片上传时间，这个时间在模组反馈图片上传结果（0x62）中也会返回这个时间。
注意：解锁时间和事件上报时间均是以时间作为标识 id，用于区分事件记录的，请严格按照规则要求填充数据，请勿修改或者将数据进行时区转换。

实现流程

流程

注意:

1. 有图片传输功能需求的产品需要在 0x01 查询产品信息中返回 cap 字段内容；

2. 每次图片状态上报，需要等待模组返回入网激活成功状态之后；

3. 每次有图片状态上报时，必须先发送 0x60 指令，通知 Wi-Fi 模组；

4. 当图片上传的过程中，模组反馈图片上传结果为失败（0x62 指令），若需要再次传输图片，则需要从 0x60 开始重新触发图片上传流程；

涉及协议

0x08 记录型数据上报：开门/告警信息用该状态上报。

0x60 事件状态通知：用于通知 Wi-Fi 模组，当前有触发携带图片上报的事件发生，模组收到该指令后开启相关图片传输功能。

0x61 图片上传：用于和 Wi-Fi 模组传输图片，此命令的数据交互支持 spi 或 uart。具体通信协议在 0x01 查询产品信息。

0x62 图片上传结果反馈：模组通过此命令字来反馈当前图片传输结果，当模组反馈的结果是失败后，若图片需要重传，需要重新从 0x60 开始启动图片传输流程。

0x63 图片上传状态获取：用于 MCU 主动查询当前模组图片传输的状态。

补充说明

校时

建议门锁定期主动向云端校时。

相关 MCU 指令：获取格林时间/获取本地时间

OTA

MCU固件OTA（涂鸦平台只支持从低版本到高版本升级）。

相关MCU指令：请求MCU固件升级——升级启动——升级包传输——查询产品信息的MCU回复（返回最新的固件版本）

Wi-Fi模组固件升级，当模组有升级提醒时使用。

相关MCU指令：请求Wi-Fi模组固件升级

产测

当需要整机产测时使用。

相关MCU指令：Wi-Fi功能性测试

Wi-Fi信号获取

一般在调试阶段可使用该功能。

相关MCU指令：查询当前连接路由信号强度

告警设置

需要app弹窗提醒部分信息，IoT 平台设置操作可参考 设置告警。

模组信息

• 推荐使用模组：空间位置允许的前提下，推荐使用XR1（有板载与外置天线两种规格）
• 模组规格书：请在产品的硬件调试-模组详情中查看下载
• PCBA设计建议：板载天线模组后部分建议镂空处理，模组供电允许最高电流建议选择500ma
• 支持波特率：支持115200和9600
• 调试模拟助手：请在硬件调试中下载MCU调试助手与云调试助手模拟