跳至主要内容

MQTT 設備接入

概述​

本文檔詳細介紹了透過 MQTT 協議將設備接入 Neuron 平台的完整流程。該方式適用於各類設備，核心要求是確保設備上報的數據格式與平台配置嚴格匹配，從而實現數據的準確解析和穩定接入。

開始之前​

確認數據來源​

如果您需要將來自Kafka等訊息佇列的現有設備數據接入中台, 則需選擇MQTT方式。【Kafka預配置指南】。

權限配置​

為確保以下操作流程正常進行，請您確認是否擁有專案管理員權限。

前置配置​

提示

您的設備將透過 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 轉換器​

提示

若預設的 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 轉換器】。

配置物模型​

提示

物模型定義：在 Neuron 平台內，將某一類具有相同能力或特徵的設備的合集被稱為一款物模型。

設備接入前可在中台物模型列表中進行預配置，或在設備接入過程中逐一配置。詳情請見【物模型管理】。

device_twins_list

選擇接入方式​

在設備管理列表頁點選“新增”按鈕，進入設備接入流程。

device_list

接入方式選擇 MQTT，點選下一步。

deviceAccess

選擇數據上報格式​

提示

設備數據的推送有著嚴格的格式匹配規則，系統會按照您配置的 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​

提示

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 轉換器流程詳見上文）；
  • 狀態：開啟。

配置完成後，點選下一步，進入設備註冊頁面。

設備註冊​

提示

支援兩種錄入方式：線上編輯或下載 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 平台登記，狀態為已登記，但未接通即時數據。系統會根據配置的參數去訂閱上報的數據並清洗入庫後，設備狀態更新為已連線，並顯示在設備列表中。