Programska oprema DIVUS VISION API

Specifikacije

• Izdelek: DIVUS VISION API
• Proizvajalec: DIVUS GmbH
• Različica: 1.00 REV0 1 – 20240528
• Lokacija: Pillhof 51, Eppan (BZ), Italija

Informacije o izdelku

DIVUS VISION API je programsko orodje, zasnovano za povezovanje s sistemi DIVUS VISION. Uporabnikom omogoča dostop in nadzor različnih elementov znotraj sistema z uporabo protokolov MQTT.

pogosta vprašanja

V: Ali lahko uporabljam DIVUS VISION API brez predhodnega znanja o osebnem računalniku ali tehnologiji avtomatizacije?

O: Priročnik je prilagojen uporabnikom s predznanjem na teh področjih, da se zagotovi učinkovita uporaba API-ja.

SPLOŠNE INFORMACIJE

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

Navodila za uporabo, priročniki in programska oprema so avtorsko zaščiteni. Vse pravice pridržane. Kopiranje, razmnoževanje, prevajanje, prevajanje v celoti ali delno ni dovoljeno. Izjema velja za izdelavo varnostne kopije programske opreme za osebno uporabo.
Priročnik se lahko spremeni brez predhodnega obvestila. Ne moremo zagotoviti, da so podatki v tem dokumentu in na priloženem mediju za shranjevanje brez napak in pravilni. Predlogi za izboljšave in namigi o napakah so vedno dobrodošli. Sporazumi veljajo tudi za posebne priloge tega priročnika. Oznake v tem dokumentu so lahko blagovne znamke, katerih uporaba s strani tretjih oseb za lastne namene lahko krši pravice njihovih lastnikov. Navodila za uporabnika: Pred prvo uporabo preberite ta priročnik in ga shranite na varno mesto za poznejšo uporabo. Ciljna skupina: Priročnik je namenjen uporabnikom s predznanjem osebnega računalnika in tehnike avtomatizacije.

PREDSTAVITEVNA KONVENCIJA

Uvod

SPLOŠNI UVOD

Ta priročnik opisuje VISION API (Application Programming Interface) – vmesnik, prek katerega je mogoče naslavljati in nadzorovati VISION iz zunanjih sistemov.
V praksi to pomeni, da lahko uporabljate sisteme, kot je npr

• MQTT Explorer (https://www.microsoft.com/store/… – za testiranje),
• Domači pomočnik (https://www.home-assistant.io/) oz
• Vozlišče-RED (https://nodered.org/)

za nadzor elementov, ki jih upravlja VISION, ali branje njihovega stanja. Dostop in komunikacija potekata preko protokola MQTT, ki s pomočjo tako imenovanih tem naslavlja posamezne funkcije ali sklope funkcij oziroma se obvešča o spremembah le-teh. V ta namen se uporablja MQTT strežnik (broker), ki skrbi za varnost in upravljanje/distribucijo sporočil udeležencem. V tem primeru se strežnik MQTT nahaja neposredno na DIVUS KNX IQ in je posebej konfiguriran za ta namen. Čeprav je VISION API mogoče uporabljati tudi brez znanja programiranja, je ta funkcionalnost primerna za napredne uporabnike.

POVEZANOST Z DNE

Kot je pojasnjeno v priročniku VISION, mora biti uporabnik API-ja privzeto najprej aktiviran, da ga lahko uporablja. Dostop do API-ja deluje samo z uporabo podatkov za preverjanje pristnosti uporabnikov API-ja. Kar zadeva uporabniške pravice, je aktivacijo te funkcionalnosti mogoče konfigurirati na vseh ali na posameznih elementih. Glej poglavje 0. Seveda potrebujete tudi projekt VISION, v katerem so elementi, ki jih želite nadzorovati od zunaj, popolnoma konfigurirani in je povezava z njimi uspešno testirana. Za naslavljanje posameznih elementov prek API-ja mora biti znan njihov ID elementa: ta je prikazan na dnu obrazca za nastavitve elementa

VARNOST

Zaradi varnosti je dostop do API-ja mogoč le lokalno (tj. ne prek oblaka). Varnostno tveganje pri aktiviranju dostopa API je zato majhno. Kljub temu elementov, pomembnih za varnost, ne bi smeli omogočiti ali izrecno zavrniti za dostop do API-ja.

MQTT IN NJEGOVI POGOJI – KRATKA RAZLAGA

• V MQTT je vloga posrednika centralizirano upravljanje in distribucija vseh sporočil. Čeprav strežnik MQTT in posrednik MQTT nista sinonima (strežnik je širši izraz za vlogo, ki jo lahko igrajo tudi odjemalci MQTT), je v tem priročniku vedno mišljen posrednik, ko je omenjen strežnik MQTT. Sam DIVUS KNX IQ igra vlogo posrednika MQTT / strežnika MQTT v kontekstu tega priročnika.
• Strežnik MQTT uporablja tako imenovane teme: hierarhično strukturo, s katero so podatki kategorizirani, upravljani in objavljeni.
• Primarni cilj objavljanja je omogočiti dostop do podatkov drugim udeležencem prek tem. Če želite spremeniti vrednost, pišete v želeno temo skupaj z želeno spremembo vrednosti, tudi z uporabo dejanja objave. Ciljna naprava ali strežnik MQTT prebere želeno spremembo, ki vpliva nanjo, in jo ustrezno sprejme. Če želite preveriti, ali je bila sprememba uveljavljena, lahko pogledate v temo v realnem času, na katero ste naročeni, da vidite, ali se sprememba tam odraža – če je vse dobro delovalo.
• Stranke izberejo teme, ki jih zanimajo: to se imenuje naročanje. Vsakič, ko se spremeni vrednost v/pod temo, so vsi naročeni odjemalci obveščeni – torej brez izrecnega vprašanja, ali se je kaj spremenilo ali kakšna je trenutna vrednost.
• Ločen komunikacijski kanal s strežnikom MQTT lahko odprete (ali naslovite) tako, da v temo vnesete kateri koli edinstven niz, imenovan client_id. Client_id je treba uporabiti v temi za obdelavo vrednosti. To služi za identifikacijo izvora vsake spremembe, pomaga pri morebitnih napakah in ne vpliva na druge odjemalce, saj ustrezni odgovori s strežnika, vključno z morebitnimi kodami napak in sporočili, prav tako dosežejo samo temo z istim client_id (in tako samo ta stranka). Client_id je edinstven niz znakov, sestavljen iz poljubne kombinacije znakov 0–9, az, AZ, »-«, »_«.
• Na splošno teme naročanja strežnika MQTT DIVUS KNX IQ vsebujejo status ključne besede, medtem ko teme objave vsebujejo zahtevo za ključno besedo. Tisti s statusom se samodejno posodobijo takoj, ko pride do zunanje spremembe vrednosti ali takoj, ko odjemalec prek objave zahteva spremembo vrednosti in je bila uspešno uporabljena. Tiste za objavo delimo še na tiste tipa (request/)get in tiste tipa (request/)set.
• Spremembe vrednosti in drugi neobvezni parametri so dodani temi s tako imenovano koristno obremenitvijo. Parametri posameznih elementov (element-id, ime, tip, funkcije)

Glavna razlika med MQTT in klasičnim modelom odjemalec-strežnik, kjer odjemalec zahteva in nato spremeni podatke, je osredotočena na koncepte naročanja in objave. Udeleženci lahko podatke objavijo in jih dajo na razpolago drugim, ki se nanje, če jih zanima, lahko naročijo. Ta arhitektura omogoča minimiziranje izmenjave podatkov in ohranja vse zainteresirane strani na tekočem. Več o podrobnostih tukaj: in tukaj je treba uporabiti posebne parametre (uuid, filtri). Čeprav obstaja več možnosti, je tovor v tem priročniku prikazan v formatu JSON. JSON uporablja oklepaje in vejice za predstavitev podatkov katere koli strukture in tako zmanjša velikost podatkovnih paketov, ki jih je treba prenesti. Več podrobnosti o koristnih tovorih je na voljo kasneje v priročniku.

• Za posebne namene je možno filtriranje glede na vrsto funkcije, npr. naslavljanje samo vklop/izklop, tj. 1-bitna stikala. V ta namen se uporablja parameter filtrov v obremenitvi. Filtriranje je trenutno možno samo po vrsti funkcije.
• Za naslavljanje posameznih elementov je potreben njihov ID elementa. To je mogoče najti v VISION v meniju lastnosti elementa ali pa ga prebrati neposredno iz podatkov, ki so prikazani pred vsakim razpoložljivim elementom v splošni naročnini MQTT Explorerja (elementi so tam navedeni po abecedi glede na ID elementa).

Konfiguracija za dostop API

KONFIGURIRANJE VISION ZA UPORABNIŠKI DOSTOP API

V VISION kot skrbnik pojdite na Configuration – User/API Access Management, kliknite na Users/API access in z desno miškino tipko kliknite API User (ali pritisnite in držite), da odprete okno za urejanje. Tam boste našli te parametre in podatke

• Omogoči (potrditveno polje)
  • Uporabnik je tukaj najprej omogočen. Privzeto je onemogočeno
• Uporabniško ime
  • Ta niz je potreben za dostop prek API-ja – kopirajte ga od tukaj
• Geslo
  • Ta niz je potreben za dostop prek API-ja – kopirajte ga od tukaj
• Dovoljenja
  • Tukaj lahko določite privzete pravice za branje in pisanje vrednosti elementov VISION, kar pomeni, da tukaj definirano velja za vse obstoječe in bodoče elemente. Če želite dovoliti dostop samo do posameznih elementov, teh privzetih pravic ne spreminjajte

DOVOLJENJA NA POSAMEZNIH ELEMENTIH

Priporočljivo je, da API dostopa ne dodelite celotnemu projektu, temveč le želenim elementom. Nadaljujte kot sledi

1. prijavite se v VISION kot skrbnik
2. izberite želeni element in odprite meni z njegovimi nastavitvami (z desno miškino tipko kliknite ali pridržite, nato Nastavitve)
3. pod menijskim vnosom Splošno – Dovoljenja aktivirajte “Preglasi privzeta dovoljenja” in nato pojdite na podpostavko Dovoljenja, kjer je prikazana matrika dovoljenj.
4. tukaj aktivirajte dovoljenje za nadzor, ki omogoča tudi view dovoljenje neposredno. Če želite samo brati podatke prek API dostopa, je dovolj, da omogočite view dovoljenje.
5. ponovite isti postopek za vse elemente, do katerih želite dostopati

Povezava preko MQTT

UVOD

Kot bivšiampLe bomo prikazali dostop prek API-ja MQTT DIVUS KNX IQ z relativno preprosto, brezplačno programsko opremo, imenovano MQTT Explorer (glejte poglavje 1.1), ki je na voljo za Windows, Mac in Linux. Predvideno je osnovno znanje in izkušnje z MQTT.

PODATKI, POTREBNI ZA POVEZAVO

Kot je bilo že omenjeno (glejte razdelek 2.1), sta potrebna uporabniško ime in geslo uporabnika API-ja. Tukaj je konecview vseh podatkov, ki jih je treba zbrati pred vzpostavitvijo povezave:

• Uporabniško ime Preberite na strani s podrobnostmi uporabnika API-ja
• Geslo Preberite na strani s podrobnostmi uporabnika API-ja
• Naslov IP Preberite v nastavitvah zaganjalnika pod Splošno – Omrežje – Ethernet (ali prek sinhronizatorja)
• Vrata 8884 (ta vrata so rezervirana za ta namen)

PRVA POVEZAVA Z MQTT EXPLORER IN SPLOŠNA NAROČNICA

Običajno MQTT razlikuje med dejavnostma naročanja in objave. MQTT Explorer to poenostavi s samodejno naročanjem na vse razpoložljive teme (št. teme), ko se vzpostavi prva povezava. Posledično je drevo, ki vodi do vseh razpoložljivih elementov (tj odobrenega uporabniškega dostopa API-ja), po uspešni povezavi mogoče videti neposredno v levem delu okna MQTT Explorer. Če želite vnesti nadaljnje naročene teme ali zamenjati # z bolj specifično temo, pojdite na Napredno v oknu za povezavo. Tema, prikazana zgoraj desno, izgleda nekako takole:

kjer je 7f4x0607849x444xxx256573x3x9x983 uporabniško ime API-ja in objects_list vsebuje vse razpoložljive elemente. Ta tema je vedno posodobljena, tj. vse spremembe vrednosti se tam odražajo v realnem času. Če se želite naročiti samo na posamezne elemente, vpišite ID elementa želenega elementa za objects_list/.

Opomba: Ta vrsta naročnine približno ustreza logiki za povratne naslove KNX; prikazuje trenutno stanje elementov in se lahko uporablja za preverjanje, ali so bile želene spremembe uspešno uporabljene. Če želite samo prebrati podatke, ne pa jih spremeniti, zadostuje ta vrsta naročnine.

En sam preprost element je v zapisu JSON videti nekako takole

Opomba: Vse vrednosti imajo sintakso, prikazano zgoraj, npr. { “vrednost”: “1” } kot rezultat naročenih tem, medtem ko je vrednost zapisana neposredno v koristnem tovoru za spremembo vrednosti (tj. za objave tem) – oklepaji in »value« so izpuščeni, npr. »onoff«: »1«.

Napredni ukazi

UVOD

Na splošno obstajajo 3 vrste tem:

1. Naročite se na teme, če si želite ogledati razpoložljive elemente in prejemati spremembe vrednosti v realnem času
2. Naročite se na teme, da boste prejeli odgovore (stranke ) objaviti zahteve
3. Objavite teme, da dobite ali nastavite elemente z njihovimi vrednostmi

Kasneje se bomo te vrste sklicevali z oštevilčenjem, prikazanim tukaj (npr. teme tipa 1, 2, 3). Več podrobnosti v naslednjih razdelkih in v poglavju. 4.2.

NAROČITE SE NA TEME, DA SI SI OGLEDATE RAZPOLOŽLJIVE ELEMENTE IN DA PREJMETE SPREMEMBE VREDNOSTI V REALNEM ČASU

Te so bile že opisane

NAROČITE SE NA TEME, DA PRIDOBITE ODGOVORE NA ZAHTEVE STRANKE ZA OBJAVO

Tovrstne teme niso obvezne. Omogoča, da

• odprite edinstven komunikacijski kanal s strežnikom MQTT z uporabo poljubnega client_id. Več o tem v pogl. 4.2.2
• pridobite rezultat zahtev za objavo na ustrezni temi za naročanje: uspeh ali neuspeh s kodo napake in sporočilom.

Obstajajo različne teme, kjer lahko dobite odgovore ali nastavite ukaze za objavo. Ustrezna razlika v Ko dobite potrebne teme za vaš sistem, se lahko odločite, da odstranite ta korak in neposredno uporabite teme objave.

 OBJAVITE TEME, DA PRIDOBITE ALI NASTAVITE ELEMENTE Z NJIHOVIMI VREDNOSTMI

Te teme uporabljajo pot, podobno tistim za naročanje - edina sprememba je beseda "zahteva" namesto "statusa", ki se uporablja za naročanje. Celotne poti tem so prikazane kasneje v poglavju. 4.2.2\ Tema get bo zahtevala branje elementov in vrednosti strežnika MQTT. Koristni tovor se lahko uporabi za filtriranje glede na tip funkcije elementov. Nastavljena tema bo zahtevala spremembo nekaterih delov elementa, kot je podrobno opisano v njeni nosilnosti.

PREPONA ZA UKAZE IN USTREZNE ODZIVE

 KRATKA RAZLAGA

Vsi ukazi, ki so poslani na strežnik MQTT, imajo skupen začetni del, in sicer:

PODROBNA RAZLAGA

Teme v realnem času (tip 1) bodo imele splošno predpono (glejte zgoraj), ki ji bo sledila

or

Pri nastavljenih ukazih ima koristni tovor očitno glavno vlogo, saj bo vseboval želene spremembe (tj. spremenjene vrednosti za funkcije elementa). Opozorilo: nikoli ne uporabljajte možnosti zadrževanja v svojih ukazih tipa 3, ker lahko povzroči težave na strani KNX.

EXAMPLE: OBJAVI ZA SPREMEMBO VREDNOSTI POSAMEZNEGA ELEMENTA

Najenostavnejši primer je, da želite spremeniti vrednost enega od elementov, ki jih prikazuje splošni subscribe.
Na splošno je spreminjanje/preklapljanje funkcije VISION prek MQTT sestavljeno iz 3 korakov, od katerih vsi niso nujno potrebni, vendar kljub temu priporočamo, da jih izvedete, kot je opisano.

1. Tema, ki vsebuje funkcijo, ki jo želimo urediti, je naročena z uporabo custom client_id
2. Tema za urejanje je objavljena skupaj s tovorom z želenimi spremembami z uporabo client_id, izbranega v 1.
3. Če želite preveriti, si lahko nato ogledate odgovor v temi (1.) – tj. ali je (2.) delovalo ali ne
4. V splošnem naročanju, kjer se ob spremembah posodobijo vse vrednosti, si lahko ogledate želene spremembe vrednosti, če je vse v redu.

Koraki za to so:

1. izberite client_id, npr. “Divus” in ga vstavite v pot za uporabniškim imenom API-ja
   To je popolna tema za naročanje na lasten komunikacijski kanal s strežnikom MQTT. To pove strežniku, kje pričakujete odgovore na spremembe, ki jih nameravate poslati. Bodite pozorni na del stanja/nastavitve, ki definira a. da je naročena tema in b. da bo dobil odgovore na ukaze vrste set.
2. Tema objave bo enaka, razen zamenjave ključnih besed za zahtevo po statusu
3. kaj naj obsega sprememba je zapisano v koristnem tovoru. Tukaj je nekaj bivšihamples.
   • Izklop elementa, ki ima funkcijo vklop/izklop (1 bit):
   • Vklop elementa, ki ima funkcijo vklop/izklop (1 bit). Poleg tega, če je več takšnih ukazov zagnanih iz istega odjemalca, se lahko za dodelitev odgovor na ustrezno poizvedbo, saj je ta parameter – če je prisoten v poizvedbi – mogoče najti tudi v odgovoru.
   • Vklop in nastavitev svetlosti zatemnilnika na 50 %
   • Odgovor na zgoraj prikazano temo in nanjo naročen (natančneje, njena obremenitev) je npr.ample.
     Zgornji odgovor je example v primeru pravilne nosilnosti, čeprav element nima funkcije zatemnitve. Če gre za resnejše težave, zaradi katerih koristni tovor ni pravilno interpretiran, bo odgovor videti tako (npr.):
     za razlago kod napak in sporočil, vendar na splošno, tako kot za http, je 200 kod pozitivnih odgovorov, medtem ko je 400 negativnih.

EXAMPLE: OBJAVI ZA SPREMINJANJE VREDNOSTI VEČ ELEMENTOV

Postopek je podoben prejšnjemu za spremembo posameznega elementa. Razlika je v tem, da element_id izpustite iz tem in nato navedete nabor element_ids pred podatki znotraj koristnega tovora. Oglejte si sintakso in strukturo spodaj.

FILTRIRANJE PO VRSTI FUNKCIJE V POIZVEDBAH

Parameter filtrov v obremenitvi dovoljuje, da se obravnavajo samo želene funkcije elementa. Funkcija vklopa/izklopa stikala ali zatemnitve se imenuje "onoff", nprample, ustrezen filter pa je definiran na ta način:

Odgovor je potem videti takole, nprample

Oglati oklepaj pomeni, da lahko filtrirate tudi po več funkcijah, npr

vodi do takega odgovora:

Dodatek

KODE NAPAK

Napake v komunikaciji MQTT povzročijo številčno kodo. Naslednja tabela vam pomaga razčleniti.

PARAMETRI NOSILNOSTI

Tovor podpira različne parametre, odvisno od konteksta. Naslednja tabela prikazuje, kateri parametri se lahko pojavijo v posameznih temah

OPOMBE RAZLIČICE

• VERZIJA 1.00

Novice:

• Prva objava

Dokumenti / Viri

	Programska oprema DIVUS VISION API [pdfUporabniški priročnik Programska oprema VISION API, programska oprema API, programska oprema
	Programska oprema DIVUS Vision API [pdf] Uporabniški priročnik Programska oprema Vision API, Vision, programska oprema API, programska oprema

Reference

• Uporabniški priročnik