网关业务协议

本文档定义基于ESP32的鑫泓佳网关的业务通信协议。

协议概述

网关业务协议基于FDP-P2P通信模型实现,通过MQTT进行消息传输。

本协议必须使用以下MQTT主题：

主题	用途	说明
`{namespace}/{username}/pending`	发送命令	APP/服务端向网关发送业务指令
`{namespace}/{username}/ack`	确认收到命令	网关收到命令后发送确认消息
`{namespace}/{username}/complete`	命令执行结果	网关返回命令执行结果（成功或失败）

其他主题（如 progress、failed、status 等）可根据后续功能扩展需要自行使用。

指令列表

1. 扫描附近设备列表

扫描网关周围的蓝牙设备。

action: scan_devices

请求 value 参数：

json

{
  "credential": {
    "secret": "550e8400-e29b-41d4-a716-446655440000"
  },
  "duration": 10
}

字段	类型	必填	说明
credential	对象	是	网关凭证
credential.secret	字符串	是	配网时获得的密钥
duration	整型	否	扫描时长(秒),默认10秒,范围5-30秒

响应 value 数据：

json

{
  "devices": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "name": "TMH_51a33a754edc",
      "rssi": -45
    },
    {
      "mac": "11:22:33:44:55:66",
      "name": "TMH_51a33a754edc",
      "rssi": -58
    }
  ]
}

字段	类型	必填	说明
devices	数组	是	设备列表
devices[].mac	字符串	是	设备MAC地址
devices[].name	字符串	是	设备名称
devices[].rssi	整型	是	信号强度(dBm)

2. 绑定设备

将扫描到的智能锁设备绑定到网关。网关收到设备列表后,仅需存储设备信息和密钥,无需进行实际的蓝牙连接操作。

action: bind_devices

请求 value 参数：

json

{
  "credential": {
    "secret": "550e8400-e29b-41d4-a716-446655440000"
  },
  "devices": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "name": "TMH_51a33a754edc",
      "public_key": "0102030405060708090A0B0C0D0E0F10",
      "private_key": "1112131415161718191A1B1C1D1E1F20",
      "sign_key": "2122232425262728292A2B2C2D2E2F30"
    },
    {
      "mac": "11:22:33:44:55:66",
      "name": "TMH_51a33a754edc",
      "public_key": "3132333435363738393A3B3C3D3E3F40",
      "private_key": "4142434445464748494A4B4C4D4E4F50",
      "sign_key": "5152535455565758595A5B5C5D5E5F60"
    }
  ]
}

字段	类型	必填	说明
credential	对象	是	网关凭证
devices	数组	是	设备列表
devices[].mac	字符串	是	设备MAC地址
devices[].name	字符串	否	设备名称
devices[].public_key	字符串	是	设备公钥,16字节十六进制字符串(32字符)
devices[].private_key	字符串	是	设备私钥,16字节十六进制字符串(32字符)
devices[].sign_key	字符串	是	签名密钥,16字节十六进制字符串(32字符)

密钥说明

这三个密钥用于网关与智能锁的蓝牙通信加密: 密钥由APP在绑定智能锁时通过蓝牙从锁中读取,然后传递给网关存储。网关无需连接设备，实际的蓝牙连接在执行开门、关门等业务指令时按需建立。

响应 value 数据：

json

{}

3. 添加用户

添加设备用户。

action: add_user

请求 value 参数：

json

{
  "credential": {
    "secret": "550e8400-e29b-41d4-a716-446655440000"
  },
  "device_mac": "AA:BB:CC:DD:EE:FF",
  "is_permanent": true,
  "start_date": 1710000000,
  "end_date": 1710000000,
  "use_count": 0xFFFF,
  "is_round": false,
  "week_days": [1,2,3],
  "start_time": "08:00",
  "end_time": "09:00",
  "role": 1,
  "password": "123456"
}

字段	类型	必填	说明
credential	对象	是	网关凭证
credential.secret	字符串	是	配网时获得的密钥
device_mac	字符串	是	目标设备MAC地址
is_permanent	布尔	是	是否永久生效,true=永久,false=临时
start_date	整型	否	生效开始时间戳(秒),is_permanent为false时必填
end_date	整型	否	生效结束时间戳(秒),is_permanent为false时必填
use_count	整型	是	使用次数限制,0xFFFF表示无限制
is_round	布尔	是	是否循环,true=启用循环,false=不循环
week_days	数组	否	循环的星期,is_round为true时必填,值为1-7(周一到周日)
start_time	字符串	否	循环的每日开始时间,格式"HH:MM",is_round为true时必填
end_time	字符串	否	循环的每日结束时间,格式"HH:MM",is_round为true时必填
role	整型	是	用户角色，1=超级管理员，2=管理员，3=普通用户
password	字符串	是	用户密码

响应 value 数据：

json

{
  "status": 0,
  "no": 100
}

字段	类型	必填	说明
status	整型	是	0=成功，255=失败
error	字符串	否	错误描述（status为255时必填）
no	整型	是	用户编号

错误描述

错误描述会直接展示给用户，请务必返回清晰、易懂的中文提示信息。

示例： 网关未搜索到该设备，请确保设备在网关范围内后重试

4. 开门

控制门锁开启或关闭。

action: open_lock

请求 value 参数：

json

{
  "credential": {
    "secret": "550e8400-e29b-41d4-a716-446655440000"
  },
  "device_mac": "AA:BB:CC:DD:EE:FF",
  "user_id": 1001,
  "online_token": "a1b2c3d4e5f6g7h8",
  "time": 1710000000,
  "operation": 1
}

字段	类型	必填	说明
credential	对象	是	网关凭证
device_mac	字符串	是	目标设备MAC地址
user_id	整型	是	星云用户ID,用于操作日志记录
online_token	字符串	是	联网TOKEN,无需校验时回复空字符串
time	整型	是	当前时间戳(秒)
operation	整型	是	1=开门，2=关门

响应 value 数据：

json

{
  "status": 0,
  "power": 100
}

字段	类型	必填	说明
status	整型	是	0=成功，255=失败
error	字符串	否	错误描述（status为255时必填）
power	整型	是	设备电量

错误描述

错误描述会直接展示给用户，请务必返回清晰、易懂的中文提示信息。

示例： 网关未搜索到该设备，请确保设备在网关范围内后重试

5. 解绑网关

解除网关的绑定。网关收到解绑请求后,清除本地储存信息，恢复出厂设置。

action: unbind_gateway

请求 value 参数：

json

{
  "credential": {
    "secret": "550e8400-e29b-41d4-a716-446655440000"
  }
}

字段	类型	必填	说明
credential	对象	是	网关凭证
credential.secret	字符串	是	配网时获得的密钥

响应 value 数据：

json

{}

6. 获取设备信息

获取网关的设备信息，包括固件版本、蓝牙MAC地址等。

action: device_info

请求 value 参数：

json

{
  "credential": {
    "secret": "550e8400-e29b-41d4-a716-446655440000"
  }
}

字段	类型	必填	说明
credential	对象	是	网关凭证
credential.secret	字符串	是	配网时获得的密钥

响应 value 数据：

json

{
  "bluetooth_mac": "3c:84:27:c1:5d:00",
  "firmware_version": "1.0.0",
  "model": "XHJ-Gateway",
  "serial_number": "GW01_c39eae",
  "network_mac": "aa:bb:cc:dd:ee:ff"
}

字段	类型	必填	说明
bluetooth_mac	字符串	是	蓝牙MAC地址
firmware_version	字符串	是	固件版本号
model	字符串	是	设备型号
serial_number	字符串	是	设备序列号
network_mac	字符串	是	网络MAC地址

7. OTA升级

对网关进行固件OTA升级。升级过程中，网关需通过 {namespace}/{username}/progress 主题发送升级进度。

action: ota

请求 value 参数：

json

{
  "credential": {
    "secret": "550e8400-e29b-41d4-a716-446655440000"
  },
  "url": "https://example.com/firmware/v1.2.4.bin",
  "version": "1.2.4",
  "size": 1048576,
  "md5": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

字段	类型	必填	说明
credential	对象	是	网关凭证
credential.secret	字符串	是	配网时获得的密钥
url	字符串	是	固件下载地址
version	字符串	是	固件版本号
size	整型	是	固件文件大小(字节)
md5	字符串	否	固件文件MD5值，用于校验

响应 value 数据：

json

{
  "status": 0
}

字段	类型	必填	说明
status	整型	是	0=成功，255=失败
error	字符串	否	错误描述（status为255时必填）

error 说明

常见的错误描述包括：

"下载失败" - 固件下载失败，请检查设备网络连接后重试
"安装失败" - 固件安装失败，请稍后重试

APP收到status: 255时，应将error字符串显示给用户。

8. 清理设备用户

清理设备上的指定用户。

action: clean_user

请求 value 参数：

json

{
  "credential": {
    "secret": "550e8400-e29b-41d4-a716-446655440000"
  },
  "device_mac": "AA:BB:CC:DD:EE:FF",
  "user_id_list": [100, 101, 102]
}

字段	类型	必填	说明
credential	对象	是	网关凭证
credential.secret	字符串	是	配网时获得的密钥
device_mac	字符串	是	目标设备MAC地址
user_id_list	数组	是	要清理的用户编号列表

响应 value 数据：

json

{
  "status": 0
}

字段	类型	必填	说明
status	整型	是	0=成功，255=失败
error	字符串	否	错误描述（status为255时必填）

错误描述

错误描述会直接展示给用户，请务必返回清晰、易懂的中文提示信息。

网关业务协议 ​

协议概述 ​

指令列表 ​

1. 扫描附近设备列表 ​

2. 绑定设备 ​

3. 添加用户 ​

4. 开门 ​

5. 解绑网关 ​

6. 获取设备信息 ​

7. OTA升级 ​

8. 清理设备用户 ​

网关业务协议

协议概述

指令列表

1. 扫描附近设备列表

2. 绑定设备

3. 添加用户

4. 开门

5. 解绑网关

6. 获取设备信息

7. OTA升级

8. 清理设备用户