DIVUS VISION API Software

Technische Daten

• Produkt: DIVUS VISION API
• Hersteller: DIVUS GmbH
• Version: 1.00 REV0 1 – 20240528
• Standort: Pillhof 51, Eppan (BZ), Italien

Produktinformationen

Die DIVUS VISION API ist ein Softwaretool zur Schnittstelle mit DIVUS VISION-Systemen. Sie ermöglicht Benutzern den Zugriff auf und die Steuerung verschiedener Elemente innerhalb des Systems über MQTT-Protokolle.

Häufig gestellte Fragen

F: Kann ich die DIVUS VISION API ohne PC- oder Automatisierungstechnik-Vorkenntnisse nutzen?

A: Das Handbuch ist auf Benutzer mit Vorkenntnissen in diesen Bereichen zugeschnitten, um eine effiziente Nutzung der API zu gewährleisten.

ALLGEMEINE INFORMATIONEN

• DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – Italien

Bedienungsanleitungen, Handbücher und Software sind urheberrechtlich geschützt. Alle Rechte vorbehalten. Das Kopieren, Vervielfältigen, Übersetzen, Übertragen im Ganzen oder in Teilen ist nicht gestattet. Ausgenommen hiervon ist die Erstellung einer Sicherungskopie der Software für den persönlichen Gebrauch.
Änderungen des Handbuchs ohne vorherige Ankündigung vorbehalten. Für die Fehlerfreiheit und Richtigkeit der in diesem Dokument und auf den mitgelieferten Datenträgern enthaltenen Daten wird keine Gewähr übernommen. Verbesserungsvorschläge sowie Hinweise auf Fehler sind jederzeit willkommen. Die Vereinbarungen gelten auch für die spezifischen Anhänge dieses Handbuchs. Die Bezeichnungen in diesem Dokument können Marken sein, deren Verwendung durch Dritte für ihre eigenen Zwecke die Rechte ihrer Inhaber verletzen kann. Benutzerhinweise: Bitte lesen Sie dieses Handbuch vor der ersten Verwendung und bewahren Sie es zum späteren Nachschlagen an einem sicheren Ort auf. Zielgruppe: Das Handbuch richtet sich an Benutzer mit Vorkenntnissen in PC- und Automatisierungstechnik.

PRÄSENTATIONSKONVENTIONEN

Einführung

ALLGEMEINE EINFÜHRUNG

Dieses Handbuch beschreibt die VISION API (Application Programming Interface) – eine Schnittstelle, über die VISION von externen Systemen angesprochen und gesteuert werden kann.
In der Praxis bedeutet dies, dass Sie Systeme wie

• MQTT Explorer (https://www.microsoft.com/store/… - zum Prüfen),
• Home-Assistent (https://www.home-assistant.io/) oder
• Knoten-RED (https://nodered.org/)

um die von VISION verwalteten Elemente zu steuern oder deren Status auszulesen. Der Zugriff und die Kommunikation erfolgen über das MQTT-Protokoll, welches sogenannte Topics nutzt, um einzelne Funktionen oder Funktionssätze anzusprechen oder über Änderungen daran informiert zu werden. Dabei kommt ein MQTT-Server (Broker) zum Einsatz, der die Sicherheit und die Verwaltung/Verteilung der Nachrichten an die Teilnehmer übernimmt. Der MQTT-Server befindet sich in diesem Fall direkt auf dem DIVUS KNX IQ und ist speziell für diesen Zweck konfiguriert. Obwohl die VISION API auch ohne Programmierkenntnisse nutzbar ist, ist diese Funktionalität für fortgeschrittene Anwender geeignet.

VORAUSSETZUNGEN

Wie im VISION-Handbuch erklärt, muss der API-Benutzer standardmäßig zuerst aktiviert werden, um ihn verwenden zu können. Der API-Zugriff funktioniert nur über die Authentifizierungsdaten des API-Benutzers. Was die Benutzerrechte betrifft, kann die Aktivierung für diese Funktionalität dann entweder auf allen oder auf einzelnen Elementen konfiguriert werden. Siehe Kap.0. Natürlich benötigen Sie auch ein VISION-Projekt, in dem die Elemente, die Sie von außen steuern möchten, vollständig konfiguriert sind und die Verbindung zu ihnen erfolgreich getestet wurde. Um einzelne Elemente über die API ansprechen zu können, muss deren Element-ID bekannt sein: Diese wird unten im Einstellungsformular des Elements angezeigt.

SICHERHEIT

Aus Sicherheitsgründen ist der API-Zugriff nur lokal (also nicht über die Cloud) möglich. Das Sicherheitsrisiko bei der Aktivierung des API-Zugriffs ist daher gering. Trotzdem sollten sicherheitsrelevante Elemente nicht für den API-Zugriff freigegeben oder explizit verweigert werden.

MQTT UND SEINE BEGRIFFE – KURZE ERKLÄRUNG

• Die Rolle der zentralen Verwaltung und Verteilung aller Nachrichten liegt bei MQTT beim Broker. Obwohl MQTT-Server und MQTT-Broker keine Synonyme sind (Server ist ein weiter gefasster Begriff für eine Rolle, die auch MQTT-Clients spielen können), ist in diesem Handbuch immer der Broker gemeint, wenn von MQTT-Server die Rede ist. Der DIVUS KNX IQ selbst spielt im Rahmen dieses Handbuchs die Rolle des MQTT-Brokers / MQTT-Servers.
• Ein MQTT-Server verwendet sogenannte Topics: eine hierarchische Struktur, mit der Daten kategorisiert, verwaltet und veröffentlicht werden.
• Publizieren hat das primäre Ziel, Daten über Topics anderen Teilnehmern zur Verfügung zu stellen. Möchte man einen Wert ändern, schreibt man zusammen mit der gewünschten Wertänderung in das gewünschte Topic, ebenfalls über eine Publizieren-Aktion. Das Zielgerät bzw. der MQTT-Server liest die gewünschte Änderung, die es betrifft und übernimmt sie entsprechend. Um zu prüfen, ob die Änderung übernommen wurde, kann man im abonnierten Echtzeit-Topic nachschauen, ob sich die Änderung dort widerspiegelt – wenn alles geklappt hat.
• Clients wählen die Themen aus, die sie interessieren: das nennt man abonnieren. Immer wenn sich in/unter einem Thema ein Wert ändert, werden alle abonnierten Clients darüber informiert – also ohne explizit nachfragen zu müssen, ob sich etwas geändert hat oder was der aktuelle Wert ist.
• Durch die Eingabe einer beliebigen eindeutigen Zeichenfolge namens client_id in ein Topic kann ein eigener Kommunikationskanal mit dem MQTT-Server geöffnet (bzw. angesprochen) werden. Die client_id muss im Topic zur Verarbeitung von Werten verwendet werden. Dies dient zur Erkennung der Herkunft jeder Änderung, hilft bei etwaigen Fehlern und hat keine Auswirkungen auf die anderen Clients, da die entsprechenden Antworten des Servers inklusive eventueller Fehlercodes und Meldungen auch nur das Topic mit der gleichen client_id (und damit nur diesen Client) erreichen. Die client_id ist eine eindeutige Zeichenfolge bestehend aus einer beliebigen Kombination der Zeichen 0-9, az, AZ, „-“, „_“.
• Generell enthalten die Subscribe Topics des MQTT-Servers des DIVUS KNX IQ das Schlüsselwort status, während die Publish Topics das Schlüsselwort request enthalten. Die mit status werden automatisch aktualisiert, sobald eine externe Wertänderung vorliegt oder sobald eine Wertänderung vom Client selbst über einen Publish angefordert und erfolgreich übernommen wurde. Die zum Publizieren unterteilen sich noch einmal in die vom Typ (request/)get und die vom Typ (request/)set.
• Wertänderungen und weitere optionale Parameter werden mit dem sogenannten Payload dem Topic hinzugefügt. Die Parameter der einzelnen Elemente (Element-ID, Name, Typ, Funktionen)

Der Hauptunterschied zwischen MQTT und dem klassischen Client-Server-Modell, bei dem der Client Daten anfordert und dann ändert, besteht in den Konzepten „Subscribe“ und „Publish“. Teilnehmer können Daten veröffentlichen und sie so anderen zur Verfügung stellen, die sie bei Interesse abonnieren können. Diese Architektur ermöglicht es, den Datenaustausch zu minimieren und dennoch alle Interessenten auf dem Laufenden zu halten. Näheres dazu hier: und es sind spezielle Parameter (uuid, Filter) zu verwenden. Obwohl es mehrere Möglichkeiten gibt, wird die Payload in diesem Handbuch als JSON formatiert dargestellt. JSON verwendet Klammern und Kommas, um Daten beliebiger Struktur darzustellen und minimiert so die Größe der zu übertragenden Datenpakete. Näheres zu den Payloads finden Sie weiter unten im Handbuch.

• Für spezielle Zwecke ist es möglich, nach Funktionstyp zu filtern, um z.B. nur Ein/Aus also 1-Bit-Schalter anzusprechen. Hierzu dient der Filterparameter in der Payload. Die Filterung ist derzeit nur nach Funktionstyp möglich.
• Um einzelne Elemente ansprechen zu können, wird deren Element-ID benötigt. Diese findet man in VISION im Element-Eigenschaften-Menü oder kann auch direkt aus den Daten ausgelesen werden, die vor jedem verfügbaren Element im allgemeinen Subscriber des MQTT-Explorers angezeigt werden (Elemente werden dort alphabetisch nach Element-ID aufgelistet).

Konfiguration für den API-Zugriff

KONFIGURIEREN VON VISION FÜR DEN API-BENUTZERZUGRIFF

Gehen Sie in VISION als Administrator zu Konfiguration – Benutzer-/API-Zugriffsverwaltung, klicken Sie auf Benutzer/API-Zugriff und klicken Sie mit der rechten Maustaste auf API-Benutzer (oder drücken und halten), um das Bearbeitungsfenster zu öffnen. Dort finden Sie diese Parameter und Daten

• Aktivieren (Kontrollkästchen)
  • Hier wird der Benutzer zunächst aktiviert. Standardmäßig ist er deaktiviert
• Benutzername
  • Dieser String wird für den Zugriff über die API benötigt – kopieren Sie ihn von hier
• Passwort
  • Dieser String wird für den Zugriff über die API benötigt – kopieren Sie ihn von hier
• Berechtigungen
  • Hier können die Standardrechte zum Lesen und Schreiben der Werte der VISION-Elemente definiert werden, d.h. was hier definiert wird, gilt für alle bestehenden und zukünftigen Elemente. Wenn Sie nur den Zugriff auf einzelne Elemente erlauben möchten, sollten Sie diese Standardrechte nicht ändern

Berechtigungen für einzelne Elemente

Es empfiehlt sich, den API-Zugriff nicht auf das gesamte Projekt zu gewähren, sondern nur auf die gewünschten Elemente. Gehen Sie dazu wie folgt vor

1. Melden Sie sich als Administrator bei VISION an.
2. Wählen Sie das gewünschte Element aus und öffnen Sie dessen Einstellungsmenü (Rechtsklick oder gedrückt halten, dann Einstellungen)
3. Aktivieren Sie hierzu unter dem Menüpunkt Allgemein – Berechtigungen die Option „Standardberechtigungen überschreiben“ und wechseln Sie anschließend zum Unterpunkt Berechtigungen, welcher die Berechtigungsmatrix anzeigt.
4. Aktivieren Sie hier die Steuerungsberechtigung, die auch die view Berechtigung direkt. Wenn Sie nur Daten über den API-Zugriff lesen möchten, reicht es aus, die view Erlaubnis.
5. Wiederholen Sie den Vorgang für alle Elemente, auf die Sie zugreifen möchten

Anbindung über MQTT

EINFÜHRUNG

Als ExampIm Folgenden demonstrieren wir den Zugriff über die MQTT-API des DIVUS KNX IQ mit einer relativ einfachen, kostenlosen Software namens MQTT Explorer (siehe Kap. 1.1), die für Windows, Mac und Linux verfügbar ist. Grundkenntnisse und Erfahrungen mit MQTT werden vorausgesetzt.

FÜR DIE VERBINDUNG ERFORDERLICHE DATEN

Wie bereits erwähnt (siehe Abschnitt 2.1), werden der Benutzername und das Passwort des API-Benutzers benötigt. Hier ist eineview aller Daten, die vor dem Verbindungsaufbau erhoben werden müssen:

• Benutzername Wird auf der Detailseite des API-Benutzers ausgelesen
• Passwort Auslesbar auf der Detailseite des API-Benutzers
• IP-Adresse auslesen in den Launcher-Einstellungen unter Allgemein – Netzwerk – Ethernet (oder über Synchronizer)
• Port 8884 (dieser Port ist für diesen Zweck reserviert)

ERSTE VERBINDUNG MIT MQTT EXPLORER UND ALLGEMEINES ABONNIEREN

Normalerweise unterscheidet MQTT zwischen den Aktivitäten Subscribe und Publizieren. MQTT Explorer vereinfacht dies, indem beim ersten Verbindungsaufbau automatisch alle verfügbaren Topics (Topic #) abonniert werden. Dadurch ist nach erfolgreicher Verbindung direkt im linken Bereich des MQTT Explorer Fensters der Baum zu sehen, der zu allen verfügbaren Elementen (also gewährten API-Benutzerzugriff) führt. Um weitere Subscribe Topics einzutragen oder die # durch ein spezifischeres Topic zu ersetzen, geht man im Verbindungsfenster auf Erweitert. Das oben rechts angezeigte Topic sieht dann etwa so aus:

wobei 7f4x0607849x444xxx256573x3x9x983 der API-Benutzername ist und objects_list alle verfügbaren Elemente enthält. Dieses Thema wird immer auf dem neuesten Stand gehalten, d. h. alle Wertänderungen werden dort in Echtzeit angezeigt. Wenn Sie nur einzelne Elemente abonnieren möchten, geben Sie nach objects_list/ die Element-ID des gewünschten Elements ein.

Hinweis: Diese Art des Abonnierens entspricht in etwa der Logik hinter den KNX-Rückmeldeadressen, zeigt den aktuellen Status der Elemente an und kann zur Kontrolle verwendet werden, ob die gewünschten Änderungen erfolgreich übernommen wurden. Wenn Sie Daten nur auslesen, aber nicht ändern möchten, reicht diese Art des Abonnierens aus.

Ein einzelnes einfaches Element sieht in JSON-Notation ungefähr so ​​aus

Hinweis: Alle Werte haben die oben gezeigte Syntax, z. B. { „Wert“: „1“ } als Ausgabe der Abonnementthemen, während der Wert direkt in die Nutzlast geschrieben wird, um einen Wert zu ändern (also für Veröffentlichungsthemen) – die Klammern und „Wert“ werden weggelassen, z. B. „an/aus“: „1“.

Erweiterte Befehle

EINFÜHRUNG

Es gibt im Allgemeinen drei Arten von Themen:

1. Abonnieren Sie Themen, um die verfügbaren Elemente anzuzeigen und Wertänderungen in Echtzeit zu erhalten.
2. Abonnieren Sie Themen, um die Antworten auf (die Kunden ) Anfragen veröffentlichen
3. Themen veröffentlichen, um Elemente mit ihren Werten abzurufen oder festzulegen

Wir werden diese Typen später anhand der hier gezeigten Nummerierung bezeichnen (z. B. Themen vom Typ 1, 2, 3). Näheres dazu in den folgenden Abschnitten und im Kapitel 4.2.

ABONNIEREN SIE THEMEN, UM DIE VERFÜGBAREN ELEMENTE ZU SEHEN UND WERTVORÄNDERUNGEN IN ECHTZEIT ZU ERHALTEN

Diese wurden bereits beschrieben

THEMEN ABONNIEREN, UM ANTWORTEN AUF DIE VERÖFFENTLICHUNGSANFRAGEN DES KUNDEN ZU ERHALTEN

Diese Art von Themen ist optional. Sie ermöglicht es,

• Öffnen Sie einen eindeutigen Kommunikationskanal mit dem MQTT-Server unter Verwendung einer beliebigen Client-ID. Mehr dazu in Kapitel 4.2.2
• Holen Sie sich das Ergebnis von Veröffentlichungsanforderungen zum entsprechenden Abonnementthema: Erfolg oder Misserfolg mit Fehlercode und Meldung.

Es gibt verschiedene Themen, um Antworten zu erhalten oder Publish-Befehle zu setzen. Der entsprechende Unterschied in Sobald Sie die für Ihr System erforderlichen Themen ermittelt haben, können Sie diesen Schritt überspringen und direkt die Veröffentlichungsthemen verwenden.

 THEMEN VERÖFFENTLICHEN, UM ELEMENTE MIT IHREN WERTEN ZU ERHALTEN ODER EINZUSTELLEN

Diese Themen verwenden einen Pfad, der denen zum Abonnieren ähnelt – die einzige Änderung ist das Wort „Anforderung“ anstelle des zum Abonnieren verwendeten „Status“. Vollständige Themenpfade werden später in Kapitel 4.2.2 angezeigt. Ein Get-Thema fordert das Lesen der Elemente und Werte des MQTT-Servers an. Die Nutzlast kann zum Filtern basierend auf dem Funktionstyp der Elemente verwendet werden. Ein Set-Thema fordert das Ändern einiger Teile eines Elements an, wie in seiner Nutzlast beschrieben.

PRÄFIX FÜR BEFEHLE UND ENTSPRECHENDE ANTWORTEN

 KURZE ERKLÄRUNG

Alle Befehle, die an den MQTT-Server gesendet werden, haben einen gemeinsamen Anfangsteil, nämlich:

DETAILLIERTE ERKLÄRUNG

Die Echtzeitthemen (Typ 1) haben das allgemeine Präfix (siehe oben), gefolgt von

or

Bei Set-Befehlen spielt die Nutzlast offensichtlich die Hauptrolle, da sie die gewünschten Änderungen enthält (d. h. geänderte Werte für die Funktionen des Elements). Eine Warnung: Verwenden Sie in Ihren Typ-3-Befehlen niemals die Option „Retain“, da dies auf der KNX-Seite zu Problemen führen kann.

EXAMPLE: PUBLISH ZUM ÄNDERN DER WERTE EINES EINZELNEN ELEMENTS

Der einfachste Fall besteht darin, dass Sie den Wert eines der vom allgemeinen Abonnement angezeigten Elemente ändern möchten.
Das Ändern/Schalten einer Funktion von VISION über MQTT umfasst grundsätzlich 3 Schritte, von denen nicht alle zwingend notwendig sind, wir empfehlen aber trotzdem diese wie beschrieben durchzuführen.

1. Das Thema, das die zu bearbeitende Funktion enthält, wird mit einer benutzerdefinierten Client-ID abonniert
2. Das zu bearbeitende Thema wird zusammen mit der Nutzlast mit den gewünschten Änderungen unter Verwendung der in 1. gewählten Client-ID veröffentlicht.
3. Zur Kontrolle kannst du dann die Antwort im Thema (1.) nachlesen – also ob (2.) geklappt hat oder nicht
4. Im allgemeinen Abonnement, in dem alle Werte bei Änderungen aktualisiert werden, können Sie, wenn alles geklappt hat, die gewünschte(n) Wertänderung(en) sehen.

Die Schritte hierzu sind:

1. Wählen Sie eine Client-ID, z. B. „Divus“, und fügen Sie sie in den Pfad nach dem API-Benutzernamen ein
   Dies ist das vollständige Thema zum Abonnieren Ihres eigenen Kommunikationskanals mit dem MQTT-Server. Dadurch wird dem Server mitgeteilt, wo Sie die Antworten auf die Änderungen erwarten, die Sie senden möchten. Beachten Sie den Status-/Set-Teil, der definiert, a. dass es sich um ein Abonnementthema handelt und b. dass es die Antworten auf Befehle vom Typ „Set“ erhält.
2. Das Veröffentlichungsthema bleibt dasselbe, außer dass die Schlüsselwörter für die Statusanfrage geändert werden.
3. Woraus die Änderung bestehen soll, steht in der Payload. Hier sind einige Beispieleamples.
   • Ausschalten eines Elementes mit der Funktion Ein/Aus (1 Bit):
   • Einschalten eines Elements, welches die Funktion An/Aus (1 Bit) besitzt. Werden zudem mehrere solcher Befehle vom selben Client gestartet, lässt sich über den Parameter uuid („unique ID“, ist meist ein 128-bit String im Format 8-4-4-4-12 Ziffern Hex) die Antwort der entsprechenden Abfrage zuordnen, da dieser Parameter – sofern in der Abfrage vorhanden – auch in der Antwort zu finden ist.
   • Einschalten und Helligkeit eines Dimmers auf 50% einstellen
   • Die Antwort auf das oben gezeigte und abonnierte Thema (genauer gesagt dessen Payload) lautet dann beispielsweiseample.
     Die obige Antwort ist ein Beispielample im Falle einer korrekten Payload, obwohl das Element keine Dimmfunktion hat. Liegen schwerwiegendere Probleme vor, die dazu führen, dass die Payload nicht korrekt interpretiert wird, sieht die Antwort beispielsweise so aus:
     für eine Erklärung der Fehlercodes und -nachrichten, aber im Allgemeinen sind, wie bei http, 200 Codes positive Antworten, während 400 negativ sind.

EXAMPLE: PUBLISH ZUM ÄNDERN MEHRERER ELEMENTWERTE

Das Verfahren ähnelt dem zuvor gezeigten zum Ändern eines einzelnen Elements. Der Unterschied besteht darin, dass Sie die Element-ID aus den Themen weglassen und dann den Satz von Element-IDs vor den Daten innerhalb der Nutzlast angeben. Siehe Syntax und Struktur unten.

FILTERN NACH FUNKTIONSTYP IN ABFRAGEN

Der Parameter „filters“ in der Payload ermöglicht es, nur die gewünschte(n) Funktion(en) eines Elements anzusprechen. Die Ein-/Aus-Funktion eines Schalters oder Dimmers wird beispielsweise „onoff“ genannt.ample, und der entsprechende Filter wird folgendermaßen definiert:

Die Antwort sieht dann beispielsweise so aus:ample

Die eckige Klammer zeigt an, dass Sie auch nach mehreren Funktionen filtern können, zB

führt zu einer Antwort wie dieser:

Anhang

FEHLERCODES

Fehler in der MQTT-Kommunikation führen zu einem Zahlencode. Die folgende Tabelle hilft bei der Aufschlüsselung.

Parameter der Nutzlast

Die Payload unterstützt je nach Kontext unterschiedliche Parameter. Die folgende Tabelle zeigt, welche Parameter in welchen Topics vorkommen können

VERSIONSHINWEISE

• 1.00 VERSION

Nachricht:

• Erstveröffentlichung

Dokumente / Ressourcen

	DIVUS VISION API Software [pdf] Benutzerhandbuch VISION API-Software, API-Software, Software
	DIVUS Vision API Software [pdf] Benutzerhandbuch Vision-API-Software, Vision, API-Software, Software

Verweise

• Bedienungsanleitung