MQTT 常见功能问题

通信组件-MQTT服务是什么？适合什么场景？

什么是MQTT通信组件？

MQTT通信组件是一个灵活的MQTT客户端连接器，用于对接第三方MQTT Broker或自定义主题的设备。它支持零代码配置、灵活主题映射、多产品管理、实时测试验证和智能自动回复。

MQTT通信组件

适用场景选择

使用nexiot内置EMQX的场景：

设备可以按照nexiot标准主题规范进行开发
使用nexiot平台内置的MQTT Broker
设备数量较少，不需要独立的MQTT服务器

使用MQTT通信组件的场景：

设备的MQTT主题格式无法修改（如第三方设备、已上线设备）
MQTT Broker部署在其他服务器上（如阿里云、腾讯云、自建服务器）
需要支持任意自定义主题格式
需要灵活的主题映射和数据转换

功能说明

1. 基础配置

配置MQTT Broker的连接信息：

服务器地址：MQTT Broker的IP或域名
端口号：默认1883（非加密）或8883（加密）
认证信息：用户名和密码
ClientID前缀：自定义客户端标识前缀
连接超时：连接超时时间设置
连接状态：实时显示运行中/已停止

2. 主题订阅与映射

支持MQTT标准通配符，灵活匹配设备主题：

单级通配符 +：匹配一个层级，例如 device/+/data 可以匹配 device/001/data、device/002/data
多级通配符 #：匹配多个层级，例如 $third/up/# 可以匹配 $third/up/device001、$third/up/device001/data

配置选项：

产品绑定：将主题绑定到特定产品，或留空自动匹配
数据类型：物模型（标准JSON格式）或透传（需要编解码处理）
QoS等级：0（最多一次）、1（至少一次）、2（只有一次）

3. 主题测试工具

在配置完成后，可以使用测试工具验证：

实时测试主题模式是否匹配
验证配置的正确性
显示匹配的产品信息

4. 高级设置

重连机制：自动重连配置
消息缓存：离线消息缓存设置
其他参数：MQTT客户端高级参数

配置示例

假设你有一个温度传感器设备，发送数据到主题：sensor/temperature/device001/data

配置步骤：

进入"通信组件"，创建MQTT通信组件
填写Broker连接信息（地址、端口、用户名、密码）
在"主题订阅"中添加主题模式：sensor/temperature/+/data
选择数据类型（物模型或透传）
关联对应的产品（或留空自动匹配）
使用测试工具验证主题匹配
启动MQTT通信组件

设备交互应答配置

什么是设备自动应答？

当设备上报数据到平台后，平台可以自动向设备回复确认消息（ACK）。这对于需要确认应答的设备场景非常有用，比如设备需要知道数据是否成功上报。

回复主题的配置方式

平台支持3种优先级的回复主题配置方式，优先级从高到低：

优先级1：脚本中动态指定（最高优先级）

在编解码脚本中，通过 downTopic 字段动态指定回复主题：

javascript

var decode = payload => {
    var propertiesObj = {
        "messageType": "PROPERTIES",
        "properties": {},
        "replyPayload": {"status": "ok"},
        // 动态指定回复主题（会覆盖其他配置）
        "downTopic": "$thing/down/681c0775c2dc427d0480ab5f/cz001923"
    }
    return propertiesObj;
}

优先级2：端云配置中指定（中等优先级）

在产品的"端云配置"中配置默认下行主题，支持占位符：

#{productKey} 或 - 自动替换为产品Key
#{deviceId} 或 - 自动替换为设备ID
+ - MQTT通配符，按顺序替换为productKey和deviceId（向后兼容）

配置示例：

cat4_lock/p2p/11GID_lock@@@#{deviceId}

实际发送时会替换为：

cat4_lock/p2p/11GID_lock@@@device123

优先级3：系统默认规则（最低优先级）

如果以上两种方式都没有配置，系统会使用默认规则构建回复主题：

内置MQTT：/{productKey}/{deviceId}/thing/down
第三方MQTT：使用第三方配置的下发主题模板

回复内容的配置方式

通过产品的编解码脚本，在解码函数中设置 replyPayload 字段来指定回复内容。

完整脚本示例：

javascript

//解码
var decode = payload => {
    var result = []
    log.info("编解码收到消息={}", payload)
    var dt = toJson(payload)
    
    var propertiesObj = {
        "messageType": "PROPERTIES",
        "properties": {}
    }

    // 1. 构建回复内容（对象格式）
    var repayObj = {}
    repayObj.tips = "我想改啥就改啥"
    repayObj.randomNo = randomSign()
    repayObj.wings = "universal-iot-great"
    repayObj.iot = "iotuniv"
    
    // 2. 设置属性
    propertiesObj.properties = dt
    propertiesObj.properties.sn = randomSign()
    
    // 3. 设置MQTT自动回复内容（必填）
    propertiesObj.replyPayload = repayObj
    // 也可以直接设置字符串：propertiesObj.replyPayload = "xzzxc" + randomSign()
    
    // 4. 可选：动态指定回复主题（会覆盖端云配置）
    // propertiesObj.downTopic = "$thing/down/681c0775c2dc427d0480ab5f/cz001923"
    
    return propertiesObj;
}

关键字段说明：

replyPayload：必填，设置回复的内容，可以是对象或字符串
downTopic：可选，动态指定回复主题，会覆盖端云配置中的默认主题

完整执行流程

1. 设备上报数据

设备通过MQTT发送数据到订阅的主题，例如：sensor/temperature/device001/data

2. 平台接收并解码

平台接收到数据后，执行产品配置的编解码脚本，解析数据内容

3. 判断是否需要回复

检查脚本返回的数据中是否包含 replyPayload 字段：

如果有 replyPayload，触发自动回复流程
如果没有，不发送回复

4. 确定回复主题

按照优先级确定回复主题：

第一优先级：检查脚本中是否设置了 downTopic
第二优先级：检查端云配置中是否配置了下行主题
第三优先级：使用系统默认规则构建主题

5. 编码回复内容

根据产品配置的编码器类型（encoderType）对 replyPayload 进行编码：

JSON格式：保持JSON字符串格式
HEX格式：转换为十六进制字符串
Base64格式：转换为Base64编码
自定义格式：使用产品配置的编码器处理

6. 发送回复消息

选择合适的MQTT服务器发送回复：

内置MQTT：通过nexiot内置的EMQX发送
第三方MQTT：通过配置的第三方MQTT服务器发送

7. 记录回复日志

发送成功后，系统会自动保存一条设备日志：

消息类型：ACK（确认消息）
日志内容：完整的回复内容
时间戳：发送时间

使用场景示例

场景1：温度传感器上报并确认

流程：
1. 设备上报：{"temperature": 25.5, "humidity": 60}
2. 平台解码并处理数据
3. 平台自动回复：{"code": 200, "msg": "success"}
4. 设备收到确认，继续下一次上报

场景2：智能门锁开锁确认

流程：
1. 门锁上报：{"action": "unlock", "userId": "user001"}
2. 平台验证权限并记录日志
3. 平台回复：{"result": "ok", "timestamp": 1234567890}
4. 门锁收到确认，执行开锁动作

场景3：批量数据上报

流程：
1. 设备批量上报5条历史数据
2. 平台逐条处理每条数据
3. 平台发送5条ACK消息
4. 设备收到全部确认后清空本地缓存

调试技巧

1. 查看回复日志

在"设备管理 → 设备详情 → 设备日志"中筛选：

消息类型：选择 ACK
时间范围：选择对应的时间段

2. 检查回复主题

在日志中查看实际使用的主题：

[MQTT批量回复处理器] 回复消息发布成功 - 主题: /product001/device001/thing/down

3. 验证编码格式

在日志中查看编码类型和内容：

encoderType: JSON, 内容: {"code":200,"msg":"success"}

4. 排查发送失败

常见失败原因：

MQTT服务器未连接或连接断开
主题权限不足
消息格式错误
编码类型配置错误

注意事项

编码格式匹配：产品配置的编码类型必须与设备端解码方式一致
主题优先级：脚本中的 downTopic 优先级最高，会覆盖端云配置
性能考虑：大批量回复时注意MQTT服务器的性能和带宽
日志记录：每条回复都会记录日志，方便问题排查
QoS等级：回复消息的QoS等级继承上报消息的QoS等级

技术参数

支持的通配符：+（单级）、#（多级）
支持的QoS等级：0、1、2
支持的编码格式：JSON、HEX、Base64、自定义
消息类型标识：ACK
处理器执行顺序：2000（在数据推送后执行）

MQTT 常见功能问题 ​

通信组件-MQTT服务是什么？适合什么场景？ ​

设备交互应答配置 ​

MQTT 常见功能问题

通信组件-MQTT服务是什么？适合什么场景？

设备交互应答配置