鑫泓佳网关集成指南

本文档介绍如何将基于ESP32的鑫泓佳网关集成到业务系统中。

产品简介

鑫泓佳网关是一款基于ESP32的智能网关设备,主要功能包括:

• ✅ WiFi+蓝牙双模: 通过WiFi连接云端,通过蓝牙连接智能锁
• ✅ 远程控制: 支持通过云端远程控制门锁开关
• ✅ 设备管理: 扫描、绑定和管理多个蓝牙智能锁
• ✅ 密码管理: 远程添加临时/永久密码
• ✅ 状态监控: 实时查询门锁电量和状态

集成架构

架构说明

• 业务系统可选: 本架构支持无服务端运行,APP可以直接与网关通信
• APP直连MQTT: 所有业务指令由APP直接通过MQTT发送到网关,不经过后端转发
• 后端作用: 如果有后端,主要用于凭证存储、权限管理、操作审计,而非指令转发

集成流程

第一步: APP给网关配网

使用GATT配网协议完成网关的初始化配置。

配网流程包括:

1. APP扫描并连接网关设备,通过128位UUID识别:
   • 扫描时过滤UUID前缀为01758825的设备
   • 确保设备为未配网状态(参考设备广播规范)
2. 配网状态检查(check_status)
3. 配网绑定(provision),配网完成后获得网关凭证(credential.secret)

重要

1. APP端：配网完成后获得的credential.secret是操作网关的唯一凭证,拥有该凭证即拥有网关的完全控制权,务必妥善保管。

2. 网关端：在配网绑定时,APP下发的config配置中包含eventReportUrl和gatewayEventReportUrl字段,用于事件上报的API地址,网关需要保存该地址,后续智能锁的事件将通过该地址上报到业务系统

第二步: 使用网关业务协议

通过网关业务协议与网关进行通信。

重要

无论有无后端,业务指令始终由APP直接发送到MQTT,不经过后端转发。后端的作用仅限于凭证存储、权限管理和操作审计。

事件发现机制

网关通过扫描门锁的蓝牙广播来发现是否有新事件需要上报。

工作原理

事件标志位

网关通过检查门锁UUID广播中的特定bit位来判断是否有新事件:

UUID格式	标志位位置	检查方式	含义
32位UUID	字节1 [0], bit 1	(uuid[0] & 0x02) >> 1	1=有新事件
128位UUID	字节12 [11], bit 1	(uuid[11] & 0x02) >> 1	1=有新事件

详细说明

完整的UUID字节结构请参考蓝牙广播规范

触发条件

网关读取门锁事件需同时满足以下条件:

1. 设备识别: UUID厂商标识为鑫泓佳门锁
   • 32位UUID: 字节4为 0x77（鑫泓佳）或 0x75（公版，兼容早期出货设备）
   • 128位UUID: 字节13~15为 24 88 77（鑫泓佳）或 24 88 75（公版，兼容早期出货设备）
2. 事件标志: has_new_event bit为 1
   • 32位UUID: (uuid[0] & 0x02) >> 1 == 1
   • 128位UUID: (uuid[11] & 0x02) >> 1 == 1
3. 防重复: 设备不在黑名单中(60秒内已读取过的设备会被临时加入黑名单)

读取范围

网关每次读取门锁前30分钟内产生的事件记录。

锁事件上报

1. 请求链接: 通过前面APP配网完成后，获取到的config字段对象中的eventReportUrl字段值，作为请求链接

2. 请求方式: POST

3. 请求头:

名称	类型	是否必需	示例	描述
Authorization	string	Y	"Bearer 1234567890"	使用设备凭证密钥 secret

4. 参数说明:

名称	类型	是否必需	示例	描述
lockMac	String	Y	"01:02:03:04:05:06"	锁MAC地址
records	array	Y	[]	事件记录
records[].type	int	Y	1	事件类型
records[].user_no	int	Y	1	门锁用户No
records[].success	int	Y	1	是否成功 1成功 0失败
records[].password	string	N	"123456"	密码
records[].timestamp	int	N	1769159553	操作记录时间戳

4. 返回参数及示例:

参数	类型	描述
errcode	int	错误码
errmsg	string	错误信息
description	string	详细描述
data	object	返回数据
data.lastRecordTime	int	最后一条记录的时间戳

{
  "errcode": 0,
  "errmsg": "success",
  "description": "success",
  "data": {
    "lastRecordTime": 1769159553
  }
}

网关事件上报

1. 请求链接: 通过前面APP配网完成后，获取到的config字段对象中的gatewayEventReportUrl字段值，作为请求链接

2. 请求方式: POST

3. 请求头:

名称	类型	是否必需	示例	描述
Authorization	string	Y	"Bearer 1234567890"	使用设备凭证密钥 secret

4. 参数说明:

名称	类型	是否必需	示例	描述
event_type	int	Y	1	事件类型 1:网关状态 2:网关重置
status	string	N	"online"	网关状态 online:在线 offline:离线 事件类型为1时必填写

网关状态上报

在线：网关通电后并且非重置状态，需上报或mqtt连接完成后上报 重置：网关重置按钮触发后上报

4. 返回参数及示例:

参数	类型	描述
errcode	int	错误码
errmsg	string	错误信息
description	string	详细描述
data	object	返回数据
data.lastRecordTime	int	最后一条记录的时间戳

{
  "errcode": 0,
  "errmsg": "success",
  "description": "success",
  "data": {}
}