跳到主要内容

自定义主题报文设备接入

一、概述​

主题转换功能用于将设备自定义的 MQTT 主题映射到平台规范主题，实现不同厂商设备的无侵入接入。

核心概念：

  • 原始主题：设备实际发布/订阅的真实主题
  • 目标主题：平台规范化后的主题
  • 数据方向：
    • 上行：设备 → 平台
    • 下行：平台 → 设备

功能组合： 主题转换可与数据处理功能搭配使用，对上下行报文进行格式转换、字段映射等处理，解决非规范报文设备的接入问题。

二、上行主题转换​

定义​

设备实际发布的 MQTT 主题。支持使用 + 作为路径占位符匹配变量部分，不支持 #。可选使用变量区分消息。

基础示例​

设备发布： 123456789/up/devices

配置映射：

  • 原始主题：+/up/devices
  • 目标主题：devices/telemetry

处理结果： 设备发布到 123456789/up/devices 的消息会被自动转发到平台规范主题 devices/telemetry

关于 message_id​

  • 自动生成：若目标主题配置为 devices/attributes/{message_id}，设备发布时可不带 message_id，系统会自动生成
  • 响应追踪：响应主题会携带 message_id，用于设备识别对应的响应内容

三、下行主题转换​

定义​

设备实际订阅的 MQTT 主题。支持动态变量，目标主题末尾可使用 + 匹配 message_id。

基础示例​

设备订阅： 123456789/down

配置映射：

  • 原始主题：{device_number}/down
  • 目标主题：devices/telemetry/control/{device_number}

处理结果： 平台发布到 devices/telemetry/control/123456789 的消息会被自动转发到设备订阅的主题 123456789/down

多映射场景​

当一个设备支持多种指令类型时，通过 data_identifier 识别和路由。

配置示例：

映射1: devices/command/{device_number}/+ → wled/{device_number}/cmd (data_identifier = "wled")
映射2: devices/command/{device_number}/+ → default/{device_number}/cmd (data_identifier = "default")

消息处理流程：

  1. Web端发送：{"method": "wled", "params": {"delay": 3}} 到 devices/command/{device_number}/+
  2. 系统匹配 method="wled" → 命中映射1
  3. 设备收到：{"delay": 3} 至 wled/{device_number}/cmd（仅转发 params 部分）

兜底规则：

  • 如果所有配置的 data_identifier 都不匹配，则使用第一个 data_identifier 为空的配置进行转发（payload 保持原样）

四、数据处理功能​

定义​

数据处理功能用于对上下行报文进行预处理，包括格式转换、字段映射、数据清洗等，解决设备报文格式与平台规范不一致的问题。

使用场景​

场景示例1：非JSON格式转换为JSON格式

某些设备上报的数据可能是自定义格式或CSV格式，需要转换为平台标准的JSON格式。

  1. 设备上报格式（自定义分隔符）：temp:25.5|hum:60|press:1013.25
  2. 平台规范格式：{"temperature": 25.5, "humidity": 60, "pressure": 1013.25}
  3. 解决方案：
    • 配置主题转换：将设备主题 device/{device_number}/data 映射到平台规范主题 devices/telemetry
    • 配置数据处理：通过「上报数据预处理」解析自定义格式，转换为标准JSON结构

场景示例2：嵌套JSON结构转换为扁平JSON结构

某些设备上报的数据是嵌套结构，需要转换为平台要求的扁平结构。

  1. 设备上报格式（嵌套结构）： 
    {
      "sensor": {
        "temperature": 25.5,
        "humidity": 60
      },
      "timestamp": 1699123456
    }
  2. 平台规范格式（扁平结构）： 
    {
      "temperature": 25.5,
      "humidity": 60,
      "timestamp": 1699123456
    }
  3. 解决方案：
    • 配置主题转换：将设备主题映射到平台规范主题
    • 配置数据处理：通过「上报数据预处理」将嵌套结构展开为扁平结构

处理流程：

设备发布 → 主题转换 → 数据处理 → 平台规范主题

五、操作步骤​

5.1 进入协议配置页面​

进入协议配置页面

  1. 进入设备模板详情页
  2. 点击「协议配置」标签页
  3. 选择协议类型为「MQTT」

5.2 添加上行主题映射​

添加上行主题映射

  1. 点击「添加」按钮
  2. 填写映射信息：
    • 映射名称：规则名称（必填）
    • 数据方向：选择「发布：上行（设备 → 云）」
    • 原始主题：设备实际发布的主题，支持 + 占位符
    • 目标主题：平台规范主题（下拉选择）
    • 描述：可选说明
  3. 点击「保存」

5.3 添加下行主题映射​

添加下行主题映射

  1. 点击「添加」按钮
  2. 填写映射信息：
    • 映射名称：规则名称（必填）
    • 数据方向：选择「订阅：下行（云 → 设备）」
    • 原始主题：设备实际订阅的主题，必须包含 {device_number}
    • 目标主题：平台规范主题（下拉选择）
    • 命令标识符（可选）：用于多映射场景，匹配 payload 中的 method 字段
    • 描述：可选说明
  3. 点击「保存」

5.4 编辑和删除映射​

  • 点击「编辑」按钮可修改映射配置
  • 点击「删除」按钮可删除映射规则
  • 修改后需点击页面底部的「保存」按钮生效

5.5 配置数据处理​

配置数据处理

  1. 在设备模板详情页，点击「数据处理」标签页
  2. 点击「新增数据处理」按钮
  3. 选择处理类型：
    • 上报数据预处理：处理设备上报的遥测数据
    • 下发数据预处理：处理平台下发的控制数据
    • 属性上报/下发预处理：处理属性相关数据
    • 指令下发预处理：处理指令下发数据
    • 事件上报预处理：处理事件上报数据
  4. 配置数据处理规则（如字段映射、格式转换等）
  5. 保存配置

处理顺序：

  • 主题转换先执行，将消息转发到规范主题
  • 数据处理后执行，对消息内容进行格式转换

六、注意事项​

  1. 占位符规则：

    • 支持 +（单层匹配），不支持 #（多层匹配）
    • 下行原始主题必须包含 {device_number} 变量

  2. 优先级：

    • 映射按优先级（priority）从小到大依次匹配
    • 优先级越小，越先匹配

  3. 多映射匹配：

    • 下行主题转换时，优先匹配 data_identifier 不为空的配置
    • 匹配成功时，payload 会被精简为 params 部分
    • 未匹配时，使用 data_identifier 为空的兜底配置，payload 保持原样

  4. 缓存机制：

    • 映射配置变更后会自动清除缓存
    • 如遇配置不生效，可等待缓存刷新或重启服务

  5. 主题转换与数据处理：

    • 主题转换负责主题映射，数据处理负责报文内容转换
    • 两者可配合使用，实现完整的非规范设备接入方案
    • 处理顺序：主题转换 → 数据处理

七、常见问题​

Q: 为什么设备发布的消息没有被转发？

A: 检查以下几点：

  • 确认原始主题模式是否正确匹配设备实际主题
  • 确认设备已关联正确的设备模板

Q: 下行消息的 payload 为什么被修改了？

A: 当 data_identifier 匹配成功时，系统会自动将 payload 精简为 params 部分。如需保持原样，请使用 data_identifier 为空的兜底配置。

Q: 如何测试主题映射是否生效？

A: 可以使用 MQTT 客户端工具：

  • 上行：模拟设备发布到原始主题，观察平台规范主题是否收到消息
  • 下行：在平台发布到规范主题，观察设备订阅的原始主题是否收到消息

Q: 主题转换和数据处理有什么区别？

A:

  • 主题转换：解决主题名称不一致的问题，将设备自定义主题映射到平台规范主题
  • 数据处理：解决报文格式不一致的问题，对消息内容进行格式转换、字段映射等处理
  • 两者配合使用可解决非规范设备的完整接入需求