MCU 对接协议

更新时间:2023-04-03 12:39:39下载pdf

本文档主要为涂鸦蓝牙透传方案中串口协议描述。适用于如下架构的通讯方案:

MCU 对接协议

串口通讯约定

名词 说明
波特率(bps) 9600
数据位 8
奇偶校验
停止位 1
数据流控

名词解释

名词 说明
DP 全称 Data Point,即功能点或者一条/一对指令码。
PID product id,产品id,描述一类产品功能(DP)的集合。在 涂鸦 IoT 平台 创建的每一个产品都会产生一个唯一的产品编号,关联了产品具体的功能点、APP控制面板、出货信息等所有跟这个产品相关的信息。

帧数据包结构

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 协议升级扩展用
3 1 命令字CMD 具体帧类型
4
5
2 数据长度Len Len高8位
Len低8位
6~6+Len-1 Len 数据 -
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

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

DP格式

字段 长度(byte) 说明
dp_id 1 DP的指令码
dp_type 1 DP的数据类型
dp_data_len 2 DP的数据长度
dp_data_value dp_data_len DP的数据(具体参考DP规范)

Dp_type的取值范围及含义(云端定义):

dp_type 取值 长度(byte) 说明
raw 0x00 1~255 原始类型,HEX 数组
bool 0x01 1 布尔值
value 0x02 4 值类型(int)
string 0x03 0~255 字符串(可能为空)
enum 0x04 1 枚举型

通用固件品类划分

  • 为了扩展蓝牙通用固件的功能,使通用固件具备某一品类的特性,对通用串口协议进行了扩展。目前,整个协议文档大致分为通用对接协议低功耗功能附加协议门锁类通用固件附加协议

  • 所有通用固件都支持通用对接协议,低功耗功能附加协议部分支持。而门锁类通用固件附加协议仅对应品类的通用固件支持。

各通用对接品类支持模组一览表:

通用对接品类 芯片/模组
门锁类 TYBN1、BK3431Q
健康/共享类 BK3432、BK3431Q、TYBT3L
基础类 BK3432、TYBT3L、TYBT4L等telink模组

部分模组会有多个品类的通用固件。

各品类通用固件协议接口支持情况

不同品类的通用固件支持的协议情况不同,同一品类不同版本对协议接口的支持情况也不同。

各品类通用固件协议接口支持详情,如下图:

MCU 对接协议

通用对接协议

基本工作流程示意图:

MCU 对接协议

心跳包(CMD-0x00)

  • 模组上电后,以 3s 的间隔定期发送心跳。收到MCU 的心跳包回应后,模组会认为MCU 正常工作。在MCU首次(上电或重启)回复心跳包后,模组会向MCU查询产品信息。

  • MCU侧也可依据此心跳定期检测模组是否正常工作。若模组无心跳下发,则 MCU 可通过模组提供的硬件复位引脚复位模组。

  • 模组在获取MCU信息之后,在低功耗模式下无心跳,正常功耗模式下以10s的间隔定期发送心跳。

    Telink模组在低功耗下无心跳,在获得MCU信息(PID)后也不再发送心跳包,因此也无法检测MCU是否发生重启。

模组发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0x00
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

MCU返回:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0x00
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State返回值 说明
0x00 仅MCU 上电后第一次收到模组心跳包后的返回值,模组端也可依据这一点判断工作过程中MCU是否重启。
0x01 除 MCU 重启后第一次返回 0x00 外,其余均返回此值。

获取MCU信息(CMD-0x01)

  • prodect key:固定为 8 字节,由涂鸦云开发者平台生成,用于云端记录产品相关信息。
  • 产品信息主要是PID信息。

模组发送:

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

MCU返回:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0x01
4
5
2 数据长度 0x00
0x0d
6~18 0x0d Data 见下表
19 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data格式:

1~8 9~13
PID 保留字段

例:55 AA 00 01 00 0D 66 74 62 38 78 32 78  30 31 2E 30 2E 30 C0 (pid=ftb8x2x0,mcu ver=1.0.0)
PID为8位字符串,如“ftb8x2x0”。

保留字段原填充的是MCU软件版本号,但模组目前不对该字段做解析,字段保留。MCU版本号通过CMD E8\E9上报。

请求模组工作模式(CMD-0x02)

模组工作模式主要针对如何指示模组的工作状态以及如何重置模组而言,主要分两种情况:

  1. MCU 与模组配合处理,即模组通过串口通知 MCU 模组当前的工作状态,然后MCU 提供显示支持;MCU 检测出模组的重置需求,通过串口通知模组重置模组。
  2. 模组自处理:不支持。

目前仅支持MCU 与模组配合处理模式。

模组发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0x02
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

例:55 aa 00 02 00 00 01

MCU回复:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0x02
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

例:55 AA 00 02 00 00 01

发送模组工作状态(CMD-0x03)

  • 模组工作状态:0x00-未绑定;0x01-绑定未连接;0x02-绑定已连接。
  • 当模组收到MCU 请求模组工作模式回复CMD 0x02后,则会向MCU下发模组工作状态。
  • 当模组检测到模组状态发生变化,则主动下发模组状态至 MCU。

模组发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0x03
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State 工作状态说明 健康类/共享类通用固件注意
0x00
0x01
未绑定
绑定未连接
健康类/共享类产品对“绑定”这个概念进行了模糊处理,
未绑定和绑定未连接在健康类/共享类都认为是可配网状态
0x02 绑定已连接 绑定已连接在健康类/共享类认为是已配网已连接状态

重置模组(CMD-0x04)

断开模组蓝牙连接,解除蓝牙绑定关系,清除模组离线缓存信息,清除虚拟ID,重启。

由于之前Telink平台存在许多客户使用该接口作为解绑接口来使用,为了不影响这部分客户的功能,Telnik平台重置后不会清除虚拟id。

MCU发送:

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

例:55 aa 00 04 00 00 03

模组回复:

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

例:55 AA 00 04 00 00 03

命令下发(CMD-0x06)

  • datapoint 参考 DP 格式说明
  • “命令下发”可含多个 datapoint“命令数据单元”。
  • “命令下发”为异步处理协议,对应于 MCU 的datapoint“状态上报”。

模组发送:

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

datapoint格式:

1 2 3~4 5~ …… n n+1 n+1~n+2 n+3~
dp1_id dp1_type dp1_len dp1_data …… dpN_id dpN_type dpN_len dpN_data

例:55 aa 00 06 00 05 03 01 00 01 01 10

MCU返回:

状态上报(CMD-0x07)

  • datapoint 参考 DP 格式说明
  • “状态上报”可含多个 datapoint“命令数据单元”。
  • “状态上报” 为异步处理协议,“状态上报” 触发机制有三类:
  1. MCU 收到“命令下发处理帧时,正确执行相应datapoint 命令,再通过“状态上报” 帧将变化后的datapoint 状态发送至模组;
  2. MCU 主动检测到datapoint 有变化,将变化后的datapoint 状态发送至模组;
  3. MCU 收到状态查询帧时,将所有的 datapoint 状态发送至模组。

MCU发送:

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

datapoint格式:

1 2 3~4 5~ …… n n+1 n+1~n+2 n+3~
dp1_id dp1_type dp1_len dp1_data …… dpN_id dpN_type dpN_len dpN_data

例:55 aa 00 06 00 05 03 01 00 01 01 10

模组返回:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0x07
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State返回值说明:
0x00: 成功
0x01:失败

状态查询(CMD-0x08)

  • “状态查询” 为异步处理协议,主要用于模组查询 MCU 所有的“obj” 类型的 datapoint状态,当MCU 收到此帧时,通过CMD 0x07状态上报帧上报 datapoint 状态。
  • “状态查询” 发送时机主要有两种:
    1. 模组绑定已连接状态下,检查到MCU发生重启(通过心跳回复判断),查询发送;(备注:Telink通用固件不支持检测MCU重启)
    2. 模组蓝牙离线再上线(由绑定未连接状态变化成绑定已连接状态) 的情况,查询发送。

模组发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0x08
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

例:55 aa 00 08 00 00 07

MCU返回:

模组解绑(CMD-0x09)

  • 仅解除和手机的绑定关系,并且断开蓝牙连接,不会清除数据和虚拟ID。
  • 备注:健康类(共享类)通用固件“绑定”概念被模糊处理了,故不支持模组解绑接口。
  • 更多详情,请参考 各品类通用固件协议接口支持情况

MCU发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0x09
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

模组返回:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0x09
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State返回值说明:
0x00: 成功
0x01:失败

查询模组连接状态(CMD-0x0A)

  • 用于MUC主动查询模组的连接状态。模组收到查询后将通过CMD 0x03 发送模组工作状态。
  • 模组工作状态:0x00-未绑定;0x01-绑定未连接;0x02-绑定已连接。

MCU发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0x0A
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

记录型数据上报(CMD-0xE0)

  • 该接口主要用于重要数据的上报,如果上报时模组处于离线状态,模组会将数据存储在模组flash中,待模组上线再上报至APP。如果模组在线时,会在最后一条数据上报成功(连续上报的最后一条)后,释放缓存数据至app。
  • 模组可存储最多存储N条DP数据,记录将循环覆盖存储:
  1. nrf52832/BK3431q最多可存储80条,每条数据最长200字节。
  2. nrf52832/BK3431q最多可存储80条,每条数据最长200字节。
  3. bk3432最多存储32条,每条数据最长32字节。
  • 蓝牙模组内部时钟精度有限,24小时误差小于1分钟,但每次重连会重新校准时钟。如果用户对精度要求高,建议使用MCU自带时间上报。

无论设备是在线还是离线状态,记录型数据【强烈建议】使用该接口上报。

MCU发送:

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

Data格式:

1 2~x x x+1 x+2~x+3 x+4~ …… n n+1 n+1~n+2 n+3~
TYPE Time_Str dp1_id dp1_type dp1_len dp1_data …… dpN_id dpN_type dpN_len dpN_data

Time_Str:13位UNIX时间字符串

TYPE 说明
0x01 格式1-蓝牙模组自带时间上报
0x02 格式2-只上报原始数据,时间为实际上报时候的实时时间
0x03 格式3-MCU自带时间上报

unix_time_string:仅TYPE等于0x02时需要填,其他格式不用填。

示例:

  • 格式1-蓝牙模组自带时间上报:
    55 AA 00 E0 00 17 01 66 02 00 04 00 00 00 01 67 03 00 05 72 77 72 77 77 68 04 00 01 00 89
  • 格式2-只上报原始数据,时间为实际上报时候的实时时间:
    55 AA 00 E0 00 1B 02 66 02 00 04 00 00 00 01 67 03 00 09 72 77 72 77 77 61 66 61 66 68 04 00 01 00 20
  • 格式3-MCU自带时间上报:
    55 AA 00 E0 00 28 03 31 35 38 39 31 36 38 33 32 37 30 30 30 66 02 00 04 00 00 00 01 67 03 00 09 72 77 72 77 77 61 66 61 66 68 04 00 01 00 D0

模组返回:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xE0
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State返回值说明:
0x00: 存储成功
其他:存储失败

获取实时时间(CMD-0xE1)

  • 年月日格式时间请求建议使用格式0x02。
  • 设备上线后会主动同步一次云端时间给MCU。

MCU返回:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xE1
4
5
2 数据长度 0x00
0x01
6 1 Time_Type 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Time_type说明:

Time_Type 说明
0x00 格式0-获取7字节时间时间类型+2字节时区信息
0x01 格式1-获取13字节ms级unix时间+2字节时区信息
0x02 格式2-获取7字节时间时间类型+2字节时区信息
  • 格式0获取自定义时间存在不同平台兼容性问题,后面版本会废除,年月日时间格式建议使用0x02格式。
  • Telink通用固件已经不再支持格式0,请求格式0时间则会返回格式2时间。
  • 时区:实际时区的 100 倍,例如北京东八区为 8x100=800,西 7.5 区为-750。

模组返回:

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

Time_Data格式0:

结果码 时间格式 星期 时区
1 2 3 4 5 6 7 8 9 10~11
Result Time_Type 2018+year mon day hour min sec week time_zone

Time_Data格式1:

结果码 时间格式 ms级unix时间 时区
1 2 3~15 16~17
Result Time_Type unix_time_string time_zone

Time_Data格式2:

结果码 时间格式 星期 时区
1 2 3 4 5 6 7 8 9 10~11
Result Time_Type 2000+year mon day hour min sec week time_zone

Result为0x00表示成功,其他表示失败。

示例:

  • Time_Data格式0:
    • MCU-55 AA 00 E1 00 01 00 E1
    • 模组-55 AA 00 E1 00 0B 00 00 01 0C 1E 0F 34 1F 01 03 20 9C //2019年12月30日15点52分31秒 星期一 东八区
  • Time_Data格式1:
    • MCU-55 AA 00 E1 00 01 01 E2
    • 模组-55 AA 00 E1 00 11 00 01 31 35 37 37 36 39 32 33 39 35 30 30 30 03 20 BB// 时间戳1577692395000 东八区
  • Time_Data格式2:
    • MCU-55 AA 00 E1 00 01 02 E3
    • 模组-55 AA 00 E1 00 0B 00 02 13 0C 1E 10 09 29 01 03 20 90 //2019年12月30日16点09分35秒 星期一 东八区

MCU-OTA部分接口

查询MCU版本号(CMD-0xE8)

模组发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xE8
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

MCU返回:

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

DATA格式:

1~3 4~6
Soft_Ver Hard_ver

Soft_Ver:Mcu当前固件版本号,例如0x01 00 02代表版本为V1.0.2。

Hard_ver:Mcu当前硬件版本号,PCBA版本号。

MCU主动发送当前版本号(CMD-0xE9)

  • 为了确保模组及时获取到MCU版本信息,MCU在每次启动时(一般在串口初始化后)需要主动发送一次当前版本号到模组,如果没有收到模组的响应,需要再次发送。
  • 更多详情,请参考 各品类通用固件协议接口支持情况

MCU返回:

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

DATA格式:

1~3 4~6
Soft_Ver Hard_ver

Soft_Ver:Mcu当前固件版本号,例如0x01 00 02代表版本为V1.0.2。

Hard_ver:Mcu当前硬件版本号,PCBA版本号。

模组返回:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xE9
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State返回值说明:
0x00: 成功
其他:失败

MCU-OTA流程图

MCU 对接协议

MCU-OTA升级请求(CMD-0xEA)

模组发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xEA
4
5
2 数据长度 0x00
0x02
6~7 2 最大单包数据长度len1 见说明
8 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Len1:最大单包数据长度,设备允许的单包数据最大长度,单位字节。

例: 55 AA 00 EA 00 02 00 C8 B3

MCU回复:

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

Data格式:

1 2~4 5~6
Flag Mcu当前固件版本号version 可接受最大数据长度len2

Flag: 0x00-允许升级,0x01-拒绝升级。

Version:当前固件版本号,例如0x01 00 02代表版本为V1.0.2。

Len1:模组限定最大单包数据长度。

Len2:MCU可接受最大包长度,如果len1<len2,升级以len1为准,反之以len2为准。

例: 55 AA 00 EA 00 06 00 01 00 00 00 C8 B8

MCU-OTA升级文件信息(CMD-0xEB)

模组发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xEB
4
5
2 数据长度 0x00
0x23
6~40 35 Data 见下表
41 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data格式:

8字节 3字节 16字节 4字节 4字节
产品PID 文件版本 文件MD5 文件长度 CRC32

PID: MCU的PID。
文件版本:例如,0x010002代表版本为V1.0.2。
文件MD5:升级固件的md5值。
文件长度:升级固件的总长度,单位字节。
CRC32:升级固件的CRC32 。

MCU回复:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xEB
4
5
2 数据长度 0x00
0x19
6~30 25 Data 见下表
31 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data格式:

1字节 4字节 4字节 16字节
STATE 已储存文件长度 已储存文件CRC32 已储存文件MD5(目前不使用)

STATE:
0x00-正常升级。
0x01-产品PID不一致。
0x02-文件版本低于或者等于当前版本。
0x03-文件大小超过范围。
其他-保留。

为了支持断点续传,这里会返回设备端已经储存的文件信息。 APP收到信息后,根据设备返回的已储存文件长度,计算新文件对应长度的CRC32,然后和设备返回的CRC32对比。如果两者都吻合,那么在下面的文件起始传输请求中将起始传输偏移量改为该长度值,否则文件起始传输偏移量改为0,表示从头开始传输。

每次断点续传都会完全按照MCU OTA流程的顺序,从OTA升级请求开始,所以MCU端如果有维护升级状态的话,需要在收到模组工作状态为非绑定已连接的其他状态时重置升级状态,以确保可以开始下一个升级流程。

MCU-OTA升级文件偏移请求(CMD-0xEC)

更多详情,请参考 各品类通用固件协议接口支持情况

模组发送:

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

说明:offset-文件起始传输偏移量,四字节。

例: 55 AA 00 EA 00 02 00 C8 B3

MCU回复:

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

offset: MCU要求的起始传输文件偏移量

说明:实际文件传输的偏移地址应该以mcu端要求的为准,且mcu端要求的地址会小于等于APP端给出的偏移。

MCU-OTA升级数据(CMD-0xED)

更多详情,请参考 各品类通用固件协议接口支持情况

模组发送:

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

Data格式:

2字节 2字节 2字节 n字节
包号 当前包数据长度n 当前包数据CRC16 当前包数据

注:包号从0开始,当前包数据长度不能大于OTA升级请求指令制定的最大包长度。

MCU回复:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xED
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State 说明
0x00 成功
0x01 包号异常
0x02 长度不一致
0x03 CRC校验失败
0x04 其他

MCU-OTA升级结束(CMD-0xEE)

更多详情,请参考 各品类通用固件协议接口支持情况

模组发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xEE
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

MCU回复:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xEE
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

说明:

State 说明
0x00 成功
0x01 数据总长度错误
0x02 长度不一致
0x03 其他

产测相关接口

RF射频测试(CMD-0x0E)

  • 为了检测出厂后蓝牙模组的射频是否正常工作,需要测试模组的RSSI信号强度。
  • 测试工具:蓝牙信标 (涂鸦提供),作用:发射名称为ty_mdev的广播信号。
  • 测试步骤:首先将信标放在距离模组较近(0.5米左右) 的地方。然后通过串口发送该rf 射频测试指令,模组会搜索蓝牙信标并返回信号强度值,一般信号强度大于-70db认为模组射频工作正常。
  • 一些特殊芯片/模组,目前只有BK3431Q,BK3432,这类模组不支持扫描信标的方式,测试RSSI需要使用以下工具:
  • 测试工具:蓝牙dongle (涂鸦提供),作用:连接被测设备并返回rssi。
  • 测试步骤:首先将dongle放在距离模组较近(0.5米左右) 的地方。然后通过串口向模组发送该rf 射频测试指令,dongle会连接模组并返回信号强度值,一般信号强度大于-70db认为模组射频工作正常。
  • 模组需要保持非低功耗模式,且模组处于非绑定状态。

MCU发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0x0E
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

模组回复:

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

Data格式:

Data 说明
{“ret”:true,“rssi”:“-55”} 信号强度为-55db
{“ret”:false} 没有搜索到该信号

低功耗功能附加协议

不同品类的通用固件在低功耗工作设计上有一些差别,下面将分别描述:


门锁类低功耗工作说明-TYBN1/BK3431Q

  • 模组在获得MCU信息后,低功耗状态将不再发送心跳包,非低功耗下心跳包正常。
  • 工作模式分为低功耗模式和非低功耗模式。
    • 非低功耗模式下,蓝牙广播间隔固定为100ms,模组串口可上行可下行。
    • 低功耗模式下,蓝牙广播间隔为MCU设置的参数(如果是0则关闭广播,默认1s)。该模式下模组串口下行正常工作,上行禁用(不接收MCU串口数据)。
  • 模组的低功耗工作状态由模组低功耗控制引脚SCL的电平决定,MCU可以通过SCL输出不同电平控制模组的功耗状态,具体参考下表:
平台\说明 模组低功耗控制引脚SCL 低功耗对应的SCL电平 非低功耗对应的SCL电平
NORDIC IO11
BK P03

建议在唤醒模组后延时20ms再使用串口。

模组唤醒外部MCU的引脚为SDL,当模组需要发送数据给外部MCU时,模组会改变SDL的电平 200ms,然后再发送数据,发送完成后恢复默认电平。

平台\说明 模组唤醒MCU引脚SDL 发数据时SDL电平 空闲时SDL电平
NORDIC IO14
BK P10
  • 不支持使能低功耗接口,无需使能,直接由模组低功耗控制引脚SCL的电平决定。
  • 不支持关闭系统计时功能。

SCL各平台默认上下拉情况可能存在差异,MCU端与SCL对接引脚不要使用悬空状态。

修改低功耗模式下的广播间隔(CMD-0xE2)

  • BK3432健康类通用固件暂不支持
  • 为降低休眠时的功耗,可以通过该指令修改广播间隔,广播参数将永久保存。当设置为0时,将关闭广播。该设置将永久储存。
  • 低功耗下广播间隔默认1s,广播间隔越大连接所需要的时间越长,甚至某些性能差手机可能很难连接上,不建议客户修改更大的广播间隔值。
  • 更多详情,请参考 各品类通用固件协议接口支持情况

MCU发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xE2
4
5
2 数据长度 0x00
0x01
6 1 Adv_interval 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Adv_interval:可设置数值范围为0到20,单位为100ms,即实际广播间隔范围为100ms到2秒,当设置数值为0时将关闭广播

例:
55 aa 00 E2 00 01 00 E2(设置低功耗模式下关闭广播)
55 aa 00 E2 00 01 06 E8(设置低功耗下广播间隔为600ms)

模组回复:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xE2
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State返回值说明:
0x00: 设置成功
其他:设置失败

关闭系统计时器(CMD-0xE4)

  • 为降Telink芯片低休眠时的功耗,可以通过该指令关闭蓝牙模组内部计时功能,如果MCU不需要时间功能,可以关闭该功能,当计时功能和广播功能都关闭后,然后拉低SDA,模组将进入深度睡眠,功耗降低至3ua,唤醒后,模组重启,重新运行。该设置将永久储存。
  • BK3431Q和TYBN1中,由于单纯计时功耗比较低,主要耗电的是存flash操作,这里只是关闭了flash存储操作。打开后,时钟可周期性(1min)存flash,可解决重启后模组RTC时钟时间重置的问题。(默认为关闭)

MCU发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xE4
4
5
2 数据长度 0x00
0x01
6 1 Data 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data格式:

Data 说明
0x00 关闭系统计时器
0x01 打开系统计时器

模组回复:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xE4
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State返回值说明:
0x00: 设置成功
其他:设置失败

主动断开蓝牙连接(CMD-0xE7)

为降低休眠时的功耗,MCU在不需要蓝牙连接的时候,可以先断开模组蓝牙连接,再控制模组进入低功耗,以达到模组最低功耗状态。该接口主要功能为断开蓝牙连接。

MCU发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xE7
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

模组回复:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xE7
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State返回值说明:
0x00: 设置成功
其他:设置失败

MCU低功耗唤醒配置(CMD-0xB0)

  • 适用模组:TYBN1门锁通用固件6.2以上版本支持,BK3431Q门锁通用固件3.3以上版本支持。
  • 考虑到原定唤醒时间200ms过长,开放该值由mcu设置,用于mcu配置自身从低功耗唤醒所需要的时间t,默认200ms。模组向mcu发送串口数据将会先拉高或拉低 t 时间左右的mcu唤醒引脚。
  • MCU修改后需测试唤醒时间是否能正常唤醒mcu,如果不能需则调大。如果对于该延迟时间不是特别在意,建议不设置,使用默认值。
  • 调用时机:建议MCU在收到CMD 0x02 (55 aa 00 02 00 00 01)后,调用该接口设置mcu低功耗唤醒配置。(该设置非永久存储,模组上电/重启后默认200ms)
  • 更多详情,请参考 各品类通用固件协议接口支持情况

MCU发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xB0
4
5
2 数据长度 0x00
0x01
6 1 interval 见说明
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

interval: 单位(10ms),取值范围1~20。即目前设定最小支持10ms,最大支持200ms。

例:
55 aa 00 E2 00 01 00 E2(设置低功耗模式下关闭广播)
55 aa 00 E2 00 01 06 E8(设置低功耗下广播间隔为600ms)

模组回复:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xB0
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State返回值说明:
0x00: 设置成功
其他:设置失败

门锁类通用固件附加协议

该章节协议为门锁类通用固件附加的协议,其他品类通用固件不支持该协议。目前门锁类通用固件有BK3431Q通用固件,TYBN1通用固件。

动态密码(CMD-0xE6)

  • 模组计算动态密码基于时间,必须确保云端和设备时间同步,计算的动态密码才一致,否则将导致密码错误。 (设备与APP建立连接会自动同步时间)
  • 管理员密码入参暂不支持,当前管理员密码长度填0即可
  • 更多详情,请参考 各品类通用固件协议接口支持情况

MCU发送:

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

Data格式:

8字节 1字节 N字节 N字节 ……
password 管理员密码长度 第1组管理员密码 第2组管理员密码 ……

password:用户输入的密码数据Data[0]~Data[7]数据内容范围为 ‘0’~’9’ 数据传输使用 ASCII 码

管理员密码入参暂不支持,当前管理员密码长度填0即可

例: MCU发送不带管理员密码的数据包

55 aa 00 E6 00 09 30 31 32 33 34 35 36 37 00 8a

模组回复:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xE6
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State返回值说明:
0x00: 密码核对通过
0x01: 密码核对失败

例:
55 AA 00 E6 00 01 01 E7(密码核对失败)
55 AA 00 E6 00 01 00 E6 (密码核对通过)

新动态密码校验(CMD-0xA7)

  • 协议中的时间数据用于运算当前的动态密码,这里的动态密码运算时间都为当前的格林时间,设备需要给模组格林时间数据。
  • 功能上和CMD-0xE6完全相同,参数部分有改动,支持MCU传递时间。
  • 更多详情,请参考 各品类通用固件协议接口支持情况

MCU发送:

序号 长度(byte) 字段 说明
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 时间来源于MCU上传的year/mon/day/hort/min/sec字段 ; 0x01使用模组内部时间,year/mon/day/hort/min/sec不解析,填0x00即可

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

模组回复:

序号 长度(byte) 字段 说明
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-0xA5)

  • 该接口主要用于网关按需连接,MCU调用该接口后,蓝牙模组会启动30s高频广播,类似一个“举手”的过程,蓝牙主机扫描带标志的模组广播后,会主动连接模组。模组上线后,MCU即可正常上报DP。
  • 通常用法:记录型数据都调用0xE0上报,如果MCU检测到模组为绑定未连接状态,则调用该接口请求上线,模组上线后会自动释放通过0xE0上报的数据。
  • 实时数据不符合主动上报一般使用场景,但MCU端如果想实时数据也上报,有两种方法:
  1. 调用该接口后,等待模组工作状态变为绑定已连接(模组上线会下发工作状态)
  2. 通过0xE0的0x02格式上报实时数据,模组上线后会将数据释放给APP(不建议使用)

MCU发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xA5
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

模组回复:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xA5
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State返回值说明:
0x00: 成功
0x01: 失败

离线密码(CMD-0xA2)

  • 设备长时间不联网也可使用的动态密码。
  • 模组内部时钟精度不是很高,24小时低于1min,模组在每次上线时会同步一次云端时间,模组内部时钟不支持掉电工作,即掉电会重置。 如果MCU有外接时钟,强烈建议时钟源选择0x00-MCU上传格林时间。(使用模组内部时钟可找研发要测试程序测量时钟误差)
  • 更多详情,请参考 各品类通用固件协议接口支持情况

MCU发送:

序号 长度(byte) 字段 说明
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 时间来源于MCU上传的year/mon/day/hort/min/sec字段 ; 0x01使用模组内部时间,year/mon/day/hort/min/sec不解析,填0x00即可

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

Code_len:密码长度
Code:密码(区别于动态密码中密码传ASCII码‘1’~‘9’的格式,离线密码直接传数字,1即0x01……9即0x09,可参考下面示例)

模组回复:

序号 长度(byte) 字段 说明
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-0xA3)

  1. 模组非低功耗固定100ms间隔的广播,低功耗默认1000ms间隔(MCU可设置0~2000,0代表广播)的广播。 APP扫描到广播即可配网。一些用户希望配网的时机完全由MCU控制,可调用该接口来实现。
  2. 广播使能状态模组会记录在flash中,即希望配网时间由MCU控制的用户,需要在串口初始化后调用该接口调整为MCU希望的默认使能状态。 MCU应该在需要配网的时候打开使能,不需要配网的时候关闭使能。
  3. 模组默认是使能广播状态,通过该接口关闭模组广播使能,模组不管是低功耗还是非低功耗都不会有广播。
  4. 如果关闭广播使能之前模组处于广播状态,关闭后模组会立即停止广播。
  5. 打开广播使能后模组会立即启动广播,具体参照(1)。
  6. 更多详情,请参考 各品类通用固件协议接口支持情况

区别:与修改低功耗下广播间隔来控制广播的区别主要在于,该接口可控制非低功耗下的广播,而修改低功耗下广播间隔只能作用于低功耗状态。所以控制配网时机需要使用使能广播接口。

MCU发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xA3
4
5
2 数据长度 0x00
0x01
6 1 Data 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data格式:

Data 说明
0x00 关闭广播使能
0x01 打开广播使能

模组回复:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xA3
4
5
2 数据长度 0x00
0x01
6 1 State 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State返回值说明:
0x00: 设置成功
其他:设置失败

恢复出厂设置通知(CMD-0xA1)

  • 当APP向模组发送恢复出厂设置命令时,模组会向MCU发出恢复出厂设置通知,MCU可以根据该指令做恢复出厂设置功能。
  • 更多详情,请参考 各品类通用固件协议接口支持情况

模组发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xA1
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

MCU返回:

MCU查询模组版本号(CMD-0xA0)

MCU发送:

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字CMD 0xA0
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

模组回复:

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

DATA格式:

1~3 4~6
Soft_Ver Hard_ver

Soft_Ver:模组当前固件版本号,例如0x01 00 02代表版本为V1.0.2。

Hard_ver:模组当前硬件版本号,PCBA版本号。

门锁业务功能配置(CMD-0xA6)

  • 适用模组: TYBN1门锁通用固件6.2以上版本支持,BK3431Q门锁通用固件3.3以上版本支持。
  • 一些门锁功能需要模组封装处理DP部分字段,为了不影响不使用这些功能的客户,将对这部分功能设置开关,且默认关闭。(该设置永久存储)
  • 目前需要通过该接口配置的功能有:①门锁端配件功能②配件端开关锁功能③门锁密码进制配置。
  • 更多详情,请参考 各品类通用固件协议接口支持情况

MCU发送:

序号 长度(byte) 字段 说明
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:保留。

  • bit3:保留。

  • bit4:保留。

  • bit5:保留。

  • bit6:保留。

  • 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(关闭门锁配件功能)

模组回复:

序号 长度(byte) 字段 说明
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: 设置成功
其他:设置失败
点击展开对接指南

Q: 这个协议接口有什么作用?什么时候需配置?

A:用于配置模组端业务功能逻辑的开关(主要是涉及到DP的业务)。目前有三个业务逻辑的封装:1.门锁端配件功能;2.配件端开关锁功能;(这两个功能都是服务于门锁蓝牙配件的,一个是用于门锁的,一个是用于配件的。)3.多位密码配置。

如果门锁用不到配件的可以不配置,默认是全关闭的。如果有配件需求的,可以在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:MCU对接-门锁配件功能对接介绍

门锁配件功能涉及门锁DP规范中的4个DP-链接,以及一个通用串口协议接口CMD 0xA6(门锁业务功能配置)

门锁和配件之间的配对、重连这些其实已经被门锁封装门锁通用固件中了,这部分无需关心。
为了提高安全等级,确保配件出现后门锁端的相对安全,在业务层进行了身份的二次确认,过程如下:

  • 云端为主机(APP/配件)分配“主机id+主机随机数”,用于唯一识别主机;
    云端为从机(门锁)分配“从机id+从机随机数”,用于唯一识别从机;

  • 云端首先将APP的“主机id+主机随机数”和门锁的“从机id”发送给门锁,此时认为APP和门锁完成了业务配对;
    然后将配件的“主机id+主机随机数”发送给门锁,将配件的“主机id+主机随机数”和门锁的“从机id”发送给配件,此时认为配件和门锁完成了业务配对;

  • 此时,门锁端存储着:
    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)接口将配件端开关锁功能使能,使能的目的为打开配件的相关业务功能:

  1. 模组在收到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端需要存储:

  1. 从机ID(门锁的ID)

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

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

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