DIVUS VISION API ソフトウェア ユーザー マニュアル

DIVUS VISION API ソフトウェア

仕様

• 製品: DIVUS VISION API
• メーカー: DIVUS GmbH
• バージョン: 1.00 REV0 1 – 20240528
• 所在地: Pillhof 51、Eppan (BZ)、イタリア

製品情報

DIVUS VISION API は、DIVUS VISION システムとのインターフェイス用に設計されたソフトウェア ツールです。これにより、ユーザーは MQTT プロトコルを使用してシステム内のさまざまな要素にアクセスし、制御することができます。

よくある質問

Q: PC や自動化技術に関する事前の知識がなくても、DIVUS VISION API を使用できますか?

A: このマニュアルは、API を効率的に使用できるように、これらの分野に関する事前の知識を持つユーザー向けに作成されています。

一般情報

• DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – イタリア

操作手順、マニュアル、ソフトウェアは著作権で保護されています。無断複写・転載を禁じます。全体または一部の複製、複写、翻訳、翻訳は許可されません。ただし、個人使用目的でソフトウェアのバックアップ コピーを作成する場合は例外となります。
マニュアルは予告なく変更されることがあります。この文書および提供される記憶媒体に含まれるデータに誤りがなく正確であることは保証できません。改善の提案や誤りのヒントはいつでも歓迎します。合意は、このマニュアルの特定の付録にも適用されます。この文書内の名称は商標である可能性があり、第三者が独自の目的で使用すると所有者の権利を侵害する可能性があります。ユーザー指示: 初めて使用する前にこのマニュアルを読み、将来の参照のために安全な場所に保管してください。対象グループ: このマニュアルは、PC および自動化技術に関する知識を持つユーザー向けに書かれています。

プレゼンテーションの慣例

導入

概要

このマニュアルでは、VISION を外部システムからアクセスおよび制御できるインターフェイスである VISION API (アプリケーション プログラミング インターフェイス) について説明します。
実際には、次のようなシステムを使用できることを意味します。

• MQTTエクスプローラー（https://www.microsoft.com/store/… - テスト用）、
• ホームアシスタント（https://www.home-assistant.io/） または
• Node-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 サーバーのサブスクライブ トピックにはキーワード status が含まれ、パブリッシュ トピックにはキーワード request が含まれます。ステータスを持つトピックは、外部の値が変更されるか、クライアント自体がパブリッシュを介して値の変更を要求し、それが正常に適用されるとすぐに、自動的に更新されます。パブリッシュ用のトピックは、さらに (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次に、Windows、Mac、Linux で使用できる MQTT Explorer (第 1.1 章を参照) と呼ばれる比較的シンプルな無料ソフトウェアを使用して、DIVUS KNX IQ の MQTT API 経由でアクセスする方法を説明します。MQTT に関する基本的な知識と経験が必要です。

接続に必要なデータ

前述のように（セクション2.1を参照）、APIユーザーのユーザー名とパスワードが必要です。view 接続を確立する前に収集する必要があるすべてのデータ:

• ユーザー名 APIユーザーの詳細ページで読み上げられる
• APIユーザーの詳細ページで読み上げられるパスワード
• IPアドレスは、ランチャー設定の「一般」-「ネットワーク」-「イーサネット」（またはSynchronizer経由）で読み取られます。
• ポート 8884 (このポートはこの目的のために予約されています)

MQTTエクスプローラーと一般購読との最初の接続

通常、MQTT はサブスクライブとパブリッシュのアクティビティを区別します。MQTT Explorer は、最初の接続が確立されたときに、利用可能なすべてのトピック (トピック番号) を自動的にサブスクライブすることでこれを簡素化します。その結果、接続が成功した後、利用可能なすべての要素 (つまり、API ユーザー アクセスの許可) につながるツリーが MQTT Explorer ウィンドウの左側の領域に直接表示されます。さらにサブスクライブ トピックを入力するか、# をより具体的なトピックに置き換えるには、接続ウィンドウの [詳細] に移動します。右上に表示されるトピックは次のようになります。

ここで、7f4x0607849x444xxx256573x3x9x983 は API ユーザー名で、objects_list には利用可能なすべての要素が含まれています。このトピックは常に最新の状態に保たれ、値の変更はリアルタイムで反映されます。個々の要素のみをサブスクライブする場合は、objects_list/ の後に目的の要素の要素 ID を入力します。

注: このタイプのサブスクライブは、KNX フィードバック アドレスの背後にあるロジックにほぼ対応しています。要素の現在のステータスを示し、必要な変更が正常に適用されたかどうかを確認するために使用できます。データを読み出すだけで変更しない場合は、このタイプのサブスクライブで十分です。

単一の単純な要素はJSON表記では次のようになります。

注: すべての値には、サブスクライブ トピックの出力として上記の構文 (例: { “value”: “1” }) がありますが、値はペイロードに直接書き込まれて値を変更します (つまり、パブリッシュ トピックの場合)。括弧と “value” は省略されます (例: “onoff”: “1”)。

高度なコマンド

導入

一般的にトピックには 3 種類あります。

1. トピックを購読して、利用可能な要素を確認し、リアルタイムの値の変更を取得します。
2. 回答を得るにはトピックを購読してください（クライアント ) 公開リクエスト
3. トピックを公開して、要素の値を取得または設定します。

後ほど、ここで示した番号を使用してこれらの種類を参照します (例: タイプ 1、2、3 のトピック)。詳細については、次のセクションと第 4.2 章を参照してください。

利用可能な要素を確認し、リアルタイムの値の変更を取得するには、トピックを購読してください

これらはすでに説明されている

クライアントの公開リクエストに対する回答を得るにはトピックを購読してください

この種のトピックはオプションです。

• 任意の client_id を使用して MQTT サーバーとの一意の通信チャネルを開きます。詳細については、第 4.2.2 章を参照してください。
• 対応するサブスクライブ トピックに対するパブリッシュ要求の結果 (成功または失敗、エラー コード、メッセージ) を取得します。

回答を取得したり、公開コマンドを設定したりするためのさまざまなトピックがあります。対応する違いは システムに必要なトピックを正しく取得したら、この手順を削除して公開トピックを直接使用することもできます。

 トピックを公開して要素とその値を取得または設定する

これらのトピックは、サブスクライブ用のパスに似たパスを使用します。唯一の違いは、サブスクライブに使用される「ステータス」の代わりに「リクエスト」という単語が使用されることです。完全なトピック パスは、第 4.2.2 章で後述します。get トピックは、MQTT サーバーの要素と値の読み取りを要求します。ペイロードは、要素の機能タイプに基づいてフィルター処理するために使用できます。set トピックは、ペイロードに詳細が示されているように、要素の一部を変更するように要求します。

コマンドと対応する応答の接頭辞

 簡単な説明

MQTT サーバーに送信されるすべてのコマンドには、共通の初期部分があります。

詳細な説明

リアルタイムトピック（タイプ1）には、一般的なプレフィックス（上記参照）が付き、その後に

or

set コマンドの場合、ペイロードには必要な変更 (つまり、要素の機能の変更された値) が含まれるため、ペイロードが主な役割を果たします。警告: タイプ 3 コマンドでは、KNX 側で問題が発生する可能性があるため、retain オプションを使用しないでください。

EXAMPLE: 単一要素の値を変更するために公開する

最も単純なケースは、一般的な subscribe によって表示される要素の 1 つの値を変更することです。
一般的に、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 進数でフォーマットされた XNUMX ビットの文字列) を使用して、対応するクエリに応答を割り当てることができます。このパラメータは、クエリ内に存在する場合、応答内にも存在するためです。
   • 調光器をオンにして明るさを50%に設定する
   • 上で示され、購読されているトピック（正確にはそのペイロード）に対する答えは、例えばampル。
     上記の回答は例ですamp要素に調光機能がない場合でも、ペイロードが正しい場合は、応答は次のようになります。ペイロードが正しく解釈されないより深刻な問題がある場合、応答は次のようになります (例):
     エラー コードとメッセージの説明については、http の場合と同様に、一般的に 200 コードは肯定的な回答であり、400 コードは否定的な回答です。

EXAMPLE: 複数の要素の値を変更するために公開する

この手順は、1 つの要素を変更する前に示したものと似ています。違いは、トピックから element_id を省略し、ペイロード内のデータの前に element_id のセットを指定することです。以下の構文と構造を参照してください。

クエリの機能タイプによるフィルタリング

ペイロードのフィルターパラメータにより、要素の必要な機能のみを処理できます。スイッチや調光器のオン/オフ機能は「onoff」と呼ばれます。例:ample であり、対応するフィルタは次のように定義されます。

答えは次のようになります。例えばample

角括弧は、複数の関数でフィルタリングできることを示しています。例:

次のような答えが導き出されます。

付録

エラーコード

MQTT 通信でエラーが発生すると、数値コードが生成されます。次の表は、エラーの詳細を示しています。

ペイロードのパラメータ

ペイロードはコンテキストに応じて異なるパラメータをサポートします。次の表は、どのパラメータがどのトピックで発生する可能性があるかを示しています。

バージョンノート

• 1.00 VERSION

ニュース：

• 初出版