MQTT 接入

FastBee 开源版内置基于 Netty 开发的 MQTT Broker，无需额外部署 EMQX。本文介绍设备如何通过 MQTT 协议接入平台。

接入流程

1. 在产品管理中创建并发布 MQTT 产品，确认产品 ID、设备编号、MQTT 账号和密码
2. 设备或 MQTTX 使用约定的 clientId、userName、password 连接 MQTT 服务
3. 连接成功后先发布 /info/post，再发布 /property/post 或 /event/post
4. 平台侧通过设备详情的运行状态、事件日志和指令日志确认链路闭环

连接信息

参数	TCP 连接	WebSocket 连接
地址	服务器 IP	ws://服务器IP:8083/mqtt
端口	1883	8083
协议	MQTT 3.1.1	MQTT over WebSocket

设备认证

提示

• 认证类型：S = 简单认证，E = 加密认证
• 产品启用设备授权码后，授权码不能为空
• 用户 ID 是登录用户的 ID，使用不同用户 ID 设备归属不同用户
• 设备编号可以是平台创建的编号，也可以是设备 MAC/IMEI 等唯一编码（平台会自动注册设备）

简单认证（推荐测试使用）

clientId = S&设备编号&产品ID&用户ID
userName = MQTT账号
password = MQTT密码
password = MQTT密码&设备授权码（产品启用设备授权时）

示例：

clientId = "S&D68329VL588&2&1"
userName = "fastbee"
password = "PHYFED93WSFF1DAS"

加密认证（推荐生产使用）

clientId = E&设备编号&产品ID&用户ID
userName = MQTT账号
password = AES加密(MQTT密码&过期时间戳&授权码(可选))

• 密码使用产品密钥进行 AES-CBC 加密（偏移量 wumei-smart-open，输出 Base64）
• 过期时间戳精确到毫秒，建议 24 小时以内

示例：

clientId = "E&D68329VL588&2&1"
userName = "fastbee"
password = "/W2A/4MK+9cEGBhyBDgr2K5c62DAjAK4m0b5pvwxX6FFMzI3h1pUmaDY3BH1P2mI"

AES 加密说明

采用 AES-CBC 加密模式，测试可使用 在线加解密工具：

参数	值
加密模式	CBC
填充	pkcs5padding
数据块	128 位
偏移量	wumei-smart-open
输出	Base64
密码	产品密钥
加密内容	MQTT密码&expireTime&授权码(可选)

订阅主题（平台 → 设备）

主题	描述
/{productId}/{deviceNum}/function/get	订阅平台指令（属性设置、功能调用）
/{productId}/{deviceNum}/info/get	订阅设备信息请求（收到后发布设备信息）
/{productId}/{deviceNum}/monitor/get	订阅实时监测请求（返回次数和间隔）
/{productId}/{deviceNum}/ntp/get	订阅时钟同步（可选）
/{deviceNum}/http/upgrade/set	HTTPS 方式订阅 OTA 升级
/{deviceNum}/fetch/upgrade/set	二进制包方式订阅 OTA 升级

发布主题（设备 → 平台）

主题	描述
/{productId}/{deviceNum}/property/post	发布属性/功能数据（实时显示并存储）
/{productId}/{deviceNum}/event/post	发布事件
/{productId}/{deviceNum}/info/post	发布设备信息
/{productId}/{deviceNum}/monitor/post	发布实时监测数据（仅实时图表，不存储）
/{productId}/{deviceNum}/ntp/post	发布时钟同步（可选）
/{deviceNum}/http/upgrade/reply	HTTPS 方式回复 OTA 升级
/{deviceNum}/fetch/upgrade/reply	二进制包方式回复 OTA 升级

提示

• {productId} 为产品 ID（非产品编号），在平台产品详情中获取
• {deviceNum} 为设备编号，与平台设备完全一致

数据格式

设备和平台交互使用 JSON 格式。

发布属性/功能/事件 — /property/post、/event/post

[{
    "id": "temperature",
    "value": "27.43",
    "remark": "温度正常"
}, {
    "id": "switch",
    "value": "1",
    "remark": "开关已打开"
}]

• id：物模型标识符，产品详情中查看，产品下唯一
• value：值以字符串传递；布尔类型用 "0"/"1"；枚举类型对应枚举键值；数组类型以逗号分隔
• remark：备注信息，设备日志中可查看

订阅平台指令 — /function/get

[{
    "id": "gear",
    "value": "1",
    "remark": "场景联动触发"
}, {
    "id": "switch",
    "value": "0",
    "remark": "定时关闭"
}]

发布设备信息 — /info/post

{
    "rssi": -43,
    "firmwareVersion": 1.2,
    "status": 3,
    "userId": 1,
    "longitude": 0,
    "latitude": 0,
    "summary": {
        "name": "FastBee",
        "chip": "ESP32"
    }
}

字段	说明
rssi	信号强度（极好 [-55~0]，好 [-70~-55]，一般 [-85~-70]，差 [-100~-85]）
firmwareVersion	固件版本号
status	设备状态，固定为 3（在线）
userId	用户 ID
longitude/latitude	可选，设备定位
summary	可选，设备摘要信息

实时监测 — /monitor/get、/monitor/post

平台下发监测请求：

{
    "count": 60,
    "interval": 1000
}

设备按指定次数和间隔上报数据：

[{
    "id": "temperature",
    "value": "27.43",
    "remark": ""
}]

时钟同步 — /ntp/post、/ntp/get

设备发布：

{
    "deviceSendTime": "1592361428000"
}

平台回复：

{
    "deviceSendTime": "1592361428000",
    "serverRecvTime": "1592366463548",
    "serverSendTime": "1592366463548"
}

设备当前时间 = (serverRecvTime + serverSendTime + deviceRecvTime - deviceSendTime) / 2

物模型标识符规则

• 所有标识符产品下唯一，以字母和数字为主，避免特殊字符
• 对象类型子模型 ID 格式：parentId_childId
• 数组类型标识符以 array_索引 开头（索引为两位数，如 array_00_power_switch），数组长度不超过 100

设备 AP 配网（可选，仅限 WiFi 设备）

设备开启热点（地址 192.168.4.1），移动端通过设备 Web 服务传递配置信息。

检测设备

GET http://192.168.4.1/api/wifi/status

HTTP 200 表示检测到设备，响应包含设备信息与当前网络状态。

配置接口

POST http://192.168.4.1/api/wifi/config?SSID=WiFi名称&password=WiFi密码&userId=用户ID

参数	说明
SSID	WiFi 名称（必传，兼容小写 ssid）
password	WiFi 密码（必传，兼容别名 pwd）
userId	用户 ID（必传）
deviceNum	设备编号（可选）
extra	产品编号（可选）

HTTP 200 表示配网成功（设备随后自动切换 STA 模式），400 表示必传参数缺失，500 表示保存失败。 接口详细说明见《网络配置 · 手机/移动端 AP 配网 API》。

使用 MQTTX 测试

1. 下载 MQTTX 客户端
2. 新建连接：
   • Host: mqtt://服务器IP，Port: 1883
   • Client ID: S&设备编号&产品ID&1
   • Username: MQTT 账号
   • Password: MQTT 密码
3. 订阅 /{productId}/{deviceNum}/function/get
4. 向 /{productId}/{deviceNum}/info/post 发布设备信息
5. 向 /{productId}/{deviceNum}/property/post 发布属性数据
6. 观察平台控制台设备在线状态和运行数据

联调验收清单

步骤	验收内容	成功表现
1	产品已发布	产品状态为已发布
2	MQTTX 连接	设备详情显示在线
3	/info/post	设备信息、信号、版本字段更新
4	/property/post	运行状态显示物模型属性值
5	/event/post	事件日志出现上报事件
6	/function/get	平台下发后设备收到指令
7	回传结果	设备按下发结果回传，平台状态刷新
8	规则/场景	相关规则、场景、告警能被触发

常见错误

连接被拒绝

1. 服务器 1883 端口是否开放
2. 内置 MQTT Broker 是否启动
3. clientId 格式是否正确（S&设备编号&产品ID&用户ID）
4. 产品是否启用设备授权码
5. 设备是否被禁用

设备在线但属性不刷新

1. 发布主题是否为 /{productId}/{deviceNum}/property/post
2. productId 是否使用产品 ID（非产品编号）
3. deviceNum 是否与设备编号完全一致
4. 消息体是否为 JSON 数组格式
5. id 是否与物模型标识符完全一致
6. value 是否符合数据类型

平台下发设备收不到

1. 设备是否订阅 /{productId}/{deviceNum}/function/get
2. 设备是否仍在线
3. 物模型是否为可写功能或可下发属性
4. 用户是否有设备详情和指令下发权限

规则或告警没有触发

1. 设备数据是否进入平台运行状态
2. 场景或规则绑定的产品、设备、变量是否正确
3. 条件表达式是否与上报值类型一致
4. 告警配置是否启用

规则脚本转换

如果设备使用自定义数据格式，可在 规则脚本 中编写转换逻辑，将原始数据转为平台标准格式。详见 规则脚本。

关联文档

• 产品管理
• 设备管理
• 物模型
• 场景联动