Software DIVUS VISION API
Specifikimet
- Produkti: DIVUS VISION API
- Prodhuesi: DIVUS GmbH
- Versioni: 1.00 REV0 1 – 20240528
- Vendndodhja: Pillhof 51, Eppan (BZ), Itali
Informacioni i produktit
DIVUS VISION API është një mjet softuerik i krijuar për ndërlidhjen me sistemet DIVUS VISION. Ai i lejon përdoruesit të aksesojnë dhe kontrollojnë elementë të ndryshëm brenda sistemit duke përdorur protokollet MQTT.
FAQ
Pyetje: A mund ta përdor DIVUS VISION API pa njohuri paraprake për kompjuterin ose teknologjinë e automatizimit?
Përgjigje: Manuali është përshtatur për përdoruesit me njohuri të mëparshme në këto fusha për të siguruar përdorim efikas të API-së.
INFORMACION I PËRGJITHSHËM
- DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – Itali
Udhëzimet e funksionimit, manualet dhe softueri mbrohen nga e drejta e autorit. Të gjitha të drejtat e rezervuara. Nuk lejohet kopjimi, dublikimi, përkthimi, përkthimi tërësisht ose pjesërisht. Një përjashtim vlen për krijimin e një kopje rezervë të softuerit për përdorim personal.
Manuali mund të ndryshojë pa paralajmërim. Ne nuk mund të garantojmë që të dhënat e përfshira në këtë dokument dhe në median e ruajtjes së dhënë janë pa gabime dhe të sakta. Sugjerimet për përmirësime si dhe sugjerimet për gabimet janë gjithmonë të mirëseardhura. Marrëveshjet zbatohen gjithashtu për anekset specifike të këtij manuali. Emërtimet në këtë dokument mund të jenë marka tregtare, përdorimi i të cilave nga palët e treta për qëllimet e tyre mund të cenojë të drejtat e pronarëve të tyre. Udhëzimet e përdorimit: Ju lutemi lexoni këtë manual përpara se ta përdorni për herë të parë dhe mbajeni në një vend të sigurt për referencë në të ardhmen. Grupi i synuar: Manuali është shkruar për përdoruesit me njohuri të mëparshme të kompjuterit dhe teknologjisë së automatizimit.
KONVENTAT E PREZANTIMIT
Hyrje
HYRJE E PËRGJITHSHME
Ky manual përshkruan VISION API (Application Programming Interface) – një ndërfaqe përmes së cilës VISION mund të adresohet dhe kontrollohet nga sistemet e jashtme.
Praktikisht kjo do të thotë se mund të përdorni sisteme si p.sh
- MQTT Explorer (https://www.microsoft.com/store/… – për testim),
- Asistent në shtëpi (https://www.home-assistant.io/) ose
- Nyja-KUQ (https://nodered.org/)
për të kontrolluar elementët e menaxhuar nga VISION ose për të lexuar statusin e tyre. Qasja dhe komunikimi bëhet nëpërmjet protokollit MQTT, i cili përdor të ashtuquajturat tema për të trajtuar funksione individuale ose grupe funksionesh ose për t'u informuar për ndryshimet në to. Për këtë qëllim përdoret një server (broker) MQTT, i cili merret me sigurinë dhe menaxhimin/shpërndarjen e mesazheve tek pjesëmarrësit. Në këtë rast, serveri MQTT ndodhet direkt në DIVUS KNX IQ dhe është i konfiguruar posaçërisht për këtë qëllim. Edhe pse VISION API mund të përdoret gjithashtu pa njohuri programimi, ky funksionalitet është i përshtatshëm për përdoruesit e avancuar.
Kushtet paraprake
Siç shpjegohet në manualin VISION, përdoruesi i API duhet si parazgjedhje fillimisht të aktivizohet në mënyrë që të mund ta përdorë atë, qasja në API funksionon vetëm duke përdorur të dhënat e vërtetimit të përdoruesve të Api. Për sa i përket të drejtave të përdoruesit, aktivizimi për këtë funksionalitet mund të konfigurohet ose në të gjithë ose në elementë individualë. Shih kapitullin 0. Sigurisht, ju duhet gjithashtu një projekt VISION në të cilin elementët që dëshironi të kontrolloni nga jashtë janë konfiguruar plotësisht dhe lidhja me ta është testuar me sukses. Për të qenë në gjendje të adresoni elementë individualë nëpërmjet API-së, ID-ja e elementit të tyre duhet të dihet: kjo shfaqet në fund të formularit të cilësimeve të elementit.
SIGURIA
Për arsye sigurie, qasja në API është e mundur vetëm në nivel lokal (dmth. jo përmes cloud). Prandaj, rreziku i sigurisë kur aktivizohet aksesi në API është i ulët. Megjithatë, elementët që kanë të bëjnë me sigurinë nuk duhet të aktivizohen ose mohohen në mënyrë eksplicite për aksesin në API.
MQTT DHE KUSHTET E TIJ – SHPJEGIM I SHKURTËR
Në MQTT, roli i menaxhimit dhe shpërndarjes së centralizuar të të gjitha mesazheve është ai i ndërmjetësit. Megjithëse serveri MQTT dhe ndërmjetësi MQTT nuk janë sinonime (serveri është një term më i gjerë për një rol që mund të luajnë edhe klientët MQTT), ndërmjetësi nënkuptohet gjithmonë në këtë manual kur përmendet serveri MQTT. Vetë DIVUS KNX IQ luan rolin e ndërmjetësit MQTT / serverit MQTT në kontekstin e këtij manuali.
Një server MQTT përdor të ashtuquajturat tema: një strukturë hierarkike me të cilën të dhënat kategorizohen, menaxhohen dhe publikohen.
Publikimi ka për qëllim parësor vënien e të dhënave të disponueshme për pjesëmarrësit e tjerë përmes temave. Nëse dëshironi të ndryshoni një vlerë, ju shkruani temës së dëshiruar së bashku me ndryshimin e vlerës së dëshiruar, duke përdorur gjithashtu një veprim publikimi. Pajisja e synuar ose serveri MQTT lexon ndryshimin e dëshiruar që ndikon në të dhe e miraton atë në përputhje me rrethanat. Për të kontrolluar nëse ndryshimi është zbatuar, mund të shikoni në temën e abonuar në kohë reale për të parë nëse ndryshimi është pasqyruar atje - nëse gjithçka ka funksionuar mirë.
Klientët zgjedhin temat që u interesojnë: kjo quhet abonim. Sa herë që një vlerë ndryshon në/nën një temë, të gjithë klientët e abonuar informohen – dmth pa pasur nevojë të pyesin në mënyrë eksplicite nëse diçka ka ndryshuar ose cila është vlera aktuale.
Ju mund të hapni (ose adresoni) një kanal të veçantë komunikimi me serverin MQTT duke futur çdo varg unik të quajtur klient_id në një temë. Client_id duhet të përdoret në temë për të përpunuar vlerat. Kjo shërben për të identifikuar origjinën e çdo ndryshimi, ndihmon me çdo gabim dhe nuk ndikon te klientët e tjerë, pasi përgjigjet përkatëse nga serveri, duke përfshirë çdo kod gabimi dhe mesazh, gjithashtu arrijnë temën vetëm me të njëjtin klient_id (dhe kështu vetëm ai klient). Client_id është një varg karakteresh unik i përbërë nga çdo kombinim i karaktereve 0-9, az, AZ, “-“, “_”.
Në përgjithësi, temat e abonimit të serverit MQTT të DIVUS KNX IQ përmbajnë statusin e fjalës kyçe, ndërsa temat e publikimit përmbajnë kërkesën për fjalë kyçe. Ato me status përditësohen automatikisht sapo ka një ndryshim vlere të jashtme ose sapo një ndryshim vlere është kërkuar nga vetë klienti nëpërmjet një publikimi dhe është aplikuar me sukses. Ato për botim ndahen më tej në ato të tipit (kërkim/)get dhe ato të tipit (kërkim/)vendosje.
Ndryshimet e vlerës dhe parametrat e tjerë opsionalë i shtohen temës me të ashtuquajturën ngarkesë. Parametrat e elementeve individuale (element-id, emri, lloji, funksionet)
Dallimi kryesor midis MQTT dhe modelit klasik klient-server, ku klienti kërkon dhe më pas ndryshon të dhënat, përqendrohet në konceptet e abonimit dhe publikimit. Pjesëmarrësit mund të publikojnë të dhëna, duke i vënë ato në dispozicion të të tjerëve, të cilët nëse janë të interesuar mund të abonohen në to. Kjo arkitekturë bën të mundur minimizimin e shkëmbimit të të dhënave dhe mbajtjen ende të përditësuar të të gjitha palëve të interesuara. Më shumë për detajet këtu: dhe parametra të veçantë (uuid, filtra) do të përdoren këtu. Megjithëse ka disa opsione, ngarkesa e dobishme shfaqet e formatuar si JSON në këtë manual. JSON përdor kllapa dhe presje për të përfaqësuar të dhënat e çdo strukture dhe kështu minimizon madhësinë e paketave të të dhënave që do të transmetohen. Më shumë detaje rreth ngarkesave të dobishme mund të gjenden më vonë në manual.
Për qëllime të veçanta, është e mundur të filtrohet sipas llojit të funksionit, p.sh. të adresohet vetëm on/off, p.sh. ndërprerësit 1-bit. Për këtë qëllim përdoret parametri i filtrave në ngarkesë. Filtrimi aktualisht është i mundur vetëm sipas llojit të funksionit.
Për të qenë në gjendje të adresoni elementë individualë, kërkohet ID e elementit të tyre. Kjo mund të gjendet në VISION në menynë e vetive të elementit ose gjithashtu mund të lexohet drejtpërdrejt nga të dhënat që shfaqen përpara çdo elementi të disponueshëm në pajtimin e përgjithshëm të MQTT Explorer (elementet atje renditen në mënyrë alfabetike sipas ID-së së elementit).
Konfigurimi për aksesin në API
KONFIGURIMI I VIZIONIT PËR QASJE TË PËRDORUESIT API
Në VISION si administrator, shkoni te Konfigurimi – Menaxhimi i Aksesit të Përdoruesit/API, kliko tek Përdoruesit/API Access dhe kliko me të djathtën mbi Përdoruesin API (ose shtyp dhe mbaje shtypur) për të hapur dritaren e redaktimit. Aty do të gjeni këto parametra dhe të dhëna
- Aktivizo (kutinë e zgjedhjes)
- Përdoruesi aktivizohet fillimisht këtu. Parazgjedhja është e çaktivizuar
- Emri i përdoruesit
- Ky varg kërkohet për qasje nëpërmjet API - kopjojeni atë nga këtu
- Fjalëkalimi
- Ky varg kërkohet për qasje nëpërmjet API - kopjojeni atë nga këtu
- Lejet
- Të drejtat e paracaktuara për leximin dhe shkrimin e vlerave të elementeve VISION mund të përcaktohen këtu, dmth ajo që është përcaktuar këtu vlen për të gjithë elementët ekzistues dhe të ardhshëm. Nëse dëshironi të lejoni qasjen vetëm në elementë individualë, nuk duhet t'i ndryshoni këto të drejta të paracaktuara
LEJET MBI ELEMENTET INDIVIDUALE
Rekomandohet që të mos jepni akses API për të gjithë projektin, por vetëm për elementët e dëshiruar. Veproni si më poshtë
- hyni në VISION si administrator
- zgjidhni elementin e dëshiruar dhe hapni menynë e cilësimeve të tij (klikoni me të djathtën ose mbani shtypur, më pas Cilësimet)
- nën hyrjen e menysë General – Permissions, aktivizoni “Override default permissions” dhe më pas shkoni te nën-artikulli Permissions, i cili tregon matricën e lejeve.
- aktivizoni lejen e kontrollit këtu, e cila gjithashtu mundëson view leje direkt. Nëse dëshironi të lexoni të dhëna vetëm përmes aksesit API, mjafton të aktivizoni view leje.
- përsëritni të njëjtën procedurë për të gjithë elementët që dëshironi të përdorni
Lidhja përmes MQTT
HYRJE
Si një ishampLe, do të demonstrojmë aksesin nëpërmjet API-së MQTT të DIVUS KNX IQ me një softuer relativisht të thjeshtë dhe falas të quajtur MQTT Explorer (shih kapitullin 1.1), i cili është i disponueshëm për Windows, Mac dhe Linux. Nënkuptohet një njohuri dhe përvojë bazë me MQTT.
TË DHËNAT TË KËRKOHEN PËR LIDHJE
Siç u përmend më herët (shih seksionin 2.1), kërkohet emri i përdoruesit dhe fjalëkalimi i përdoruesit API. Këtu është një fundview nga të gjitha të dhënat që duhet të mblidhen përpara se të vendoset një lidhje:
- Emri i përdoruesit Lexoni në faqen e detajeve të përdoruesit të API
- Fjalëkalimi Lexoni në faqen e detajeve të përdoruesit të API
- Adresa IP Lexoni në cilësimet e lëshuesit nën General – Network – Ethernet (ose nëpërmjet Sinkronizuesit)
- Porti 8884 (ky port është i rezervuar për këtë qëllim)
LIDHJA E PARË ME MQTT EXPLORER DHE ABONIM TË PËRGJITHSHËM
Normalisht, MQTT bën dallimin midis aktiviteteve që regjistrohen dhe publikohen. MQTT Explorer e thjeshton këtë duke u abonuar automatikisht në të gjitha temat e disponueshme (tema #) kur të bëhet lidhja e parë. Si rezultat, pema që çon te të gjithë elementët e disponueshëm (dmth. qasja e përdoruesit të API është dhënë) mund të shihet drejtpërdrejt në zonën e majtë të dritares së MQTT Explorer pas një lidhjeje të suksesshme. Për të futur tema të tjera të abonimit ose për të zëvendësuar # me një temë më specifike, shkoni te Advanced në dritaren e lidhjes. Tema e treguar në të djathtën e sipërme duket diçka si kjo:
ku 7f4x0607849x444xxx256573x3x9x983 është emri i përdoruesit të API-së dhe lista e objekteve përmban të gjithë elementët e disponueshëm. Kjo temë mbahet gjithmonë e përditësuar, dmth çdo ndryshim në vlerë pasqyrohet aty në kohë reale. Nëse dëshironi të regjistroheni vetëm në elementë individualë, futni ID-në e elementit të elementit të dëshiruar pas listave_objekte/.
Shënim: Ky lloj abonimi përafërsisht korrespondon me logjikën prapa adresave të reagimit KNX; ai tregon statusin aktual të elementeve dhe mund të përdoret për të kontrolluar nëse ndryshimet e dëshiruara janë zbatuar me sukses. Nëse dëshironi vetëm të lexoni të dhëna, por jo t'i ndryshoni ato, ky lloj pajtimi është i mjaftueshëm.
Një element i vetëm i thjeshtë duket diçka si kjo në shënimin JSON
Shënim: Të gjitha vlerat kanë sintaksën e treguar më lart, p.sh. { “vlera”: “1” } si rezultat i temave të abonimit, ndërsa vlera shkruhet drejtpërdrejt në ngarkesën për të ndryshuar një vlerë (dmth për temat e publikuara) – kllapat dhe "vlera" janë hequr p.sh. "onoff": "1".
Komandat e avancuara
HYRJE
Në përgjithësi ekzistojnë 3 lloje temash:
- Abonohuni te temat për të parë elementët e disponueshëm dhe për të marrë ndryshimet e vlerës në kohë reale
- Regjistrohu për temat për të marrë përgjigjet për (klientët ) publikoni kërkesat
- Publikoni temat për të marrë ose për të vendosur elementë me vlerat e tyre
Më vonë do t'u referohemi këtyre llojeve duke përdorur numërimin e treguar këtu (p.sh. tema të tipit 1, 2, 3). Më shumë detaje në seksionet e mëposhtme dhe në kapitullin. 4.2.
ABONOHUNI TEMA PËR TË SHIKONI ELEMENTET E DISPONUESHME DHE PËR TË MERRNI NDRYSHIMET E VLERËS SË KOHA REALTË
Këto tashmë janë përshkruar
ABONOHUNI TEMA PËR TË MERRNI PËRGJIGJE NË KËRKESAT PËR PUBLIKIM TË KLIENTIT
Ky lloj temash është fakultativ. Ajo lejon të
- hapni një kanal unik komunikimi me serverin MQTT duke përdorur një klient_id arbitrar. Më shumë rreth kësaj në kapitull. 4.2.2
- merrni rezultatin e kërkesave për publikim në temën përkatëse të abonimit: suksesi ose dështimi me kodin dhe mesazhin e gabimit.
Ka tema të ndryshme për të marrë përgjigje për të marrë ose për të vendosur komandat e publikimit. Dallimi përkatës në
Pasi të keni vendosur temat e nevojshme për sistemin tuaj, mund të vendosni ta hiqni këtë hap dhe të përdorni drejtpërdrejt temat e publikimit.
PUBLIKONI TEMA PËR TË MERRNI OSE PËR TË VENDOSUR ELEMENTET ME VLERAT E TYRE
Këto tema përdorin një rrugë të ngjashme me ato për abonim - ndryshimi i vetëm është fjala "kërkesë" në vend të "statusit" të përdorur për t'u abonuar. Shtigjet e plota të temës tregohen më vonë në kapitull. 4.2.2\ Një temë marrë do të kërkojë të lexojë elementet dhe vlerat e serverit MQTT. Ngarkesa mund të përdoret për të filtruar bazuar në llojin e funksionit të elementeve. Një temë e caktuar do të kërkojë të ndryshojë disa pjesë të një elementi, siç detajohet në ngarkesën e tij.
PARAFAKS PËR KOMANDA DHE PËRGJIGJE KOMPJENTE
SHPJEGIM I SHKURTËR
Të gjitha komandat që dërgohen në serverin MQTT kanë një pjesë fillestare të përbashkët, domethënë:
SHPJEGIMI I DETAJ
Temat në kohë reale (lloji 1) do të kenë prefiksin e përgjithshëm (shih më lart) më pas do të pasohen nga
or
Për komandat e vendosura, padyshim që payload luan rolin kryesor pasi do të përmbajë ndryshimet e dëshiruara (dmth. vlerat e ndryshuara për funksionet e elementit). Një Paralajmërim: Mos përdorni kurrë opsionin e mbajtjes në komandat tuaja të tipit 3 pasi mund të shkaktojë probleme në anën KNX.
EXAMPLE: PUBLIKONI PËR NDRYSHIMIN E VLERËS SË NJË ELEMENTIT TË VETEM
Rasti më i thjeshtë është të dëshironi të ndryshoni vlerën e njërit prej elementeve të treguar nga abonimi i përgjithshëm.
Në përgjithësi, ndryshimi/ndërrimi i një funksioni të VISION nëpërmjet MQTT përbëhet nga 3 hapa, jo të gjithë prej të cilëve janë absolutisht të nevojshëm, por megjithatë ne rekomandojmë kryerjen e tyre siç përshkruhet.
- Tema që përmban funksionin që duam të modifikojmë është abonuar duke përdorur një klient_id të personalizuar
- Tema për redaktim publikohet së bashku me ngarkesën me ndryshimet e dëshiruara duke përdorur klientin_id të zgjedhur në 1.
- Për të kontrolluar, atëherë mund të shihni përgjigjen në temën (1.) – dmth nëse (2.) funksionoi apo jo
- Në pajtimin e përgjithshëm, ku të gjitha vlerat përditësohen kur bëhen ndryshime, mund të shihni ndryshimin(et) e dëshiruar të vlerës nëse gjithçka ka funksionuar mirë.
Hapat për ta bërë këtë janë:
- zgjidhni një klient_id p.sh. "Divus" dhe futeni atë në shtegun pas emrit të përdoruesit të API
Kjo është tema e plotë për t'u abonuar në kanalin tuaj të komunikimit me serverin MQTT. Kjo i tregon serverit se ku prisni përgjigjet ndaj ndryshimeve që keni ndërmend të dërgoni. Vini re pjesën e statusit/setit që përcakton a. se është një temë subscribe dhe b. se do të marrë përgjigjet për të vendosur komandat e tipit. - Tema e publikimit do të jetë e njëjtë me përjashtim të ndërrimit të fjalëve kyçe të kërkesës për status
- se çfarë duhet të konsistojë ndryshimi shkruhet në ngarkesë. Këtu janë disa ishamples.
- Fikja e një elementi që ka funksionin e ndezjes/fikjes (1 bit):
- Ndezja e një elementi që ka funksionin e ndezjes/fikjes (1 bit). Përveç kësaj, nëse disa komanda të tilla nisen nga i njëjti klient, parametri uuid ("ID unike", zakonisht është një varg 128-bit i formatuar si 8-4-4-4-12 shifra hex) mund të përdoret për të caktuar përgjigje ndaj pyetjes përkatëse, pasi ky parametër – nëse është i pranishëm në pyetje – mund të gjendet edhe në përgjigje.
- Ndezja dhe vendosja e ndriçimit të një dimmer në 50%
- Përgjigja për temën e treguar dhe të abonuar më lart (për të qenë të saktë, ngarkesa e saj) është atëherë, p.shample.
Përgjigja e mësipërme është një ishample në rastin e një ngarkese të saktë, megjithëse elementi nuk ka funksion zbehjeje. Nëse ka probleme më serioze që bëjnë që ngarkesa të mos interpretohet saktë, përgjigja do të duket si kjo (p.sh.):
për një shpjegim të kodeve të gabimit dhe mesazheve, por në përgjithësi, si për http, 200 kode janë përgjigje pozitive ndërsa 400 janë negative.
- Fikja e një elementi që ka funksionin e ndezjes/fikjes (1 bit):
EXAMPLE: PUBLIKONI PËR NDRYSHIMIN E VLERAVE TË SHUMË ELEMENTEVE
Procedura është e ngjashme me atë të treguar më parë për të ndryshuar një element të vetëm. Dallimi është se ju e hiqni elementin_id nga temat dhe më pas tregoni grupin e elementeve_id përpara të dhënave brenda ngarkesës. Shihni sintaksën dhe strukturën më poshtë.
FILTRONI SIPAS LLOJIT FUNKSIONI NË PYETJE
Parametri i filtrave në ngarkesë lejon adresimin e vetëm funksioneve të dëshiruara të një elementi. Funksioni i ndezjes/fikjes së një çelësi ose dimmeri quhet "ndezje", p.shample, dhe filtri përkatës përcaktohet në këtë mënyrë:
Përgjigja atëherë duket si kjo, p.shample
Kllapa katrore tregon se mund të filtrosh edhe sipas disa funksioneve, p.sh
çon në një përgjigje të tillë:
Shtojca
KODET E GABIMIT
Gabimet në komunikimin MQTT rezultojnë në një kod numerik. Tabela e mëposhtme ndihmon për ta zbërthyer atë.
PARAMETRAT E NGARKESËS SË PAGESËS
Ngarkesa mbështet parametra të ndryshëm në varësi të kontekstit. Tabela e mëposhtme tregon se cilat parametra mund të ndodhin në cilat tema
SHËNIME TË VERSIONIT
- VERSIONI 1.00
Lajme:
• Publikimi i parë
Dokumentet / Burimet
 |
Software DIVUS VISION API [pdf] Manuali i Përdoruesit Softueri VISION API, Softuer API, Softuer |
 |
Software DIVUS Vision API [pdfUdhëzuesi i përdoruesit Vision API Software, Vision, API Software, Software |