蓝牙门锁 DP 参考

本文介绍了涂鸦智能蓝牙门锁应用中涉及的 DP 功能、帧格式及其使用方法，适用于蓝牙门锁公版项目。

背景信息

名词解释

下表罗列了本文涉及到的部分名词和解释，更多详情，请参考 名词解释。

名词	解释
DP	全称为 Data Point，同时被称为 DP 点。一个 DP 指的就是一个功能点或者一条/对指令码，DP-data point。
PID	全称为 Product ID，表示描述一类产品功能（DP）的集合。 在涂鸦开发者平台创建的每一个产品都会产生一个唯一的产品编号， 关联了产品具体的功能点、App 控制面板、出货信息等所有跟这个产品相关的信息。
uuid	设备的唯一识别 ID，又称作 License，长度是 20 位。
authkey	设备在云端注册时需要的密钥，和 uuid 是一一对应的关系，长度是 32 位。
固件 key	固件在 涂鸦开发者平台 的唯一身份标识。
成员	也称作用户，是同一个概念。
成员 ID	1 字节无符号整数，指成员编号（也称为用户编号）。由服务器分配下发，本地无需维护，取值范围 0x01~0x64，其他为保留值。
硬件 ID	1 字节无符号整数，指开锁方式相关的硬件编号。由本地分配维护，每一个开锁方式对应一个硬件 ID。 例如：指纹一硬件 ID 为 0x01，密码一硬件 ID 为 0x02，取值范围 0x00~0xFE，0xFF 为保留值。
时效性	某个具体的开锁方式（例如指纹或密码）在指定的时间范围内有效。
锁帖	一种将传统门锁升级为智能门锁的装置，详情请自行搜索。
下发	数据传输的方向，手机/网关 → 蓝牙设备。
上报	数据传输的方向，蓝牙设备 → 手机/网关。

角色分配

• 主机：涂鸦 智能生活 App、蓝牙网关、或门锁配件

• 从机：蓝牙门锁

  主机通过蓝牙广播识别从机，并对已授权的从机发起配对请求，完成配对的主从机处于绑定状态。

  处于绑定状态的主从机之间存在一条符合蓝牙规范的安全通道，所有的业务类通信都在该安全通道中进行。

安全通道的建立过程可以简述如下：

• 连接：普通的蓝牙连接，此处特指 App 和门锁设备的连接

• 配对：视为一种 过程，一系列的密钥交换过程
• 绑定：视为一种 状态，配对完成后的状态称之为绑定状态，处于绑定状态的两个设备可以进行安全通信
• 重连：视为一种 过程，依然是一系列的密钥交换过程，可以认为是简化的配对，该过程的前提是此前已经进入过一次绑定状态。
• 移除：视为一种 过程，秘钥删除和绑定状态的清除

DP 格式

使用涂鸦蓝牙门锁方案（SDK 或模组）开发时，dp_data_len 的长度为 1 或 2 个字节 （由蓝牙通信协议版本决定，3.x 的为 1 字节，4.x 及其以上的为 2 字节）。DP 格式定义，请参见下表：

字段	长度（bytes）	说明
dp_id	1	DP 的指令码
dp_type	1	DP 的数据类型
dp_data_len	1/2	DP 的数据长度
dp_data_value	dp_data_len	DP 的数据内容

解锁方式管理

添加开锁方式

数据 方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
下发	1	raw	len	类型 (1 字节)	阶段 (1 字节)	管理员标记 (1 字节)	成员 ID (1 字节)	硬件 ID (1 字节)	时效性 (17 字节)	次数 (1 字节)	密码长度 (1 字节)	密码内容 (n 字节)
				0x01：密码 0x02：门卡 0x03：指纹 0x04：人脸 0x05：掌纹 0x06：指静脉	0x00：录入开始 0xFE：录入取消 (App 端发起)	0x00：普通成员 0x01：管理员	0x01~0x64	0xFF：默认值	详见 附录 1	取值 范围	说明	说明
上报	1	raw	len	类型 (1 字节)	阶段 (1 字节)	管理员标记 (1 字节)	成员 ID (1 字节)	硬件 ID (1 字节)	次数 (1 字节)		返回状态 (1 字节)
				0x01：密码 0x02：门卡 0x03：指纹 0x04：人脸 0x05：掌纹 0x06：指静脉	0x00：录入开始	0x00：普通成员 0x01：管理员	0x00~0x64	0xFF：默认值	需要录入的总次数 例如：指纹一般是 6 次， 门卡一般是 1 次		0x00：默认值
					0xFC：录入进行	0x00：普通成员 0x01：管理员	0x00~0x64	0xFF：默认值	录入次数的序号 例如：指纹一般是 6 次， 填写每次的编号（从 1 开始）		录入异常原因： 0x00：无异常 0x01：指纹不全
					0xFD：录入失败	0x00：普通成员 0x01：管理员	0x00~0x64	0xFF：默认值	当前的录入阶段： 0x00：录入开始 0xFC：录入进行， 0xFF：录入完成		录入失败原因
					0xFE：录入取消 (App 端发起)	0x00：普通成员 0x01：管理员	0x00~0x64	0xFF：默认值	0x00：默认值		0x00：默认值
					0xFF：录入完成	0x00：普通成员 0x01：管理员	0x00~0x64	0x00~0xFE	0x00：默认值		0x00：默认值

交互示例

• 当开锁方式为密码、门卡、人脸时，交互流程如下图所示：

• 当开锁方式为指纹时，交互流程如下图所示：

删除开锁方式

数据 方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
下发	2	raw	len	类型 (1 字节)	阶段 (1 字节)	管理员标记 (1 字节)	成员 ID (1 字节)	硬件 ID (1 字节)	删除方式 (1 字节)
				0x00：删除成员	0x00：默认	0x00：普通成员 0x01：管理员	0x01~0x64	0xFF：默认值	0x00：删除某个成员下所有开锁方式
				0x01：密码 0x02：门卡 0x03：指纹 0x04：人脸 0x05：掌纹 0x06：指静脉	0x00：默认	0x00：普通成员 0x01：管理员	0x01~0x64	0x00~0xFE	0x01：删除某成员的某一个开锁方式
上报	2	raw	len	类型 (1 字节)	阶段 (1 字节)	管理员标记 (1 字节)	成员 ID (1 字节)	硬件 ID (1 字节)	删除方式 (1 字节)		返回状态 (1 字节)
				0x00：删除成员	0x00：默认	0x00：普通成员 0x01：管理员	0x01~0x64	0xFF：默认值	0x00：删除某个成员下所有开锁方式		0x00：删除失败 0xFF：删除成功
				0x01：密码 0x02：门卡 0x03：指纹 0x04：人脸 0x05：掌纹 0x06：指静脉	0x00：默认	0x00：普通成员 0x01：管理员	0x01~0x64	0x00~0xFE	0x01：删除某成员的某一个开锁方式		0x00：删除失败 0x01：开锁方式不存在 0xFF：删除成功

修改开锁方式

数据 方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
下发	3	raw	len	类型 (1 字节)	阶段 (1 字节)	管理员标记 (1 字节)	成员 ID (1 字节)	硬件 ID (1 字节)	时效性 (17 字节)	次数 (1 字节)	密码长度 (1 字节)	密码内容 (n 字节)
				0x00：仅修改某 个成员的时效性	0x00：默认	0x00：普通成员 0x01：管理员	0x01~0x64	0xFF：默认值	详见 附录 1	0x00：默认值 (次数不允许修改)	说明	说明
				0x01：密码 0x02：门卡 0x03：指纹 0x04：人脸 0x05：掌纹 0x06：指静脉	0x00：默认	0x00：普通成员 0x01：管理员	0x01~0x64	0x00~0xFE	详见 附录 1	取值 范围	说明	说明
上报	3	raw	len	类型 (1 字节)	阶段 (1 字节)	管理员标记 (1 字节)	成员 ID (1 字节)	硬件 ID (1 字节)	次数 (1 字节)		返回状态 (1 字节)
				0x00：仅修改某 个成员的时效性	0x00：默认	0x00：普通成员 0x01：管理员	0x01~0x64	0xFF：默认值	0x00：默认值 (次数不允许修改)		0x00：修改失败 0xFF：修改成功
				0x01：密码 0x02：门卡 0x03：指纹 0x04：人脸 0x05：掌纹 0x06：指静脉	0x00：默认	0x00：普通成员 0x01：管理员	0x01~0x64	0x00~0xFE	取值范围		0x00：修改失败 0xFF：修改成功

临时密码管理

添加临时密码

临时密码包括一次性密码和周期性密码。临时密码和普通密码的不同之处有以下几点：

• 临时密码不属于任何成员

• 临时密码的时效性在连接状态下可单独更改

• 临时密码作为开门方式时的 类型定义为 0xF0 （0x01 为密码，0x02 为门卡，0x03 为指纹……）

临时密码的使用 风险 在于：

• 如果设备断电，不能及时连接上网络同步时钟，会导致本地时钟不能正确工作，周期性密码的周期重复功能会出现在本地无法准确判断的问题。
• 解决方案建议：
  • 本地添加后备电池，确保本地时钟不因断电产生异常。
  • 产品接受在上述情况下产生的问题。

数据 方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
下发	51	raw	len	类型 (1 字节)	时效性 (17 字节)	次数 (1 字节)	密码长度 (1 字节)	密码内容 (n 字节)
				0x00：类型 0 0x01：类型 1	详见 附录 1	取值范围	密码字节数 n (仅用于密码类型)	说明
上报	51	raw	len	硬件 ID （1 字节）			返回状态 （1 字节）
				0x00~0xFE			0x00：添加成功 0x01：添加失败 0x02：硬件 ID 分配完 0x03：密码重复

删除临时密码

数据 方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
下发	52	raw	len	硬件 ID (1 字节)
				0x00~0xFE
上报	52	raw	len	硬件 ID (1 字节)	返回状态 (1 字节)
				0x00~0xFE	0x00：删除成功 0x01：删除失败 0x02：临时密码不存在 (不存在时也可回复 0x00 删除成功)

修改临时密码

数据 方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
下发	53	raw	len	硬件 ID (1 字节)	类型 (1 字节)	时效性 (17 字节)	次数 (1 字节）	密码长度 (1 字节)	密码内容 (n 字节)
				0x00~0xFE	0x00：类型 0 0x01：类型 1	详见 附录 1	取值范围	密码字节数 n (仅用于密码类型)	说明
上报	53	raw	len	硬件 ID (1 字节)			返回状态 (1 字节)
				0x00~0xFE			0x00：修改成功 0x01：修改失败

解锁方式同步

全量同步(新版)

• 目的与意义：为了保持云端和设备本地开锁方式的一致性，每次进入面板内成员管理列表或者在成员管理界面下拉刷新时，都会触发解锁方式的全量同步(包括手机和本地添加的所有开锁方式）。
• 硬件类型枚举：用来通知设备端本次需要同步的解锁方式类型，未下发的硬件类型本地无需上报。阶段为 同步中 的每包数据长度由您自定义，建议每包数据总长度不大于 200 个字节。
• 同步本地添加的开锁方式：本地添加的开锁方式通过同步的方式上报给云端，目前有以下几种情况：
  • 上报时用户 ID 为 0xFF，云端统一将本地添加的开锁方式挂到配网账户下，并存储相应的用户 ID，之后每次下发该类开锁方式时，相应的用户 ID 也为 0xFF（仅用于百洛、汇力挂锁，云端不可删除）。
  • 上报时用户 ID 为 0xFD，云端统一将本地添加的开锁方式挂到配网账户下，并存储相应的用户 ID，之后每次下发该类开锁方式时，相应的用户 ID 也为 0xFD（通用）。

数据方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
下发	54	raw	len	硬件类型枚举 (len 字节)
				0x01：密码 0x02：门卡 0x03：指纹 0x04：人脸 0x05：掌纹 0x06：指静脉
上报	54	raw	len	阶段 (1 字节)	数据包序号 (1 字节)	同步数据 (n 字节)
				0x00：同步中	0x00~0xFF 序号从 0 开始依次递增	数据 1、数据 2、……、数据 n 数据格式定义
上报	54	raw	len	阶段 (1 字节)	总包数 (1 字节)
				0x01：同步结束	总包数 例如发送了 2 次阶段为同步中的包，则总包数为 2

差量同步(弃用)

为了尽量降低同步时的传输数据量，每次仅同步有差异化的部分。

同步开锁方式开始时，App 会将云端储存的硬件 ID、硬件类型和每个硬件 ID 绑定的属性（例如成员 ID，冻结状态）的 crc8 值下发给本地，本地收到数据后与本地存储的数据进行比对，然后选取有差异化的硬件 ID，并将其属性值重新上传。

数据方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1 字节)	dp_data_value
下发	35	raw	len	硬件 ID 个数 (1 字节)	下发硬件 1 (3 字节)	下发硬件 2 (3 字节)	……	下发硬件 n (3 字节)
				个数	详见说明	详见说明	……	详见说明
上报	35	raw	len	硬件 ID 个数 (1 字节)	上报硬件 1 (3 字节)	上报硬件 2 (3 字节)	……	上报硬件 n (3 字节)
				个数	详见说明	详见说明	……	详见说明

说明：

• 下发硬件 n = 硬件 IDn+硬件类型+硬件 CRC8
• 上报硬件 n = 操作类型+硬件 IDn+硬件类型+硬件属性

• 操作类型：1 字节，0x00-更新硬件属性（服务器和本地不一致），0x01-删除该硬件 ID（本地无记录）。
  硬件类型：1 字节，0x01-密码，0x02-门卡，0x03-指纹，0x04-人脸。
  硬件属性：2 字节
  • 成员 ID：1 字节，取值范围：0x01~0x64。
  • 冻结状态：1 字节，0x01-未冻结，0x00-冻结。

• crc8 计算方法：此处的 crc8 为 crc16 取低字节，crc16 的 C 语言计算方法如下：

  uint16_t cpt_crc16_compute(uint8_t* buf, uint16_t size, uint16_t* p_crc)
  {
      uint16_t poly[2] = {0, 0xa001}; //0x8005 <==> 0xa001
      uint16_t crc = 0xffff;
      int i, j;
  
      for (j=size; j>0; j--)
      {
          uint8_t ds = *buf++;
          for (i=0; i<8; i++)
          {
              crc = (crc >> 1) ^ poly[(crc ^ ds) & 1];
              ds = ds >> 1;
          }
      }
  
      return crc;
  }
  

蓝牙近场解锁

蓝牙开锁

当 App 成功连接蓝牙门锁并通过面板进行开锁，设备收到请求后开锁，通过 DP19 上报开锁记录。

数据方向	dp_id （1 字节）	dp_type （1 字节）	dp_data_len （1/2 字节）	dp_data_value
下发	6	raw	len	功能 （1 字节）	成员 ID （1 字节）
				0x00：关锁 0x01：开锁	0x01~0x64
上报	6	raw	len	返回状态 （1 字节）	成员 ID （1 字节）
				0x00：失败 0x01：成功	0x01~0x64

手动关锁

数据方向	dp_id （1 字节）	dp_type （1 字节）	dp_data_len （1/2 字节）	dp_data_value
下发	46	bool	len	固定值 (1 字节)
				0x01：关锁
上报	46	bool	len	返回状态 (1 字节)
				0x00：失败 0x01：成功

远程解锁管理

配置秘钥

• 重点：如果方案 选择了支持配件功能 那么该 DP 会 被 DP73 取代，详见 配件功能 章节。

• 进行远程开锁前，必须先配置远程开锁，一般配网成功后由云端下发。

• 远程解锁 DP61 指令里的 秘钥内容 就是通过 远程解锁设置秘钥 指令进行配置的。

• 该指令中的 是否生效、成员 ID、秘钥生效时间、秘钥失效时间、秘钥使用次数 都是预留的字段，可暂不做处理。

  为更高安全性，远程解锁秘钥会不定期更新，规则由云端控制，使用 n 次后会通过 配置秘钥 DP 重新下发给设备做解锁秘钥更新。

数据 方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
下发	60	raw	len	是否生效 (1 字节)	成员 ID (2 字节)	秘钥生效时间 (4 字节)	秘钥失效时间 (4 字节)	秘钥使用次数 (2 字节)	秘钥内容 (8 字节)
				0x00：失效 0x01：生效	0x01~0x64	unix 时间戳	unix 时间戳	0x0000~0xFFFF 默认 0,永久有效	ASCII 码
上报	60	raw	len	返回状态 (1 字节)			成员 ID (2 字节)
				0x00：成功 0x01：失败			0x01~0x64

远程解锁

远程开锁指的是通过网关的通信链路进行开锁：

• 如果是手机通过网关进行开锁，则称为 手机远程开锁，下发的指令为 DP61。
• 如果是音箱通过网关进行开锁，则称为 语音远程开锁，下发的指令为 DP61。
• 如果是手机直连蓝牙设备进行开锁，则称为 蓝牙近场开锁，下发的指令为 DP6。

数据 方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len （1/2 字节）	dp_data_value
下发	61	raw	len	功能 (1 字节)	成员 ID (2 字节)	秘钥内容 (8 字节)	解锁方式 (2 字节)
				0x00：关锁 0x01：开锁	0x01~0x64	ASCII 码	0x0000：未定义远程开锁 0x0001：手机 app 远程开锁 0x0002：语音音箱远程开锁
上报	61	raw	len	返回状态 (1 字节)			成员 ID (2 字节)
				0x00：成功 0x01：失败 0x02：失效 0x03：秘钥使用次数用完 0x04：密钥不在有效期内 0x05：秘钥对比错误			0x01~0x64

锁相关设置

功能	数据方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
门铃音效	下发/上报	26	enum	len	音效（1 字节）
					0x00：音效 0 …… 0x0A：音效 10
门锁音量	下发/上报	31	enum	len	音量（1 字节）
					门铃音量 DP27 按键音量 DP30 作用与此 DP 相同，已弃用 取值范围
门锁语言 (显示与播报)	下发/上报	28	enum	len	语言（1 字节）
					取值范围
显示屏欢迎词	下发/上报	29	string	len	欢迎词（len 字节）
					0~50bytes
自动落锁开关	下发/上报	33	bool	len	开关（1 字节）
					0x00：关闭 0x01：打开
自动落锁定时	下发/上报	36	value	len	定时时间（s）（4 字节）
					0x00000001~0xFFFFFFFF
单一开锁与 组合开锁设置	下发/上报	34	enum	len	开锁方式的 可能组合（1 字节）
					取值范围
电机转动方向	下发/上报	48	enum	len	转动方向（1 字节）
					0x00：顺时针开 0x01：逆时针开
电机扭力	下发/上报	56	enum	len	电机扭力（1 字节）
					0x00：低扭力 0x01：中扭力 0x02：高扭力
离家布防	下发/上报	58	bool	len	开关（1 字节）
					0x00：关闭 0x01：开启
上锁校验开关	下发/上报	75	bool	len	开关（1 字节）
					0x00：关闭 0x01：打开
勿扰模式开关	下发/上报	76	bool	len	开关（1 字节）
					0x00：关闭 0x01：打开
勿扰模式时间段	下发/上报	77	raw	len	时间段（4 字节）
					HH:MM-HH:MM 每天循环

实时状态上报

功能	数据方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
电量百分比	上报	8	value	len	百分比（4 字节）
					0x00~0x64
电量状态/档位	上报	9	enum	len	档位（1 字节）
					0x00：高电量 0x01：中电量 0x02：低电量 0x03：电量空
童锁状态	上报	10	bool	len	状态（1 字节）
					0x00：童锁关闭 0x01：童锁打开
上提反锁状态	上报	11	bool	len	状态（1 字节）
					0x00：未上提反锁 0x01：已上提反锁
反锁状态	下发/上报	32	bool	len	状态（1 字节）
					0x00：未反锁 0x01：已反锁
门铃提醒	上报	24	bool	len	固定值（1 字节）
					0x00
门开合状态	上报	40	enum	len	状态（1 字节）
					0x00：未知 0x01：门打开 0x02：门关闭
锁开合状态	上报	47	bool	len	状态（1 字节）
					0x00：锁关闭 0x01：锁打开

记录数据上报

告警与解锁记录

功能	数据方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
指纹开锁记录	上报	12	value	len	硬件 ID（4 字节）
					0x00~0xFE
密码开锁记录	上报	13	value	len	硬件 ID（4 字节）
					0x00~0xFE
门卡开锁记录	上报	15	value	len	硬件 ID（4 字节）
					0x00~0xFE
机械钥匙开锁记录	上报	16	value	len	硬件 ID（4 字节）
					0x00~0xFE
人脸开锁记录	上报	39	value	len	硬件 ID（4 字节）
					0x00~0xFE
虹膜开锁记录	上报	41	value	len	硬件 ID（4 字节）
					0x00~0xFE
掌纹开锁记录	上报	42	value	len	硬件 ID（4 字节）
					0x00~0xFE
指静脉开锁记录	上报	43	value	len	硬件 ID（4 字节）
					0x00~0xFE
临时密码开锁记录	上报	55	value	len	硬件 ID（4 字节）
					0x00~0xFE
组合开锁记录 (弃用, 新版请用 DP74）	上报	57	enum	len	开锁方式的 可能组合（1 字节）
					取值范围
蓝牙近场开锁记录	上报	19	value	len	成员 ID（4 字节）
					0x00~0x64
远程手机 App 开锁	上报	62	value	len	成员 ID（4 字节）
					0x00~0x64
远程语音音箱开锁	上报	63	value	len	成员 ID（4 字节）
					0x00~0x64
门从内侧打开记录	上报	18	bool	len	固定值（1 字节）
					0x00
告警记录	上报	21	enum	len	告警原因（1 字节）
					取值范围

关锁记录

数据方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
上报	20	raw	0x05	关锁/落锁方式 (1 字节)	成员 ID (4 字节)
				0x00：未定义 xxx 关锁 0x01：手机远程关锁 0x02：语音远程关锁 0x03：地理围栏关锁 0x04：App 长按关锁 0x05：配件关锁 0x06：自动落锁 0x07：本地手动落锁	0x01~0x64

组合解锁记录(新版)

数据方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
上报	74	raw	len	组合类型 (1 字节)	开锁方式-1 (1 字节)	硬件 ID-1 (1 字节)	开锁方式-2 (1 字节)	硬件 ID-2 (1 字节)
				0x00：单一开锁 0x01：组合开锁	0x01：密码 0x02：门卡 0x03：指纹 0x04：人脸 0x05：掌纹 0x06：指静脉 0xF0：临时密码	0x01~0xFE	0x01：密码 0x02：门卡 0x03：指纹 0x04：人脸 0x05：掌纹 0x06：指静脉 0xF0：临时密码	0x01~0xFE

特殊自定义功能

提供三种类型（布尔、枚举、raw）可自定义配置功能的 DP，您可按设备能力、使用场景自定义使用。

功能	数据方向	dp_id （1 字节）	dp_type （1 字节）	dp_data_len （1/2 字节）	dp_data_value
引导功能	下发	59	raw	len	功能 (1 字节)
					0x00：功能 0 0x01：功能 1 ……
	上报	59	raw	len	功能 (1 字节)	返回状态 (1 字节)
					0x00：功能 0 0x01：功能 1 ……	0x00：成功 0x01：失败
特殊功能	下发/上报	68	enum	len	功能（1 字节）
					0x00：功能 0 0x01：功能 1 ……
特殊控制	下发/上报	78	bool	len	开关（1 字节）
					0x00：关闭 0x01：打开

算法密码

本小节介绍作为开锁方式的算法密码，包括离线密码和动态密码。工作原理大致为：云端与设备端运行相同的算法生成密码与验证密码，当用户输入生成的密码时，设备端验证通过即认为合法，可执行开锁等操作。

动态密码

门锁本地和云端都独立拥有一套完全相同的动态密码生成算法，两者唯一的联系在于 Unix 时间戳。如果门锁本地和云端的 Unix 时间戳相差不超过 300s（±5 分钟），则认为两者生成的动态密码一致，此时门锁本地允许开门。

离线密码

• 使用场景：

  操作人员通过 App 获取离线密码，并告知用户

  • 用户得到 单次密码：6 小时内使用，开门成功，密码失效，并产生一条开门记录。否则 6 小时后失效
  • 用户得到 时效密码：24 小时内使用 1 次，密码激活，时效内都可使用，使用一次产生一条开门记录。24 小时内未使用则失

• 用户得到 清空单条密码：时效性和要清空的那条密码相同，多次使用只有第 1 次生效，产生使用过 清空单条密码的记录

  • 用户得到 清空所有密码：24 小时内使用，清空所有密码，只有 1 次，产生使用过"清空所有密码"的记录。否则 24 小时后失效

• 清空单条密码/所有密码的限制：

  • 只能清空 至少使用过 1 次的时效密码（即激活的时效密码）
  • 不能清空 单次密码，因为单次密码使用 1 次后就失效了

• 使用方式：如是模组通用对接请参考 MCU 对接协议-0xA2 指令。如是 SDK 对接请参考对应接口文档。

相关协议

功能	数据方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
离线密码 设置 T0 时间	下发/上报	64	string	len	T0 时间戳字符串（10 字节）
					unix 时间戳字符串
离线密码 开锁记录	上报	67	raw	len	加密结果（16 字节）
					详见说明
离线密码 清空单条记录	上报	65	raw	len	加密结果（16 字节）
					详见说明
离线密码 清空所有记录	上报	66	raw	len	加密结果（16 字节）
					详见说明
动态密码 开锁记录	上报	14	value	len	硬件 ID（4 字节）
					0xFF：默认值

配件功能

当前蓝牙门锁公版方案默认均需对接新增 DP，因为引入配件（设备类型如蓝牙钥匙、密码盘等）能力后，手机App变相的也理解为一种特殊主机配件。

新增 DP 总览

功能	数据方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
获取记录	无	69	raw	len	见下文
主从机配对	无	70	raw	len
开关锁	无	71	raw	len
开关锁记录	无	72	raw	len
远程解锁配置秘钥	无	73	raw	len

获取记录

背景信息：门锁设备被连接后，如有历史记录，则会主动上报。当增加配件能力后，对于门锁设备来说 无法区分当前被连接的对象 是 App、网关、还是配件。使用逻辑上，不能把历史记录上报给配件（配件没有上云能力）。因此，增加了该条命令用于通知门锁设备上报历史记录。

• 门锁设备被连接时，如有历史记录需上报，则发送 DP 69 告知对端请求上报记录。
• 如果是手机 App 或蓝牙网关连接时，进入面板会回复下发 DP 69 通知门锁子设备。如果是配件连接，则不会回复。

数据方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
上报	69	raw	len	从机 ID (2 字节)		动作 (1 字节)
				0~10000		0x01：请求上报记录
下发	69	raw	len	主机 ID (2 字节)	从机 ID (2 字节)	随机数 (8 字节)	固定值 (1 字节)
				0~10000	0~10000	主机随机数	0x00

主从机配对

主从机配对指的是配件和门锁配对时使用的指令，由手机 App 通过 DP 70 下发给门锁设备，告知门锁待配对主机信息，包括主机 ID 和主机随机数。

• 主机 ID：0xFFFF，代表手机，配对和解绑操作均是通过 App 来发起。
• 从机 ID：云端给门锁分配的从机 ID。
• 随机数：第一次为全 0，后续为云端给手机 App 分配的主机随机数。
• 操作：0x00 表示添加配件，0x01 表示删除配件。
• 待配置主机 ID：云端给手机/配件分配的主机 ID 。第一次待配置主机为手机，后续为配件。
• 待配置主机随机数：云端给手机/配件分配的主机随机数 。第一次待配置主机为手机，后续为配件。

数据方向	dp_id （1 字节）	dp_type （1 字节）	dp_data_len （1/2 字节）	dp_data_value
下发	70	raw	len	主机 ID （2 字节）	从机 ID （2 字节）	随机数 （8 字节）	操作 （1 字节）	待配置主机 ID （2 字节）	待配置主机随机数 （8 字节）
				0-10000	0-10000	主机随机数	0x00：添加 0x01：删除	0-10000	说明
上报	70	raw	len	从机 ID （2 字节）	主机 ID （2 字节）	随机数 （8 字节）	操作 （1 字节）	待配置主机 ID （2 字节）	返回状态 （1 字节）
				0-10000	0-10000	主机随机数	0x00：添加 0x01：删除	0-10000	取值范围

开关锁

• 如果选用了该 DP，就不允许再使用 DP 6，否则会导致设备的操作变得不安全。
• 无论通过手机还是配件去操作开/关门锁，均需使用该 DP 指令。
• 使用开关锁指令时，门锁端需要校验 主机 ID、从机 ID 和 随机数的合法性，才能保证安全。
• 开关锁时间戳、开关锁方式 和 开关锁信息 是配件下发的信息，门锁端只需要通过 DP72 原样上报即可，可以理解为门锁代理上报配件操作记录。

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

开关锁记录

• 开关锁记录指令是门锁上报给手机的 DP。
• 开关锁时间戳、开关锁方式 和 开关锁信息 是配件在 开关锁 操作时通过 DP71 下发给门锁的信息。门锁端只需要按 DP72 格式，通过记录型数据上报即可，可理解为门锁代理上报配件操作记录。

数据方向	dp_id （1 字节）	dp_type （1 字节）	dp_data_len （1/2 字节）	dp_data_value
上报	72	raw	len	从机 ID （2 字节）	主机 ID （2 字节）	随机数 （8 字节）	操作 （1 字节）	开关锁 时间戳 （4 字节）	开关锁 方式 （1 字节）	开关锁 信息 （len 减 18 字节）
				0-10000	0-10000	主机随机数	0x00：关锁 0x01：开锁	说明	说明	说明

远程解锁配置秘钥

• 如果选用了该 DP，就不允许再使用 dp_id = 60 的 DP，否则会导致设备的操作变得不安全。
• 进行远程开锁前，必须先配置远程解锁秘钥给设备，一般配网成功后由云端下发。
• 远程解锁 DP61 指令里的 秘钥内容 就是通过 远程解锁设置秘钥 指令进行配置的。
• 该指令中的 是否生效、成员 ID、秘钥生效时间、秘钥失效时间、秘钥使用次数 都是预留的字段，可暂不做处理。

数据方向	dp_id （1 字节）	dp_type （1 字节）	dp_data_len （1/2 字节）	dp_data_value
下发	73	raw	len	主机 ID （2 字节）	从机 ID （2 字节）	随机数 （8 字节）	是否生效 （1 字节）	成员 ID （2 字节）	秘钥 生效时间 （4 字节）	秘钥 失效时间 （4 字节）	秘钥 使用次数 （2 字节）	秘钥内容 （8 字节）
				0-10000	0-10000	主机 随机数	0x00：失效 0x01：生效	0x01-0x64	Unix 时间戳 （同附录 1）	Unix 时间戳 （同附录 1）	0x0000 -0xFFFF	ASCII 码
上报	73	raw	len	从机 ID （2 字节）	主机 ID （2 字节）	随机数 （8 字节）	是否生效 （1 字节）	成员 ID （2 字节）	返回状态 （1 字节）
				0-10000	0-10000	主机 随机数	0x00：失效 0x01：生效	0x01-0x64	取值范围

蓝牙靠近解锁功能

前置条件：需要地理围栏功能，Android 手机需要有 GMS 框架（Google 服务）或华为国际包支持 HMS。

设备端：蓝牙门锁持续周期发送广播包

App 端：设置地理围栏后，当用户走进围栏会唤起应用，当走进到门锁一定范围内，收到门锁广播包，连上设备，下发开锁指令，开锁成功后再断开门锁连接。

功能	数据方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
靠近解锁记录	上报	86	value	len	成员 id(4 字节)
					0x00~0x64
扫描超时	无	87	enum	len	仅 app 使用，设备无需关心
靠近解锁 rssi 值	无	88	enum	len	仅 app 使用，设备无需关心
靠近解锁落锁延时	下发/上报	89	enum	len	延时枚举值(1 字节)
					0x00：不启用，维持原有自动落锁逻辑 0x01：4 秒 0x02：6 秒 0x03：8 秒 0x04：10 秒 0x05：12 秒 0x06：15 秒 0x07：20 秒 0x08：30 秒 0x09：60 秒
靠近解锁使能	下发/上报	90	bool	len	状态(1 字节)
					0x00：关闭 0x01：开启

冻结解冻用户

• 冻结和解冻的对象为其他成员（包含分享用户）。

• 家庭所有者和管理员都可对其他成员进行冻结/解冻。

• 为了保持和本地的一致性，冻结/解冻指令仅在设备处于连接状态时才能在面板上操作。

• 一旦冻结后，该成员下的所有开门方式都将被冻结，除非解冻。

• 一旦冻结后，成员对开门方式的增删改等操作也没有权限，除非解冻。

• 一旦冻结后，家庭所有者和管理员唯一可对其进行的操作就是解冻。

  公版方案目前暂不支持，暂可不对接具体功能。

功能	数据方向	dp_id (1 字节)	dp_type (1 字节)	dp_data_len (1/2 字节)	dp_data_value
冻结用户	下发/上报	49	value	len	成员 ID (4 字节)
					0x01~0x64
解冻用户	下发/上报	50	value	len	成员 ID (4 字节)
					0x01~0x64

仅云端用的 DP

功能	数据方向	dp_id （1 字节）	dp_type （1 字节）	dp_data_len （1/2 字节）	dp_data_value
短信通知	无	25	bool	len	无
劫持报警	无	22	bool	len	无
硬件时钟 RTC	无	44	bool	len	无

附录 1-时效性

字节	含义	说明	举例
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:00 到 2018-08-08 09:56:32 期间内，每周一至周五的早上 8:00 到 8:30 生效，则时效性为 0x 5A6A6F80 5B6A4DD0 02 0000003E 0800 081E：

• 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