Appearance
MQTT 设备接入
本文演示如何将 MQTT 协议设备接入平台。MQTT 属于网关设备，平台作为 MQTT 客户端连接外部 Broker，通过订阅主题采集子设备数据。
接入流程
创建子产品 → 配置物模型 → 添加 MQTT 网关设备 → 添加子设备 → 查看数据前置条件： 平台已内置 MQTT 驱动，对应的网络组件和网关产品已自动创建。
MQTT 通信说明
MQTT 设备通过**主题（Topic）**与平台交互：
| 方向 | 说明 |
|---|---|
| 设备 → 平台（上行） | 设备发布数据到指定主题，平台订阅并接收 |
| 平台 → 设备（下行） | 平台发布指令到指定主题，设备订阅并执行 |
MQTT 网关设备需要能访问到外部 MQTT Broker。平台作为客户端连接到该 Broker，订阅子设备上报的数据主题。
步骤 1：创建子产品
进入 基础信息 → 产品配置，点击"新增"：
| 配置项 | 填写内容 | 说明 |
|---|---|---|
| 名称 | 智能电表 | 自定义产品名称 |
| 产品类型 | 仪表 | 根据实际设备选择 |
| 产品代码 | smart_meter | 自定义产品代码 |
| 设备类型 | 网关子设备 | 可选值：直连设备 / 网关设备 / 网关子设备 |
| 父产品 | 默认 Mqtt 产品 | 仅设备类型选“网关子设备”时显示，系统已预置的网关产品 |
设备类型选择“网关子设备”后才会显示“父产品”字段，MQTT 是网关类型，必须选择父产品。
图：新增子产品弹框，设备类型选“网关子设备”后选择父产品
步骤 2：配置物模型
2.1 新增属性
先添加基础数据类型属性：
| 属性名称 | 标识符 | 数据类型 | 单位 | 读写类型 |
|---|---|---|---|---|
| 电压 | voltage | float | V | 只读 |
| 电流 | current | float | A | 只读 |
| 功率 | power | float | W | 只读 |
| 开关 | switch | boolean | — | 可读可写 |
再添加一个 JSON 类型属性，将上面的基础属性包含进来：
| 属性名称 | 标识符 | 数据类型 | 说明 |
|---|---|---|---|
| 上报数据 | reportData | json | 包含 voltage、current、power |
添加 JSON 属性时，需要逐个配置每个基础属性对应的 JSONPath（用于从设备上报的 JSON 中提取对应字段值）：
| 选择属性 | 填写 Path | 说明 |
|---|---|---|
| voltage | $.voltage | 从 JSON 中提取 voltage 字段 |
| current | $.current | 从 JSON 中提取 current 字段 |
| power | $.power | 从 JSON 中提取 power 字段 |
JSONPath 说明： 平台使用 fastjson 的 JSONPath 语法从设备上报的 JSON 中提取属性值。常见用法：
JSON 结构 Path 写法 提取结果 {"voltage": 220.5}$.voltage220.5 {"data": {"voltage": 220.5}}$.data.voltage220.5 {"sensors": [{"voltage": 220.5}, {"voltage": 230.1}]}$.sensors[0].voltage220.5（取第一个元素） {"sensors": [{"voltage": 220.5}, {"voltage": 230.1}]}$.sensors[1].voltage230.1（取第二个元素） 每个基础属性的 path 为必填项，即使 JSON 字段名和属性标识符一致也需要填写对应的 path。
图：物模型属性列表，基础属性和 JSON 类型属性配置完成后的效果
2.2 新增事件模型（采集数据）
事件模型的基本表单字段：
| 字段 | 说明 |
|---|---|
| 事件名称 | 自定义名称，如“数据上报” |
| 协议指令 | 从 MQTT 驱动提供的指令列表中选择，如“订阅”指令 |
| 接口代码 | 自定义唯一标识，如 dataReport |
| 频率标签 | 默认（MQTT 设备主动上报，频率标签主要用于采集器场景） |
| 事件说明 | 可选，描述该事件模型的用途 |
选择协议指令后，会出现上行配置选项卡，配置项根据所选指令动态变化。
| 配置项 | 填写内容 |
|---|---|
| 事件名称 | 数据上报 |
| 协议指令 | 选择 MQTT 驱动提供的“订阅”指令 |
| 接口代码 | dataReport |
| 频率标签 | 默认 |
| 事件说明 | 接收设备上报的 JSON 数据 |
| 上行配置 - topic | 订阅主题（以子产品编号开头，如 smart_meter/{deviceSn}/data） |
| 上行配置 - payload | @reportData（绑定上面创建的 JSON 类型属性） |
MQTT 的事件模型使用"订阅"指令，平台通过订阅主题接收子设备上报的 JSON 数据。设备发布的数据格式示例：
{"voltage": 220.5, "current": 1.2, "power": 264.6}
图：事件配置弹框，选择“订阅”指令后在上行配置中填写主题和上报负载（@绑定 JSON 属性）
Topic 匹配机制： 平台将 topic 按 / 拆分为多段，逐段匹配设备上报的 topic 和事件模型配置的 topic。匹配规则：
- 段数必须相同 — 拆分后的段数不一致则直接不匹配
- 占位符段 — 如
{deviceSn}，用于提取 topic 中的特定信息（设备编号、网关编号等），不做字面匹配 - 固定段 — 必须与设备上报的 topic 对应段完全一致
一个产品可以配置多个事件模型，只要 topic 中某一段不同就能区分。例如：
| 事件模型 | topic 配置 | 设备实际发布的 topic | 匹配结果 |
|---|---|---|---|
| 数据上报 | smart_meter/{deviceSn}/data | smart_meter/METER-001/data | 匹配成功，解析到 dataReport |
| 状态上报 | smart_meter/{deviceSn}/status | smart_meter/METER-001/status | 匹配成功，解析到 statusReport |
| 告警上报 | smart_meter/{deviceSn}/alarm | smart_meter/METER-001/alarm | 匹配成功，解析到 alarmReport |
以上示例中，区分不同事件模型的是最后一段（data/status/alarm），但实际上这个区分段可以出现在 topic 的任意位置，只要各事件模型的 topic 配置不同即可。
2.3 新增功能模型（控制设备）
功能模型的基本表单字段：
| 字段 | 说明 |
|---|---|
| 功能名称 | 自定义名称，如“开关控制” |
| 协议指令 | 从 MQTT 驱动提供的指令列表中选择，如“发布”指令 |
| 接口代码 | 自定义唯一标识，如 switchControl |
| 序号 | 用于标识接口的重要程度，值越低排序越靠前 |
| 功能说明 | 可选，描述该功能模型的用途 |
选择协议指令后，会出现下行配置选项卡，配置项根据所选指令动态变化。
| 配置项 | 填写内容 |
|---|---|
| 功能名称 | 开关控制 |
| 协议指令 | 选择 MQTT 驱动提供的“发布”指令 |
| 接口代码 | switchControl |
| 序号 | 1 |
| 功能说明 | 控制设备开关 |
| 下行配置 - topic | 下发主题（如 smart_meter/{deviceSn}/write） |
| 下行配置 - PublicPayload | @switch |
下行值说明： 下行值可以写死固定值（如
{"switch": 1}），也可以用@属性字段动态绑定模型属性的值。对于有多个状态的控制场景（如开关），建议先添加一个布尔类型的模型属性，配置字典（如“开”=1、“关”=0），再用@属性字段绑定，在界面上通过下拉框选择来控制设备。
图：功能配置弹框，选择“发布”指令后在下行配置中填写主题和下发负载
步骤 3：添加 MQTT 网关设备
进入 设备管理 → MQTT 设备，点击"新增"：
| 配置项 | 填写内容 | 说明 |
|---|---|---|
| 客户端名称 | 1号 MQTT 网关 | 自定义名称 |
| 设备地址 | 1号车间机房（可选） | 设备安装位置，非必填 |
| 所属产品 | 选择系统预置的 MQTT 网关产品 | 自动关联 |
| 主机 | broker.emqx.io | MQTT Broker 地址 |
| 端口 | 1883 | MQTT 默认端口 |
| 用户名 | （按需填写） | Broker 认证用户名 |
| 密码 | （按需填写） | Broker 认证密码 |
| 客户端ID | client_001 | MQTT 客户端唯一标识 |
| 保活时间 | 3600 | 心跳间隔（秒） |
| 消息等级 | 0 | QoS 等级（0/1/2） |
| 订阅的主题 | smart_meter/+ | 订阅主题，以子产品编号开头 |
订阅主题说明： 主题需要与子设备实际发布数据的主题匹配。支持使用占位符
{deviceSn}、{gatewaySn}，多个主题用逗号分隔。
图：MQTT 网关设备编辑框，填写 Broker 连接信息，订阅主题以子产品编码开头
步骤 4：添加子设备
在 设备管理 → MQTT 设备 列表中，找到步骤3创建的网关设备（1号 MQTT 网关），点击右侧的 "子设备" 按钮，弹出子设备列表框，点击"新增"：
| 配置项 | 填写内容 | 说明 |
|---|---|---|
| 设备名称 | 1号智能电表 | 自定义名称 |
| 设备地址 | 1号车间配电柜（可选） | 设备安装位置，非必填 |
| 设备编号 | METER-001 | 设备唯一标识 |
| 所属产品 | 智能电表（步骤1创建的子产品） | 自动继承物模型 |
| 所属组 | 选择设备分组（可选） | 可选 |
添加完成后，该设备自动成为当前 MQTT 网关的子设备，无需手动关联父设备。
MQTT 设备数据由设备主动上报，不需要配置采集器。配置好物模型事件模型后，平台订阅主题即可自动接收数据。
图：网关子设备编辑框，所属产品选择步骤 1 创建的子产品
子设备上下线机制： MQTT 子设备的在线状态由平台自动管理。当平台收到设备上报的数据时，会从 topic 中解析出设备编号（通过 {deviceSn} 占位符提取），第一次收到该设备编号的数据时，自动将设备切换为在线状态。当设备断开与 Broker 的连接时，MQTT Broker 会发布遗嘱消息到遗嘱主题，平台收到遗嘱消息后将对应设备切换为离线状态。
步骤 5：查看数据
- 进入 运行管控 → 运行展板，查看设备在线状态和实时数据
- 进入 数据中心 → 模型数据，查看历史数据曲线
常见问题
Q: 设备显示离线？ 检查 MQTT Broker 的地址和端口是否正确，确认平台能访问到 Broker。如果 Broker 需要认证，确认用户名和密码正确。
Q: 设备在线但没有数据？ 检查子设备上报的主题是否与事件模型中配置的订阅主题一致。主题需要以子产品编号开头，并包含设备编号。
Q: 下发指令设备不响应？ 检查功能模型中"发布"指令的主题格式，确认平台发布的主题与设备订阅的一致。
Q: 多个子设备如何快速配置？ 多个子设备可以复用同一个子产品。创建子设备时选择相同产品，只需确保每个子设备发布数据的主题中包含各自的设备编号（使用 {deviceSn} 占位符）。