Software DIVUS VISION API

Specifikace

• Produkt: DIVUS VISION API
• Výrobce: DIVUS GmbH
• Verze: 1.00 REV0 1 – 20240528
• Místo: Pillhof 51, Eppan (BZ), Itálie

Informace o produktu

DIVUS VISION API je softwarový nástroj navržený pro propojení se systémy DIVUS VISION. Umožňuje uživatelům přistupovat a ovládat různé prvky v systému pomocí protokolů MQTT.

FAQ

Otázka: Mohu používat DIVUS VISION API bez předchozí znalosti PC nebo automatizační technologie?

Odpověď: Příručka je přizpůsobena uživatelům s předchozími znalostmi v těchto oblastech, aby bylo zajištěno efektivní využití API.

OBECNÉ INFORMACE

• DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – Itálie

Návody k obsluze, manuály a software jsou chráněny autorským právem. Všechna práva vyhrazena. Kopírování, rozmnožování, překládání, překládání vcelku nebo po částech není povoleno. Výjimka se vztahuje na vytvoření záložní kopie softwaru pro osobní použití.
Návod se může změnit bez upozornění. Nemůžeme zaručit, že data obsažená v tomto dokumentu a na dodaných paměťových médiích jsou bez chyb a správná. Návrhy na vylepšení, stejně jako tipy na chyby jsou vždy vítány. Dohody se vztahují také na konkrétní přílohy tohoto návodu. Označení v tomto dokumentu mohou být ochrannými známkami, jejichž použití třetími stranami pro jejich vlastní účely může porušovat práva jejich vlastníků. Pokyny pro uživatele: Před prvním použitím si přečtěte tento návod a uschovejte jej na bezpečném místě pro budoucí použití. Cílová skupina: Manuál je napsán pro uživatele s předchozími znalostmi PC a automatizační techniky.

PREZENTAČNÍ KONVENCE

Zavedení

OBECNÝ ÚVOD

Tato příručka popisuje VISION API (Application Programming Interface) – rozhraní, jehož prostřednictvím lze VISION adresovat a ovládat z externích systémů.
V praxi to znamená, že můžete používat systémy jako např

• Průzkumník MQTT (https://www.microsoft.com/store/… – pro testování),
• Domácí asistent (https://www.home-assistant.io/) nebo
• Uzel-ČERVENÝ (https://nodered.org/)

ovládat prvky spravované VISION nebo číst jejich stav. Přístup a komunikace probíhá přes protokol MQTT, který pomocí tzv. témat řeší jednotlivé funkce nebo sady funkcí nebo je informován o jejich změnách. K tomuto účelu slouží MQTT server (broker), který se stará o bezpečnost a správu/distribuci zpráv účastníkům. V tomto případě je server MQTT umístěn přímo na DIVUS KNX IQ a je speciálně nakonfigurován pro tento účel. Přestože VISION API lze používat i bez znalosti programování, je tato funkcionalita vhodná pro pokročilé uživatele.

Předpoklady

Jak je vysvětleno v manuálu VISION, uživatel rozhraní API musí být ve výchozím nastavení nejprve aktivován, aby jej bylo možné používat. Přístup k rozhraní API funguje pouze pomocí autentizačních dat uživatelů rozhraní API. Pokud jde o uživatelská práva, aktivaci této funkcionality lze pak nakonfigurovat buď na všech, nebo na jednotlivých prvcích. Viz kap.0. Samozřejmě potřebujete také projekt VISION, ve kterém jsou prvky, které chcete ovládat zvenčí, plně nakonfigurovány a propojení s nimi bylo úspěšně otestováno. Aby bylo možné oslovit jednotlivé prvky přes API, musí znát jejich ID prvku: zobrazí se ve spodní části formuláře nastavení prvku

ZABEZPEČENÍ

Z bezpečnostních důvodů je přístup k API možný pouze lokálně (tj. ne přes cloud). Bezpečnostní riziko při aktivaci API přístupu je tedy nízké. Nicméně prvky relevantní pro zabezpečení by neměly být povoleny nebo explicitně odepřeny pro přístup k API.

MQTT A JEHO PODMÍNKY – STRUČNÉ VYSVĚTLENÍ

• V MQTT je úlohou centralizované správy a distribuce všech zpráv zprostředkovatel. Přestože server MQTT a broker MQTT nejsou synonyma (server je širší termín pro roli, kterou mohou hrát i klienti MQTT), je v této příručce vždy myšlen broker, když je zmíněn server MQTT. Samotný DIVUS KNX IQ hraje roli zprostředkovatele MQTT / serveru MQTT v kontextu této příručky.
• Server MQTT používá takzvaná témata: hierarchickou strukturu, pomocí které jsou data kategorizována, spravována a publikována.
• Publikování má primární cíl zpřístupnit data dalším účastníkům prostřednictvím témat. Pokud chcete změnit hodnotu, napíšete do požadovaného tématu spolu s požadovanou změnou hodnoty také pomocí akce publikování. Cílové zařízení nebo server MQTT přečte požadovanou změnu, která jej ovlivňuje, a podle toho ji převezme. Chcete-li zkontrolovat, zda byla změna aplikována, můžete se podívat do přihlášeného tématu v reálném čase, abyste zjistili, zda se tam změna projevila – pokud vše proběhlo v pořádku.
• Klienti si vybírají témata, která je zajímají: tomu se říká předplatné. Při každé změně hodnoty v/pod tématem jsou informováni všichni přihlášení klienti – tj. aniž by se museli explicitně ptát, zda se něco změnilo nebo jaká je aktuální hodnota.
• Můžete otevřít (nebo oslovit) samostatný komunikační kanál se serverem MQTT zadáním libovolného jedinečného řetězce s názvem client_id do tématu. Ke zpracování hodnot musí být v tématu použit client_id. To slouží k identifikaci původu každé změny, pomáhá s případnými chybami a neovlivňuje ostatní klienty, protože odpovídající odpovědi ze serveru, včetně případných chybových kódů a zpráv, se také dostanou k tématu pouze se stejným client_id (a tedy pouze ten klient). Client_id je jedinečný znakový řetězec skládající se z libovolné kombinace znaků 0-9, az, AZ, „-“, „_“.
• Obecně platí, že témata odběru serveru MQTT DIVUS KNX IQ obsahují stav klíčového slova, zatímco témata publikování obsahují požadavek na klíčové slovo. Ty se statusem jsou automaticky aktualizovány, jakmile dojde k externí změně hodnoty nebo jakmile si změnu hodnoty vyžádal samotný klient prostřednictvím publikování a byla úspěšně aplikována. Ty pro publikování se dále dělí na ty typu (request/)get a ty typu (request/)set.
• Změny hodnot a další volitelné parametry se přidávají k tématu s tzv. payload. Parametry jednotlivých prvků (id-prvku, název, typ, funkce)

Hlavní rozdíl mezi MQTT a klasickým modelem klient-server, kde klient požaduje a následně mění data, se soustředí na koncepty přihlášení k odběru a publikování. Účastníci mohou data zveřejňovat a zpřístupňovat je ostatním, kteří se v případě zájmu mohou přihlásit k jejich odběru. Tato architektura umožňuje minimalizovat výměnu dat a přitom udržovat všechny zainteresované strany aktuální. Více o detailech zde: a speciální parametry (uuid, filtry) mají být použity zde. Přestože existuje několik možností, datová část je v této příručce zobrazena ve formátu JSON. JSON používá závorky a čárky k reprezentaci dat libovolné struktury a tím minimalizuje velikost datových paketů, které mají být přenášeny. Další podrobnosti o užitečné zátěži naleznete dále v příručce.

• Pro speciální účely je možné filtrovat podle typu funkce, např. adresovat pouze on/off tj. 1bitové přepínače. K tomuto účelu slouží parametr filters v užitečné zátěži. Filtrování je aktuálně možné pouze podle typu funkce.
• Aby bylo možné adresovat jednotlivé prvky, je vyžadováno jejich ID prvku. To lze nalézt ve VISION v nabídce vlastností prvku nebo jej lze také číst přímo z dat, která jsou zobrazena před každým dostupným prvkem v obecném odběru MQTT Exploreru (prvky jsou zde seřazeny abecedně podle ID prvku).

Konfigurace pro přístup k API

KONFIGURACE VIZE PRO PŘÍSTUP UŽIVATELE API

Ve VISION jako správce přejděte do Konfigurace – Správa přístupu uživatelů/API, klikněte na Uživatelé/Přístup k API a klikněte pravým tlačítkem na Uživatel API (nebo stiskněte a podržte), čímž otevřete editační okno. Zde najdete tyto parametry a údaje

• Povolit (zaškrtávací políčko)
  • Zde je uživatel nejprve povolen. Výchozí nastavení je zakázáno
• Uživatelské jméno
  • Tento řetězec je vyžadován pro přístup přes API – zkopírujte jej odtud
• Heslo
  • Tento řetězec je vyžadován pro přístup přes API – zkopírujte jej odtud
• Oprávnění
  • Zde lze definovat výchozí práva pro čtení a zápis hodnot prvků VISION, tj. to, co je zde definováno, platí pro všechny existující i budoucí prvky. Pokud chcete povolit přístup pouze k jednotlivým prvkům, neměli byste tato výchozí práva měnit

OPRÁVNĚNÍ K JEDNOTLIVÝM PRVKŮM

Doporučuje se neudělovat API přístup k celému projektu, ale pouze k požadovaným prvkům. Postupujte následovně

1. přihlaste se do VISION jako správce
2. vyberte požadovaný prvek a otevřete jeho nabídku nastavení (klikněte pravým tlačítkem nebo podržte stisknuté a poté Nastavení)
3. pod položkou nabídky Obecné – Oprávnění aktivujte „Přepsat výchozí oprávnění“ a poté přejděte na podpoložku Oprávnění, která zobrazuje matici oprávnění.
4. zde aktivujte oprávnění k ovládání, které také umožňuje view povolení přímo. Pokud chcete data pouze číst přes API přístup, stačí povolit view povolení.
5. opakujte stejný postup pro všechny prvky, ke kterým chcete získat přístup

Připojení přes MQTT

ZAVEDENÍ

Jako example, předvedeme přístup přes MQTT API DIVUS KNX IQ pomocí relativně jednoduchého, bezplatného softwaru nazvaného MQTT Explorer (viz kap. 1.1), který je dostupný pro Windows, Mac a Linux. Předpokládá se základní znalost a zkušenost s MQTT.

DATA VYŽADOVANÁ PRO PŘIPOJENÍ

Jak již bylo zmíněno dříve (viz část 2.1), je vyžadováno uživatelské jméno a heslo uživatele API. Tady je konecview všech údajů, které je třeba shromáždit před navázáním připojení:

• Uživatelské jméno Přečtěte si na stránce podrobností o uživateli API
• Heslo Přečtěte si na stránce podrobností o uživateli API
• IP adresa Přečtěte si v nastavení spouštěče v části Obecné – Síť – Ethernet (nebo přes Synchronizer)
• Port 8884 (tento port je vyhrazen pro tento účel)

PRVNÍ SPOJENÍ S PRŮZKUMNÍKEM MQTT A OBECNÉ PŘEDPLATNÉ

MQTT běžně rozlišuje mezi aktivitami přihlášení a publikování. MQTT Explorer to zjednodušuje automatickým přihlášením k odběru všech dostupných témat (téma #) při prvním připojení. Výsledkem je, že strom, který vede ke všem dostupným prvkům (tj. udělený uživatelský přístup k API), je po úspěšném připojení vidět přímo v levé části okna MQTT Explorer. Chcete-li zadat další témata k odběru nebo nahradit znak # konkrétnějším tématem, přejděte v okně připojení na Pokročilé. Téma zobrazené vpravo nahoře vypadá asi takto:

kde 7f4x0607849x444xxx256573x3x9x983 je uživatelské jméno API a seznam objektů obsahuje všechny dostupné prvky. Toto téma je vždy aktuální, tj. jakékoli změny hodnot se zde projeví v reálném čase. Pokud se chcete přihlásit pouze k odběru jednotlivých prvků, zadejte za seznam_objektů/ ID prvku požadovaného prvku.

Poznámka: Tento typ odběru zhruba odpovídá logice adres zpětné vazby KNX; zobrazuje aktuální stav prvků a lze jej použít ke kontrole, zda byly požadované změny úspěšně aplikovány. Pokud chcete data pouze číst, ale neměnit, stačí tento typ předplatného.

Jediný jednoduchý prvek vypadá v zápisu JSON asi takto

Poznámka: Všechny hodnoty mají syntaxi uvedenou výše, např. { “value”: “1” } jako výstup témat k odběru, zatímco hodnota se zapisuje přímo do užitečného zatížení pro změnu hodnoty (tj. pro publikování témat) – závorky a „hodnota“ jsou vynechány, např. „onoff“: „1“.

Pokročilé příkazy

ZAVEDENÍ

Obecně existují 3 druhy témat:

1. Přihlaste se k odběru témat, abyste viděli dostupné prvky a získali změny hodnot v reálném čase
2. Přihlaste se k odběru témat a získejte odpovědi na (klientů ) zveřejňovat žádosti
3. Publikováním témat získáte nebo nastavíte prvky s jejich hodnotami

Později budeme na tyto druhy odkazovat pomocí zde uvedeného číslování (např. témata typu 1, 2, 3). Více podrobností v následujících částech a v kap. 4.2.

PŘIHLÁSTE SE K ODBĚRU TÉMAT, ABY SI ZOBRAZILI DOSTUPNÉ PRVKY A ZÍSKALI ZMĚNY HODNOTY V REÁLNÉM ČASE

Ty již byly popsány

PŘIHLAŠTE TÉMATA A ZÍSKEJTE ODPOVĚDI NA PUBLIKOVANÉ POŽADAVKY KLIENTA

Tento druh témat je volitelný. Umožňuje to

• otevřít jedinečný komunikační kanál se serverem MQTT pomocí libovolného client_id. Více o tom v kap. 4.2.2
• získat výsledek požadavků na zveřejnění na odpovídající téma odběru: úspěch nebo neúspěch s kódem chyby a zprávou.

Existují různá témata pro získání odpovědí pro získání nebo nastavení příkazů publikování. Odpovídající rozdíl v Jakmile získáte potřebná témata pro váš systém, můžete se rozhodnout tento krok odstranit a přímo použít publikování témat.

 ZVEŘEJNĚTE TÉMATA, ABYSTE ZÍSKALI NEBO NASTAVILI PRVKY S JEJICH HODNOTAMI

Tato témata používají podobnou cestu jako pro přihlášení k odběru – jedinou změnou je slovo „požadavek“ namísto „stavu“ použitého k přihlášení k odběru. Kompletní cesty k tématu jsou uvedeny dále v kap. 4.2.2\ Téma get bude vyžadovat čtení prvků a hodnot serveru MQTT. Užitnou zátěž lze použít k filtrování na základě typu funkce prvků. Nastavené téma bude vyžadovat změnu některých částí prvku, jak je podrobně popsáno v jeho užitečné zátěži.

PŘEDPONA PRO PŘÍKAZY A ODPOVÍDAJÍCÍ ODPOVĚDI

 KRÁTKÉ VYSVĚTLENÍ

Všechny příkazy odesílané na server MQTT mají společnou počáteční část, a to:

PODROBNÉ VYSVĚTLENÍ

Témata v reálném čase (typ 1) budou mít obecnou předponu (viz výše), po níž bude následovat

or

U set příkazů hraje samozřejmě hlavní roli payload, který bude obsahovat požadované změny (tj. změněné hodnoty funkcí prvku). Varování: Nikdy nepoužívejte možnost zachování v příkazech typu 3, protože to může způsobit problémy na straně KNX.

EXAMPLE: PUBLIKOVAT PRO ZMĚNU HODNOTY JEDNOHO PRVKU

Nejjednodušším případem je chtít změnit hodnotu jednoho z prvků zobrazených obecným předplatitelem.
Obecně řečeno, změna/přepnutí funkce VISION přes MQTT sestává ze 3 kroků, z nichž ne všechny jsou absolutně nutné, ale přesto je doporučujeme provést tak, jak je popsáno.

1. Téma, které obsahuje funkci, kterou chceme upravit, je přihlášeno pomocí vlastního client_id
2. Téma pro úpravu je publikováno spolu s užitečným zatížením s požadovanými změnami pomocí client_id zvoleného v 1.
3. Pro kontrolu pak můžete vidět odpověď v tématu (1.) – tedy zda (2.) fungovalo nebo ne
4. V obecném odběru, kde jsou všechny hodnoty aktualizovány, když jsou provedeny změny, můžete vidět požadované změny hodnot, pokud vše fungovalo dobře.

Postupujte takto:

1. vyberte client_id, např. „Divus“ a vložte jej do cesty za uživatelské jméno API
   Toto je kompletní téma pro přihlášení k odběru vašeho vlastního komunikačního kanálu se serverem MQTT. Tím sdělíte serveru, kde očekáváte odpovědi na změny, které hodláte odeslat. Všimněte si části stavu/nastavení, která definuje a. že jde o téma k odběru a b. že dostane odpovědi na příkazy typu set.
2. Téma publikování bude stejné, s výjimkou přepnutí klíčových slov požadavku stavu
3. v čem má změna spočívat je napsáno v užitečné zátěži. Zde jsou některé examples.
   • Vypnutí prvku, který má funkci on/off (1 bit):
   • Zapnutí prvku, který má funkci on/off (1 bit). Kromě toho, pokud je od stejného klienta spuštěno několik takových příkazů, lze k přiřazení parametru uuid ("unique ID", obvykle 128bitový řetězec formátovaný jako 8-4-4-4-12 číslic) použít odpověď na odpovídající dotaz, protože tento parametr – pokud je v dotazu přítomen – lze nalézt také v odpovědi.
   • Zapnutí a nastavení jasu stmívače na 50%
   • Odpověď na výše uvedené a přihlášené téma (jeho užitečné zatížení, abych byl přesný) je pak napřample.
     Výše uvedená odpověď je example v případě správného užitečného zatížení, ačkoli prvek nemá žádnou funkci stmívání. Pokud se vyskytnou vážnější problémy, které vedou k tomu, že užitečné zatížení není správně interpretováno, bude odpověď vypadat takto (např.):
     pro vysvětlení chybových kódů a zpráv, ale obecně, jako u http, 200 kódů jsou kladné odpovědi, zatímco 400 jsou záporné.

EXAMPLE: PUBLIKOVAT PRO ZMĚNU HODNOT VÍCE PRVKŮ

Postup je podobný tomu, který byl ukázán dříve pro změnu jednoho prvku. Rozdíl je v tom, že vynecháte element_id z témat a pak uvedete sadu element_ids před daty uvnitř užitečného zatížení. Viz syntaxe a struktura níže.

FILTROVAT PODLE TYPU FUNKCE V DOTAZY

Parametr filtrů v užitečné zátěži umožňuje adresovat pouze požadovanou funkci (funkce) prvku. Funkce zapnutí/vypnutí spínače nebo stmívače se nazývá „onoff“, napřample a odpovídající filtr je definován takto:

Odpověď pak vypadá takto, napřample

Hranaté závorky značí, že můžete také filtrovat podle několika funkcí, např

vede k takové odpovědi:

Dodatek

CHYBOVÉ KÓDY

Chyby v komunikaci MQTT mají za následek číselný kód. Následující tabulka vám to pomůže rozebrat.

PARAMETRY UŽITEČNÉ ZÁTĚŽE

Užitná zátěž podporuje různé parametry v závislosti na kontextu. Následující tabulka ukazuje, které parametry se mohou vyskytnout v jakých tématech

POZNÁMKY K VERZI

• 1.00 VERZE

Zprávy:

• První publikace

Dokumenty / zdroje

	Software DIVUS VISION API [pdfUživatelská příručka VISION API Software, API Software, Software
	Software DIVUS Vision API [pdfUživatelská příručka Vision API Software, Vision, API Software, Software

Reference

• Uživatelská příručka