门锁服务

门锁类蓝牙单点通用模组可以提供接入涂鸦门锁技术的服务，以便支持涂鸦公版门锁相关的部分功能。

简介

适用场景

适用于使用涂鸦公版门锁技术方案的产品。

功能列表

门锁类蓝牙单点通用模组提供以下协议指令：

命令字	命令说明
0xA7	提供动态密码校验功能
0xA2	提供离线密码校验功能
0xA6	提供门锁业务功能配置
0xA8	涂鸦公版门锁方案中的 靠近解锁 相关的指令

门锁相关协议

动态密码校验（CMD-0xA7）

• 模组计算动态密码基于时间，必须确保云端和设备时间同步，以便保证计算的动态密码一致。连接建立时，设备与 App 会自动同步时间。
• 协议中的时间数据用于计算当前的动态密码，动态密码的计算需要以当前的格林时间为准。设备需要提供相应的格林时间数据给模组。

MCU 发送

序号	字节数	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xA7
4 5	2	数据长度 Len	Len 高 8 位 Len 低 8 位
6~6+Len-1	Len	Data	见下表
6+Len	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

1 字节	1 字节	1 字节	1 字节	1 字节	1 字节	1 字节	1 字节	N 字节
TimeSource	2000+Year	Mon	Day	Hour	Min	Sec	Code_len	Code

• TimeSource：填写 0x00 即可。

  • 0x00：时间来源于 MCU 上传的 year/mon/day/hour/min/sec 字段。

  • 0x01：使用模组内部时间，year/mon/day/hour/min/sec 不解析。

    MCU 上传时间说明：MCU 传的时间应是格林时间的年月日格式，即 0 时区的年月日时间。例如北京时间 2020 年 6 月 20 日 12 时 00 分 00 秒，格林时间填 0x14 0x06 0x14 0x04 0x00 0x00。

• Code_len：密码长度。

• Code：密码。区别于旧动态密码 CMD-0xE6 中密码传 ASCII 码 1~9 的十进制格式，新动态密码直接传数字，1 即 0x01，9 即 0x09。可参考以下示例。

示例：

55 AA 00 A7 00 10 00 14 0A 09 0D 33 2C 08 01 08 05 08 06 04 04 05 7A

模组回复

序号	字节数	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xA7
4 5	2	数据长度 Len	Len 高 8 位 Len 低 8 位
6~6+Len-1	Len	State	返回的状态值
6+Len	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明：

• 0x00：密码核对通过
• 0x01：密码核对失败

示例：

• 55 AA 00 A7 00 01 01 A8：密码核对失败
• 55 AA 00 A7 00 01 00 A7：密码核对通过

离线密码（CMD-0xA2）

• 离线密码是指设备长时间不联网也可使用的动态密码。
• 模组内部时钟精度不高，24 小时低于 1min，模组在每次上线时会同步一次云端时间，模组内部时钟不支持掉电工作，即掉电会重置。
  如果 MCU 有外接时钟，强烈建议时钟源选择 0x00，即 MCU 上传格林时间。使用模组内部时钟，可联系研发要测试程序，测量时钟误差。

MCU 发送

序号	字节数	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xA2
4 5	2	数据长度 Len	Len 高 8 位 Len 低 8 位
6~6+Len-1	Len	Data	见下表
6+Len	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

1 字节	1 字节	1 字节	1 字节	1 字节	1 字节	1 字节	1 字节	N 字节
TimeSource	2000+Year	Mon	Day	Hour	Min	Sec	Code_len	Code

• TimeSource：填 0x00 即可。

  • 0x00 时间来源于 MCU 上传的 year/mon/day/hour/min/sec 字段。

  • 0x01 使用模组内部时间，year/mon/day/hour/min/sec 不解析。

    MCU 上传时间说明：MCU 传的时间应是格林时间的年月日格式，即 0 时区的年月日时间。如北京时间 2020 年 6 月 20 日 12 时 00 分 00 秒，格林时间填 0x14 0x06 0x14 0x04 0x00 0x00。

• Code_len：密码长度。

• Code：密码。区别于动态密码中密码传 ASCII 码 1~9 的十进制格式，离线密码直接传数字，1 即 0x01，9 即 0x09。可参考以下示例。

模组回复

序号	字节数	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xA2
4 5	2	数据长度 Len	Len 高 8 位 Len 低 8 位
6~6+Len-1	Len	Data	见下表
6+Len	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

1 字节	1 字节	1 字节	N 字节
Result	Type	Decode_len	Decode

• Result：

  • 0x00：正确
  • 其他：错误（后续数据无意义）

• Type：

  • 0x00：验证成功
  • 0x01：清空单条成功
  • 0x02：清空所有成功

• Code_len：加密后的数据长度

• code：加密后的清空码和开锁密码

  Type 和 code 用于 MCU DP 上报使用，参照门锁 DP 协议离线密码功能解析，dpid 为 65、66、67。

例如：使用模组内部时间+密码（2279084005）

• MCU：55 AA 00 A2 00 12 01 00 00 00 00 00 00 0A 02 02 07 09 00 08 04 00 00 05 E3
• 模组：55 AA 00 A2 00 13 00 00 10 F3 50 3C 8F FF 03 F5 E9 0D 54 99 2A 62 A1 DE 42 F9

门锁业务功能配置（CMD-0xA6）

• 适用模组：
  • TYBN1 门锁通用固件 6.2 以上版本支持
  • BK3431Q 门锁通用固件 3.3 以上版本支持
• 一些门锁功能需要模组封装处理 DP 部分字段，为了不影响使用这些功能，将对这部分功能设置开关，且默认关闭。该设置永久存储。
• 目前，需要通过该接口配置的功能有：
  • 门锁端配件功能
  • 配件端开关锁功能
  • 门锁密码进制配置

MCU 发送

序号	字节数	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xA6
4 5	2	数据长度	0x00 0x04
6~9	4	DATA	见下表
10	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

CFG 格式：

配置项 0	配置项 1	配置项 2	配置项 3
1	2	3	4
FLAG	PWD_NUM	PWD_BEGIN_NUM	保留(0x00)

• FLAG：

  • bit0：门锁端配件功能使能（0 关，1 开，默认关闭）

  • bit1：配件端开关锁功能使能（0 关，1 开，默认关闭）

    bit0 和 bit1 互斥，即打开一个后，另外一个则自动变成关闭。

  • bit2 到 bit7：保留

• PWD_NUM：表示组成门锁密码的数字个数，默认 10 个（数字 0~数字 9）。部分密码盘上只有 4~9 个连续数字的情况，可以通过该字段进行配置。另外可通过 PWD_BEGIN_NUM 配置密码从数字 0 开始还是从数字 1 开始。

  PWD_NUM 字段只有填 0x04~0x09 才会生效，其余数字均使用默认设置（10 个数字）。

• PWD_BEGIN_NUM：表示密码盘上最小的数字，从数字 0 开始还是从数字 1 开始。如果密码盘从数字 0 开始，则填 0x00。如果从数字 1 开始，则填 0x01。

  PWD_BEGIN_NUM 字段只有填 0x00 或 0x01 才会生效，其余数字均使用默认设置（从数字 0 开始）。

示例：

• 55 AA 00 A6 00 04 01 00 00 00 AA：打开门锁配件功能
• 55 AA 00 A6 00 04 00 00 00 00 A9：关闭门锁配件功能

模组回复

序号	字节数	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xA6
4 5	2	数据长度	0x00 0x01
6	1	State	返回的状态值
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明：

• 0x00：设置成功
• 其他：设置失败

iBeacon 配置接口（CMD-0xA8）

• 适用固件：门锁类通用固件。
• 从设备角度看，支持防丢功能或靠近解锁功能，就是在一段时间内进行特定的广播，广播内容符合 iBeacon 数据结构。手机搜索到 iBeacon 后进行一些操作。
• 防丢功能和靠近解锁功能的业务依赖相关功能的 DP 以及 App。
• 模组不记忆防丢 iBeacon 的配置，重启不会继续之前的动作。模组会记忆靠近解锁 iBeacon 的配置到 Flash，重启后会继续之前的动作。
• 解绑或重置设备后，会重置 iBeacon 配置。

MCU 发送

序号	长度（byte）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xA8
4 5	2	数据长度	0x00 0x06
6~11	6	CFG	见下表
12	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

CFG 格式：

1 字节	1 字节	2 字节	2 字节
1	2	3~4	4~5
operation	config_type	ibeacon_interval	timeout

• operation：

  • 0x00：关闭防丢 iBeacon
  • 0x01：打开防丢 iBeacon
  • 0x02：关闭靠近解锁 iBeacon
  • 0x03：打开靠近解锁 iBeacon

• config_type：

  • 0x00：使用默认配置，ibeacon_interval 和 timeout 字段填 0x00 即可，模组不做解析。
  • 0x01：使用自定义配置，见 ibeacon_interval 和 timeout 字段。

• ibeacon_interval：低功耗下的 iBeacon 广播间隔，单位 100ms，实际广播间隔为 ibeacon_interval × 100ms，可设置范围 100ms~2s。非低功耗固定为 100ms。

  开启 iBeacon 后的广播间隔补充说明：

  • 非低功耗状态下，广播间隔为 100ms。
  • 低功耗状态下，若使用默认配置，广播间隔为 500ms。该广播间隔与 CMD-0xE2 设置的广播间隔互相独立。打开 iBeacon 的时候，低功耗状态以 ibeacon_interval 设置的间隔进行广播。
  • 防丢功能打开，以 ibeacon_interval 间隔广播 iBeacon 内容。
  • 靠近解锁功能打开，以 ibeacon_interval 间隔交替广播 iBeacon 广播和涂鸦标准广播内容。每个广播切换间隔（1s）会进行涂鸦标准广播和 iBeacon 广播的广播内容切换，广播切换间隔不可配置，所以 ibeacon_interval 应小于 1s。

• timeout：iBeacon 超时关闭时间，单位 5s，即 5 × timeout 秒后超时。可设置范围 5s~2min，仅作用于防丢功能。靠近解锁功能没有超时时间，需要通过配置关闭。

示例：

• 防丢 iBeacon：55 AA 00 A8 00 06 01 00 00 00 00 00 AE
• 靠近解锁 iBeacon：55 AA 00 A8 00 06 03 00 00 00 00 00 B0

模组回复

序号	长度（byte）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xA8
4 5	2	数据长度	0x00 0x01
6	1	State	返回的状态值
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明：

• 0x00：设置成功
• 其他：设置失败

常见问题

Q：门锁业务功能配置接口（CMD-0xA6）有何作用？何时需配置？

A：用于配置模组端业务功能逻辑的开关（主要是设计到 DP 的业务）。目前有三个业务逻辑的封装：

• 门锁端配件功能。
• 配件端开关锁功能。（这两个功能都是服务于门锁蓝牙配件的，一个是用于门锁，一个是用于配件。）
• 多位密码配置。

如果门锁用不到配件，可以不配置，默认是全关闭的。如果有配件需求，在 MCU 串口初始化后，发送一次进行配置即可，该配置永久存储。

Q：非十进制密码盘怎么办？多位密码功能如何配置？

• PWD_NUM：表示组成门锁密码的数字个数，默认 10 个（数字 0~数字 9）。部分密码盘上只有 4~9 个连续数字的情况，可以通过该字段进行配置。另外可通过 PWD_BEGIN_NUM 配置密码从数字 0 开始还是从数字 1 开始。

  PWD_NUM 字段只有填 0x04~0x09 才会生效，其余数字均使用默认设置（10 个数字）。

• PWD_BEGIN_NUM：表示密码盘上最小的数字，从数字 0 开始还是从数字 1 开始。如果密码盘从数字 0 开始，则填 0x00。如果从数字 1 开始，则填 0x01。

  PWD_BEGIN_NUM 字段只有填 0x00 或 0x01 才会生效，其余数字均使用默认设置（从数字 0 开始）。

配置示例

• 示例 1：密码盘上只有数字 1、2、3、4、5、6，则 PWD_NUM 设置为 6，PWD_BEGIN_NUM 设置为 1。

• 示例 2：密码盘上只有数字 0、1、2、3、4、5、6，7、8，则 PWD_NUM 设置为 9，PWD_BEGIN_NUM 设置为 0。

Q：门锁端配件功能如何对接？

A：门锁配件功能涉及 4 个 门锁新增的 DP，以及一个通用串口协议接口 CMD 0xA6（门锁业务功能配置）。门锁和配件之间的配对、重连这些其实已经被封装在门锁通用固件中了，这部分无需关心。

为了提高安全等级，确保配件出现后门锁端的相对安全，在业务层进行了身份的二次确认，过程如下：

1. 云端为主机（App/配件）分配 主机 ID+主机随机数，用于唯一识别主机。
   云端为从机（门锁）分配 从机 ID+从机随机数，用于唯一识别从机。

2. 云端首先将 App 的 主机 ID+主机随机数 和门锁的 从机 ID 发送给门锁，此时认为 App 和门锁完成了业务配对。
   然后将配件的 主机 ID+主机随机数 发送给门锁，将配件的 主机 ID+主机随机数 和门锁的 从机 ID 发送给配件，此时认为配件和门锁完成了业务配对。

3. 此时，门锁端存储着：
   App 的 主机 ID+主机随机数
   配件的 主机 ID+主机随机数（一个/多个）
   门锁的 从机 ID

   配件端存储着：
   配件的 主机 ID+主机随机数
   门锁的 从机 ID

此时，配件能够对门锁做的操作只有 开锁，且配件在做这一操作之前，需要告诉门锁自己的身份（配件的 主机 ID+主机随机数）和门锁的身份（门锁的 从机 ID），以此保证通信的安全。

以上逻辑门锁通用固件对其进行了封装。但是该逻辑需要对 DP 内容进行抓取、解析，因此属于业务逻辑，且通用固件原则上是不处理 DP 内容，只进行透传。所以，门锁通用固件为了保持通用性，对该逻辑默认进行了关闭处理。如果您需要对接和使用该功能，通过 CMD 0xA6 接口对该功能进行配置打开，模组才会对其处理（模组只是抓取内容和解析主机 ID、从机 ID、随机数，并不会改变数据内容）。

否则，模组将直接对数据进行透传处理，由 MCU 完成相关逻辑。

配件身份验证逻辑封装

通过 CMD 0xA6（55 AA 00 A6 00 04 01 00 00 00 AA）打开门锁配件功能后，模组将会完全处理 dpid=70 配置主机随机数，不会透传给 MCU。

而对于 dpid=71 开关锁 和 dpid=73 远程开锁配置，模组会抓取 DP 内容中的主机 ID、从机 ID、随机数字段进行身份验证：

• 如果身份验证成功，模组将 DP 数据完全透传给 MCU，MCU 需要对 开关锁 和 远程开锁配置 除了主机 ID、从机 ID、随机数部分的门锁业务逻辑进行处理。
• 如果身份验证失败，模组将不会透传给 MCU，而是直接回复失败信息。

MCU 端 DP 处理

开启模组门锁配件业务能力后，模组只是根据主机 ID、从机 ID、随机数来对配件进行身份验证，进而决定是否透传给 MCU 处理。MCU 收到后虽然不需要对主机 ID、从机 ID、随机数这几个字段做逻辑判断和处理，但需要根据协议对字段调整位置，例如 dpid=71：

功能	数据 方向	dp_id （1 字节）	dp_type （1 字节）	dp_da ta_len （1 字节）	dp_data_value
开 关 锁	下发	71	raw	len	主机 ID （2 字节）	从机 ID （2 字节）	随机数 （8 字节）	操作 （1 字节）	开关锁 时间戳 （4 字节）	开关锁 方式 （1 字节）	开关锁 信息 （len-12 字节）
					0~10000	0~10000	主机随机数	0x00：关锁 0x01：开锁	说明	说明	说明
	上报	71	raw	len	从机 ID （2 字节）	主机 ID （2 字节）	随机数 （8 字节）	操作 （1 字节）	开关锁 时间戳 （4 字节）	开关锁 方式 （1 字节）	返回状态 （1 字节）
					0~10000	0~10000	主机随机数	0x00：关锁 0x01：开锁	说明	说明	取值范围

MCU 需要注意主机 ID 和从机 ID 的位置需要对调了：

• 模组 -> MCU：55 AA 00 06 00 17 47 00 00 13 00 02 00 01 39 38 36 35 33 36 33 39 01 01 E4 6D 11 5F 00 ED
• MCU -> 模组：55 AA 00 07 00 17 47 00 00 13 00 01 00 02 39 38 36 35 33 36 33 39 01 01 E4 6D 11 5F 00 EE

其他 dpid=73 也是一样处理。

MCU 在收到 dpid=71 开关锁 DP 后，需要记录下主机 ID、从机 ID、随机数，然后在开/关锁成功后通过 开关锁记录 上报下开关锁记录，其中主机 ID、从机 ID、随机数来源之前 dpid-71 记录的。

功能	数据 方向	dp_id （1 字节）	dp_type （1 字节）	dp_da ta_len （1 字节）	dp_data_value
开 关 锁 记 录	上报	72	raw	len	从机 ID （2 字节）	主机 ID （2 字节）	随机数 （8 字节）	操作 （1 字节）	开关锁 时间戳 （4 字节）	开关锁 方式 （1 字节）	开关锁 信息 （len-12 字节）
					0~10000	0~10000	主机随机数	0x00：关锁 0x01：开锁	说明	说明	说明

Q：配件端开关锁功能如何对接？

A：蓝牙配件-MCU 对接方案，需要先使用 门锁业务功能配置（CMD-0xA6） 接口将配件端开关锁功能使能，以便打开配件的相关业务功能：

模组在收到 MCU 发送的 开关锁 命令后，模组会根据开关锁 DP 中的从机 ID，在 Flash 中查询是否有相关信息，有则说明门锁已经添加过该配件，配件可以控制门锁开关锁。然后模组会对门锁发起重连并转发开关锁 DP，门锁收到开关锁 DP 后进行开关锁操作。

功能	数据 方向	dp_id （1 字节）	dp_type （1 字节）	dp_da ta_len （1 字节）	dp_data_value
开 关 锁	下发	71	raw	len	主机 ID （2 字节）	从机 ID （2 字节）	随机数 （8 字节）	操作 （1 字节）	开关锁 时间戳 （4 字节）	开关锁 方式 （1 字节）	开关锁 信息 （len-12 字节）
					0~10000	0~10000	主机随机数	0x00：关锁 0x01：开锁	说明	说明	说明
	上报	71	raw	len	从机 ID （2 字节）	主机 ID （2 字节）	随机数 （8 字节）	操作 （1 字节）	开关锁 时间戳 （4 字节）	开关锁 方式 （1 字节）	返回状态 （1 字节）
					0~10000	0~10000	主机随机数	0x00：关锁 0x01：开锁	说明	说明	取值范围

主机 ID 和随机数，配件 MCU 上报 DP 的时候可以不用填，只需要填从机 ID。配件蓝牙模组中如果有存储从机 ID 对应的信息，配件会自动填充主机 ID 和随机数。

配件 MCU 端需要存储：

• 从机 ID（门锁的 ID）

  门锁 ID 在添加开门方式的时候会下发，具体见 DP 协议规范。

• 其余 DP，模组不会处理，直接透传。

  连上之后，配件会转发 MCU 报上来的开关锁 DP 给门锁，启动 30s 定时器。若门锁超过 30s 未回复开锁结果，则断开蓝牙连接。若收到开锁结果，也断开蓝牙连接。