MCU 通用对接协议

更新时间:2024-06-14 07:27:30下载pdf

涂鸦系列 Wi-Fi 门锁串口通用协议为涂鸦定制的 Wi-Fi 模组串口通用协议,主要用于涂鸦 Wi-Fi 模组与其它门锁 MCU 串口直连做串口通信,其架构框图如下图所示。

MCU 通用对接协议

其他方案如需要其他 I/O 引脚的(例如 Wi-Fi 保活方案),请参考各系列方案的硬件设计指导。

名词解释

名词 说明
DP 即设备功能(Data Point),代表一条或一对指令码。更多详情,请参考 产品功能
PID 即产品 ID(Product ID),描述一类产品功能(DP)的集合。在 涂鸦开发者平台 创建的每一个产品都会产生一个唯一的产品编号,关联了产品具体的设备功能、App 控制面板、出货信息等所有跟这个产品相关的信息。
设备绑定 通过涂鸦 App 将设备配网激活成功。
设备解绑 指设备解除与 App 账号的绑定关系。
设备重置 指在 App 上操作解绑并清除数据。
蓝牙双模配网 适用于 Wi-Fi 和低功耗蓝牙双模组方案。配网过程分为两个阶段:
  1. 蓝牙配网:核心是 App 将用于配网的路由器 SSID、密码、配网 Token 通过低功耗蓝牙加密传给设备。
  2. 设备上网:设备解密完配网信息后,由设备的 Wi-Fi 模组连接上对应的路由器完成联网,并取收到的 Token 向服务端注册并登录 MQTT 服务器,完成上网流程。

串口通讯约定

  • 波特率:9600 / 115200

  • 数据位:8

  • 奇偶校验:无

  • 停止位:1

  • 数据流控:无

    • Wi-Fi 模组首次上电使用时,会启动波特率轮询。每个周期切换一次波特率发送查询产品信息 0x01 指令,若收到 MCU 回复,则判断为通讯波特率,停止轮询并写配置(包含:波特率、PID 等产品信息参数)保存到 Flash。下一次模组重新上电或重启时,就不会再重新查询产品信息。
    • Wi-Fi 模组被重置后,会清除当前记忆信息,重新查询。

帧格式说明

字段 字节数 说明
帧头 2 固定为 0x55AA
版本 1 升级扩展用
命令字 1 具体帧类型
数据长度 Len 2 Len 高 8 位
Len 低 8 位
数据 N -
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

说明

  • 字节序:大端模式,所有大于 1 个字节的数据均采用大端模式传输。

  • 版本:版本用于拓展功能使用,为兼容新老版本协议。历史版本上出现过 0x00/0x03,模组暂不校验该字段

  • 重传:一般情况下,采用同命令字一发一收同步机制,即一方发出命令,另一方应答。若发送方超时未收到正确的响应包,则超时传输,Wi-Fi 模组主动发起的通信发送包超时时间为 500ms,重传次数为 3 次。如下图所示:

    MCU 通用对接协议

DP 格式(状态数据单元)

使用涂鸦 Wi-Fi 系列化门锁方案开发时,dp_data_len 的长度为 2 个字节。其他 DP 格式信息,请参考下表:

字段 字节数 说明
dp_id 1 DP 的指令码
dp_type 1 DP 的数据类型
dp_data_len 2 DP 的数据长度
dp_data_value dp_data_len DP 的数据内容(具体详见 DP 协议详解)

系列方案协议支持汇总

表格色块说明:通用指令保活方案指令拓展功能传图/音视频指令其他高级能力

协议分类 指令名称 命令字 非保活基础版
WBR1/3
非保活音视频版
WBRU/7252/7916
保活音视频
WBRL
可视对讲
T31 门锁
通用基础 查询产品信息 0x01 支持 支持 支持 支持
报告设备联网状态 0x02 支持 支持 支持 支持
获取设备联网状态 0x1A 不支持 支持 支持 支持
重置 Wi-Fi 0x03 支持 支持 支持 支持
重置 Wi-Fi-可选配网模式 0x04 支持 支持 不支持 不支持
模组重置状态通知 0x25 支持 支持 支持 支持
获取本地时间 0x06 支持 支持 支持 支持
获取格林时间 0x10 支持 支持 支持 支持
实时状态上报 0x05 支持 支持 支持 支持
记录型数据上报 0x08 支持 支持 支持 支持
模组 DP 命令下发 0x09 支持 支持 支持 支持
获取 DP 缓存命令 0x15 支持 支持 支持 支持
MCU OTA 升级 自动升级 0x21 支持 支持 支持 支持
升级启动 0x0D 支持 支持 支持 支持
升级数据传输 0x0E 支持 支持 支持 支持
门锁密码服务 密码进制设置 0x1C 支持 支持 支持 不支持
请求拉取云端临时密码 0x14 支持 支持 不支持(用 0x1D) 不支持(用 0x1D)
请求比对动态密码 0x12 支持 支持 不支持(用 0x16) 支持
请求比对算法密码 0x16 支持 支持 支持 支持
保活方案
特有协议
时间同步-综合时间 0x1B 不支持 不支持 支持 支持
请求云端临时密码-DP 格式 0x1D 不支持 不支持 支持 支持
深度休眠时间参数 0x80 不支持 不支持 支持 支持
驱屏时间控制 0x83 不支持 不支持 不支持 支持
上电配网使能控制 0x84 不支持 不支持 支持 支持
模组拓展服务 查询当前连接路由信号强度 0x0B 支持 支持 支持 支持
上报 MCU 的 SN 编号 0x17 支持 支持 支持 支持
MCU 断电通知 0x22 支持 支持(bk7252 不支持) 不支持 不支持
恢复出厂设置 0x340A 不支持 支持(bk7252 不支持) 不支持 不支持
休眠参数配置 0xD3 不支持 部分支持(7916) 支持 不支持
模组调试协议 0xDB 支持 支持 支持 支持
功能性产测服务 基础类产测方案 0x07 支持 支持 支持 支持
音视频类产测方案 0xF0 支持 支持(bk7252 不支持) 支持 不支持
传图/音视频功能 触发抓拍命令 0x64 不支持 支持 支持 支持
抓拍结果通知 0x62 不支持 支持 支持 支持
获取推流状态 0x6B 不支持 部分支持(7916) 支持 不支持
串口传图-数据上传 0x61 不支持 部分支持(WBRU) 支持 不支持
串口传图-状态获取 0x63 不支持 部分支持(WBRU) 支持 不支持
单芯片解决方案
相关功能
通用参数配置 0x65 不支持 部分支持(7252) 不支持 不支持
通用参数配置 0xDA 不支持 部分支持(7916) 不支持 不支持
本地拉流 0xD2 不支持 部分支持(7916) 不支持 不支持
双模蓝牙相关功能 报告蓝牙连接状态 0x3504 支持(门禁) 支持(门禁) 不支持 不支持
获取蓝牙连接状态 0x3505 支持(门禁) 支持(门禁) 不支持 不支持
关闭蓝牙通信功能 0x3506 支持(门禁) 支持(门禁) 不支持 不支持
低功耗蓝牙+X 相关功能 查询模组信息 0xD000 不支持 部分支持(WBRU) 不支持 不支持
授权信息同步 0xD001 不支持 部分支持(WBRU) 不支持 不支持
激活信息同步 0xD002 不支持 部分支持(WBRU) 不支持 不支持
共享秘钥协商 0xD003 不支持 部分支持(WBRU) 不支持 不支持
数据透传功能
(门锁-模组-猫眼)
锁控查询模组信息 0xD100 不支持 部分支持(WBRU,AC7916) 不支持 支持

系列方案支持的配网方式

模组型号 热点配网 快连配网 热点和快连共存 蓝牙配网 二维码配网
WBR1/3
WBRU
WBRL
BK7252
AC7916
T31 可视对讲

通用基础协议

查询产品信息 0x01

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x01
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x01
数据长度 2 N
数据 N 产品信息,详见下文说明
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

产品信息示例

{"p":"vHXEcqntLpkAlOsy","v":"1.0.0","n":0,"cap":11}

其中 p、v 为必选字段,其他按设备能力按需选择,说明如下:

字段 说明
p 即您在 涂鸦开发者平台 上创建的产品的 PID。示例中,表示产品 ID 为 vHXEcqntLpkAIOsy
v 表示 MCU 固件版本号为 1.0.0,MCU 版本号格式采用点分十进制形式,格式为 x.x.x,其中 x 为十进制数,取值范围为 0-99。
n(可选) 表示选择模组的 Wi-Fi 配网模式,包括快连配网(Smartconfig 或 EZ)和热点联网(AP)。双模设备,如设备支持
蓝牙配网或其他方式,不受 n 值影响,进入配网模式后多一种配网路径。
  • 0:表示传统模式,热点与快连两种配网模式互相切换(每次重置复位后切换到另一种配网模式)
  • 1:表示仅支持热点配网模式,这种模式下产品只能通过热点联网连接的方式进行设备配网
  • 2:表示共存模式,热点与快连两种配网模式同时存在
cap(可选) 表示设备能力,采用 bit 位方式,cap :xx 值为 bit 值换算后 10 进制字符串,具体如下定义:
bit0:表示设备是否支持拍照/音视频功能
  •  0:不支持
  •  1:支持
bit1:表示设备采用哪种通信方式上传图片(仅在 bit0 为 1 时有效
  • 0:串口
  • 1:SPI
bit2保留字段,默认 0
bit3:表示是否需要模组重置状态通知(T31/WBRL 方案模组侧默认使能
  • 0:不需要
  • 1:需要
bit4:表示是否支持自动升级(协议详见 0x21 指令。T31/WBRL 方案模组侧默认使能
  • 0:不支持
  • 1:支持
bit5:表示深度休眠逻辑与功能实现端为模组还是 MCU
  • 0:模组端实现
  • 1:MCU 端实现
bit6:表示是否支持 ble+x 复合模式
  • 0:不支持,单 Wi-Fi 模式
  • 1:支持,Wi-Fi 做插件模式
bit7:表示 pir 功能实现端(模组 / MCU)
  • 0:模组端实现
  • 1:MCU 端实现
bit8:表示屏幕休眠时间控制方式
  • 0:通过引脚中断控制
  • 1:通过串口指令控制
bit9:表示上电是否默认进入配网模式
  • 0:默认进入可配网模式
  • 1:MCU 使能控制,使能指令详见 0x84
`

系列模组方案 cap 能力支持汇总表

  • 不生效/不支持:表示该 cap 字段 bit 位设置固件不做处理。

  • 支持:表示该 cap 字段 bit 位设置固件会做对应处理。

  • 默认使能:表示无论 MCU 传入什么参数,均当默认支持处理。

BIT 位(能力) WBR1/WBR3 WBRU BK7252 AC7916 WBRL T31 可视对讲
bit0(拍照/音视频能力) 不生效 支持 不生效 不生效 支持 支持(默认使能)
bit1(与猫眼通信方式) 不生效 支持 不生效 不生效 支持 支持(默认使能)
bit2(运营商能力) 不生效 不生效 不生效 不生效 不生效 不生效
bit3(模组重置通知) 支持 支持 支持 支持 支持(默认使能) 支持(默认使能)
bit4(自动升级能力) 支持 支持 支持 支持 支持(默认使能) 支持(默认使能)
bit5(深睡唤醒实现方式) 不支持 不支持 不支持 不支持 支持 支持
bit6(ble+x 能力) 不支持 支持 不支持 不支持 不支持 不支持
bit7(pir 功能实现端) 不支持 不支持 不支持 不支持 不支持 支持
bit8(屏幕休眠控制方式) 不支持 不支持 不支持 不支持 不支持 支持
bit9(上电是否进配网模式) 不支持 不支持 不支持 不支持 支持 支持

示例

  • 55 aa 00 01 00 00 00,模组查询产品信息。
  • 55 aa 00 01 xx xx {"p":"vHXEcqntLpkAlOsy","v":"1.0.0","n":0,"cap":11} xx,MCU 回复产品信息。

报告设备联网状态 0x02

设备联网状态 描述 状态值
状态 1 快连配网状态 0x00
状态 2 热点配网状态 0x01
状态 3 Wi-Fi 已配置但未连上路由器 0x02
状态 4 Wi-Fi 已配置且连上路由器 0x03
状态 5 已连上路由器且连接到云端 0x04
状态 6 Wi-Fi 设备处于低功耗模式 0x05
状态 7 二维码扫描识别成功(需支持二维码配网) 0x06
状态 8 Wi-Fi 设备初始化完成 (表示可正常接收串口指令) 0x07
状态 9 快连和热点 共存 配网状态 0x08
状态 10 进入深度休眠状态(适用于 AC7916 方案 0x09
  • 当模组的 Wi-Fi 状态发生变化时,会主动下发 Wi-Fi 状态 至 MCU。
  • 状态包用于 MCU 设备得知模组目前的状态,MCU 可基于不同的状态做相关的操作,如配网指引。
  • 涂鸦推荐用户支持热点配网,配网成功率高。快连配网方式存在少部分路由兼容性问题,并且涂鸦会逐渐的下架掉对快连配网的支持。
  • 如设备支持蓝牙配网(通过蓝牙链路传输配网路由信息),是在 Wi-Fi 配网方式的基础上多了一种配网方式,因此不会有单独的状态用于标识,当状态为状态 1、状态 2、状态 9 时均表示可通过蓝牙配网。
  • 在未配网前,模组上电默认处于低功耗状态。需要 MCU 主动发 重置 Wi-Fi 指令后,模组才会进入待配网状态。
  • 手机移除设备后,模组进入低功耗状态,需要 MCU 主动发 重置 Wi-Fi 指令后,模组才会进入待配网状态。
  • Wi-Fi 模组进入配网模式后,如果在 10S 内未连接路由并且模组断电了,下次模组上电后依旧保持上一次的配网状态。同样的,进入配网模式后,3 分钟内未操作自动进入低功耗模式。

MCU 在收到已连接路由器且连接到云端的状态 0x04 之后,禁止立即给模组断电。需延时至少 3s 后断电,否则可能导致模组无法正常工作。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x02
数据长度 2 0x0001
数据 1 Wi-Fi 联网状态,详见上表
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x02
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 55 aa 00 02 00 01 04 06,模组发送连接状态,表示已连上路由器且连接到云端。
  • 55 aa 00 02 00 00 01 ,MCU 回复应答。

获取设备联网状态 0x1A

  • MCU 可根据此条命令获取 Wi-Fi 状态,例如 MCU 重上电或软件重启,可主动向模组查询当前联网状态。
  • 返回 Wi-Fi 状态见 设备联网状态表
  • 保活类 Wi-Fi 门锁方案均支持该指令,部分非保活类方案支持,详见 系列方案协议支持汇总

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x1A
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x1A
数据长度 2 0x0002
数据 2 Data[0]:详见设备联网状态表
Data[1]:表示模组配网激活状态
  • 0x00:未配网
  • 0x01:已配网
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 55 AA 00 1A 00 00 19,MCU 主动查询 Wi-Fi 联网状态。
  • 55 AA 00 1A 00 02 04 01 20,模组返回查询结果为 0x04-已连上路由器且连接到云端,同时模组为已激活状态。

重置 Wi-Fi 0x03

  • 共存配网模式:重置后仍然为热点和快连共存配网状态。
  • 仅热点配网模式:重置后仍然为热点配网模式。
  • 传统模式:热点与快连两种配网模式互相切换(每次重置复位后切换到另一种配网模式),重置 Wi-Fi 状态转化如下图所示:

MCU 通用对接协议

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x03
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x03
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 55 aa 00 03 00 00 02 ,MCU 发送重置 Wi-Fi 指令。
  • 55 aa 00 03 00 00 02,模组回复应答。

重置 Wi-Fi(可选配网模式) 0x04

  • 此重置指令只针对 查询产品信息 设置的 Wi-Fi 模式为传统的工作模式(即热点和快连切换模式)才有效,也就是产品信息字段 n=0。
  • 相对于 重置 Wi-Fi 0x03 而言,该命令提供可指定重置复位重启后的 Wi-Fi 配网方式,MCU 根据需求自行选择。
  • 保活门锁方案与可视门锁方案不支持该指令,仅支持 03 重置指令。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x04
数据长度 2 0x0001
数据 1 n=0 有效
0x00:重置后进入快连配网模式
0x01:重置后进入热点配网模式
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x04
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 55 aa 00 04 00 01 01 05,MCU 发送指令让模组重置并重启后进入热点配网模式。
  • 55 aa 00 04 00 00 03,模组回复应答。

重置状态通知 0x25

  • 该指令与 查询产品信息 0x01 指令的返回相关联,MCU 需使能 cap 能力的 bit3,当模组被重置时,才会发送 0x25 指令。
  • 当模组被操作重置时(如 App 内移除设备、本地重置等操作),会将具体重置原因报告给 MCU,其可根据不同的重置原因执行不同的操作。
  • 重置原因与操作场景说明。
    • 本地重置:MCU 发送 0x03 / 0x04 重置指令。
    • App 内移除设备-解除绑定:用于在 App 内做解绑操作。
    • App 内移除设备-解绑并清除数据:用户在 App 内做解绑并清除数据操作,也就是俗称的恢复出厂设置。
    • 本地数据清除,但设备不离网:

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x25
数据长度 2 0x0001
数据 1 重置原因:
0x00:模组本地重置
0x01:App 内移除设备-解除绑定
0x02:App 内移除设备-解绑并清除数据
0x03:清除本地数据,但设备不离网
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

MCU 回复

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x25
数据长度 2 0
数据 -
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 55 aa 00 25 00 01 01 26,设备从 App 内被移除-解绑绑定,同步重置原因给 MCU。
  • 55 aa 00 25 00 00 24,MCU 回复应答。

获取格林时间 0x10

格林时间,即 0 时区标准 UTC 时间戳,不带有时区和夏令时相关因素,是一个国际标准的时间基准。

  • 对于门锁产品,很多功能的正常使用都依赖于时间,因此确保门锁时间同步非常重要,请务必对接。
  • 模组每次上电在未联网成功之前无法同步时间,需要等待设备连接上云端(也就是收到设备联网状态 5)后可发送获取本地时间指令。
  • 设备连接上云端后 有可能会获取时间失败 (在网络情况非常差的情况下,模组未同步到时间)。对于依赖时间的设备(如门锁),当获取失败时可在一定时间后重试获取,确保时间数据获取成功。
  • 建议每次连云成功均同步获取一次时间,已完成设备校时。
  • 获取完格林时间后可再获取一次本地时间,通过两者的时间差值可计算出当前 所处时区

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x10
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x10
数据长度 2 0x0008
数据 8 Data[0] 为是否获取时间结果标识
  • 0x00:获取失败
  • 0x01:获取成功
Data[1] 为年,0x00 表示 2000 年
Data[2] 为月,从 1 开始到 12 结束
Data[3] 为日,从 1 开始到 31 结束
Data[4] 为时,从 0 开始到 23 结束
Data[5] 为分,从 0 开始到 59 结束
Data[6] 为秒,从 0 开始到 59 结束
Data[7] 为星期,从 1 开始到 7 结束,1 代表星期一
注:Data[7]星期字段无意义,默认值
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 55 aa 00 10 00 00 0F,MCU 获取格林时间。

  • 55 aa 00 10 00 08 01 17 02 01 08 09 05 03 65,模组返回获取成功与格林时间数据,解释如下:

    • 格林时间:2023-2-1 8:9:5 星期三。

    • 如设备所处东 8 区间,则对应本地时间:2023-2-1 16:9:5 星期三。

获取本地时间 0x06

本地时间,即设备本地时间,是在格林时间的基础上加上当地(设备激活所在地)时区和夏令时的时间。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x06
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x06
数据长度 2 0x0008
数据 8 Data[0]:获取时间结果标识
  • 0x00:获取失败
  • 0x01:获取成功
Data[1] 为年,0x00 表示 2000 年
Data[2] 为月,从 1 开始到 12 结束
Data[3] 为日,从 1 开始到 31 结束
Data[4] 为时,从 0 开始到 23 结束
Data[5] 为分,从 0 开始到 59 结束
Data[6] 为秒,从 0 开始到 59 结束
Data[7] 为星期,从 1 开始到 7 结束,1 代表星期一
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例
55 aa 00 06 00 00 05,MCU 获取本地时间。
55 aa 00 06 00 08 01 17 02 01 10 09 05 03 49 ,模组返回获取成功结果与本地时间数据,2023-2-1 16:9:5 星期三。

实时状态上报 0x05

  • 实时状态数据会直接上报到云端,故设备联网状态必须为 已连接到云端,否则数据上报失败。
  • 状态数据单元说明请参考 DP 格式(状态数据单元)支持组合形式上报,一次可含多个状态数据单元。
  • 实时状态上报,主要触发机制有三类,分别如下:
    • MCU 检测到状态有变化(如设备电量或某个检测状态),将变化后的 DP 状态发送至模组去上报。
    • MCU 收到命令下发处理帧时,正确执行相应 DP 命令,再通过状态上报帧,将变化后的 DP 状态发送至模组去上报。
    • MCU 收到状态查询帧/或每次成功连上云时,建议将所有的 DP 状态发送至模组。
  • MCU 上报的数据请注意数据的合法性,确保 DPID 与数据类型以及内容,与在 涂鸦开发者平台 创建的 PID 下的 DP 功能点内容信息一致。对于非法上报,模组将返回对应错误码。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x05
数据长度 2 取决于 命令数据单元 类型以及个数
数据 N DP 格式(状态数据单元)
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x05
数据长度 2 0x0001
数据 1 0x00:成功,模组收到并成功上报到云端
0x01:失败
0x02:保留
0x03:PID 未配置该 DP
0x04:DP 类型错误
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 单个状态数据单元 单独上报 示例:DP 109 bool 型变量,数值为 1

    55 aa 00 05 00 05 6d 01 00 01 01 79

  • 多个状态数据单元 组合上报 示例

    • DP 109 bool 型变量,数值为 1
    • DP 102 string 型变量,201804121507 (具体传输对应 ASCII 值)

    55 aa 00 05 00 15 6d 01 00 01 01 66 03 00 0c 32 30 31 38 30 34 31 32 31 35 30 37 5d

  • 模组回复应答,接收成功并上报到云端

    55 aa 00 05 00 01 00 05

记录型数据上报 0x08

  • 使用场景:门锁设备日常使用操作时,会产生开门记录(如指纹开门)以及告警记录(试错告警),设备需要通过该指令将对应的操作记录上报至云端从而在 App 上展示对应的操作记录。

  • 建议流程:以非保活门锁为例,门锁设备产生记录,MCU 给 Wi-Fi 模组上电(推荐:设置连云超时时间 15 秒+)等待其连云成功。通过 0x08 指令上报记录型数据,等待模组应答,若应答成功并无历史记录需上报,2 秒后可给模组做断电处理。若上电连云超时时间内模组都未连接至云端,MCU 也可上报记录型数据让模组缓存,模组应答成功后可做断电处理。

    • 没有网络情况下,模组 支持缓存 MCU 上报的记录型数据(回复给 MCU 应答也会是推送成功-00),当网络恢复并成功连上云则自动补发上报历史记录。
    • 模组支持储存历史记录的条数最大为 20 条 (每条最大长度 80 字节),采用 FIFO 方式存取。当超过 20 条从最早储存的记录开始覆盖,如此循环覆盖。
    • 如模组回复结果为 0x01-上报成功并有滞留/历史数据,此时说明模组内尚有历史记录未上报,此时 MCU 应等待模组上报结束(直到回复状态为 0x00)再给模组做断电处理。
  • 网络环境差、数据拥塞等异常情况下,模组可能会在 5 秒后返回失败,建议 MCU 等待应答超时时间至少 5 秒。

    • MCU 上报的数据请注意数据的合法性,确保 DPID、数据类型以及内容,与在 涂鸦开发者平台 创建的 PID 下的 DP 功能点内容信息一致。
    • 不推荐使用时间类型 0,如强制要用必须在模组获取时间后使用,否则记录的时间将不准确。
    • 相同时间内不太可能同时发生多件记录型事件,因此对于门锁类设备而言建议都使用单条上报(一个状态数据单元)。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x08
数据长度 2 取决于 命令数据单元 类型以及个数
数据 7 记录型数据时间信息,类型+时间,共计 7 字节。
Data[0] 为上报时间类型,定义如下:
  • 0x00:用模组时间,其 Data[1~6]无效。不推荐
  • 0x01:用 MCU 传的本地时间 Data[1~6]
  • 0x02:用 MCU 传的格林时间 Data[1~6]
Data[1] 为年,0x00 表示 2000 年
Data[2] 为月,从 1 开始到 12 结束
Data[3] 为日,从 1 开始到 31 结束
Data[4] 为时,从 0 开始到 23 结束
Data[5] 为分,从 0 开始到 59 结束
Data[6] 为秒,从 0 开始到 59 结束
数据 N DP 格式(状态数据单元)
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x08
数据长度 2 0x0001
数据 1 表示上报结果:
0x00:上报成功,无滞留/历史记录需上报
0x01:上报成功,有滞留/历史记录需上报
0x02:上报失败
0x03:PID 没有配置该 DP
0x04:DP 类型错误
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 单条记录型数据单元上报例子

    DP 109 bool 型变量,数值为 1

    • 时间类型=0,模组当前时间为准:

      55 aa 00 08 00 0c 00 00 00 00 00 00 00 6d 01 00 01 01 83

    • 时间类型=1,设备 MCU 传的本地时间为准(2018/04/19/ 13 点 3 分 29 秒)

      55 aa 00 08 00 0c 01 12 04 13 0d 03 1d 6d 01 00 01 01 da

    • 时间类型=2,设备 MCU 传的格林时间为准(2018/04/19/ 5 点 3 分 29 秒)

      55 aa 00 08 00 0c 02 12 04 13 05 03 1d 6d 01 00 01 01 d3

  • 模组回复应答,接收上报成功,无滞留/历史数据需上报

    • 55 aa 00 08 00 01 00 08
  • 模组回复应答,接收上报成功,有滞留/历史数据需上报

    • 55 aa 00 08 00 01 01 09

模组 DP 命令下发 0x09

  • 命令下发可含多个 datapoint 状态数据单元。

  • MCU 收到指令后 需先回复 0x09 应答包,然后根据 DP 命令数据执行对应功能,若 DP 协议需上报或状态发生改变,MCU 还需使用状态上报 0x05 指令来上报/同步最新状态。示例流程如下:

    MCU 通用对接协议

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x09
数据长度 2 取决于 命令数据单元 类型以及个数
数据 N DP 格式(状态数据单元)
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

MCU 回复

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x09
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 55 aa 00 09 00 05 03 01 00 01 01 13,模组下发 DP 命令(对应 DPID 为 3,bool 型变量,数值为 1)。
  • 55 aa 00 09 00 00 08,MCU 回复应答。

获取 DP 缓存命令 0x15

  • 使用场景:对于非保活 Wi-Fi 门锁方案,平时基本都处于被断电状态,不可实时接收云端下发的 DP 命令。对于某些带设置属性的信息支持先缓存在云端,模组上线后 MCU 可通过该指令获取缓存 DP 命令,从而完成相关设置。
  • 支持按 DP ID 值查询(当 dp_num 非 0,后跟待查的 DP ID 数据)或查询所有缓存 DP(当 dp_num=0 时)。
  • 如对接方案上 有设置指令缓存相关需求请对接该指令,否则可不对接。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x15
数据长度 2 N
数据 N 格式:dp_num + dp_1 + … + dp_n
  • dp_num:1 字节,表示查询个数(0 查询所有)
  • dp_x:1 字节,表示查询的 DP ID 值
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x15
数据长度 2 取决于 命令数据单元 类型以及个数
数据 ~ 格式:result + dp_num + 数据 1 +…+ 数据 n
  • result:1 字节,0-失败,1-成功
  • dp_num:1 字节,为 0 表示无缓存
  • DP 数据:详见 DP 格式(状态数据单元)
result=0 失败时后无数据,数据长度为 1
dp_num 为 0 时,表示当前没有缓存命令
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • MCU 查询指定 DP ID 的 DP 缓存,如获取 DP 10、DP 11 的 DP 缓存

    55 AA 00 15 00 03 02 0A 0B 2E

  • 模组返回获取结果,DP10(自动落锁开启,布尔型)+ DP 11(自动落锁延时时间 5 秒,数值型)

    55 AA 00 15 00 0F 01 02 0A 01 00 01 01 0B 02 00 04 00 00 00 05 49

  • MCU 查询所有 DP 缓存

    55 AA 00 15 00 01 00 15

  • 模组返回获取结果,无 DP 缓存

    55 AA 00 15 00 02 01 00 17

MCU OTA 升级服务

  • 涂鸦 Wi-Fi 门锁方案均支持 OTA 升级服务,支持给模组、外部 MCU 固件升级。

  • 当客户的 MCU 或者 Wi-Fi 模组的固件功能有重大升级时,或者有严重 BUG 或紧急问题修复时,需要覆盖到已出货产品,客户可以在涂鸦平台配置 OTA 升级。

  • 目前涂鸦开发者平台的 MCU 升级支持下面 四种升级方式 的配置:

    • App 提醒升级:用户每次进入设备控制面板都会收到升级提醒的弹窗,是否确认升级由用户自己在 App 确认。
    • App 自动升级:App 不会有任何提醒弹窗,模组上电后一分钟内会去自动去检测升级发现有高版本的升级包会自动开始拉取相关升级包,第一次上电后模组会间隔 24 小时去云端检测一次是否有升级包配置。
    • App 强制升级:App 会有升级提醒弹窗,如果用户不确认升级用户就没法正常使用这个产品的控制面板。
    • App 检测升级:App 不会有任何升级提醒的弹窗,必须要用户自己在 App 上单击相关固件版本检测,如果有高版本的固件配置才会显示升级提示信息。
  • MCU 升级相关流程图:

    Wi-Fi 模组发送完所有的升级包,会重新发送 01 命令字(查询产品信息),MCU 需要在一分钟回复产品信息中的 MCU 软件版本号(升级后的版本号),版本号需要和在涂鸦后台配置升级的版本号保持一致,App 端才会收到固件升级成功的通知。

    MCU 通用对接协议

自动/静默升级 0x21

  • 一般 Wi-Fi 模组的电源由 MCU 控制,当处于升级时会将升级状态(检测到有升级、升级开始、升级成功、升级失败等)同步通知给 MCU,MCU 需根据对应状态控制模组供电。
  • 该功能与 查询产品信息 0x01 指令的返回相关联,MCU 需使能 cap 能力的 bit4=1。如未使能该标志位,则不会通过 0x21 指令通知 MCU,需 MCU 通过 0x0C、0x0D 指令主动请求拉取请求固件升级,涂鸦已不推荐使用。
  • 用户在涂鸦开发者平台配置模组、MCU 升级时,配置升级方式为自动保持设备更新。
  • 上电模组连接至云端会查询否有新固件更新,如有则发送给模组,模组接收到有新固件则发送协议给 MCU,MCU 根据升级固件类型做对应处理并回复。
  • 模组收到 MCU 回复命令,如果升级则下发开始升级命令。升级成功则发送升级成功命令。其他等异常失败均回复升级失败。
  • 使能自动升级后,MCU 务必实现对 0x21 命令的回复-允许升级,否则模组也不能 OTA 升级。

  • 接收到模组向 MCU 发送的升级成功命令后 15s 后断电,因为模组升级成功后,会重新连接网络,检测固件版本是否升级成功,如果成功,App 端才会收到固件升级成功的通知。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x21
数据长度 2 0x0002
数据 2 Data[0]:升级状态
  • 0x00:检测到有固件升级(不可断电)
  • 0x01:升级开始(不可断电)
  • 0x02:升级成功(15 秒后断电
  • 0x03:升级失败(可断电)
Data[1]:固件类型
  • 0x00:模组固件
  • 0x01:MCU 固件
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x21
数据长度 2 0x0001
数据 1 0x00:允许升级
0x01:电量不足拒绝升级
0x02:其它原因
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 55 aa 00 21 00 02 00 01 23,模组发送固件自动升级信息,检测到有新的 MCU 固件。
  • 55 aa 00 21 00 01 00 21 ,MCU 返回允许升级。
  • 55 aa 00 21 00 01 01 22 ,MCU 返回拒绝升级,因电池电量不足原因。

升级启动 0x0D

  • 升级启动方式含自动及手动升级两种方式:

    • 当处于自动升级时,模组检测云端 MCU 有更新版本固件,则自动启动与 MCU 升级包交互流程。
    • 当处于手动升级时,通过 App 确定,模组才启动与 MCU 升级包交互流程。
  • 当升级启动时,模组会将升级固件包的信息给 MCU(主要包含文件大小,单位:字节)。MCU 返回应答时可根据需要选择分片传输数据包大小,若不选择则默认为 256 Bytes。

    MD5 文件校验值仅在模组支持 ble+x 模式时才有效,否则无该字段。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x0d
数据长度 2 0x0004 / 0x0024
数据 4 Data[0~3]:固件包大小(大端),4 字节
Data[4-35]:固件 MD5 校验值,32 字节

注:MD5 字段仅在支持低功耗蓝牙+x 方案时才有
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x0d
数据长度 2 0x0001
数据 1 分片传输数据大小
  • 0x00:分包大小 256 字节
  • 0x01:分包大小 512 字节
  • 0x02:分包大小 1024 字节
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 55 aa 00 0d 00 04 00 00 68 00 78,模组发送升级固件大小 (固件包长度 26624 Bytes )。
  • 55 aa 00 0d 00 01 00 0d,MCU 确认包回复,选择分包传输大小为 256 Bytes。

升级数据传输 0x0E

  • 升级包传输数据格式:文件偏移量 + 包数据。

  • 若 MCU 收到该帧数据长度为 4,并且偏移量 >= 固件大小,则表示升级文件传输完成。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x0e
数据长度 2 0x0004 + N
数据 4+N Data[0~3]:固定为文件偏移(大端)
Data[4~n]:升级数据
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x0e
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 模组发送文件数据,若要升级的文件大小 530Byte

    • 第一包数据,包偏移为 0x00000000,分包升级数据长度为 256

      55 aa 00 0e 0104 00000000 xx…xx XX

    • 第二包数据,包偏移为 0x00000100,分包升级数据长度为 256

      55 aa 00 0e 0104 00000100 xx…xx XX

    • 第三包数据,包偏移为 0x00000200,分包升级数据长度为 18(最后分片

      55 aa 00 0e 0016 00000200 xx…xx XX

    • 最后一包,包偏移为 0x00000212,分包升级数据长度为 0(传输完成

      55 aa 00 0e 0004 00000212 XX

  • MCU 每个分片数据包均要回复应答

    • 55 aa 00 0e 00 00 0d

门锁密码服务

密码进制设置 0x1C

目的与意义:部分门锁的密码键盘可输入的数字按键范围并非支持 0-9,例如钥匙盒类产品仅支持 1-6 数字按键输入。对这样的需求就需要通过产品配置告知云端、面板与模组端,从而通过进制算法转换成正确密码。其中云端、面板的配置用户可在平台前台产品能力中配置。嵌入式端的配置就需要 MCU 通过 0x01C 指令告知模组。

概念说明:主要包含两个主要概念:进制与起始值。

  • 进制:表示所有密码数字按键的个数,目前支持 4-10。
  • 起始值:表示密码数字按键开始的数值,目前仅支持 0 和 1,也可理解为是否包含 0。
  • 几种示例:
    • 密码键盘可输入数字 12345,则配置进制为 5,起始值为 1。
    • 密码键盘可输入数字 012345,则配置进制为 6,起始值为 0。
    • 密码键盘可输入数字 123456789,则配置进制为 9,起始值为 1。
    • 密码键盘可输入数字 0123456789,则配置进制为 10,起始值为 0。

转换原理:云端默认生成的算法类密码均是按 10 进制来的,使用端根据配置/设置的进制将其转换,然后根据起始值如果为 1,再将转换后的值每个数字+1。同理,使用端根据对应的规则也可将其转换成原来的 10 进制。示例:用户可以配置密码从 1 开始,且按键只支持 1-6 这 6 个数字,这样用户本地密码键盘只需要支持 1-6 这 6 个数字按键即可。面板获取云端动态密码 76829103,面板按进制转换后显示为:22453525254。当用户本地开门时,门锁端输入 22453525254,MCU 将输入的密码通过对应指令传给模组,模组提取原来的 10 进制密码 76829103 进行算法比对,并将结果返回给 MCU。转换原理涂鸦方案各端会自行处理,MCU 使用端可不必理解详细的原理,只需配置设置好对应的参数使用即可。

密码进制参照表

密码进制
对应密码按键数量
密码按键
从 1/0 开始
是否支持
动态密码
是否支持
离线密码
在线密码
最小密码长度
安全等级 在线密码
多语言配置
4 可选 不支持 不支持 8 1/29W 支持 8-12 位密码
5 可选 支持 不支持 8 1/39W 支持 8-12 位密码
6 可选 支持 不支持 8 1/100W 支持 8-12 位密码
7 可选 支持 支持 8 1/100W 支持 8-11 位密码
8 可选 支持 支持 7 1/100W 支持 7-11 位密码
9 可选 支持 支持 7 1/100W 支持 7-10 位密码
10 不可选 支持 支持 6 1/100W 支持 6-10 位密码
  • 密码进制 0x1C 设置,需要在获取信息查询产品信息 0x01 之后进行设置,并在密码操作前设置。
  • 如果进行了密码进制 0x1C 设置,即开启了密码进制服务,0x14 命令必须使用新版协议格式。
  • 模组默认进制参数为 10 进制,每次设置会保存对应参数,如需设置 MCU 在配网成功后设置一次即可。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x1C
数据长度 2 0x0002
数据 2 Data[0]:密码进制值,取值范围:4-10
Data[1]:密码起始值,从 0 或 1 开始
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x1C
数据长度 2 0x0001
数据 1 结果返回
0x00:设置成功
其他:设置失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例
55 aa 00 1c 00 02 05 01 23,MCU 密码键盘可输入数字 12345,配置进制为 5,起始值为 1。
55 aa 00 1c 00 01 00 1c,模组返回设置成功。

请求拉取临时密码-老 0x14

使用场景:临时密码支持设备未联网时创建,信息缓存在云端。当用户在门锁密码键盘上输入密码请求开门,MCU 判断不属于本地密码,根据输入的密码长度向 Wi-Fi 模组发送不同的指令去请求或验证。

  • 临时密码云端都是全量下发,每次拉取成功,门锁 MCU 端均需要根据服务端返回的所有密码和状态进行更新,并保存与本地。
  • 支持设置生效失效时间,支持设置重复规则(周循环 + 每天窗口时段)。
  • 密码编号说明:云端创建生成的临时密码编码规则为 900+x(0-50)。设备请求拉取获取到的编号为 x,MCU 端保存在本地的临时密码编号一般也会是 x。当用该临时密码解锁上报记录时,使用的密码编号需是 900+x,云端才可正确对应。
  • 密码生效、时间说明:采用格林时间,年月日时分秒编码。
  • 重复规则一天的起始-结束时间:也是格林时间,HH:MM 编码。
  • 重复循环规则说明:当前在面板内创建的临时密码,仅支持设置一条重复循环规则。
  • 非保活门锁方案,最多可创建 10 组 临时密码。保活方案因是长在线直接 DP 下发,离线时也支持缓存在云端,设备上线通过 0x1D 指令拉取(为保持 MCU 处理数据统一格式,均为 DP 格式,详见具体指令描述)。
  • 临时密码是否处于有效期,极其依赖设备时间正确,因此建议每次连云成功均获取时间校时,或设备硬件配备时钟芯片并带后背电池。

老版本指令,都是 7 位定长临时密码,不支持密码进制。新出模组方案都不再使用该老版本指令,请使用新版本请求临时密码指令。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x14
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x14
数据长度 2 1 / N
数据 1 / N Data[0]:获取临时密码结果标识
  • 0x00:失败,后续无数据,数据长度为 1
  • 0x01:成功
Data[1]:本包数据密码组数(值范围:0-10)
 组数=0 表示未创建,无后续密码数据
Data[2]:密码长度,以下简用 N
Data[3]:分包标识+序号,其中
  • bit7:为 1 表示后续还有数据包。
  • bit6-bit0:表示本包序号(从 0 开始)
// 第 1 组临时密码数据
Data[4]:密码编号(900+x)
Data[5]:密码有效次数,0-不限次数,1-仅一次
Data[6]:密码状态,0-有效,1-失效(已删)
Data[7~12]:密码生效时间
Data[13~18]:密码失效时间
 生效、失效时间格式: 年月日时分秒(格林时间)
Data[19~19+N-1]:临时密码(Ascii 码表示)
Data[19+N]:重复循环规则条数(目前仅一条)
Data[20+N]:是否全天有效,0-非全天,1-全天
Data[21+N]:开始时间(小时)
Data[22+N]:开始时间(分钟)
Data[23+N]:结束时间(小时)
Data[24+N]:结束时间(分钟)
 开始-结束时间格式:HH:MM(格林时间)
Data[25+N]:周循环,详见周编码规则
  • bit0-周日,bit1-周 1, …, bit6-周 6,bit7-默认 0
// 第 2 组临时密码数据

// 第 n 组临时密码数据
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 门锁拉取缓存的临时密码 (老版本指令、不支持密码进制)

    55 aa 00 14 00 00 13

  • 模组返回拉取的临时密码数据

    55 aa 00 14 00 21 01 01 07 00 0A 00 00 14 0A 09 01 31 19 14 0A 0D 02 31 19 38 30 32 34 33 36 36 01 00 00 00 01 00 3E DD

    • 01 // 获取结果:成功

    • 01 // 密码组数:1 组

    • 07 // 密码长度:7

    • 00 // 本包序号 0,且后续无数据包(bit7:后续是否还有数据包。bit6-bit0:本包序号,从 0 开始)

      // 第 1 组临时密码数据

    • 0A // 密码编号 10(实际编号需要在密码编号基础上加 900)

    • 00 // 密码有效次数(0:有效期内可不限次数开门。1:有效期内只能开一次门)

    • 00 // 密码当前状态(0:密码有效。1:密码无效)

    • 14 0A 09 01 31 19 // 生效时间(格林时间),北京时间:2020-10-09 09:49

    • 14 0A 0D 02 31 19 // 失效时间(格林时间),北京时间:2020-10-13 10:49

    • 38 30 32 34 33 36 36 // 密码内容 Ascii 码,对应密码数字 8024366

      // 重复循环规则数据

    • 01 // schedule 条数(目前仅支持一条)

    • 00 // 非全天有效(1:全天有效,后面的起始时间数据无效)

    • 00 // 开始时间(小时)

    • 00 //开始时间(分钟)

    • 01 // 结束时间(小时)

    • 00 // 结束时间(分钟)

    • 3E // 周循环:0011 1110,即周一到周五循环。Bit 0:周日。Bit 1:周一。Bit 2:周二。Bit 3:周三。Bit 4:周四。Bit 5:周五。Bit 6:周六

请求拉取临时密码-新 0x14

使用场景:临时密码支持设备未联网时创建,信息缓存在云端。当用户在门锁密码键盘上输入密码请求开门,MCU 判断不属于本地密码,根据输入的密码长度向 Wi-Fi 模组发送不同的指令去请求或验证。

  • 临时密码云端都是全量下发,每次拉取成功,门锁 MCU 端均需要根据服务端返回的所有密码和状态进行更新,并保存与本地。
  • 支持设置生效失效时间,支持设置重复规则(周循环 + 每天窗口时段)。
  • 密码编号说明:云端创建生成的临时密码编码规则为 900+x(0-50)。设备请求拉取获取到的编号为 x,MCU 端保存在本地的临时密码编号一般也会是 x。当用该临时密码解锁上报记录时,使用的密码编号需是 900+x,云端才可正确对应。
  • 密码生效、时间说明:采用格林时间,年月日时分秒编码。
  • 重复规则一天的起始-结束时间:也是格林时间,HH:MM 编码。
  • 重复循环规则说明:当前在面板内创建的临时密码,仅支持设置一条重复循环规则。
  • 非保活门锁方案,最多可创建 10 组 临时密码。保活方案因是长在线直接 DP 下发,离线时也支持缓存在云端,设备上线通过 0x1D 指令拉取(为保持 MCU 处理数据统一格式,均为 DP 格式,详见具体指令描述)。
  • 临时密码是否处于有效期,极其依赖设备时间正确,因此建议每次连云成功均获取时间校时,或设备硬件配备时钟芯片并带后背电池。
  • 临时密码长度支持变长(密码进制),推荐使用该指令对接,功能作用上覆盖原老版指令。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x14
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x14
数据长度 2 1 / N
数据 1 / N Data[0]:获取临时密码结果标识
  • 0x00:失败,后续无数据,数据长度为 1
  • 0x01:成功
Data[1]:本包数据密码组数(值范围:0-10)
 组数=0 表示未创建,无后续密码数据
Data[2]:分包标识+序号,其中
  • bit7:为 1 表示后续还有数据包。
  • bit6-bit0:表示本包序号(从 0 开始)
// 第 1 组临时密码数据
Data[3]:密码长度,以下简用 N
Data[4]:密码编号(900+x)
Data[5]:密码有效次数,0-不限次数,1-仅一次
Data[6]:密码状态,0-有效,1-失效(已删)
Data[7~12]:密码生效时间
Data[13~18]:密码失效时间,生效、失效时间格式: 年月日时分秒(格林时间)
Data[19~19+N-1]:临时密码(Ascii 码表示)
Data[19+N]:重复循环规则条数(目前仅一条)
Data[20+N]:是否全天有效,0-非全天,1-全天
Data[21+N]:开始时间(小时)
Data[22+N]:开始时间(分钟)
Data[23+N]:结束时间(小时)
Data[24+N]:结束时间(分钟)
 开始-结束时间格式:HH:MM(格林时间)
Data[25+N]:周循环,详见周编码规则
  • bit0-周日,bit1-周 1, …, bit6-周 6,bit7-默认 0
// 第 2 组临时密码数据

// 第 n 组临时密码数据
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 门锁拉取缓存的临时密码(新版本指令、支持密码进制)
    55 aa 00 14 00 00 13

  • 模组返回拉取的临时密码数据

    55 aa 00 14 00 21 01 01 00 07 0A 00 00 14 0A 09 01 31 19 14 0A 0D 02 31 19 38 30 32 34 33 36 36 01 00 00 00 01 00 3E DD

    • 01 // 获取结果:成功

    • 01 // 密码组数:1 组

    • 00 // 本包序号 0,且后续无数据包(bit7:后续是否还有数据包。bit6-bit0:本包序号,从 0 开始)

      // 第 1 组临时密码-时效与内容数据

    • 07 // 密码长度:7

    • 0A // 密码编号 10(实际编号需要在密码编号基础上加 900)

    • 00 // 密码有效次数(0:有效期内可不限次数开门。1:有效期内只能开一次门)

    • 00 // 密码当前状态(0:密码有效。1:密码无效)

    • 14 0A 09 01 31 19 // 生效时间(格林时间),北京时间:2020-10-09 09:49

    • 14 0A 0D 02 31 19 // 失效时间(格林时间),北京时间:2020-10-13 10:49

    • 38 30 32 34 33 36 36 // 密码内容 Ascii 码,对应密码数字 8024366

      // 第 1 组临时密码-重复循环规则

    • 01 // schedule 条数(目前仅支持一条)

    • 00 // 非全天有效(1:全天有效,后面的起始时间数据无效)

    • 00 // 开始时间(小时)

    • 00 //开始时间(分钟)

    • 01 // 结束时间(小时)

    • 00 // 结束时间(分钟)

    • 3E // 周循环:0011 1110,即周一到周五循环。Bit 0:周日。Bit 1:周一。Bit 2:周二。Bit 3:周三。Bit 4:周四。Bit 5:周五。Bit 6:周六

请求比对动态密码 0x12

  • 门锁设备和云端都独立拥有一套完全相同的动态密码生成算法,两者唯一的联系在于 UNIX 时间戳。如果门锁设备和云端的 UNIX 时间戳相差 不超过 5 分钟,则认为两者生成的动态密码一致。
  • 不再建议使用该协议对接动态密码,可使用 0x16 算法密码比对指令替代(如模组方案支持)。目前仅 WBRL 模组支持,详见 系列方案协议支持汇总

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x12
数据长度 2 N
数据 N 数据格式:格林时间 + 密码
Data[0-5]:年月日时分秒 格林时间
Data[6~13]:用户输入密码数据,Ascii 码的‘0’~‘9’
Data[14]:默认填 0x00
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组回复

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x12
数据长度 2 0x0001
数据 1 0x00:比对通过
0x01:比对失败
0x02:设备未激活
0x03:数据长度错误
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • MCU 请求比对校验动态密码:41833832,格林时间:2020/09/22 03:45:07。
    55 AA 00 12 00 0F 14 09 16 03 2D 07 34 31 38 33 33 38 33 32 00 2A

  • 模组返回比对结果,比对正确

    55 AA 00 12 00 01 00 12

请求比对算法密码(动态/离线) 0x16

  • 使用场景:主人在 App 面板内生成算法密码,有效时间内访客在门锁上输入对应的密码即可开门。算法密码(动态/离线)的创建和使用均不依赖网络,可以在门锁离线时使用。算法密码依赖时间因子,因此需要 MCU 的时间准确来保证,从而完成离线密码校对。

  • 建议流程:用户在门锁密码键盘上输入离线密码请求开门,MCU 判断不属于本地密码,根据输入的密码长度(一般 8 位以上)向 Wi-Fi 模组发送算法密码 0x16 指令去请求验证,模组根据 MCU 传的时间戳以及密码内容,通过运算对应算法返回结果,结果内容包含:校验结果 + 密码类型 + 编码数据。如校验正确,MCU 还需根据密码类型与编码数据上报对应开门/操作记录,详见下文。

  • 动态密码说明

    门锁设备和云端都独立拥有一套完全相同的动态密码生成算法,两者唯一的联系在于 unix 时间戳。如果门锁设备和云端的 unix 时间戳相差 不超过 5 分钟,则认为两者生成的动态密码一致

  • 离线密码类型说明

    • 单次密码:一次性密码创建成功即生效,有效期为 6 小时,失效前仅能使用一次。每个整点 60 分钟内,只有 10 组可用的单次密码。

    • 限时密码:不限次数密码生效、失效时间可编辑,有效期最长只能设置 1 年区间。有效期内可不限次数使用。生效后 24 小时内至少使用一次,否则密码将失效。同一设备在相同生效、失效时间段内仅能获取 1 组密码。

    • 清空码 (清空单个):对于不限次数密码,还可获取对应离线清空码用于删除该离线密码,单击离线密码 - 删除即可获取。清空单个密码,只可清空单条在门锁上至少被使用过一次的离线不限次数密码,不能清空一次性密码以及没有在门锁上使用过的不限次数密码。

      非保活公版方案,仅支持对限时密码做单个删除操作,没有清空所有的操作入口,因此原返回类型 type 上未做清空单个、所有的区分。

    • 清空码 (清空所有):清空所有离线密码,有效期 24 小时内。

      可视对讲保活公版,支持选择清空单个、所有离线密码,因此增加返回类型 type 用于 MCU 区分上报不同的操作记录。

  • 模组支持说明:目前仅 WBRL 模组支持动态、离线密码统一走该指令,其他模组方案动态密码需使用 0x12 指令,详见 系列方案协议支持汇总

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x16
数据长度 2 N
数据 N 数据格式:格林时间 + 密码长度 + 密码
Data[0-5]:年月日时分秒 格林时间
Data[6]:密码长度
Data[7~N]:密码内容,10 进制(非 Ascii)
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组回复

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x16
数据长度 2 N
数据 N 数据格式:result+type+decode_len+decode
Data[0]:比对结果 result
  • 0x00:正确
  • 其他:错误(无后续数据)
Data[1]:离线密码类型 type
  • 0x00:限时开门离线密码
  • 0x01:单次开门离线密码
  • 0x02:清除离线密码(单个)
  • 0x03:动态密码
  • 0x04:清除离线密码(所有)
Data[2]:解密后数据长度 decode_len
Data[3~n]:解密数据 decode

1. decode 解密数据,用于离线密码记录上报
2. type 增加 0x03 用于表示动态密码,无后续
decode_len+decode 字段,其记录上报无需这些
3. type 增加 0x04 用于表示清除所有离线密码
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • MCU 请求比对离线密码:4183383233,格林时间:2020/09/22 03:45:07。
    55 AA 00 16 00 11 14 09 16 03 2D 07 0A 04 01 08 03 03 08 03 02 03 03 C0

  • 模组返回比对结果。

    55 AA 00 16 00 13 00 01 10 34 7B 6E BD 51 C8 73 03 FE D6 87 0D 5E A9 9B C5 71

    • 比对结果:00,正确。
    • 密码类型:01,表示一次性密码。
    • 解密数据长度:16 字节。
    • 解密数据:34 7B 6E BD 51 C8 73 03 FE D6 87 0D 5E A9 9B C5,MCU 用于记录上报。

保活方案特有协议

时间同步-综合时间 0x1B

考虑到 MCU 获取时间同步的便捷性以及信息的完整度,新增一条指令支持 MCU 可获取当前综合时间信息,包括 时间戳、时区以及夏令时信息。模组是否支持详见 系列方案协议支持汇总

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x1B
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x1B
数据长度 2 0x0011
数据 17 数据长度 17 字节,格式定义如下:
Data[0]:获取时间结果标识
  • 0x00:失败
  • 0x01:成功
Data[1]-Data[4]:unix 时间戳(大端)
Data[5]:获取时区信息结果标识
  • 0x00:失败
  • 0x01:成功
Data[6]:表示东/西时区,及时区小数位,用 bit 定义
  • bit7-4:保留,默认 0
  • bit3:3/4H-45分钟,0:无,1:有
  • bit2:1/4H-15分钟,0:无,1:有
  • bit1:1/2H-半时区,0:无,1:有
  • bit0:0:东区,1:西区
Data[7]:时区整数位。例如,东 8 区值=0x08,西 3 区值=0x03
Data[8]:是否有夏令时标识
  • 0x00:无夏令时
  • 0x01:有夏令时
Data[9]-Data[12]:进入夏令时时间戳(大端)
Data[13]-Data[16]:退出夏令时时间戳(大端)
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例
55 aa 00 1B 00 00 1A ,MCU 获取综合时间信息。
55 aa 00 1B 00 11 01 63 DA 1E 21 01 00 08 00 00 00 00 00 00 00 00 00 B1 ,模组返回综合时间信息,解析如下:

  • 获取时间戳成功,Unix 时间戳 0x63DA1E21,对应 10 进制为 1675238945,换算成时间对应 2023-2-1 8:9:5。

  • 获取时区成功,东 8 区。

  • 无夏令时信息。

  • 以上综合,设备所处时区为东 8 区,换算对应本地时间为 2023-2-1 16:9:5。

请求拉取临时密码-DP 格式 0x1D

  • 因保活类方案属于 MQTT 保活常在线设备,临时密码的创建等操作可直接通过 DP 命令下发给模组。考虑到部分使用场景,支持 设备离线时也可创建、修改、删除临时密码缓存在云端(最多支持 10 组缓存)。模组下一次上线时,MCU 可通过发送 0x1D 指令让模组去云端拉取缓存,拉取的内容为差量数据(也就是离线时操作的数据)。为了方便 MCU 端处理对应数据(1. DP 指令过来的,2. 通过 0x1D 指令拉取的),该指令核心数据部分设计采用与 DP 协议保持一致。
  • MCU 在获取到 0x1D 指令返回数据后,按协议解析每条临时密码数据,通过 云端编号判断本地是否存在
    • 如果存在,则更新并保存。
    • 如果不存在,则新建。创建结果通过添加临时密码 DP 点上报 回复。
  • 仅保活类 Wi-Fi 门锁方案支持该指令,其他非保活类方案不支持。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x1D
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x1D
数据长度 2 1 / N
数据 1 / N Data [0]:获取临时密码结果标识
  • 0x00:失败,后续无数据,数据长度为 1
  • 0x01:成功
Data[1]:分包数。0 表示未创建,无后续密码数据
 表示所有缓存的数据,分几次发送给 MCU
Data[2]:分包序号(1~n)
// 第 1 组临时密码数据
Data[3~4]:云端编号
Data[5]:密码状态,0-冻结,1-生效,2-删除
Data[6~22]:时效性详见 附录二:时效性
Data[23]:使用次数,0-永久,1-一次性
Data[24]:密码长度
Data[25~.]:密码内容(10 进制,非 Ascii 码)
// 第 2 组临时密码数据

// 第 n 组临时密码数据
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

  • 门锁获取缓存的临时密码 (DP 格式)

    55 aa 00 1D 00 00 1C

  • 模组返回拉取的临时密码数据

    55 aa 00 1D 00 20 01 01 01 00 02 01 5A 6A 6F 80 5B 6A 4D D0 02 00 00 00 3E 08 00 08 1E 00 07 03 08 03 02 06 05 01 68

    • 01 // 获取结果:成功

    • 01 // 分包数:1 个分包

    • 01 // 分包序号:1(默认从 1 开始)

    • 00 02 // 云端分配的临时密码编号 2

    • 01 // 密码当前状态(0:冻结,1:生效,2:删除)

    • 5A 6A 6F 80 5B 6A 4D D0 02 00 00 00 3E 08 00 08 1E // 时效性 17 字节

      • 5A 6A 6F 80 // 生效时间(格林时间),时间戳:1516924800,转为年月日时分秒:2018-01-26 08:00:00
      • 5B 6A 4D D0 // 失效时间(格林时间),时间戳:1533693392,转为年月日时分秒:2018-08-08 09:56:32
      • 02 // 循环方式 (02-周循环)
      • 00 00 00 3E // 循环标志数据(周 1~周 5 有效)
      • 08 00 // 一天中的开始时间,早上 8:00 生效
      • 08 1E // 一天中的结束时间,早上 8:30 结束
    • 00 // 密码有效次数(0:有效期内可不限次数开门。1:有效期内只能开一次门)

    • 07 // 密码长度:7 位

    • 03 08 03 02 06 05 01 // 密码内容,对应密码数字 3832651

深度休眠时间参数 0x80

  • 该功能与 查询产品信息 0x01 指令的返回相关联,MCU 按需设置 cap 能力的 bit5 位
    • 当 bit=0 时,深度休眠由模组端自行实现,MCU 无需对接该指令。在面板内设置开关与时间段后,模组不会通过 0x80 指令将时间参数同步给 MCU。到了休眠时间模组会自行进入深度休眠,到了退出时间模组会退出深度休眠状态进入保活状态。
    • 当 bit=1 时,深度休眠由 MCU 端实现。在面板内设置开关与时间段后,模组通过 0x80 指令将时间参数同步给 MCU。进入/退出休眠时间,对应的操作均由 MCU 来选择处理,模组不做任何逻辑。
  • 推荐 cap 使用默认值 bit5=0,让模组自行处理。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x80
数据长度 2 0x0009
数据 9 Data[0]:休眠功能是否使能
  • 0x00:关闭
  • 0x01:开启
Data[1~2]:进入休眠时间(HH:MM)
Data[3~4]:退出休眠时间(HH:MM)
Data[5~8]:预留
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x80
数据长度 2 0
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

55 aa 00 80 00 09 01 16 00 07 00 00 00 00 00 B0,模组同步休眠时间参数,开启休眠,时间段 22:00~第二天 07:00。
55 aa 00 80 00 00 7F,MCU 返回应答。

驱屏时间控制 0x83 (T31)

  • 该指令是否有效,与 查询产品信息 0x01 指令的返回相关联,MCU 按需设置 cap 能力的 bit8 位,定义如下:
    • 0:通过中断引脚控制
    • 1:通过串口指令控制
  • 通过 UVC 驱屏时由于 T31 不能休眠,因此增加该命令。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x83
数据长度 2 0x0001
数据 1 0x00:允许休眠
0x01:驱屏中不休,模组兜底时长 10min
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x83
数据长度 2 0x0001
数据 1 0x00:成功
0x01:失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

55 aa 00 83 00 01 00 83,MCU 发送指令,允许休眠。
55 aa 00 83 00 01 00 83,模组回复设置成功应答。

上电配网使能控制 0x84

  • 保活方案(T31、WBRL),在未绑定前上电即进入可配网状态,不能满足一些使用场景,因此新增设计该指令让 MCU 可根据产品需求来选择是否进入。

  • 该指令是否有效,与 查询产品信息 0x01 指令的返回相关联,MCU 按需设置 cap 能力的 bit9=1 时有效,具体逻辑如下图文所示。

    • 当产品需上电即进配网,则无需对接该指令。

    • 当产品需上电默认不进配网,后续通过某种触发方式开启,则需设置 cap 能力 bit9=1 并对接该指令。

      MCU 通用对接协议

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x84
数据长度 2 0x0001
数据 1 0x01:控制模组进入配网模式
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x84
数据长度 2 0x0001
数据 1 0x00:成功
0x01:失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

55 aa 00 84 00 01 01 85,MCU 发送指令,让模组进入配网模式。
55 aa 00 84 00 01 00 84,模组回复设置成功应答。

模组拓展服务

查询连接路由信号强度 0x0B

  • 使用场景:需要得知当前 Wi-Fi 设备与路由器热点间的信号强度怎么样,可通过该指令查询。
  • 必须在设备的联网状态为 已成功连接上路由器 以后使用,否则发送此命令将返回失败的结果。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x0b
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x0b
数据长度 2 0x0002
数据 2 Data[0]:表示查询结果
  • 0x00:失败
  • 0x01:成功
Data[1]:表示具体结果
  • 成功时:表示信号强度百分比,
       范围 0~100(0-最差,100-最强)
  • 失败时:0x00 表示设备未连接上路由
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

55 aa 00 0b 00 00 0A,MCU 查询连接路由器的信号强度。
55 aa 00 0b 00 02 01 50 5D,模组返回当前信号强度值百分比为 80。

上报 MCU 的 SN 编号 0x17

通过这个指令可将 MCU 的 SN 号上报至云端。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x17
数据长度 2 N
数据 ~ 格式:SN 长度(1 字节) + SN(n 字节)
注意:SN 长度不得超过 32bytes
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组回复

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x17
数据长度 2 1
数据 1 表示上报结果
  • 0x00:上报成功
  • 其他:上报失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

55 aa 00 17 00 09 08 41 42 43 44 31 32 33 34 FB,MCU 上报设备 SN 号字符串 ABCD1234 至平台。
55 aa 00 17 00 01 00 17,模组回复上报成功。

MCU 断电通知 0x22

背景说明:在 MCU 断电前通过该指令需要告知模组,让模组跟路由器主动断开连接(提高下一次快联成功率)

考虑到不同的 MCU 处理速度不一样,模组的回复会重复发送三次,MCU 第一次收到模组回复即可断电,不需要再接收后续的回复。

仅非保活类门锁方案,并有断电使用需求才需对接该指令。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x22
数据长度 2 0x0000
数据 ~
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组回复

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x22
数据长度 2 0x0001
数据 1 表示处理结果
  • 0x00:通知成功
  • 其他:通知失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

恢复出厂设置 0x340A

MCU 可通过该指令对模组进行 本地重置,模组数据清除,进入低功耗状态

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x34
数据长度 2 0x0002
数据 2 Data[0]:子命令 0x0A
Data[1]:模组重置并清除云端数据 0x00
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x34
数据长度 2 0x0002
数据 2 Data[0]:子命令 0x0A
Data[1]:0-成功,1-失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

55 aa 03 34 00 02 0A 00 42,MCU 主动调用恢复出厂设置。
55 aa 00 34 00 02 0A 00 3F,模组回复成功,并恢复出厂设置。

休眠参数配置 0xD3

该指令用于锁控 MCU 对模组进行休眠类参数设置,目前支持短时保活时长与锁定/解除模组深度休眠。命令预留了字段待后续扩展。

短时保活:以 7916 方案为例,该方案默认不保活,每次使用处理完相关事务后自动进入休眠,同时面板上也无视频查看的入口。为了满足 Wi-Fi 在线时可通过面板直接操作和查看视频,增加了对应入口以及通过协议用于锁控配置 Wi-Fi 上线后在线保活时长。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xD3
数据长度 2 0x000B
数据 4
  • Data[0]:短时保活时长,范围 10-180,单位为秒
  • Data[1]:锁定模组深度休眠
    • 0x00:保留
    • 0x01:锁定深度休眠
    • 0x02:解除深度休眠
  • Data[2~10]:预留待扩展,默认 0x00
注:当 Data[1] 非 0 时,Data[0] 参数无意义
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组回复

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xD3
数据长度 2 0x0001
数据 1
  • 0x00:执行成功
  • 0x01:参数错误
  • 0x02:执行失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

调试相关功能

模组调试协议 0xDB

为了方便后续排查测试过程中出现的问题,增加一条调试协议,仅供内部使用。

  • 00 命令:为实时调整日志等级,方便测试时改变日志输出等级。
  • 01 命令:为获取内存状态。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xDB
数据长度 2 0x0002
数据 2 Data[0]:子命令
  • 0x00:调整日志等级
  • 0x01:获取内存
Data[1]:对应子命令数据
当子命令为 0x00 日志等级时,对应:
  • 0x00:err 级别
  • 0x01:warning 级别
  • 0x02:notice 级别
  • 0x03:info 级别
  • 0x04:debug 级别
  • 0x05:trace 级别
当子命令为 0x01 获取内存时,默认值 0x00
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xDB
数据长度 2 0 / 4
数据 0 / 4 子命令为 0x00 时,无数据字段
子命令为 0x01 时,当前剩余内存大小
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

55 aa 00 db 00 02 00 03 b7,调整日志等级为 info 级别。
55 aa 00 db 00 00 b2,模组回复设置成功。

通用参数配置 0xDA(AC7916)

  • 为满足客户动态配置参数的需求,增加图像参数配置相关指令。发送该指令设置后模组会记录该配置,下次启动时将使用该配置来初始化图像相关参数。
  • 若未发送该配置,则模组会采用默认的图像参数来进行初始化。
  • 需在模组回复 PID 并完成初始化后发送(模组发送 02 指令后)。发送该指令后,模组会自动重启并用新的参数来完成初始化。
  • 该指令仅支持 AC7916 单芯片方案。此指令只能用于研发调试阶段,不能试用量产产品,参数确定后,正式生产请用产测工具写入相关参数。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xDA
数据长度 2 0x0010
数据 16 Data[0~1]:图像宽度 width
 示例:480 对应 0x01 0xE0
Data[2~3]:图像高度 height
 示例:320 对应 0x01 0x40
Data[4]:帧率
 示例:15fps 对应 0x0F
Data[5]:顺时针旋转角度
  • 0x00:0°
  • 0x01:90°
  • 0x02:180°
  • 0x03:270°
  • 0xFF:不设置
Data[6]:音频通道
  • 0x00:无
  • 0x01:1 路
  • 0x02:2 路
Data[7]:音频位深
  • 0x08:8 位
  • 0x10:16 位
Data[8~9]:音频采样率
  • 0x1F40:8000 (8K)
  • 0x3E80:16000(16K)
Data[10]:LCD 显示屏
  • 0x01:ili9488
  • 0x02:st7796
  • 0x03:st7796 反色
  • 0x04:uel035
Data[11]:是否反色
  • 0x00:否(默认)
  • 0x01:是
Data[12]:LCD 类型
  • 0x00:emi(默认)
  • 0x01:pap
Data[13]:垂直是否 UI 旋转 180
  • 0x00:否(默认)
  • 0x01:是
Data[14]:水平是否 UI 旋转 180
  • 0x00:否(默认)
  • 0x01:是
Data[15]:相机是否用断电模式
  • 0x00:否(默认)
  • 0x01:是
Data[16~N]:保留字段,必须为 0x00
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组回复

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xDA
数据长度 2 0x0001
数据 1 0x00:配置成功
0x01:配置失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组功能性产测服务

简介:适用于设备量产时整机产品测试模组功能使用,如测试 Wi-Fi 扫描指定路由能力与信号强度,以及传图/音视频类方案与猫眼硬件连通性(SPI、串口、GPIO)。历史版本上支持过两类产测指令,分别是:

  • 基础类方案 0x07 指令:仅支持测试 Wi-Fi 扫描指定路由能力与信号强度。
  • 传图/音视频类方案 0xF0 指令:支持 Wi-Fi 能力、与猫眼连通性测试,如用的是 WBRU、WBRL 等模组方案推荐使用。
  • 产测指令需要在模组上电完成初始化流程以后(回复 查询产品信息 的数据包)发送才有效,否则会导致产测失败或无结果。
  • 为了最大程度防止不良品,建议客户将路由于设备距离控制在 5 米左右,信号强度大于等于 60%为合格,这里可以根据自己产线和工厂环境的情况自行调整。

基础类方案 0x07

指定的产测路由器 SSID 固定为:tuya_mdev_test,密码:不做要求(可随意设置),要求路由器为 2.4G 信号。模组接收到 0x07 产测指令后,扫描指定 ssid 路由,返回扫描结果和信号强度百分比。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x07
数据长度 2 0x0000
数据 0
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x07
数据长度 2 0x0002
数据 2 Data[0]:表示产测结果
  • 0x00:失败
  • 0x01:成功
Data[1]:具体信息
  • 成功时:表示信号强度百分比。
      范围 0-100(0 信号最差,100 信号最强)
  • 失败时:表示失败原因。
    •  0x00:表示未扫描到指定的 ssid
    •  0x01:表示模组未烧录授权
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

音视频类方案 0xF0

功能性产测范围在基础指令的基础上支持了更多功能项,包括扫描指定 SSID、连接指令 SSID 以及与猫眼硬件连通性(如 WBRU 方案的 PA4+猫眼串口+SPI 通信测试/PA4+SPI 通信测试)。

  • 模组在收到该指令后,根据协议内容进行指定的测试
    • 模组收到 0x00 扫描指定路由器后,开始扫描指定 SSID 的路由器,并返回扫描结果。
    • 模组收到 0x01 扫描指定路由器后,开始连接指定 SSID 的路由器,并返回结果。
    • 模组收到 0x02 命令后,会通过 PA4 输出一个 250ms 高电平给猫眼,此时能看到猫眼被唤醒处于工作状态,屏幕点亮,认为 PA4 测试成功。(前提:猫眼处于一直供电的休眠状态,不受第三方测试及模组的供电影响)。
    • 当猫眼通过 02 指令被 PA4 唤醒后,模组会在 5s 内等待接收猫眼串口或 SPI 发送的 0x63 指令,收到后会通过猫眼串口或 SPI 回复 0x63 的就绪状态,未收到则认为失败。模组回复 0x63 指令后,会等待猫眼的 0x61,3s 内收到则测试成功,详细的失败返回值请参考下方的结果回复。
  • 扫描指定的 SSID,返回的数据中表示扫描结果和信号强度百分比。原则上若扫描成功,才可选择连接指定的路由器。
  • 指定的 SSID 固定为:tuya_mdev_test,密码为:test1234,要求路由器为 2.4G 信号

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xF0
数据长度 2 0x0002
数据 2 Data[0]:产测功能点
  • 0x00:扫描指定路由器
  • 0x01:连接指定路由器
  • 0x02:与猫眼硬件连通测试
Data[1]:子命令
  • 0x00:默认值
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xF0
数据长度 2 0x0002
数据 2 Data[0]:产测结果
  • 0x00:成功
  • 0x01:失败
Data[1]:具体信息,详见下文
 信号强度/失败原因/猫眼连通结果
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

具体产测步骤及结果回复:

  • 扫描指定路由器

    • Data[0] = 0x00 时表示扫描成功

      Data[1]表示扫描到的路由器信号强度百分比(0-100)

    • Data[0] = 0x01 时表示扫描失败

      Data[1] = 0x00 表示未扫描到指定 SSID

      Data[1] = 0x01 表示模组未授权

  • 连接指定路由器

    • Data[0] = 0x00 时表示连接成功

      Data[1] = 0x00 默认为 0x00

    • Data[0] = 0x01 时表示连接失败

      Data[1] = 0x00 默认为 0x00 连接超时

      Data[1] = 0x01 其他原因失败

  • 与猫眼硬件连通性测试

    • Data[0] = 0x00 时表示接收成功

      Data[1] = 0x00 表示 PA4+猫眼串口+SPI 或者 PA4+SPI 通信成功

      Data[1] = 0x01 表示猫眼串口接收或者猫眼 SPI 接收没有通信成功

    • Data[0] = 0x01 时表示接收失败

      Data[1] = 0x00 表示没有收到猫眼串口或者 SPI 发送的 0x63 数据

传图/音视频相关功能

  • 传图/音视频方案 详见对应模组方案的猫眼协议,这里仅描述 MCU 锁控使用到的相关指令。
  • 串口传图方案,MCU 锁控也会涉及串口传图-状态获取 0x63、串口传图-数据上传 0x61 指令,也请详见猫眼协议串口传图章节。
  • 该功能与 查询产品信息 0x01 指令的返回相关联,MCU 需使能 cap 能力的 bit0 位,并通过 bit1 指定传输方式是 SPI / 串口

触发抓拍命令 0x64

当有事件触发时,MCU 可通过此指令通知模组需触发抓拍,模组收到此指令后开启抓拍相关功能。

  • 抓拍事件编码,详见 附录一:抓拍事件编码表
  • 可通过子命令决定抓拍方式,支持抓图、开启实时视频。
  • 抓拍结果模组会通过 0x62 指令返回给 MCU。如结果成功,MCU 还需上传对应的记录,才能成功关联到对应图片或视频 (基于相同的时间戳关联:记录型数据上传的时间戳用 0x62 指令返回的时间戳)

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x64
数据长度 2 0x01+0x05+0x07
数据 1 子命令默认:0x00
2 抓拍事件编码,详见附录一
0x0000:防撬告警
0x0001:远程开门请求
0x0002:指纹开门试错
0x0003:密码开门试错

1 抓拍类型:
0x00:保留
0x01:抓拍图片
0x02:开启实时视频
0x03:门铃呼叫(抓图,仅 T31 方案支持)
0x04:门铃呼叫(短视频,仅 T31 方案支持)
1 保留字段,默认 0x00
1 保留字段,默认 0x00
7 记录型数据时间信息,类型+时间,共计 7 字节。
Data[0] 为上报时间类型,定义如下:
  • 0x00:用模组时间,其 Data[1~6]无效。不推荐
  • 0x01:用 MCU 传的本地时间 Data[1~6]
  • 0x02:用 MCU 传的格林时间 Data[1~6]
Data[1] 为年,0x00 表示 2000 年
Data[2] 为月,从 1 开始到 12 结束
Data[3] 为日,从 1 开始到 31 结束
Data[4] 为时,从 0 开始到 23 结束
Data[5] 为分,从 0 开始到 59 结束
Data[6] 为秒,从 0 开始到 59 结束
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组回复

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x64
数据长度 2 0x0001
数据 1 表示接收处理结果
0x00:信息接收成功,启动抓拍
其他:失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

55 AA 00 64 00 0D 00 00 01 02 00 00 02 YY MM DD HH MM SS 64
55 AA 00 64 00 01 00 64

抓拍结果通知 0x62

模组接收到 64 指令开启抓拍后,对应的触发抓拍或视频推流相关结果将通过 0x62 指令通知 MCU。

  • 当触发类型为图片时,通知结果为 0 代表图片上传成功。
    MCU 上报事件记录的时候需要将模组返回时间做为记录型数据时间数据。
  • 当触发类型为视频时,通知结果为 0 代表视频流建立连接。
    通知结果为视频流播放结束时,数据中所带时间信息无效,此时 MCU 需自行判断当前触发类型,并做超时断电处理。

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x62
数据长度 2 0x0009
数据 2 其他方案:返回图片 ID 号,唯一归属标识。
可视方案:返回抓拍事件类型编码
6 当前图片上传的时间:
Data[0]为年,0x00 表示 2000 年
Data[1]为月,从 1 开始到 12 结束
Data[2]为日,从 1 开始到 31 结束
Data[3]为时,从 0 开始到 23 结束
Data[4]为分,从 0 开始到 59 结束
Data[5]为秒,从 0 开始到 59 结束
1 结果返回:失败时,时间数据无效
  • 0x00:图片上传成功 / 开始推流
  • 0x01:网络异常
  • 0x02:大小超出限制
  • 0x03:抓拍超时
  • 0x04:其它原因失败
  • 0x05:推流结束
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

MCU 回复

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x62
数据长度 2 0x0001
数据 1 0x00:无后续图片上传
非 0:还有图片上传
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

获取推流状态 0x6B

在主动查看视频阶段,当前模组不会主动唤醒锁板并同步状态。对于一些特殊应用场景上,可能会出现逻辑上的冲突。例如,锁板雷达被触发,是打开人脸模组红外准备人脸识别,导致看到红色视频流。

为解决锁板需获取特定状态来做逻辑判定问题,您可以使用下述协议获取模组当前状态,包括联网状态、绑定状态、推流状态、其他待扩展。

锁控有需要获取推流状态的请对接该指令。

模组的回复数据长度为不定长度的 N。MCU 在解析该数据,务必请按照数据长度来解析当前协议定义的 Data,而非限制数据长度,防止不同模组协议长度不同带来的兼容性问题。如此,后续模组回复状态就可扩展,同时也不影响已对接 MCU 解析。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x6B
数据长度 2 0x0004
数据 4 Data[0-3]:预留待扩展,默认 0x00
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组回复

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x6B
数据长度 2 N
数据 N Data[0]:详见 设备联网状态表
Data[1]:表示模组配网激活状态
  • 0x00:未配网
  • 0x01:已配网
Data[2]:表示是否处于主动查看视频状态
  • 0x00:未处于
  • 0x01:正处于
Data[3~N-1]:预留待扩展
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

单芯片解决方案相关功能

适用于涂鸦推出的单芯片一体化 Wi-Fi 门锁解决方案,核心板集成了音视频功能,支持的模组包含:BK7252、AC7916

通用参数配置 0x65(BK7252)

  • 为满足客户动态配置参数的需求,增加图像参数配置相关指令。发送该指令,可修改图像相关的分辨率、图像质量、视频帧率、及是否动态开启红外夜视功能。模组会记录该配置,下次启动时将使用该配置来初始化图像相关相关参数。
  • 若未发送该配置,则模组会采用默认的图像参数来进行初始化。
  • 需在模组回复 PID 并完成初始化后发送(模组发送 02 指令后)。发送该指令后,模组会自动重启并用新的参数来完成初始化。
  • 若选择开启光敏检测,建议值为 500,根据实际情况选择。
  • 若选择开启自动补光,建议值为 475,根据实际情况选择。
  • 该指令仅支持 BK7252 单芯片方案。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x000A
数据 1 Data[0]:图像分辨率
  • 0x00:320 * 240
  • 0x01:640 * 480
  • 0x02:1280*720(需硬件支持)
Data[1]:图像压缩比,支持 25 / 50
Data[2]:视频帧率,支持 12 / 15 / 20 帧
Data[3~4]:光敏检测,占 2 字节
  • 0:关闭
  • 1-4095:光敏检测阈值
Data[5~6]:自动补光,占 2 字节
  • 0:关闭
  • 0-999:输出占空比
Data[7]:黑白模式切换,0-关闭,1-开启
Data[8]:回音消除 AEC,0-关闭,1-开启
Data[9]:回音消除调优参数(与结构关联)
  • 默认值:0x0A(建议设置)
  • 设置范围:0x05~0x20
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组回复

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x65
数据长度 2 0x0001
数据 1 0x00:配置成功
0x01:配置失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

本地拉流 0xD2(AC7916)

用于锁控 MCU 控制猫眼设备(如 AC7916 一体化方案)本地拉流,打开镜头并点亮屏幕显示视频流。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xD2
数据长度 2 0x0001
数据 1 0x00:关闭本地拉流
0x01:开启本地拉流
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xD2
数据长度 2 0x0001
数据 1 0x00:操作成功
0x01:操作失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

双模蓝牙相关功能

适用于 Wi-Fi & 低功耗蓝牙 Combo 模组方案,模组常供电且低功耗蓝牙通信能力开启。如涂鸦推出的 Wi-Fi 门禁方案,其他方案可无需对接该功能。

设备蓝牙状态 描述 对应状态值
状态 1 未绑定,未连接(蓝牙配网阶段产生) 0x00
状态 2 未绑定,已连接(蓝牙配网阶段产生) 0x01
状态 3 已绑定,未连接 0x02
状态 4 已绑定,已连接 0x03
状态 5 未知状态 0x04

报告蓝牙连接状态 0x3504

模组发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x35
数据长度 2 0x0002
数据 2 Data[0]:子命令 0x04
Data[1]:蓝牙状态
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

MCU 返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x35
数据长度 2 0x0001
数据 1 Data[0]:子命令 0x04
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

55 aa 00 35 00 02 04 03 3d,模组同步蓝牙连接状态 03-绑定已连接给 MCU。
55 aa 03 35 00 01 04 3c,MCU 回复接收成功。

获取蓝牙连接状态 0x3505

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x35
数据长度 1 0x0001
数据 1 Data[0]:子命令 0x05
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x35
数据长度 2 0x0002
数据 2 Data[0]:子命令 0x05
Data[1]:蓝牙状态
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

55 aa 03 35 00 01 05 3D,MCU 主动查询当前蓝牙连接状态。
55 aa 00 35 00 02 05 03 3E,模组返回当前蓝牙连接状态 03-绑定已连接。

关闭蓝牙通信功能 0x3506

使用该指令关闭蓝牙功能后,在不断电情况下,模组蓝牙功能不能被主动打开。

模组重启或断电后,关闭蓝牙仍然需要使用该指令,也就是单次有效。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x35
数据长度 2 0x0002
数据 2 Data[0]:子命令 0x06
Data[1]:关闭蓝牙通信功能(重启失效),0x00
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x35
数据长度 2 0x0002
数据 2 Data[0]:子命令 0x06
Data[1]:0-关闭成功,1-关闭失败
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

55 aa 03 35 00 02 06 00 3F,MCU 发送关闭蓝牙功能。
55 aa 00 35 00 02 06 00 3C,模组回复操作成功。

低功耗蓝牙+X 相关功能

背景与方案价值

  • 对于单点蓝牙门锁设备而言,无需额外单独购买网关,可以无缝支持 Wi-Fi 音视频和可视对讲功能。
  • 对工厂客户/方案商而言,只需对接一种方案即可同时具备两种通信能力产品(低功耗蓝牙+Wi-Fi),对接效率提高,且产品本身的竞争力同样获得提升。
  • 对消费者而言,配网过程和使用体验更加的友好,消费者无需额外购买网关,既可以体验到门锁远程功能。
  • 对涂鸦自身而言,支持多模联网方案,一是能满足用户实际的场景需求,二是方案本身具有灵活扩展的优势,可拓展更多场景。
  • 低功耗蓝牙+Wi-Fi 方案非常适用于家庭场景,本地可以通过低功耗蓝牙对门锁进行设置,蓝牙断开的情况下可以通过 Wi-Fi 链路实时掌握门锁状态。

相关流程图

MCU 通用对接协议

  • 该功能与 查询产品信息 0x01 指令的返回相关联,MCU 需使能 cap 能力的 bit6=1
  • 目前仅 WBRU 模组支持该方案,固件版本需 v1.4.0 及以上。

查询模组信息 0xD000

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0xD0
数据长度 2 0x0001
数据 1 Data[0]:子命令 0x00
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xD0
数据长度 2 N
数据 N Data[0]:子命令 0x00
Data[1]:表示查询结果
  • 0x00:获取成功
  • 其他:获取失败,无后续数据
Data[2]:模组绑定状态,0-未绑定,1-绑定
Data[3]:X 模组的类型,目前仅支持 2 和 3
  • 0x01:NB-IoT 模组
  • 0x02:Wi-Fi 模组
  • 0x03:LTE Cat.1 模组
  • 0x04:Zigbee 模组
  • 0x05:低功耗蓝牙模组
Data[4~n]:模组唯一标识
  • 当类型为 Wi-Fi 模组:6 字节的 MAC 地址。
  • 当类型为 Cat.1 模组:15 字节的 IMEI。
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

授权信息同步 0xD001

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0xD0
数据长度 2 N
数据 N Data[0]:子命令 0x01
Data[1]:加密算法
  • 0x00:AES128-CBC
  • 0x01:AES128-CCM
  • 0x02:其他扩展
Data[2~17]:随机数
Data[18~n]:授权加密信息-密文
  • 加密方式:AES, 具体算法由 Data[1]决定
  • key:共享秘钥前 16 字节
  • iv:全 0x00
  • Padding 规则:补齐非 16 整数倍相差的字节,
     缺 n 个字节就用 n 来填充
解密后为授权信息的 json 字符串,格式如下:
{
“uuid”:“xxxxxxx”, // uuid len 16 位
“auth_key”:“xxxxxxx”, // auth_key len 32 位
“psk_key”:“” // psk_key 预留
}
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xD0
数据长度 2 0x0023
数据 35 Data[0]:子命令 0x01
Data[1]:表示信息接收结果
  • 0x00:信息获取成功
  • 其他:获取失败,无后续数据
Data[2]:加密算法
  • 0x00:AES128-CBC
  • 0x01:AES128-CCM
  • 0x02:其他扩展
Data[3~34]:对 16 字节随机数做 hash 运算结果
  • hash 算法:hmac_sha256
  • key:用共享秘钥
  • key_len:32 字节
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

激活信息同步 0xD002

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0xD0
数据长度 2 N
数据 N Data[0]:子命令 0x02
Data[1~n]:激活信息-密文
  • 加密方式:AES 加密, 具体算法由加密方式决定
  • key:共享秘钥前 16 字节
  • iv:全 0x00
  • Padding 规则:补齐非 16 整数倍相差的字节,
     缺 n 个字节就用 n 来填充
解密后为激活信息的 json 字符串,格式如下:
{
devId : xxxx ,
localKey : xxxx ,
secKey : xxxx ,
env : xxxx ,
region :"xxxx,
“ssid”:“xxxx”,
“pwd”:“xxxx”
}
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xD0
数据长度 2 0x0002
数据 2 Data[0]:子命令 0x02
Data[1]:表示信息接收结果
  • 0x00:收到激活信息,正在激活中
  • 0x01:激活失败
  • 0x02:找不对对应 SSID 的路由
  • 0x03:路由器密码错误
  • 0x04:连接不上路由
  • 0x05:DHCP 错误
  • 其他:其他错误码
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

共享秘钥协商 0xD003

  • 采用 ECDH 算法来协商秘钥,协商运算后秘钥为 32 字节,后续简称 共享秘钥
  • 椭圆曲线使用:secp256r1
  • 协商双方各自生成公私秘钥对,通过该协议交换各自的公钥后,调用共享秘钥算法(自己的私钥 + 对端的公钥)计算出共享秘钥。

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xD0
数据长度 2 0x0042
数据 66 Data[0]:子命令 0x03
Data[1]:椭圆曲线
  • 0x01:secp192r1
  • 0x02:secp224r1
  • 0x03:secp256r1
  • 0x04:secp256k1
Data[2~65]:Public Key,MCU 生成的公钥
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xD0
数据长度 2 0x0042
数据 66 Data[0]:子命令 0x03
Data[1]:椭圆曲线
  • 0x01:secp192r1
  • 0x02:secp224r1
  • 0x03:secp256r1
  • 0x04:secp256k1
Data[2~65]:Public Key,模组生成的公钥
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

示例

数据中转功能(锁板-模组-猫眼)

  • 支持 MCU 查询模组信息,用于管控区分不同模组方案。
  • 支持缓存-透传锁控信息给猫眼,用于展示(例如电量信息、固件版本等)。
  • 支持缓存-透传猫眼信息给锁控,用于管控区分不同猫眼方案。
  • 仅部分方案支持该指令,WBRU 模组方案、可视对讲方案

锁控查询模组信息 0xD100

MCU 发送

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xD1
数据长度 2 0x0001
数据 1 Data[0]:子命令 0x00
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

模组返回

字段 字节数 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0xD1
数据长度 2 N
数据 N Data[0]:子命令 0x00
Data[1]:流媒体方案类型
  • 0x01:抓图
  • 0x02:推流
  • 0x03:p2p
Data[2]:硬件方案类型
  • 0x01:WBRU
  • 0x02:WBRL
  • 0x03:BK7252
  • 0x04:AC7916
  • 0x05:T31+7682
  • 0x06:T31+8720cs
  • 其他:待扩展
Data[3~n]:硬件版本信息
 格式:长度 + 硬件版本字符串
Data[n+1~m]:固件版本信息,支持多通道组合
 格式:通道号 + 长度 + 固件版本字符串
校验和 1 从帧头开始,按字节求和,得出的结果对 256 求余

附录一:抓拍事件编码表

抓怕事件类型 对应事件编码值
防撬告警 0x0000
远程开门请求 0x0001
指纹开门试错 0x0002
密码开门试错 0x0003
卡片开门试错 0x0004
人脸开门试错 0x0005
掌纹开门试错 0x0006
指静脉开门试错 0x0007
指纹开锁 0x0008
密码开锁 0x0009
卡片开锁 0x000A
人脸开锁 0x000B
掌纹开锁 0x000C
指静脉开锁 0x000D
临时密码解锁 0x000E
动态密码解锁 0x000F
远程解锁 0x0010
离线密码解锁上报 0x0011
门铃请求上报 0x0012
劫持警告 0x0013
低电报警 0x0014
钥匙插入报警 0x0015
高温报警 0x0016
门铃 + 远程开门 0x0017
有人停留/逗留告警 0x0018
门锁被破坏 0x0019
特殊指纹开锁 0x001A
布防模式下开锁 0x001B

附录二:时效性

字节 含义 说明 举例
1 时效起始时间 unsigned int
4 字节(大端)
例如 unix 时间为:
123-456-789 = 0x075BCD15
若时效为永久有效,则起始时间为 0x386CD300
07
2 5B
3 CD
4 15
5 时效结束时间 unsigned int
4 字节(大端)
例如 unix 时间为:
999-999-999 = 0x3B9AC9FF
若时效为永久有效,则结束时间为 0x72BC9B7F
3B
6 9A
7 C9
8 FF
9 时效循环方式 0x00:不循环 0x01:天循环 0x02:周循环 0x03:月循环
10 循环标志位 1 不循环时 10~17
字节全部为 0
该字节
默认为 0x00
该字节
默认为 0x00
bit7:默认为 0
bit6:31 号
……
bit0:25 号
11 循环标志位 2 该字节
默认为 0x00
该字节
默认为 0x00
bit7:24 号
……
bit0:17 号
12 循环标志位 3 该字节
默认为 0x00
该字节
默认为 0x00
bit7:16 号
……
bit0:9 号
13 循环标志位 4 该字节
默认为 0x00
bit7:默认为 0
bit6:周六
……
bit1:周一
bit0:周日
bit7:8 号
……
bit0:1 号
14 一天中起始时间 1(小时数) 起始时间:8:30 08(十进制)
15 一天中起始时间 2(分钟数) 30(十进制)
16 一天中结束时间 1(小时数) 结束时间:20:30 20(十进制)
17 一天中结束时间 2(分钟数) 30(十进制)

添加/修改开锁方式时,时效性的循环方式和次数同时生效,但是一般仅使用以下两种情况:

  • 次数为 0x00,此时次数为永久有效,可仅处理时效的循环方式。
  • 时效的循环方式为 0x00,此时为不循环,可仅处理次数。

示例:设置2018-01-26 08:00:002018-08-08 09:56:32期间内,每周一至周五的早上 8:00 到 8:30 生效,则时效性为 5A 6A 6F 80 5B 6A 4D D0 02 00 00 00 3E 08 00 08 1E

  • 2018-01-26 08:00:00转换为 unix 时间为1516924800,即 0x5A6A6F80
  • 2018-08-08 09:56:32转换为 unix 时间为1533693392,即 0x5B6A4DD0
  • 时效的循环方式为:0x02-周循环
  • 循环天标志位 1 = 循环天标志位 2 = 循环天标志位 3 = 0x00
  • 循环天标志位 4 = 0x3E(周一至周五)
  • 一天中的起始时间 1 = 0x08,一天中的起始时间 2 = 0x00
  • 一天中的结束时间 1 = 0x08,一天中的结束时间 2 = 0x1E

周编码规则
bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0
保留 周六 周五 周四 周三 周二 周一 周日

协议修订记录

下表记录了 Wi-Fi 门锁设备的 MCU 对接协议相关修订说明。

版本 编写/修订说明 修订日期 备注
1.0.0 协议首版 2018.09.15 新增
1.0.1 增加支持多组临时密码的请求接口 2018.10.19 修改
1.0.2 1. 增加支持:多组临时密码接口返回面板 0 组密码时,增加返回字段
2. 增加组合开门方式的相关说明
2018.12.17 修改
1.0.3 增加获取 DP 缓存命令 2019.07.10 修改
1.0.4 在报告设备联网状态中增加低功耗状态 2019.07.13 修改
1.0.5 1. 增加离线动态密码
2. 增加上报 MCU SN 号
2019.09.09 修改
1.0.6 增加周期性临时密码(带 schedule 列表) 2019.10.10 修改
1.0.7 1.增加快速上报指令
2.增加快连和热点共存配网状态
3.查询产品信息增加配网方式字段
4.增加拍照锁相关功能
5.产品信息增加 cap 字段
6.增加模组重置状态通知
7.增加图片上传状态获取
2020.07.09 修改
1.0.8 增加支持运营商上报功能 20200713 修改
1.0.9 扩展图片上传相关的命令字适配单芯片拍照模组 20200721 修改
1.0.10 增加主动获取 Wi-Fi 状态、获取 unix 时间戳的协议 20200730 修改
1.0.11 1.修改图片上传逻辑,在收到模组回复的网络状态包时触发图片上传,
而非仅收到状态包为 0x04 时。
2.修改图片时间的关联逻辑,改为由模组关联,MCU 传图和事件上报
同一时间
20200912 修改
1.0.12 增加修改 debug 等级的调试命令 0xDB 20201014 修改
1.0.13 1.增加密码进制设置协议
2.新增新动态密码协议、多组云端临时密码协议
20210106 修改
1.0.14 0x64 中增加短视频及实时视频相关命令,修改抓拍类型的字段 20210125 修改
1.0.15 增加 SPI 产测相关指令 0xF0 20210224 修改
1.0.16 1.增加 0x65、0x66 两条配置图像参数的命令
2.取消快速上报类协议
20210226 修改
1.0.17 1.修改 64 命令中触发类型,取消短视频类型
2.增加 62 状态返回中停止推流的通知
20210327 修改
1.0.18 附录 1 增加 4 条状态 20210408 修改
1.0.19 1.废弃部分协议
2.状态数据单元变更为附录 3
3.新增模组拓展服务、蓝牙相关服务
20220518 修改
2.0.0 对各 Wi-Fi 门锁方案协议进行整合统一 2023.03.08 新版
2.0.1 1. 核对系列方案支持的指令集,文档细节优化
2. 删除 0x66 指令
2023.05.26 修改
2.0.2 1. 报告设备联网状态 0x02 指令增加新状态 10
2. 0x84 指令 增加图文使用描述
3. 0xDA 指令扩展新支持参数
4. 新增 0x6B 命令,用于 MCU 获取推流状态
2023.9.18 修改
2.0.3 1. 新增 0xD3 命令,用于 MCU 设置休眠相关参数
2. 0x1D 指令,返回的密码状态增加 02-删除
2023.10.26 修改
2.0.4 1. 0x1B 指令,Data[6] 扩展时区描述,支持半时区
2. 0x1D 指令,优化描述以及 MCU 的使用方法
3. 0x84 指令,仅保留触发模组进入配网模式的值定义
2024.03.14 修改