奈科斯（NexIoT）

主题

nexiot2026-04-19
17
1m

标准Topic ​

1. 适合哪些设备 ​

平台内置了一套 MQTT Broker（基于 EMQX），这条路适合下面这类设备：

  1. 设备 Topic 可以按平台规范调整。
  2. 设备可以直接连平台内置 Broker。
  3. 设备消息体要么是标准物模型 JSON，要么准备在标准 Topic 下走透传模式。

如果设备 Topic 改不了，或已经部署在第三方 Broker 上，请直接看 任意主题设备接入。

MQTT 平台直连 · 快速接入主线

第一次接平台内置 MQTT，按这 5 步走

01平台先具备 MQTT 接入能力

开启 MQTT 模块

配置 mqtt.protocol.enabled=true，然后启动或重启平台。

02先把产品身份定下来

创建 MQTT 产品

接入方式选 MQTT，导入物模型或选择透传模式。

03不用再回产品详情

添加设备并拿连接信息

设备管理里添加设备，进入设备详情 → 设备连接信息，直接复制 ClientID、Username、Password 和 Topic。

04物模型模式消息体即标准 JSON

设备按标准 Topic 收发

发布 $thing/up/property/{pk}/{dk}，订阅 $thing/down/{pk}/{dk}。

05属性入库、指令能下发就算跑通

透传补脚本并验证闭环

透传模式再补 decode / encode，用 MQTTX 跑通上报和下发。

2. 快速开始 ​

第一步：开启 MQTT 模块 ​

部署侧先确认配置已经打开，如 application-prod.properties：

# MQTT协议
mqtt.protocol.enabled=true

改完后需要启动或重启平台，只改配置不重启不会生效。

第二步：创建 MQTT 产品 ​

在产品管理里新建产品时，接入方式选择 MQTT。

mqtt-create

创建完产品后至少创建一个属性和一个功能

mqtt-create

第三步：添加设备并获取连接信息（推荐） ​

mcreateDevice

新版本推荐直接从 设备详情 拿连接信息，不用再回产品详情翻模板。

路径：设备管理 → 新增设备 → 进入设备详情 → 设备连接信息。

设备详情页面会给出：

  1. 连接地址（host + port）
  2. ClientID、Username、Password（全部支持一键复制）
  3. 该设备要 发送 和 订阅 的 Topic 列表（标准 $thing/... 主题，已经带上当前设备的 ProductKey/DeviceId）

mcreateDevice

平台直连一机一密规则

如果你想手动拼接，可以直接按下面的格式来：

text
ClientID = ProductKey.DeviceId
Username = DeviceId&ProductKey
Password = DeviceSecret

平台内置 Broker 的 MQTT 地址和端口，在设备连接信息和产品详情里都能看到。

第四步：了解标准 Topic ​

常用的 4 条 Topic 如下：

用途Topic谁来用
属性上报$thing/up/property/{productKey}/{deviceId}设备发布
事件上报$thing/up/event/{productKey}/{deviceId}设备发布
透传上报$thing/up/{productKey}/{deviceId}设备发布
指令下发$thing/down/{productKey}/{deviceId}设备订阅

如果还有 OTA 上报场景，平台也支持 $ota/report/{productKey}/{deviceId}。

平台从 Topic 里就能直接拿到 productKey 和 deviceId，这类设备 通常不需要写 preDecode 去识别设备。

后续处理分成两种：

模式平台怎么处理适合什么消息
THING_MODEL直接按物模型 JSON 处理属性或事件标准 JSON 上报
PASSTHROUGH继续走产品里的 decode / encodeHEX、字符串、私有 JSON

第五步：设备按标准 Topic 收发消息 ​

物模型模式 ​

设备直接往属性 Topic 发标准 JSON。

对应 Topic：

text
$thing/up/property/{productKey}/{deviceId}

属性上报示例：

json
{
  "current": 31.0,
  "power": 129,
  "powerState": 1,
  "voltage": 122.8
}

事件上报类似，把 Topic 换成 $thing/up/event/{productKey}/{deviceId} 即可。

event-pic

透传模式 ​

如果 Topic 按平台规范来，但 payload 还是厂商私有格式，继续用透传 Topic：

text
$thing/up/{productKey}/{deviceId}

这时重点就不在 Topic 了，而在产品脚本：

  1. decode 负责把设备上报转成属性或事件。
  2. encode 负责把平台功能调用转成设备报文。

第六步：用 MQTTX 跑通第一条消息 ​

建议按这个最短路径联调：

  1. 打开 MQTTX，按设备详情里的 host、端口、ClientID、Username、Password 连接。
  2. 订阅 $thing/down/{productKey}/{deviceId}（即"设备订阅"列出的 Topic）。
  3. 向 $thing/up/property/{productKey}/{deviceId} 发一条属性 JSON。
  4. 回到平台设备详情，确认数据入库。
  5. 在平台调用一次设备功能，确认 MQTTX 收到下行消息。

tools

第七步：下行 Topic 自定义（可选） ​

默认下行 Topic 是 $thing/down/{productKey}/{deviceId}。

如果你在产品 端云配置 里单独配了 downTopic，平台会优先用你配置的主题模板下发。

down-topic

常用占位符：

  1. #{productKey} / / ${productKey} / {productKey}
  2. #{deviceId} / / ${deviceId} / {deviceId}

3. 这条路最容易出错的点 ​

  1. Topic 里的 productKey 或 deviceId 写错了（建议直接从设备详情复制）。
  2. 物模型模式下，JSON 字段名和物模型字段对不上。
  3. 透传模式下，没写好 decode / encode。
  4. 产品已经绑定了 MQTT 网络组件，连接信息页面实际已切到 自建接入，此时应参考 任意主题设备接入。
  5. 产品里配置了自定义 downTopic，导致平台下发主题不是默认的 $thing/down/...。

更多排查方式可以直接看 MQTT 常见问题。