Skip to main content

MQTT 设备接入

概述​

本文档详细介绍了通过 MQTT 协议将设备接入 Neuron 平台的完整流程。该方式适用于各类设备，核心要求是确保设备上报的数据格式与平台配置严格匹配，从而实现数据的准确解析和稳定接入。

开始之前​

确认数据来源​

如果您需要将来自Kafka等消息队列的现有设备数据接入中台, 则需选择MQTT方式。【Kafka预配置指南】。

权限配置​

为确保以下操作流程正常进行，请您确认是否拥有项目管理员权限。

前置配置​

tip

您的设备将通过 MQTT Server 发送数据，Neuron 平台会根据您配置的 MQTT Server 和 Topic 订阅设备数据。因此，您需要先正确配置所使用的 MQTT Server 和 Topic 。在 Topic 的 Payload 中需包含设备各点位的实时数据，请确保 Payload 中的点位名称（name）与 Neuron 平台内物模型的 Function Type 名称一致（忽略大小写），否则平台将无法识别相应数据。

通过 MQTT 方式接入的设备需提前确认并配置所使用的。

  1. MQTT 服务器
  2. 主题
  3. 设备上报的数据格式

MQTT

配置 MQTT Server​

在左侧菜单点击 MQTT 管理 - MQTT Server，查看系统内已存在的 MQTT Server。点击添加按钮可新增您的 MQTT Server。

MQTT_List

填写 MQTT Server 信息：

  • 名称：不可重复，必填；
  • 主机/端口：根据 MQTT Server 的信息输入，必填；
  • 用户名/密码：有则填入；
  • SSL证书：不带证书的host前缀为 tcp://，带证书的前缀为 ssl://；
    • 不带证书的界面：
    • 带证书的界面(SSL配置)：
  • 状态：开启。 MQTT_Server_ADD

配置 Topic​

在左侧菜单点击 MQTT 管理 - Topic，查看系统内已存在的 Topic。点击添加按钮可新增主题。

topic

  • Topic：必填，输入订阅的 Topic；
  • MQTT Server：必填，选择所使用的 MQTT Server，如没有则需要先添加（配置 MQTT 服务器）；
  • Category: 系统分为三类；
    • Other: 默认选择, 表示 Topic 仅支持精确匹配 (topic name完全一致才能订阅成功, 只允许主题层级分隔符 / 和普通的UTF-8字符, 不能包含 + 和 #)；
    • LoRaWAN NS: 表示 Topic 支持通配 (通配格式不是一个完整的、确定的主题名，而是一个主题过滤器，用于订阅，可以匹配多个具体的主题, 通常包含+/#字符)；
    • Dataset: 此功能暂未开放。 topic_add
  • ETL 类型：必填，选择数据的类型（IoT/BMS/OpenAPI 等）。例如：若是 IoT 设备则选择 IOT_DATA；BMS 设备则选择 BMS_API；通过 openAPI 接入则选择 openAPI；
    • ETL_Type
    • ETL_Type_JSON
    • 选择后需检查下方的 JSON 格式是否与设备上报的数据格式一致。系统会按照 MQTT Server 信息订阅并解析此 JSON。若格式不匹配，设备接入将失败，需要选择/新增 ETL 转换器（详见下文 配置 ETL 转换器）。
    • ETL_Converter_check
  • ETL 转换器类型：若默认的 JSON 格式与您的设备不匹配，则需要 ETL 转换器作为桥梁精准指定单设备数据对象与系统所需数据格式间的匹配关系，目前仅支持ETL转换器，JS转换器敬请期待；
  • ETL 转换器：鉴于数据格式不匹配，新增并选择您的 ETL 转换器（详见下文 配置 ETL 转换器）；
  • 状态：开启

配置 ETL 转换器​

tip

若默认的 JSON 格式与您的设备不匹配，则需要配置 ETL 转换器进行格式转换。

在左侧菜单点击系统设置 - ETL 转换器，查看系统内已存在的 ETL 转换器。点击添加按钮可新增 ETL 转换器。

ETL_Converter

填写 ETL 转换器信息:

Add_Data_Converter

  • 名称：不可重复，必填；
  • 类型：IoT/Non IoT；
  • Payload content/有效负载内容：设备上报数据 JSON 格式，必填；
  • Device ID key：匹配 JSON 中用来识别设备的唯一 ID，通常为 Device ID / DevEUI，必填；
  • Device points object key：匹配 JSON 中设备上报数据的点位，必填；
  • Date key：匹配 JSON 中设备上报数据的时间；
  • Device name key：匹配后在平台中用于展示的设备名称；
  • Device location key：匹配后在平台中用于标记设备的位置信息；
  • 状态：开启。

操作详见【ETL 转换器】。

配置物模型​

tip

物模型定义：在 Neuron 平台内，将某一类具有相同能力或特征的设备的合集被称为一款物模型。

设备接入前可在中台物模型列表中进行预配置，或在设备接入过程中逐一配置。详情请见【物模型管理】。

device_twins_list

选择接入方式​

在设备管理列表页点击“添加”按钮，进入设备接入流程。

device_list

接入方式选择 MQTT，点击下一步。

deviceAccess

选择数据上报格式​

tip

设备数据的推送有着严格的格式匹配规则，系统会按照您配置的 MQTT 服务器信息订阅并解析。若已选择的数据上报 JSON 格式与真实的上报格式不匹配，设备接入将失败，需要选择/新增 ETL 转换器（详见上文或查看【ETL 转换器】）。

选择系统预置的格式​

列表默认展示系统预置的格式，选择一个匹配的格式后，点击下一步去配置物模型。

mqtt_dataFormat_default

选择已创建的 ETL 转换器​

如您的设备上报格式与系统预置的不匹配，则需要选择/新增 ETL 转换器。系统会根据选择的转换器中的格式解析数据。

点击切换到 转换器 面板选择一个已经创建的 ETL 转换器。

mqtt_dataFormat_converter

如需新增 ETL 转换器，操作详见【ETL 转换器】。

选择物模型​

选择已存在的物模型​

支持通过物模型名称/类型/品牌快速检索。

mqtt_check_device_twins

新增物模型​

点击新增物模型按钮，进入新增界面，填写物模型信息后，点击“提交”按钮创建物模型。

mqtt_add_device_twins

注意：物模型名称不可重复，信息提交时系统会验证名称唯一性，名称重复则添加不成功。

配置 Function Type（点）​

创建物模型成功后，可直接进行该物模型下的 Function Type 配置。

点击图中所指的“+”按钮，进入 Function Type 新增页。

lora_add_device_twins_functions

点击 Function type 输入框，选择/新增一个 Function type。其余配置说明详见【物模型管理】。

lora_adding_device_twins_functions

如该物模型有多个 Function Type 可重复上面步骤，添加多个 Function Type。配置完成后，点击下一步，进入设备注册页面。

mqtt_added_device_twins_functions

选择 Topic​

tip

Neuron 平台会根据您配置的 MQTT Server和Topic订阅设备数据。因此，您需要先正确配置所使用的 MQTT Server 和 Topic。

选择已存在的 Topic​

支持基于名称的快速检索。

mqtt_add_device_networkServer

新增 Topic​

填写 Topic 信息：

topic_add

  • Topic 名称：需与设备上报时使用的topic格式完全一致才能订阅成功 (MQTT方式接入仅支持精确匹配格式, 允许主题层级分隔符 / 和普通的UTF-8字符, 不能包含 + 和 #)；
  • Interval: 无需改动；
  • MQTT Server：必填，选择所使用的 MQTT Server，如没有则需要先添加（配置 MQTT 服务器）；
  • 分类: 通过 MQTT 方式接入的设备需选择 Other；
  • ETL 类型：无需改动, 会自动带入第一步所选的数据格式, 需检查下方的 JSON 格式是否与设备上报的数据格式一致。系统会按照 MQTT 服务器信息订阅并解析此 JSON。若格式不匹配，设备接入将失败，需要选择/新增 ETL 转换器；
    • ETL_Converter_check
  • ETL 转换器类型: 若默认的 JSON 格式与您的设备不匹配，则需要配置 ETL 转换器进行数据转换 (目前仅支持ETL转换器，JS转换器功能暂未开放)；
  • ETL 转换器：第一步若选择Converter则会自动带入, 也可选择所需 ETL 转换器（新增 ETL 转换器流程详见上文）；
  • 状态：开启。

配置完成后，点击下一步，进入设备注册页面。

设备注册​

tip

支持两种录入方式：在线编辑或下载 Excel 批量录入。

设备绑定平台项目​

注册设备前，请先选择设备所属的项目。点击项目下拉框选择现有项目。如尚未创建项目，请先新建一个，操作详见【创建项目】。

lora_add_device_binding_project

批量 Excel​

操作步骤：下载模板 -> 填写 Excel -> 上传 Excel -> 如有错误则进行在线编辑 -> 点击下一步完成设备注册。

下载模板​

在设备注册页，点击下图红框处，下载模板文件。

lora_add_device_download_temp

填写 Excel​

将需要录入的设备信息填入 Excel。MQTT 的模板分为 IoT 设备和非 IoT 设备两种：

IoT 设备模板​

lora_add_device_download_temp_csv

  • DevEUI：IoT 设备唯一标识，通常填写设备上的 DevEUI 即可，必填；
  • deviceName：设备名称，不可重复，必填；
  • buildingName：楼宇位置信息，必填；
  • location：设备位置，非必填。
非 IoT 设备模板​

noniot_excel

  • rawId：IoT 设备唯一标识，通常填写设备功能点的 Id 即可，必填；
  • buildingName：楼宇位置信息，必填；
  • deviceName：设备名称，多个功能点可以填写同一个设备名称，系统会认为这些功能点属于同一个设备，必填；
  • functionType：设备功能点位，需要和所选物模型下的功能点相匹配，必填；
  • location：设备位置，非必填；
  • isIot：标识是否为 IoT 设备，为空默认为非 IoT 设备，非必填。

上传 Excel​

点击/拖拽下图红框处，将填写好的 Excel 上传至平台。上传的设备信息将会展示在在线表格中，如有错误可以继续增删改。

mqtt_add_device_upload_temp

在线编辑​

在页面上填写设备信息，点击新增按钮添加新一行，继续录入设备信息。

mqtt_add_device_ui_add_iot

设备信息填写完成后，点击提交按钮，出现确认窗口，确认后即可完成设备注册。

mqtt_add_device_submit_confirm_iot

注册完成后会跳转到设备注册页（见下图红框处为刚注册的设备数据），平台订阅到规范的上报数据后，设备即接入成功。设备注册成功后，可在设备管理界面查看设备信息及数据，具体操作详见【设备管理】。

lora_add_device_submit_success

注意：设备注册成功表示已在 Neuron 平台登记，状态为已登记，但未接通实时数据。系统会根据配置的参数去订阅上报的数据并清洗入库后，设备状态更新为已连接，并显示在设备列表中。