腾讯云猫眼锁集成指南

本文档介绍如何将FDP协议与腾讯云物联网平台集成，实现智能门锁等设备的云端控制。

平台简介

腾讯云物联网开发平台（IoT Explorer）提供：

• 设备接入与管理
• MQTT消息通信
• 物模型定义
• 微信小程序对接

架构概览

配网说明

配网数据结构

通过蓝牙配网向设备传入的configureJson：

{
  "deviceName": "DEV123456789",
  "devicePsk": "aB3CdE5fGhI7jKlMnOpQrS==",
  "productId": "PRODUCTID01",
  "modelId": "xYz9AbCdEfGhIjKlMnOpQr",
  "mqttBroker": "PRODUCTID01.iotcloud.tencentdevices.com",
  "mqttPort": 1883,
  "mqttClientId": "PRODUCTID01DEV123456789",
  "mqttUsername": "PRODUCTID01DEV123456789;12345678;ABCDE;1234567890",
  "mqttPassword": "1a2b3c4d...;hmacsha256",
  "mqttVersion": "3.1.1"
}

字段说明

设备基本信息

字段	说明
deviceName	腾讯云三元组-设备名称
devicePsk	腾讯云三元组-设备密钥（Base64编码）
productId	腾讯云三元组-产品ID
modelId	硬件型号ID

MQTT连接配置

字段	说明
mqttBroker	MQTT代理服务器地址
mqttPort	MQTT服务器端口
mqttClientId	MQTT客户端ID（格式：产品ID + 设备名称）
mqttUsername	MQTT用户名（多参数分号分隔）
mqttPassword	MQTT连接密码（格式：密码哈希值;签名方法）
mqttVersion	MQTT协议版本

MQTT连接

连接端口

连接方式	端口
TCP	1883
TLS	8883
WebSocket	wss://host/mqtt

推荐配置

• 使用MQTT 5.0支持遗嘱消息
• 使用TLS保证传输安全性

连接示例

const client = mqtt.connect('mqtts://PRODUCTID01.iotcloud.tencentdevices.com:8883', {
  clientId: config.mqttClientId,
  username: config.mqttUsername,
  password: config.mqttPassword,
  protocolVersion: 5,
  clean: false  // 持久会话
});

FDP透传

主题映射

FDP消息通过腾讯云MQTT透传，使用FDP标准主题结构：

nodes/{username}/pending
nodes/{username}/ack
nodes/{username}/complete
nodes/{username}/failed
nodes/{username}/status

其中username对应设备的MQTT用户名（通常是productId + deviceName）。

Action定义

用于蓝牙透传的FDP action为：

starcloud-ble

消息格式

FDP消息的value字段包含星图蓝牙协议的二进制数据（Base64编码）：

{
  "sender": "app-user-001",
  "receiver": "PRODUCTID01DEV123456789",
  "msg_id": "uuid-xxx",
  "action": "starcloud-ble",
  "time": 1700000000,
  "exp": 1700000060,
  "value": "base64_encoded_ble_command"
}

状态上报

设备状态通过 nodes/{username}/status 主题发布：

• 离线状态：通过 MQTT 遗嘱消息（Will Message）触发发布，设备离线时自动发送

状态消息格式：

{
  "time": 1700000000,
  "online": true,
  "battery": 85,
  "rssi": -65,
  "call_time": 1700000000
}

字段说明

字段	类型	说明
time	Number	Unix 时间戳（秒），状态上报时间
online	Boolean	设备在线状态
battery	Number	电池电量百分比（0-100）
rssi	Number	信号强度（dBm），通常为负值
call_time	Number	通话开始时间戳（秒），开始通话时设置为当前时间戳，挂断时设置为0

事件上报

设备端上报

设备通过ouserver上传日志：

• 视频日志
• 图片日志
• 文字日志

ouserver地址通过配网获取（configureJson中的ouserverAddress）。

OTA升级

WiFi门锁的固件升级通过FDP透传蓝牙协议实现，使用 0x30E8 指令下发固件URL，由锁端自行下载升级。

可选：设备可通过 Progress 进度消息 上报升级进度。

详细协议参见：WiFi固件升级

事件类型

事件代码	说明	类型
1	指纹开门	视频
2	密码开门	视频
3	卡片开门	视频
4	蓝牙开门	视频
16	人脸开门	视频
12	密码/指纹错误冻结	视频
13	撬锁告警	视频
28	徘徊/逗留告警	视频
128	胁迫告警(指纹)	视频
129	胁迫告警(密码)	视频
156	防遮挡告警	视频
159	有人按门铃	视频

其他事件为文字事件。

微信VOIP

授权流程

授权票据格式

设备端通过扩展蓝牙协议接收授权票据：

• 指令：0x3030
• 子命令：55

请求字段：

字段	类型	长度	说明
KeyID	String	40	钥匙ID
UserID	String	20	用户ID
Token	uint32	4	鉴权token
OpenIDLength	uint16	2	微信openid长度
OpenID	String	变长	微信openid
SNTicketLength	uint16	2	授权票据长度
SNTicket	String	变长	微信授权票据

业务约束

开门方式管理

当前版本限制：

• 仅支持添加和删除，暂不支持修改
• 适用范围：电子钥匙、指纹、卡片、自定义密码
• 所有开门方式仅支持永久有效

设备型号规范

型号格式：{方案标识}-{连接方式}-{版本号}

示例：XB7-WIFI-001

• XB7：腾讯云物联网 + BK007芯片方案
• WIFI：WiFi连接方式
• 001：版本号

版本判断：

• XB7-WIFI-0xx：不支持开门方式修改
• XB7-WIFI-1xx：支持开门方式修改（规划中）

参考文档

• 腾讯云IoT设备端开发指南
• 腾讯云IoT应用端开发指南
• 星图蓝牙协议
• EMQX MQTT教程