MQTT 接入

fastbee大约 7 分钟

MQTT 接入

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

接入流程

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

连接信息

参数	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/status

HTTP 200 表示检测到设备。

配置接口

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

参数	说明
SSID	WiFi 名称（必传）
password	WiFi 密码（必传）
userId	用户 ID（必传）
deviceNum	设备编号（可选）
authCode	授权码（可选）

HTTP 200 表示配网成功，500 表示配网失败。

使用 MQTTX 测试

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

联调验收清单

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

常见错误

连接被拒绝

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

设备在线但属性不刷新

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

平台下发设备收不到

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

规则或告警没有触发

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

规则脚本转换

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