绑定指令

绑定是用户获取设备控制权的过程。绑定成功后，APP获得设备Owner用户的 userSecret，即可通过协议指令控制设备。

关于 userSecret 的详细说明，请参考数据结构 - 用户。

绑定流程

发现设备：通过BLE扫描、二维码、NFC获取 serialNum0（参见设备发现）
BLE连接：通过 serialNum0 找到设备并建立BLE连接
获取userSecret：调用 GetBindingInfo 指令获取 userSecret
保存凭证：将 userSecret 安全存储到本地和云端
WiFi配网（可选）：如设备有WiFi模块，调用 ConfirmBinding 时配置WiFi
完成绑定：调用 ConfirmBinding 完成绑定

协议与传输分离

本协议的指令不绑定特定传输渠道。无论通过蓝牙还是WiFi/MQTT发送指令，协议格式完全相同。

获取绑定信息

查询设备的基本信息和绑定状态。未绑定的设备会返回 userSecret。

指令码	指令名	方向	鉴权
`0x0100`	GetBindingInfo	APP → 设备	无需鉴权

请求参数

无参数。

响应参数

字段	类型	必填	说明
model	string	是	设备型号
firmwareVersion	string	是	固件版本号
mac	string	是	设备MAC地址
bound	bool	是	是否已绑定
ownerUserId	uint32	否	Owner用户ID（仅 bound=false 时返回）
userSecret	bytes	否	Owner用户密钥（仅 bound=false 时返回）

关于 model 的详细说明，请参考数据结构 - 产品与规格。

关于 userSecret 的详细说明，请参考数据结构 - 用户。

响应示例

未绑定设备：

json

{
  "model": "SL-X100",
  "firmwareVersion": "2.1.0",
  "mac": "AA:BB:CC:DD:EE:FF",
  "bound": false,
  "ownerUserId": 1,
  "userSecret": "a1b2c3d4e5f6..."
}

已绑定设备：

json

{
  "model": "SL-X100",
  "firmwareVersion": "2.1.0",
  "mac": "AA:BB:CC:DD:EE:FF",
  "bound": true
}

设备内置Owner用户

设备出厂时已内置一个Owner用户，绑定时直接返回该用户的 userSecret。解绑/恢复出厂时会重置Owner用户并生成新的 userSecret。

WiFi扫描（可选）

此指令为可选实现，允许APP获取设备周围的WiFi列表，供用户选择要连接的网络。

适用范围

仅适用于具有WiFi模块的设备。

设计原因

手机可扫描到的WiFi网络，设备不一定支持。例如：

5GHz WiFi网络（部分设备仅支持2.4GHz）
特定加密方式（如WPA3，部分单片机不支持）
企业级认证（如802.1X）

通过设备端扫描，仅展示设备实际可连接的WiFi网络，可显著提升配网成功率。

指令码	指令名	方向	鉴权	超时
`0x0E01`	ScanWiFi	APP → 设备	无需鉴权	15秒

请求参数

无参数。

响应参数

字段	类型	必填	说明
code	uint32	是	状态码，0=成功
networks	array	是	WiFi网络列表
networks[].ssid	string	是	WiFi名称
networks[].rssi	int8	是	信号强度（dBm）

响应示例

json

{
  "code": 0,
  "networks": [
    {
      "ssid": "HomeWiFi",
      "rssi": -40
    },
    {
      "ssid": "Office-Network",
      "rssi": -65
    }
  ]
}

实现建议

设备收到扫描请求后，建议扫描时长为4-6秒
RSSI值为负数，数值越大信号越强（如-40优于-65）
建议按信号强度降序排列网络列表
重复的SSID应去重，保留信号最强的

完成绑定

APP获取到 userSecret 后，调用此指令完成绑定流程。如设备有WiFi模块，可同时配置WiFi连接。

指令码	指令名	方向	鉴权	超时
`0x0101`	ConfirmBinding	APP → 设备	userSecret	30秒

请求参数

字段	类型	必填	说明
timestamp	uint32	是	当前时间戳（秒），用于设置设备时间
wifi	object	否	WiFi配置（有WiFi模块的设备可选）
wifi.ssid	string	是	WiFi名称
wifi.password	string	是	WiFi密码，开放网络传空字符串
mqtt	object	否	MQTT配置（需连接云端时填写）
mqtt.broker	string	是	MQTT服务器地址，格式：`mqtt://host:port`
mqtt.clientId	string	是	客户端ID
mqtt.username	string	是	用户名
mqtt.password	string	是	密码

请求示例

纯蓝牙设备：

json

{
  "timestamp": 1710000000
}

WiFi设备（仅配置WiFi）：

json

{
  "timestamp": 1710000000,
  "wifi": {
    "ssid": "HomeWiFi",
    "password": "wifi_password"
  }
}

WiFi设备（配置WiFi和MQTT）：

json

{
  "timestamp": 1710000000,
  "wifi": {
    "ssid": "HomeWiFi",
    "password": "wifi_password"
  },
  "mqtt": {
    "broker": "mqtt://iot.example.com:1883",
    "clientId": "lock_AABBCCDDEEFF",
    "username": "device_user",
    "password": "device_pass"
  }
}

响应参数

字段	类型	必填	说明
code	uint32	是	状态码，0=成功
message	string	否	错误描述（失败时返回）
ip	string	否	获取到的IP地址（WiFi配网成功时返回）

响应示例

成功（纯蓝牙）：

json

{
  "code": 0
}

成功（WiFi）：

json

{
  "code": 0,
  "ip": "192.168.1.100"
}

失败：

json

{
  "code": 1001,
  "message": "WiFi密码错误"
}

绑定效果

设备标记为已绑定（广播中 bound=1）
设备时间已同步
WiFi设备已连接网络（如配置）

解除绑定

解除当前 APP 与设备的绑定关系，设备数据保留。

指令码	指令名	方向	鉴权
`0x0102`	Unbind	APP → 设备	userSecret（Owner权限）

请求参数

无参数。

响应参数

字段	类型	必填	说明
code	uint32	是	状态码，0=成功

解绑效果

重置Owner用户，生成新的 userSecret
设备恢复到未绑定状态（广播中 bound=0）
保留所有其他用户
保留所有凭证（密码、指纹等）
保留WiFi配置
保留功能设置

适用场景

解绑适用于转让设备给他人时保留已录入的凭证和设置。新用户绑定后可继续使用原有数据。

如需彻底清除所有数据，请使用恢复出厂设置。

错误码

错误码	说明
0	成功
1001	WiFi连接失败
1002	WiFi密码错误
1003	MQTT连接失败
1004	已绑定，无法重复绑定
1005	权限不足

绑定指令 ​

绑定流程 ​

获取绑定信息 ​

请求参数 ​

响应参数 ​

响应示例 ​

WiFi扫描（可选） ​

请求参数 ​

响应参数 ​

响应示例 ​

完成绑定 ​

请求参数 ​

请求示例 ​

响应参数 ​

响应示例 ​

绑定效果 ​

解除绑定 ​

请求参数 ​

响应参数 ​

解绑效果 ​

错误码 ​

绑定指令

绑定流程

获取绑定信息

请求参数

响应参数

响应示例

WiFi扫描（可选）

请求参数

响应参数

响应示例

完成绑定

请求参数

请求示例

响应参数

响应示例

绑定效果

解除绑定

请求参数

响应参数

解绑效果

错误码