门锁服务

概述

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

适用场景

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

功能列表

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

命令字	命令说明
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 小时低于 1 min，模组在每次上线时会同步一次云端时间，模组内部时钟不支持掉电工作，即掉电会重置。
  如果 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 以上版本支持。
  • BK3633QN33 门锁通用固件 0.0.3 以上版本支持。
• 一些门锁功能需要模组封装处理 DP 部分字段，为了不影响使用这些功能，将对这部分功能设置开关，且默认关闭。该设置永久存储。
• 目前，需要通过该接口配置的功能有：
  • 作为门锁，支持被配件开关锁（BK3633 默认支持）。
  • 作为配件，支持控制门锁开关锁功能。
  • 门锁密码进制配置。

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	配件预连接超时断开时间（仅 BK3633）

• FLAG：

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

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

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

  • bit2 到 bit7：保留

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

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

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

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

• 配件连接超时时间：触发配件预连接门锁时，如果连上门锁后没有收到进一步开关锁指令，那么配件会主动断开和门锁的蓝牙连接。

  • 配件开关锁成功后，配件会立即断开和门锁的蓝牙连接。
  • 该字段配置只有 5~30 s 才会生效。其他数字均使用默认设置（8 s）。

示例

• 55 AA 00 A6 00 04 01 00 00 00 AA：支持作为门锁使用可以被配件开关锁。
• 55 AA 00 A6 00 04 02 00 00 00 AB：支持作为配件可以控制门锁。
• 55 AA 00 A6 00 04 01 0A 00 00 B4：密码数字个数为 10，最小数字为 0，即数字范围 0~9。

模组回复

序号	字节数	字段	说明
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 广播间隔，单位 100 ms，实际广播间隔为 ibeacon_interval × 100 ms，可设置范围 100 ms ~ 2 s。非低功耗固定为 100 ms。

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

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

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

示例

• 防丢 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：门锁配件功能设计 蓝牙门锁配件 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 数据进行透传处理，由 MCU 完成相关逻辑。

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

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

模组在收到配件 MCU 上报的 开关锁 DP 命令后，模组会根据开关锁 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：开锁 0xFF：预连接（仅 BK3633）	说明	说明	说明
	上报 (门锁->配件)	71	raw	len	从机 ID （2 字节）	主机 ID （2 字节）	随机数 （8 字节）	操作 （1 字节）	开关锁 时间戳 （4 字节）	开关锁 方式 （1 字节）	返回状态 （1 字节）
					0~10000	0~10000	同上	同上	同上	同上	取值范围

• 主机 ID 和随机数：配件 MCU 上报解锁 DP71 给配件时，对应字段补零即可，模组不处理。模组会自动根据连接到的从机 ID，自动填写对应的主机 ID 和随机数。

• 从机 ID：配件 MCU 需要填写，如果为 0xFFFF，模组将会连接已绑定的门锁。如果已绑定多个门锁，则只控制当次实际连接成功的门锁。配件 MCU 也可以指定从机 ID，App 在添加解锁方式时，下发当次添加的解锁方式对应的从机 ID 。

• 操作类型：0xFF 仅 BK3633模组方案支持该类型，用于触发配件端提前蓝牙连接门锁，便于配件端权限验证完成后，能够更快速的实现开关锁控制（预连接超时时间内未收到后续开关锁指令，则断开蓝牙连接）。

MCU 需要注意下发和上报的 DP 指令包里主机 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

门锁 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：开锁	说明	说明	说明

配件 MCU 在收到 dpid=71 开关锁 DP返回指令时，也要上报 配件记录上报 配件端配件解锁记录。

配件 MCU 端需要存储：

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

• 其余 DP，除离线密码 T0 参数和单开多开设置外，模组不会处理，直接透传。MCU 要回复对应的 DP 指令（包括离线密码 T0 和单开多开设置）。

• 门锁和配件配对时，通过透传通道下发的门锁信息，模组会直接处理，无需 MCU 任何操作。

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