DIVUS VISION API 軟體使用手冊

DIVUS VISION API 軟體

規格

• 產品：DIVUS VISION API
• 製造商: DIVUS GmbH
• 版本：1.00 REV0 1 – 20240528
• 地點: Pillhof 51, 埃潘 (BZ), 義大利

產品資訊

DIVUS VISION API 是一款設計用於與 DIVUS VISION 系統連接的軟體工具。它允許使用者使用 MQTT 協定存取和控制系統內的各種元素。

常問問題

Q：我可以在不了解 PC 或自動化技術的情況下使用 DIVUS VISION API 嗎？

答：本手冊是為具有這些領域知識的使用者量身定制的，以確保 API 的高效使用。

一般資訊

• DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – 義大利

操作說明、手冊和軟體均受版權保護。版權所有。禁止複製、複製、翻譯、翻譯全部或部分內容。建立供個人使用的軟體備份副本是一個例外。
本手冊如有更改，恕不另行通知。我們不能保證本文檔和所提供的儲存媒體所包含的資料沒有錯誤且正確。始終歡迎改進建議以及錯誤提示。這些協議也適用於本手冊的具體附件。本文檔中的名稱可能是商標，第三方出於自身目的使用這些商標可能會侵犯其所有者的權利。使用者說明：請在首次使用前閱讀本手冊，並妥善保存以供日後參考。目標群體： 本手冊是為具有 PC 和自動化技術知識的使用者編寫的。

演示慣例

介紹

簡介

本手冊介紹了 VISION API（應用程式介面）－透過此介面可以從外部系統對 VISION 進行尋址和控制。
實際上，這意味著您可以使用諸如

• MQTT 瀏覽器（https://www.microsoft.com/store/… - 供測試用），
• 家庭助理（https://www.home-assistant.io/） 或者
• 節點-RED (https://nodered.org/)

控制 VISION 管理的元素或讀取其狀態。存取和通訊透過 MQTT 協定進行，該協定使用所謂的主題來處理單一函數或函數集，或了解它們的變更。 MQTT 伺服器（代理）用於此目的，負責處理安全性以及向參與者管理/分發訊息。在這種情況下，MQTT 伺服器直接位於 DIVUS KNX IQ 上，並為此專門配置。儘管無需程式設計知識也可以使用 VISION API，但此功能適合進階使用者。

必備條件

正如 VISION 手冊中所述，預設必須先啟動 API 使用者才能使用它，API 存取只能使用 Api 使用者驗證資料進行。就使用者權限而言，可以在所有或單一元素上配置此功能的啟動。參見第 0 章。當然，您還需要一個 VISION 項目，其中您想要從外部控制的元素已完全配置，並且與它們的連接已成功測試。為了能夠透過 API 尋址各個元素，必須知道它們的元素 ID：它顯示在元素設定表單的底部

安全

出於安全原因，API 存取只能在本地進行（即不能透過雲端）。因此，啟動 API 存取時的安全風險較低。儘管如此，不應啟用或明確拒絕 API 存取的安全相關元素。

MQTT 及其條款 – 簡要說明

• 在 MQTT 中，集中管理和分發所有訊息的角色是代理。儘管 MQTT 伺服器和 MQTT 代理不是同義詞（伺服器是 MQTT 用戶端也可以扮演的角色的更廣泛術語），但在本手冊中提到 MQTT 伺服器時始終指的是代理。在本手冊中，DIVUS KNX IQ 本身扮演 MQTT 代理/MQTT 伺服器角色。
• MQTT 伺服器使用所謂的主題：用於對資料進行分類、管理和發布的分層結構。
• 發布的主要目標是透過主題向其他參與者提供數據。如果您想要變更某個值，您可以將所需的值變更與所需的主題一起寫入，也可以使用發佈動作。目標設備或 MQTT 伺服器讀取影響它的所需更改並相應地採用它。要檢查更改是否已套用，您可以查看訂閱的即時主題，看看更改是否反映在那裡 - 如果一切順利。
• 客戶選擇他們感興趣的主題：這稱為訂閱。每當主題中/主題下的值發生變化時，所有訂閱的客戶端都會收到通知 - 即無需明確詢問某些內容是否已更改或當前值是多少。
• 您可以透過在主題中輸入名為 client_id 的任何唯一字串來開啟（或定址）與 MQTT 伺服器的單獨通訊通道。主題中必須使用 client_id 來處理值。這用於識別每個變更的起源，有助於解決任何錯誤並且不會影響其他客戶端，因為來自伺服器的相應回應（包括任何錯誤代碼和訊息）也僅到達具有相同 client_id 的主題（因此僅那個客戶）。 client_id是一個唯一的字串，由字元0-9、az、AZ、「-」、「_」的任意組合組成。
• 一般情況下，DIVUS KNX IQ MQTT 伺服器的訂閱主題包含關鍵字狀態，發佈主題包含關鍵字請求。一旦出現外部值更改，或者客戶端本身透過發布請求值更改並已成功應用，狀態就會自動更新。用於發布的又分為(request/)get類型和(request/)set類型。
• 值變更和其他可選參數透過所謂的有效負載添加到主題中。各個元素的參數（元素 ID、名稱、型別、函數）

MQTT 與經典的客戶端伺服器模型（客戶端請求然後更改資料）之間的主要區別集中在訂閱和發布的概念上。參與者可以發布數據，使其可供其他人使用，如果有興趣，其他人可以訂閱它。這種架構可以最大限度地減少資料交換，並仍然使所有感興趣的各方保持最新狀態。有關詳細信息，請參見此處：此處將使用特殊參數（uuid、過濾器）。儘管有多種選項，但本手冊中的有效負載顯示為 JSON 格式。 JSON 使用括號和逗號來表示任何結構的數據，從而最大限度地減少要傳輸的資料包的大小。有關有效負載的更多詳細資訊可以在手冊後面找到。

• 對於特殊目的，可以根據功能類型進行過濾，例如僅尋址開/關，即1位元開關。有效負載中的過濾器參數用於此目的。目前只能按函數類型進行篩選。
• 為了能夠尋址各個元素，需要它們的元素 ID。這可以在元素屬性選單中的 VISION 中找到，也可以直接從 MQTT Explorer 常規訂閱中每個可用元素前面顯示的資料中讀取（其中的元素按元素 ID 按字母順序列出）。

API 存取的配置

配置 API 使用者存取權限的 VISION

以管理員身分在 VISION 中，進入配置 - 使用者/API 存取管理，按一下使用者/API 訪問，然後右鍵單擊 API 使用者（或按住）以開啟編輯視窗。在那裡您將找到這些參數和數據

• 啟用（複選框）
  • 用戶首先在此處啟用。預設為禁用
• 使用者名稱
  • 透過 API 存取需要此字串 – 從此處複製
• 密碼
  • 透過 API 存取需要此字串 – 從此處複製
• 權限
  • 可以在此處定義讀取和寫入 VISION 元素值的預設權限，即此處定義的內容適用於所有現有和未來的元素。如果您只想允許存取單一元素，則不應變更這些預設權限

單一元素的權限

建議您不要授予對整個專案的 API 存取權限，而僅授予所需元素的 API 存取權限。進行如下操作

1. 以管理員身分登入 VISION
2. 選擇所需的元素並開啟其設定選單（右鍵或按住，然後開啟「設定」）
3. 在選單項目“常規 - 權限”下，啟動“覆蓋預設權限”，然後轉到子項目“權限”，其中顯示權限矩陣。
4. 在這裡啟動控制權限，這也使得 view 直接許可。如果您只想透過API存取讀取數據，則啟用該功能就足夠了 view 允許。
5. 對您要存取的所有元素重複相同的過程

透過 MQTT 連接

介紹

作為前任amp在文件中，我們將示範透過 DIVUS KNX IQ 的 MQTT API 進行訪問，使用一個相對簡單的免費軟體，稱為 MQTT Explorer（請參閱第 1.1 章），該軟體適用於 Windows、Mac 和 Linux。需要具備 MQTT 的基本知識和經驗。

連接所需的數據

如前所述（請參閱第 2.1 節），需要 API 使用者的使用者名稱和密碼。這是一個結束view 建立連線之前必須收集的所有資料：

• 使用者名稱 在API使用者詳情頁讀取
• 密碼在API使用者詳情頁讀出
• IP 位址在常規 - 網路 - 乙太網路下的啟動器設定中讀出（或透過同步器）
• 連接埠 8884（此連接埠為此目的保留）

首次連接 MQTT Explorer 和常規訂閱

通常，MQTT 區分訂閱和發布活動。 MQTT Explorer 透過在第一次連接時自動訂閱所有可用主題（主題#）來簡化此過程。因此，成功連接後，可以在 MQTT Explorer 視窗的左側區域直接看到通往所有可用元素（即授予 API 使用者存取權限）的樹。若要輸入更多訂閱主題或將 # 替換為更具體的主題，請前往連線視窗中的進階。右上角顯示的主題如下所示：

其中 7f4x0607849x444xxx256573x3x9x983 是 API 用戶名，objects_list 包含所有可用元素。如果您只想訂閱單一元素，請在objects_list/後面輸入所需元素的元素ID。

注意：這種類型的訂閱大致對應於KNX回饋位址背後的邏輯；它顯示元素的目前狀態，並可用於檢查所需的變更是否已成功套用。如果你只想讀出數據而不改變它，這種類型的訂閱就足夠了。

單一簡單元素在 JSON 表示法中看起來像這樣

注意：所有值都具有上面所示的語法，例如 { “value”: “1” } 作為訂閱主題的輸出，而值直接寫入有效負載中以更改值（即對於發布主題） - 括號和“value ”被省略，例如“onoff”：“1”。

進階命令

介紹

一般有3種主題：

1. 訂閱主題以查看可用元素並獲取即時值變化
2. 訂閱主題以獲得 (客戶 ) 發布請求
3. 發布主題以取得或設定元素及其值

稍後我們將使用此處顯示的編號來引用這些類型（例如類型 1、2、3 的主題）。更多詳細資訊請參閱以下各節和第 4.2 章。 XNUMX.

訂閱主題以查看可用元素並獲取即時價值變化

這些已經描述過了

訂閱主題以獲得客戶發布請求的答案

此類主題是可選的。它允許

• 使用任意 client_id 開啟與 MQTT 伺服器的唯一通訊通道。更多相關內容請參考第 4.2.2 章。 XNUMX
• 取得相應訂閱主題上的發布請求的結果：成功或失敗，並包含錯誤代碼和訊息。

有不同的主題可以獲得獲取或設定發布命令的答案。相應的差異為 一旦您直接獲得系統所需的主題，您可以決定刪除此步驟並直接使用發布主題。

 發布主題以取得或設定元素及其值

這些主題使用與訂閱類似的路徑 - 唯一的變化是用“請求”一詞代替了用於訂閱的“狀態”。完整的主題路徑將在後面的章節中顯示。 4.2.2\ get 主題將請求讀取 MQTT 伺服器的元素和值。有效負載可用於基於元素的功能類型進行過濾。設定的主題將請求更改元素的某些部分，如其有效負載中詳述。

命令和相應回應的前綴

 簡短說明

發送到 MQTT 伺服器的所有命令都有一個共同的初始部分，即：

詳細說明

即時主題（類型 1）將具有通用前綴（見上文），然後是

or

對於設定命令，有效負載顯然起著主要作用，因為它將包含所需的變更（即元素功能的變更值）。警告：切勿在類型 3 指令中使用保留選項，因為它可能會導致 KNX 端出現問題。

EXAMPLE：發布以更改單一元素的值

最簡單的情況是想要更改一般 subscribe 顯示的元素之一的值。
一般來說，透過 MQTT 更改/切換 VISION 的功能由 3 個步驟組成，並非所有步驟都是絕對必要的，但我們仍然建議按照描述執行。

1. 使用自訂 client_id 訂閱包含我們要編輯的功能的主題
2. 用於編輯的主題與有效負載一起發布，並使用 1 中選擇的 client_id 進行所需的更改。
3. 要進行檢查，您可以查看主題 (1.) 中的答案 - 即 (2.) 是否有效
4. 在常規訂閱中，所有值在發生變更時都會更新，如果一切順利，您可以看到所需的值變更。

執行此操作的步驟是：

1. 選擇一個 client_id 例如「Divus」並將其插入 API 使用者名稱後面的路徑中
   這是使用 MQTT 伺服器訂閱您自己的通訊通道的完整主題。這告訴伺服器您期望對您打算發送的變更做出回應。注意定義 a 的狀態/設定部分。這是一個訂閱主題，並且 b.它將獲得設定類型命令的答案。
2. 除了切換狀態請求關鍵字之外，發布主題將相同
3. 更改內容應包含在有效負載中。這是一些前amp萊斯。
   • 關閉具有開/關功能的元件（1 位元）：
   • 開啟具有開/關功能的元件（1 位元）。此外，如果從同一個客戶端啟動多個此類命令，則可以使用uuid 參數（“唯一ID”，通常是格式為128-8-4-4-4 位元十六進位的12 位元字串）來分配對對應查詢的回應，因為該參數（如果存在於查詢中）也可以在回應中找到。
   • 開啟調光器並將亮度設定為 50%
   • 上面顯示和訂閱的主題的答案（準確地說是其有效負載）是，例如amp勒。
     以上回覆是前amp儘管該元件沒有調光功能，但在有效負載正確的情況下仍然有效。如果存在更嚴重的問題導致無法正確解釋有效負載，則回應將如下所示（例如）：
     對於錯誤代碼和訊息的解釋，但一般來說，就像 http 一樣，200 個代碼是肯定答案，而 400 個代碼是否定答案。

EXAMPLE：發布以更改多個元素值

該過程與先前所示的更改單一元素的過程類似。不同之處在於，您省略了主題中的 element_id，然後在有效負載內的資料前面指示 element_id 集。請參閱下面的語法和結構。

依查詢中的功能類型過濾

有效負載中的過濾器參數僅允許尋址元素的所需功能。開關或調光器的開/關功能稱為“onoff”，例如ample，對應的過濾器定義如下：

答案看起來像這樣，例如ample

方括號表示您也可以按多個函數進行過濾，例如

導致這樣的答案：

附錄

錯誤代碼

MQTT 通訊中的錯誤會導致數字代碼出現。下表有助於對其進行分解。

有效負載參數

有效負載根據上下文支援不同的參數。下表顯示了哪些參數可以出現在哪些主題中

版本說明

• 版本1.00

訊息：

• 首次發表