星图 WiFi 配网
本文档介绍星图设备的蓝牙配网协议，用于将 WiFi+蓝牙网关或带 WiFi 功能的门锁接入星图网络。
相关项目
星云项目组 / 星图互联-服务端 · GitLab 是星云智能锁业务的分布式通信架构，基于以下核心组件：
- SCD - 中央服务器，提供设备发现和注册服务
- SCRD - 中继服务器，支持 NAT 穿透和消息转发
- SLS1 协议 - 基于 UDP 的点对点通信协议
星图 WiFi 配网的目的是通过蓝牙将 WiFi 参数和星图服务器信息下发给设备，使设备能够连接 WiFi 并注册到星图中央服务器。
功能概述
星图设备通常使用基于 UDP 的星图专用网络协议进行通信，但在设备初始化阶段需要先使用蓝牙协议进行配置。
适用设备/平台：
- 芯连的WIFI锁
- 芯连的ESP32方案网关
- 代号XB007的腾讯方案门锁（计划迁移到FD配网）
不适用：
- 蓝牙门锁：它无需配网
- 鑫泓佳的ESP32网关：它使用FD配网
已废弃的对讲WiFi配网协议
早期对讲锁项目使用另一套配网协议，现已完全废弃，详见 对讲WiFi配网。
配网流程
获取设备状态
指令码: 0x30F8
方向: APP → 设备
加密: SM4 私钥模式
请求消息
| 字段名称 | 字段类型 | 字段长度 | 字段说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID |
| LockID | 字符串 | 40 | 锁 ID |
| UserID | 字符串 | 20 | 用户 ID |
应答消息
| 字段名称 | 字段类型 | 字段长度 | 字段说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID |
| Status | 整型 | 1 | 处理状态 |
| BluetoothMac | 字符串 | 20 | 蓝牙 MAC 地址 |
| SerialNum | 字符串 | 20 | 序列号 |
| Version | 字符串 | 20 | 固件版本 |
| NetworkCardMac | 字符串 | 20 | 网卡 MAC 地址 |
搜索 2.4G WiFi
指令码: 0x30F6
方向: APP → 设备
加密: SM4 私钥模式
请求消息
| 字段名称 | 字段类型 | 字段长度 | 字段说明 |
|---|---|---|---|
| UserID | 字符串 | 20 | 用户 ID |
应答消息
| 字段名称 | 字段类型 | 字段长度 | 字段说明 |
|---|---|---|---|
| Status | 整型 | 1 | 0=成功，其它=失败 |
说明
收到此命令后，设备将扫描 4 秒钟后返回结果。
WiFi 搜索结果
指令码: 0x30F7
方向: 设备 → APP
加密: SM4 私钥模式
请求消息
| 字段名称 | 字段类型 | 字段长度 | 字段说明 |
|---|---|---|---|
| Status | 整型 | 1 | 0=成功，0xFF=失败 |
| NumberOfSsid | 整型 | 1 | SSID 数量 |
| SSID | 字符串 | 32 | WiFi 名称 |
| RSSI | 整型 | 1 | 信号强度（如 -40dB） |
| ... | 混合 | (32+1)×N | 多组 SSID 信息 |
设备配网
指令码: 0x30F4
方向: APP → 设备
加密: SM4 私钥模式
请求消息
| 字段名称 | 字段类型 | 字段长度 | 字段说明 |
|---|---|---|---|
| SSID | 字符串 | 30 | WiFi 名称 |
| Password | 字符串 | 20 | WiFi 密码 |
| ConfigureJsonLength | 整型 | 2 | 配置 JSON 字符串长度 |
| ConfigureJson | 字符串 | 变长 | 网络配置字符串，从服务器获取 |
ConfigureJson 格式
json
{
"starcloudRpcPeerId": "1234567890abcdefg00000000000000000000000000",
"starcloudReportPeerId": "1234567890abcdefg000000000000000000000000001",
"starcloudUrl": "http://local.cloud.star-lock.cn",
"scdUrl": "http://sls1-scd.star-lock.cn:8710",
"starlockPeerId": "1234567890abcdefg000000000000000000000000002",
"clientId": "1OQRV3FN4Fk8FaEZKSF2Xx6O3UJOOip0",
"secretKey": "090icLDU9WzAZJkeEb",
"userPeerId": "FhxHuQMPWeLX77Lt7hFdQpxP5KNokqS75AFtHB6bbbo5"
}| 字段 | 说明 |
|---|---|
| starcloudRpcPeerId | 星云下发指令使用的 PeerId，设备需验证发送来源 |
| starcloudReportPeerId | 设备事件上报和对讲呼叫 APP 推送使用的 PeerId |
| starcloudUrl | 设备向星云发起 HTTP 请求使用的 URL（暂未使用） |
| scdUrl | 星图发现服务器 URL |
| starlockPeerId | 星锁后台的 PeerId（暂未使用） |
| clientId | 客户端标识 |
| secretKey | 身份验证密钥，类似于 Token |
| userPeerId | APP 对讲使用的 PeerId |
重要
设备需要将这些字段全部存储，后续通信会用到。
应答消息
| 字段名称 | 字段类型 | 字段长度 | 字段说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID |
| Status | 整型 | 1 | 处理状态 |
设备配网结果
指令码: 0x30F5
方向: 设备 → APP
加密: SM4 私钥模式
请求消息
| 字段名称 | 字段类型 | 字段长度 | 字段说明 |
|---|---|---|---|
| Status | 整型 | 1 | 0=成功，0xFF=失败 |
| DeviceJsonLength | 整型 | 2 | DeviceJson 长度 |
| DeviceJson | 字符串 | 变长 | 设备配网结果 |
DeviceJson 格式
json
{
"peerId": "AYzRsyaj9h4wbibCzJZE7Gki3pedTqz27QgFBfGPsYCp",
"secretKey": "090icLDU9WzAZJkeEb"
}| 字段 | 说明 |
|---|---|
| peerId | 设备在星图发现服务器注册得到的 ID |
| secretKey | 身份验证密钥，可自行随机生成或由 APP 配网时传入 |
更换网络
指令码: 0x30F9
方向: APP → 设备
加密: SM4 私钥模式
使用场景
用于已配网设备更换 WiFi 网络。
请求消息
| 字段名称 | 字段类型 | 字段长度 | 字段说明 |
|---|---|---|---|
| SSID | 字符串 | 30 | WiFi 名称 |
| Password | 字符串 | 20 | WiFi 密码 |
| Token | 整型 | 4 | 动态口令 |
| AuthCodeLen | 整型 | 1 | 鉴权码长度 |
| AuthCode | 字符串 | 变长 | 鉴权码 |
应答消息
| 字段名称 | 字段类型 | 字段长度 | 字段说明 |
|---|---|---|---|
| CmdID | 整型 | 2 | 指令 ID |
| Token | 整型 | 4 | 动态口令 |
| Status | 整型 | 1 | 处理状态 |
指令汇总
| 指令码 | 名称 | 方向 | 说明 |
|---|---|---|---|
| 0x30F8 | 获取设备状态 | APP → 设备 | 获取 MAC、版本等信息 |
| 0x30F6 | 搜索 2.4G WiFi | APP → 设备 | 启动 WiFi 扫描 |
| 0x30F7 | WiFi 搜索结果 | 设备 → APP | 返回扫描到的 WiFi 列表 |
| 0x30F4 | 设备配网 | APP → 设备 | 配置 WiFi 和星图参数 |
| 0x30F5 | 配网结果 | 设备 → APP | 返回配网结果和设备 PeerId |
| 0x30F9 | 更换网络 | APP → 设备 | 更换已配网设备的 WiFi |