Používateľská príručka softvéru DIVUS VISION API

Softvér DIVUS VISION API

Špecifikácie

• Produkt: DIVUS VISION API
• Výrobca: DIVUS GmbH
• Verzia: 1.00 REV0 1 – 20240528
• Miesto: Pillhof 51, Eppan (BZ), Taliansko

Informácie o produkte

DIVUS VISION API je softvérový nástroj určený na prepojenie so systémami DIVUS VISION. Umožňuje používateľom pristupovať a ovládať rôzne prvky v rámci systému pomocou protokolov MQTT.

FAQ

Otázka: Môžem používať DIVUS VISION API bez predchádzajúcej znalosti PC alebo automatizačnej technológie?

Odpoveď: Príručka je prispôsobená používateľom s predchádzajúcimi znalosťami v týchto oblastiach, aby sa zabezpečilo efektívne používanie API.

VŠEOBECNÉ INFORMÁCIE

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

Návody na obsluhu, manuály a softvér sú chránené autorským právom. Všetky práva vyhradené. Nie je dovolené kopírovať, duplikovať, prekladať, prekladať vcelku alebo čiastočne. Výnimka sa vzťahuje na vytvorenie záložnej kópie softvéru pre osobné použitie.
Návod sa môže zmeniť bez upozornenia. Nemôžeme zaručiť, že údaje obsiahnuté v tomto dokumente a na dodanom pamäťovom médiu sú bezchybné a správne. Návrhy na vylepšenia, ako aj tipy na chyby sú vždy vítané. Dohody sa vzťahujú aj na špecifické prílohy tohto návodu. Označenia v tomto dokumente môžu byť ochrannými známkami, ktorých použitie tretími stranami na ich vlastné účely môže porušiť práva ich vlastníkov. Pokyny pre používateľa: Pred prvým použitím si prečítajte tento návod a uschovajte ho na bezpečnom mieste pre budúce použitie. Cieľová skupina: Manuál je napísaný pre používateľov s predchádzajúcimi znalosťami PC a automatizačnej techniky.

PREZENTAČNÉ KONVENCIE

Úvod

VŠEOBECNÝ ÚVOD

Táto príručka popisuje VISION API (Application Programming Interface) – rozhranie, cez ktoré možno VISION adresovať a ovládať z externých systémov.
V praxi to znamená, že môžete využívať systémy ako napr

• MQTT Explorer (https://www.microsoft.com/store/… – na testovanie),
• Domáci asistent (https://www.home-assistant.io/) alebo
• Node-RED (https://nodered.org/)

na ovládanie prvkov spravovaných VISION alebo čítanie ich stavu. Prístup a komunikácia prebieha cez protokol MQTT, ktorý pomocou takzvaných tém rieši jednotlivé funkcie alebo súbory funkcií alebo je informovaný o ich zmenách. Na tento účel sa používa MQTT server (broker), ktorý sa stará o bezpečnosť a správu/distribúciu správ účastníkom. V tomto prípade je server MQTT umiestnený priamo na DIVUS KNX IQ a je špeciálne nakonfigurovaný na tento účel. Hoci VISION API je možné použiť aj bez znalosti programovania, táto funkcionalita je vhodná pre pokročilých používateľov.

PREDPOKLADY

Ako je vysvetlené v príručke VISION, používateľ API musí byť štandardne najprv aktivovaný, aby ho mohol používať, prístup k API funguje iba s použitím autentifikačných údajov používateľov API. Čo sa týka užívateľských práv, aktiváciu tejto funkcionality je možné následne nakonfigurovať buď na všetkých, alebo na jednotlivých prvkoch. Pozri kap.0. Samozrejme potrebujete aj projekt VISION, v ktorom sú prvky, ktoré chcete ovládať zvonku, plne nakonfigurované a prepojenie s nimi bolo úspešne otestované. Aby bolo možné adresovať jednotlivé prvky cez API, musí byť známe ich ID prvku: zobrazuje sa v spodnej časti formulára nastavení prvku

BEZPEČNOSŤ

Z bezpečnostných dôvodov je prístup k API možný len lokálne (teda nie cez cloud). Bezpečnostné riziko pri aktivácii API prístupu je teda nízke. Napriek tomu by prvky súvisiace s bezpečnosťou nemali byť povolené alebo explicitne odmietnuté pre prístup k API.

MQTT A JEHO PODMIENKY – STRUČNÉ VYSVETLENIE

• V MQTT je úlohou centralizovaného riadenia a distribúcie všetkých správ maklér. Aj keď server MQTT a maklér MQTT nie sú synonymá (server je širší pojem pre úlohu, ktorú môžu zohrávať aj klienti MQTT), v tejto príručke je vždy mienený maklér, keď sa spomína server MQTT. Samotný DIVUS KNX IQ hrá úlohu sprostredkovateľa MQTT / servera MQTT v kontexte tohto návodu.
• Server MQTT používa takzvané témy: hierarchickú štruktúru, pomocou ktorej sú údaje kategorizované, spravované a publikované.
• Publikovanie má primárny cieľ sprístupniť údaje ostatným účastníkom prostredníctvom tém. Ak chcete zmeniť hodnotu, napíšete do požadovanej témy spolu s požadovanou zmenou hodnoty aj pomocou akcie publikovania. Cieľové zariadenie alebo server MQTT prečíta požadovanú zmenu, ktorá ho ovplyvňuje, a podľa toho ju prijme. Ak chcete skontrolovať, či sa zmena uplatnila, môžete sa pozrieť do predplatenej témy v reálnom čase a zistiť, či sa tam zmena prejavila – či všetko fungovalo dobre.
• Klienti si vyberajú témy, ktoré ich zaujímajú: toto sa nazýva predplatné. Pri každej zmene hodnoty v/pod téme sú informovaní všetci prihlásení klienti – teda bez toho, aby sa museli explicitne pýtať, či sa niečo zmenilo alebo aká je aktuálna hodnota.
• Môžete otvoriť (alebo adresovať) samostatný komunikačný kanál so serverom MQTT zadaním akéhokoľvek jedinečného reťazca s názvom client_id do témy. Klient_id sa musí použiť v téme na spracovanie hodnôt. Slúži na identifikáciu pôvodu každej zmeny, pomáha pri prípadných chybách a neovplyvňuje ostatných klientov, pretože zodpovedajúce odpovede zo servera, vrátane prípadných chybových kódov a správ, sa tiež dostanú k téme s rovnakým client_id (a teda iba ten klient). Client_id je jedinečný znakový reťazec pozostávajúci z ľubovoľnej kombinácie znakov 0-9, az, AZ, „-“, „_“.
• Vo všeobecnosti témy odberu servera MQTT DIVUS KNX IQ obsahujú stav kľúčového slova, zatiaľ čo témy publikovania obsahujú požiadavku na kľúčové slovo. Tie so stavom sa automaticky aktualizujú, akonáhle dôjde k externej zmene hodnoty alebo keď si zmenu hodnoty vyžiadal samotný klient prostredníctvom zverejnenia a bola úspešne aplikovaná. Tie na publikovanie sa ďalej delia na tie typu (request/)get a tie typu (request/)set.
• Zmeny hodnôt a ďalšie voliteľné parametre sa pridávajú do témy s takzvaným payloadom. Parametre jednotlivých prvkov (identifikátor prvku, názov, typ, funkcie)

Hlavný rozdiel medzi MQTT a klasickým modelom klient-server, kde klient požaduje a následne mení údaje, sa sústreďuje na koncepty predplatenia a zverejnenia. Účastníci môžu zverejňovať údaje a sprístupňovať ich ostatným, ktorí si ich v prípade záujmu môžu predplatiť. Táto architektúra umožňuje minimalizovať výmenu údajov a zároveň udržiavať všetky zainteresované strany aktuálne. Viac o detailoch tu: a špeciálne parametre (uuid, filtre) sa majú použiť tu. Hoci existuje niekoľko možností, užitočné zaťaženie je v tejto príručke zobrazené vo formáte JSON. JSON používa zátvorky a čiarky na reprezentáciu údajov akejkoľvek štruktúry a tým minimalizuje veľkosť dátových paketov, ktoré sa majú prenášať. Viac podrobností o užitočnom zaťažení nájdete neskôr v príručke.

• Pre špeciálne účely je možné filtrovať podľa typu funkcie, napr. adresovať iba on/off tj 1-bitové prepínače. Na tento účel sa používa parameter filters v užitočnom zaťažení. Filtrovanie je momentálne možné len podľa typu funkcie.
• Aby bolo možné adresovať jednotlivé prvky, je potrebné ich ID prvku. To možno nájsť vo VISION v ponuke vlastností prvku alebo sa dá prečítať aj priamo z údajov, ktoré sú zobrazené pred každým dostupným prvkom vo všeobecnom odbere MQTT Explorer (prvky sú tam zoradené abecedne podľa ID prvku).

Konfigurácia pre prístup k API

KONFIGURÁCIA VÍZIE PRE PRÍSTUP POUŽÍVATEĽOV API

Vo VISION ako správca prejdite na Konfigurácia – Správa prístupu používateľov/API, kliknite na Používateľov/Prístup k API a kliknite pravým tlačidlom myši na Používateľ API (alebo stlačte a podržte), čím otvoríte okno úprav. Tam nájdete tieto parametre a údaje

• Povoliť (začiarkavacie políčko)
  • Tu je používateľ najprv povolený. Predvolená možnosť je vypnutá
• Používateľské meno
  • Tento reťazec je potrebný na prístup cez API – skopírujte ho odtiaľto
• heslo
  • Tento reťazec je potrebný na prístup cez API – skopírujte ho odtiaľto
• Povolenia
  • Tu je možné definovať predvolené práva na čítanie a zápis hodnôt prvkov VISION, tj to, čo je tu definované, platí pre všetky existujúce a budúce prvky. Ak chcete povoliť prístup iba k jednotlivým prvkom, tieto predvolené práva by ste nemali meniť

POVOLENIA NA JEDNOTLIVÉ PRVKY

Odporúča sa neudeľovať API prístup celému projektu, ale iba požadovaným prvkom. Postupujte nasledovne

1. prihláste sa do VISION ako administrátor
2. vyberte požadovaný prvok a otvorte jeho ponuku nastavení (kliknite pravým tlačidlom myši alebo podržte stlačené, potom Nastavenia)
3. pod položkou menu Všeobecné – Povolenia aktivujte „Prepísať predvolené povolenia“ a potom prejdite na podpoložku Povolenia, ktorá zobrazuje maticu povolení.
4. tu aktivujte oprávnenie na ovládanie, ktoré tiež umožňuje view povolenie priamo. Ak chcete dáta len čítať cez API prístup, stačí povoliť view povolenie.
5. zopakujte rovnaký postup pre všetky prvky, ku ktorým chcete získať prístup

Pripojenie cez MQTT

ÚVOD

Ako example, budeme demonštrovať prístup cez MQTT API DIVUS KNX IQ pomocou relatívne jednoduchého bezplatného softvéru s názvom MQTT Explorer (pozri kap. 1.1), ktorý je dostupný pre Windows, Mac a Linux. Predpokladá sa základná znalosť a skúsenosť s MQTT.

ÚDAJE POŽADOVANÉ PRE PRIPOJENIE

Ako už bolo spomenuté (pozri časť 2.1), vyžaduje sa používateľské meno a heslo používateľa API. Tu je koniecview všetkých údajov, ktoré sa musia zhromaždiť pred vytvorením pripojenia:

• Používateľské meno Prečítajte si na stránke s podrobnosťami o používateľovi rozhrania API
• Heslo Prečítajte si na stránke s podrobnosťami o používateľovi API
• IP adresa Prečítajte si v nastaveniach spúšťača v časti Všeobecné – Sieť – Ethernet (alebo cez Synchronizer)
• Port 8884 (tento port je vyhradený na tento účel)

PRVÉ PRIPOJENIE S PRIESKUMNÍKOM MQTT A VŠEOBECNÉ PRIHLÁSENIE

Za normálnych okolností MQTT rozlišuje medzi aktivitami prihlásením na odber a publikovaním. MQTT Explorer to zjednodušuje automatickým prihlásením na odber všetkých dostupných tém (téma #) pri prvom pripojení. Výsledkom je, že strom, ktorý vedie ku všetkým dostupným prvkom (tj udelený užívateľský prístup k API), je možné po úspešnom pripojení vidieť priamo v ľavej časti okna MQTT Explorer. Ak chcete zadať ďalšie témy na odber alebo nahradiť znak # špecifickejšou témou, prejdite na položku Rozšírené v okne pripojenia. Téma zobrazená vpravo hore vyzerá asi takto:

kde 7f4x0607849x444xxx256573x3x9x983 je používateľské meno API a zoznam objektov obsahuje všetky dostupné prvky. Táto téma je vždy aktuálna, tj akékoľvek zmeny hodnôt sa tam prejavia v reálnom čase. Ak si chcete predplatiť iba jednotlivé prvky, zadajte ID prvku požadovaného prvku za zoznam_objektov/.

Poznámka: Tento typ odberu zhruba zodpovedá logike za adresami spätnej väzby KNX; zobrazuje aktuálny stav prvkov a možno ho použiť na kontrolu, či boli požadované zmeny úspešne aplikované. Ak chcete údaje iba čítať, ale nechcete ich meniť, stačí tento typ predplatného.

Jeden jednoduchý prvok vyzerá v zápise JSON asi takto

Poznámka: Všetky hodnoty majú syntax uvedenú vyššie, napr. { “value”: “1” } ako výstup tém odberu, pričom hodnota sa zapisuje priamo do užitočného obsahu, aby sa zmenila hodnota (tj pre publikované témy) – zátvorky a „hodnota“ sa vynecháva, napr. „zapnuté“: „1“.

Pokročilé príkazy

ÚVOD

Vo všeobecnosti existujú 3 druhy tém:

1. Prihláste sa na odber tém, aby ste videli dostupné prvky a získali zmeny hodnôt v reálnom čase
2. Prihláste sa na odber tém a získajte odpovede na (klientov ) zverejniť žiadosti
3. Publikovanie tém (tém) na získanie alebo nastavenie prvkov s ich hodnotami

Na tieto druhy sa budeme neskôr odvolávať pomocou tu uvedeného číslovania (napr. témy typu 1, 2, 3). Podrobnejšie v nasledujúcich častiach a v kap. 4.2.

PRIHLÁSTE SA NA ODBER TÉM, ABY STE SI ZOBRALILI DOSTUPNÉ PRVKY A ZÍSKALI ZMENY HODNOTY V REÁLNOM ČASE

Tie už boli popísané

PRIHLÁSTE SA NA ODBER TÉM A ZÍSKAJTE ODPOVEDE NA ZVEREJNENÉ POŽIADAVKY KLIENTA

Tento druh tém je voliteľný. Umožňuje to

• otvorte jedinečný komunikačný kanál so serverom MQTT pomocou ľubovoľného client_id. Viac o tom v kap. 4.2.2
• získať výsledok požiadaviek na zverejnenie na príslušnú tému odberu: úspech alebo zlyhanie s kódom chyby a správou.

Existujú rôzne témy na získanie odpovedí na získanie alebo nastavenie príkazov zverejnenia. Zodpovedajúci rozdiel v Keď získate potrebné témy pre váš systém, môžete sa rozhodnúť tento krok odstrániť a priamo použiť publikovanie tém.

 ZVEREJŇUJTE TÉMY NA ZÍSKANIE ALEBO NASTAVENIE PRVKOV S ICH HODNOTAMI

Tieto témy používajú podobnú cestu ako pri prihlásení na odber – jedinou zmenou je slovo „žiadosť“ namiesto „stavu“, ktorý sa používa pri prihlásení na odber. Kompletné cesty k téme sú uvedené ďalej v kap. 4.2.2\ Téma get si vyžiada čítanie prvkov a hodnôt servera MQTT. Užitočné zaťaženie možno použiť na filtrovanie na základe typu funkcie prvkov. Nastavená téma bude vyžadovať zmenu niektorých častí prvku, ako je uvedené v jeho užitočnom zaťažení.

PREDPONA PRE PRÍKAZY A Zodpovedajúce odpovede

 STRUČNÉ VYSVETLENIE

Všetky príkazy odosielané na server MQTT majú spoločnú úvodnú časť, a to:

PODROBNÉ VYSVETLENIE

Témy v reálnom čase (typ 1) budú mať všeobecnú predponu (pozri vyššie), po ktorej bude nasledovať

or

Pri príkazoch množiny hrá samozrejme hlavnú úlohu užitočné zaťaženie, ktoré bude obsahovať požadované zmeny (tj zmenené hodnoty funkcií prvku). Upozornenie: Nikdy nepoužívajte možnosť ponechať v príkazoch typu 3, pretože to môže spôsobiť problémy na strane KNX.

EXAMPLE: ZVEREJNIŤ PRE ZMENU HODNOTY JEDNOHO PRVKU

Najjednoduchším prípadom je chcieť zmeniť hodnotu jedného z prvkov zobrazených všeobecným predplatiteľom.
Všeobecne povedané, zmena/prepnutie funkcie VISION cez MQTT pozostáva z 3 krokov, z ktorých nie všetky sú absolútne nevyhnutné, ale napriek tomu ich odporúčame vykonať podľa popisu.

1. Téma, ktorá obsahuje funkciu, ktorú chceme upraviť, je prihlásená na odber pomocou vlastného client_id
2. Téma na úpravu je zverejnená spolu s nákladom s požadovanými zmenami pomocou client_id zvoleného v 1.
3. Pre kontrolu si potom môžete pozrieť odpoveď v téme (1.) – teda či (2.) fungovalo alebo nie
4. Vo všeobecnom odbere, kde sa všetky hodnoty aktualizujú po vykonaní zmien, môžete vidieť požadované zmeny hodnoty, ak všetko fungovalo dobre.

Kroky, ako to urobiť, sú:

1. vyberte client_id, napr. “Divus” a vložte ho do cesty za užívateľským menom API
   Toto je úplná téma na predplatenie vášho vlastného komunikačného kanála so serverom MQTT. To povie serveru, kde očakávate odpovede na zmeny, ktoré chcete odoslať. Všimnite si časť stavu/nastavenia, ktorá definuje a. že ide o tému odberu a b. že dostane odpovede na príkazy nastaveného typu.
2. Téma zverejnenia bude rovnaká, s výnimkou prepínania kľúčových slov požiadavky na stav
3. v čom má zmena spočívať je napísané v užitočnom zaťažení. Tu sú niektoré examples.
   • Vypnutie prvku, ktorý má funkciu zapnutia/vypnutia (1 bit):
   • Zapnutie prvku, ktorý má funkciu zapnutia/vypnutia (1 bit). Okrem toho, ak je niekoľko takýchto príkazov spustených z toho istého klienta, parameter uuid (“unique ID”, je zvyčajne 128-bitový reťazec naformátovaný ako 8-4-4-4-12 číslic hex) možno použiť na priradenie odpoveď na zodpovedajúcu otázku, pretože tento parameter – ak sa v dotaze nachádza – možno nájsť aj v odpovedi.
   • Zapnutie a nastavenie jasu stmievača na 50%
   • Odpoveď na tému zobrazenú a odoberanú vyššie (jej užitočné zaťaženie, aby som bol presný) je potom naprample.
     Vyššie uvedená odpoveď je example v prípade správneho užitočného zaťaženia, hoci prvok nemá funkciu stmievania. Ak sa vyskytnú vážnejšie problémy, ktoré vedú k tomu, že užitočné zaťaženie nie je správne interpretované, odpoveď bude vyzerať takto (napr.):
     pre vysvetlenie chybových kódov a správ, ale vo všeobecnosti, podobne ako v prípade http, 200 kódov predstavuje kladné odpovede, zatiaľ čo 400 je záporných.

EXAMPLE: ZVEREJNIŤ PRE ZMENU HODNOT VIACERÝCH PRVKOV

Postup je podobný tomu, ktorý bol uvedený predtým, ak chcete zmeniť jeden prvok. Rozdiel je v tom, že vynecháte element_id z tém a potom uvediete množinu element_ids pred údajmi vo vnútri užitočného zaťaženia. Pozrite si syntax a štruktúru nižšie.

FILTROVANIE PODĽA TYPU FUNKCIE V DOTAZOCH

Parameter filtrov v užitočnom zaťažení umožňuje adresovať iba požadovanú funkciu (funkcie) prvku. Funkcia zapnutia/vypnutia spínača alebo stmievača sa nazýva „onoff“, naprample a príslušný filter je definovaný týmto spôsobom:

Odpoveď potom vyzerá takto, naprample

Hranatá zátvorka znamená, že môžete filtrovať aj podľa viacerých funkcií, napr

vedie k takejto odpovedi:

Dodatok

CHYBOVÉ KÓDY

Výsledkom chýb v komunikácii MQTT je číselný kód. Nasledujúca tabuľka vám to pomôže rozobrať.

PARAMETRE UŽITEČNÉHO ZAŤAŽENIA

Užitočné zaťaženie podporuje rôzne parametre v závislosti od kontextu. Nasledujúca tabuľka ukazuje, ktoré parametre sa môžu vyskytnúť v ktorých témach

POZNÁMKY K VERZII

• 1.00 VERZIA

novinky:

• Prvá publikácia