产品到设备的完整闭环

页面导读

适用场景适合第一次使用 FastBee 的用户，用 MQTTX 模拟真实设备，完整跑通产品、物模型、设备、上报和下发。

前置条件已完成平台部署并可登录后台，MQTT 服务端口可访问，已安装 MQTTX。

操作路径产品分类 → 产品管理 → 物模型 → 发布产品 → 设备管理 → MQTTX 模拟设备 → 数据验证。

验收点设备在线，平台能看到上报数据，平台下发指令后 MQTTX 能收到消息。

一、业务流程

建议先用直连 MQTT 设备跑通闭环，再扩展到 HTTP、CoAP、TCP、Modbus、网关子设备或视频设备。

二、准备信息

操作前先准备一张记录表，后续 MQTTX 连接和主题拼接都要用到。

信息	来源	示例	说明
平台地址	部署服务器	192.168.1.10	MQTTX 连接时填写
MQTT 端口	部署配置	1883	默认 MQTT TCP 端口
用户 ID	当前登录用户	1	管理员通常为 1
产品 ID	产品详情	2	Topic 中的 {productId}
产品编号	产品详情	系统生成	MQTT clientId 中使用
MQTT 账号	产品详情	fastbee	MQTT username
MQTT 密码	产品详情	系统生成	简单认证直接使用
设备编号	设备详情	D68329VL588	Topic 中的 {deviceNum}
设备授权码	设备授权页面	可选	产品启用设备授权时必填

提示

演示环境推荐先使用简单认证。生产环境或对外网络环境建议使用加密认证，并控制密码过期时间。

三、创建产品

平台菜单：

设备管理 > 产品管理

产品管理入口示例：

点击“新增”，填写基础信息。

字段	建议值	说明
产品名称	MQTT演示产品	便于后续查找
产品分类	选择已有分类或新建分类	用于产品归类
设备类型	直连设备	第一次体验先选择直连设备
通讯协议	JSON 解析协议或默认协议	用于解析设备上报数据
传输协议	MQTT	本文使用 MQTTX 模拟
认证方式	简单认证	演示环境更容易排查
定位方式	自动定位或自定义位置	不影响最小闭环
设备授权	关闭	第一次联调建议关闭，跑通后再启用

创建成功后进入产品详情，确认产品编号、MQTT 账号、MQTT 密码等信息已经生成。

四、定义物模型

平台菜单：

设备管理 > 产品管理 > 产品详情 > 产品模型

物模型配置入口示例：

建议先创建一个属性和一个功能，用于验证上报和下发。

1. 创建属性

字段	示例	说明
模型类型	属性	设备主动上报的数据
名称	温度	页面显示名称
标识符	temperature	设备上报时使用，必须唯一
数据类型	浮点型或整数型	根据实际数据选择
读写类型	只读	温度通常由设备上报
单位	℃	可选

2. 创建功能

字段	示例	说明
模型类型	功能	平台可下发的控制指令
名称	开关	页面显示名称
标识符	switch	下发与回传都使用该标识符
数据类型	布尔型或枚举型	开关适合布尔型
读写类型	读写	平台下发后设备可回传结果

物模型保存后，回到产品详情点击“发布产品”。产品未发布时，设备创建和设备认证可能失败。

五、创建设备

平台菜单：

设备管理 > 设备管理

设备新增入口示例：

点击“新增设备”，选择刚才创建的产品。

字段	建议值	说明
设备名称	MQTT演示设备01	页面显示名称
所属产品	MQTT演示产品	必须选择已发布产品
设备编号	自动生成或自定义	MQTT clientId 和 Topic 都会使用
固件版本	1	演示环境可保持默认
设备影子	关闭或开启	第一次联调建议关闭，避免离线指令干扰判断
禁用设备	关闭	禁用后设备无法连接

保存后进入设备详情，记录设备编号。如果产品启用了设备授权，还需要进入设备授权页面获取授权码。

六、配置 MQTTX 连接

打开 MQTTX，新建连接。

MQTTX 连接示例：

MQTTX 字段	填写方式
Host	服务器 IP 或域名
Port	1883
Client ID	S&设备编号&产品ID&用户ID
Username	产品详情中的 MQTT 账号
Password	产品详情中的 MQTT 密码

简单认证示例：

Client ID: S&D68329VL588&2&1
Username: fastbee
Password: PHYFED93WSFF1DAS

如果产品启用了设备授权，简单认证密码格式为：

MQTT密码&设备授权码

连接成功后，EMQX 控制台可以看到客户端连接，FastBee 设备详情中设备状态会逐步变为在线。

七、订阅平台下发主题

设备需要订阅平台下发主题：

/{productId}/{deviceNum}/function/get

示例：

/2/D68329VL588/function/get

如果需要测试设备信息请求，也可以订阅：

/{productId}/{deviceNum}/info/get

八、上报设备信息

设备上线后建议先上报设备信息，帮助平台同步状态、固件版本、信号和定位。

发布主题：

/{productId}/{deviceNum}/info/post

示例主题：

/2/D68329VL588/info/post

示例消息：

{
  "rssi": -43,
  "firmwareVersion": 1.0,
  "status": 3,
  "userId": 1,
  "longitude": 0,
  "latitude": 0,
  "summary": {
    "name": "FastBee MQTT Demo",
    "type": "mqttx"
  }
}

验证方式：

1. 进入设备详情，确认设备状态为在线。
2. 查看设备信息、入网地址、信号强度等字段是否刷新。
3. 查看设备日志是否有上线或信息上报记录。

九、上报属性数据

发布主题：

/{productId}/{deviceNum}/property/post

示例主题：

/2/D68329VL588/property/post

示例消息：

[
  {
    "id": "temperature",
    "value": "26.5",
    "remark": "MQTTX模拟上报"
  },
  {
    "id": "switch",
    "value": "1",
    "remark": "当前开关状态"
  }
]

验证方式：

1. 进入设备详情。
2. 打开运行状态或数据采集页面。
3. 查看 temperature 和 switch 是否更新。
4. 查看设备日志是否记录本次上报。

警告

id 必须与产品物模型标识符一致。大小写、下划线和数字都要完全一致，否则平台无法把数据映射到对应物模型。

十、平台下发指令

进入设备详情，在运行状态或功能下发入口中找到 switch，下发开关指令。

平台下发与 MQTTX 接收示例：

MQTTX 订阅的主题会收到类似消息：

[
  {
    "id": "switch",
    "value": "0",
    "remark": "平台下发"
  }
]

设备端收到指令后，应执行动作并通过属性上报主题回传结果：

[
  {
    "id": "switch",
    "value": "0",
    "remark": "开关已关闭"
  }
]

平台验证：

1. 设备运行状态中的开关值变为下发后的值。
2. 设备日志中能看到平台下发与设备回传。
3. MQTTX 中能看到 /function/get 下发消息。

十一、常见问题

MQTTX 连接失败

优先检查：

1. 产品是否已发布。
2. 设备是否被禁用。
3. Client ID 是否符合 S&设备编号&产品ID&用户ID 格式。
4. 产品 ID 是否填成了产品编号，二者不是同一个字段。
5. 用户名、密码是否来自同一个产品。
6. 产品启用设备授权时，密码是否拼接了授权码。
7. 服务器 1883 端口是否开放。

设备在线但数据不显示

优先检查：

1. 上报主题中的产品 ID 和设备编号是否正确。
2. JSON 是否为数组格式。
3. id 是否与物模型标识符完全一致。
4. value 是否符合物模型数据类型。
5. 产品是否重新发布过，设备是否继承到最新物模型。

平台下发后 MQTTX 收不到消息

优先检查：

1. MQTTX 是否订阅了 /{productId}/{deviceNum}/function/get。
2. 设备是否保持在线。
3. 下发入口选择的物模型是否为可写功能或可下发属性。
4. 浏览器页面是否有权限控制导致按钮不可用。
5. EMQX 控制台中客户端订阅是否存在。

启用设备影子后行为不一致

设备影子用于设备离线时缓存平台下发指令。第一次联调建议关闭设备影子，确认在线下发链路稳定后再开启。

十二、二次开发入口

类型	路径或模块	说明
前端产品页面	vue3/src/views/iot/product	产品、物模型、发布、应用配置入口
前端设备页面	vue3/src/views/iot/device	设备列表、详情、运行状态、指令下发
前端 API	vue3/src/api/iot	产品、设备、物模型等请求封装
后端产品接口	springboot/fastbee-open-api	/iot/product、/iot/model 等接口
后端设备接口	springboot/fastbee-open-api	/iot/device、设备日志、设备用户等接口
MQTT 认证	springboot/fastbee-open-api	/iot/tool/mqtt/auth、EMQX Webhook 认证入口
协议解析	springboot/fastbee-protocol	设备消息编解码与协议扩展
数据服务	springboot/fastbee-iot-data	设备运行数据、时序数据处理

十三、关联文档

• 10分钟跑通演示环境
• MQTTX 模拟设备接入
• MQTT 协议设备接入
• 平台主题
• 产品管理
• 设备管理
• 数据调试