DIVUS VISION API tarkvara
Tehnilised andmed
- Toode: DIVUS VISION API
- Tootja: DIVUS GmbH
- Versioon: 1.00 REV0 1 – 20240528
- Asukoht: Pillhof 51, Eppan (BZ), Itaalia
Tooteteave
DIVUS VISION API on tarkvara tööriist, mis on loodud liidestamiseks DIVUS VISION süsteemidega. See võimaldab kasutajatel MQTT-protokolle kasutades pääseda juurde ja juhtida süsteemi erinevaid elemente.
KKK
K: Kas ma saan kasutada DIVUS VISION API-t ilma eelnevate teadmisteta arvuti- või automatiseerimistehnoloogiast?
V: Käsiraamat on kohandatud nendes valdkondades varasemate teadmistega kasutajatele, et tagada API tõhus kasutamine.
ÜLDTEAVE
- DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – Itaalia
Kasutusjuhised, juhendid ja tarkvara on kaitstud autoriõigusega. Kõik õigused kaitstud. Kopeerimine, paljundamine, tõlkimine, täielik või osaline tõlkimine ei ole lubatud. Erand kehtib tarkvarast isiklikuks kasutamiseks mõeldud varukoopia loomisel.
Kasutusjuhendit võidakse ette teatamata muuta. Me ei saa garanteerida, et selles dokumendis ja kaasasolevatel andmekandjatel sisalduvad andmed on vigadeta ja õiged. Parandusettepanekud ja vihjed vigade kohta on alati teretulnud. Kokkulepped kehtivad ka käesoleva juhendi konkreetsetele lisadele. Nimetused selles dokumendis võivad olla kaubamärgid, mille kasutamine kolmandate isikute poolt oma eesmärkidel võib rikkuda nende omanike õigusi. Kasutusjuhised: Palun lugege käesolev juhend enne selle esmakordset kasutamist läbi ja hoidke seda edaspidiseks kasutamiseks kindlas kohas. Sihtrühm: Käsiraamat on kirjutatud kasutajatele, kellel on varasemad teadmised arvuti- ja automaatikatehnoloogiast.
ESITLUSKONVENTSIOONID
Sissejuhatus
ÜLDSISSEJUHATUS
Selles juhendis kirjeldatakse VISION API-d (Application Programming Interface) – liidest, mille kaudu saab VISIONit välistest süsteemidest adresseerida ja juhtida.
Praktikas tähendab see, et saate kasutada selliseid süsteeme nagu
- MQTT Explorer (https://www.microsoft.com/store/… – testimiseks),
- Koduassistent (https://www.home-assistant.io/) või
- Sõlm-PUNANE (https://nodered.org/)
VISIONi hallatavate elementide juhtimiseks või nende oleku lugemiseks. Juurdepääs ja suhtlus toimub MQTT protokolli kaudu, mis kasutab nn teemasid, et käsitleda üksikuid funktsioone või funktsioonide komplekte või olla informeeritud nende muudatustest. Selleks kasutatakse MQTT-serverit (maakler), mis tegeleb turvalisuse ja osalejatele sõnumite haldamise/jagamisega. Sel juhul asub MQTT server otse DIVUS KNX IQ-s ja on spetsiaalselt selleks otstarbeks konfigureeritud. Kuigi VISION API-t saab kasutada ka ilma programmeerimisalaste teadmisteta, sobib see funktsionaalsus edasijõudnutele.
EESMÄRGID
Nagu VISIONi juhendis selgitatud, peab API-kasutaja vaikimisi esmalt olema aktiveeritud, et seda saaks kasutada, API-juurdepääs töötab ainult Api kasutajate autentimisandmete abil. Mis puutub kasutajaõigustesse, siis selle funktsiooni aktiveerimise saab seejärel konfigureerida kas kõikidel või üksikutel elementidel. Vaata peatükki 0. Loomulikult on vaja ka VISION-projekti, mille elemendid, mida soovite väljastpoolt juhtida, on täielikult konfigureeritud ja ühendus nendega on edukalt testitud. Üksikute elementide käsitlemiseks API kaudu peab nende elemendi ID olema teada: see kuvatakse elemendi seadistuste vormi allosas
TURVALISUS
Turvalisuse huvides on API juurdepääs võimalik ainult lokaalselt (st mitte pilve kaudu). Turvarisk API juurdepääsu aktiveerimisel on seega madal. Sellegipoolest ei tohiks turvalisusega seotud elemente API juurdepääsu lubada ega selgesõnaliselt keelata.
MQTT JA SELLE TINGIMUSED – LÜHISELGITUS
MQTT-s on kõigi sõnumite tsentraliseeritud haldamise ja levitamise roll vahendajal. Kuigi MQTT server ja MQTT maakler ei ole sünonüümid (server on laiem mõiste rolli kohta, mida võivad mängida ka MQTT kliendid), mõeldakse selles juhendis MQTT serveri mainimisel alati maaklerit. DIVUS KNX IQ ise mängib selle juhendi kontekstis MQTT vahendaja / MQTT serveri rolli.
MQTT-server kasutab nn teemasid: hierarhilist struktuuri, mille abil andmeid kategoriseeritakse, hallatakse ja avaldatakse.
Avaldamise esmane eesmärk on teha andmed teemade kaudu kättesaadavaks teistele osalejatele. Kui soovite väärtust muuta, kirjutate soovitud teemasse koos soovitud väärtuse muutmisega, kasutades ka avaldamistoimingut. Sihtseade või MQTT-server loeb soovitud muudatust, mis seda mõjutab, ja võtab selle vastavalt kasutusele. Kontrollimaks, kas muudatus on rakendunud, saab tellitud reaalajas teemast vaadata, kas muudatus ka seal kajastub – kas kõik on õnnestunud.
Kliendid valivad neid huvitavad teemad: seda nimetatakse tellimiseks. Iga kord, kui mingis teemas/alla väärtus muutub, teavitatakse sellest kõiki tellitud kliente – st ilma, et peaks otse küsima, kas midagi on muutunud või milline on praegune väärtus.
MQTT-serveriga saate avada (või adresseerida) eraldi suhtluskanali, sisestades teemasse mis tahes kordumatu stringi nimega client_id. Väärtuste töötlemiseks tuleb teemas kasutada kliendi_id. See aitab tuvastada iga muudatuse päritolu, aitab vigade korral ega mõjuta teisi kliente, kuna serveri vastavad vastused, sealhulgas veakoodid ja teated, jõuavad samuti teemasse ainult sama kliendi_id-ga (ja seega ainult see klient). Kliendi_id on ainulaadne märgijada, mis koosneb mis tahes märkide kombinatsioonist 0-9, az, AZ, "-", "_".
Üldiselt sisaldavad DIVUS KNX IQ MQTT serveri tellimisteemad märksõna olekut, avaldamise teemad aga märksõna päringut. Olekuga isikuid värskendatakse automaatselt kohe, kui toimub väline väärtuse muutus või niipea, kui klient on ise avaldamise kaudu väärtuse muutmist taotlenud ja see on edukalt rakendatud. Avaldatavad on jagatud veel tüüpideks (päring/)get ja tüübiks (taotlus/)set.
Väärtuste muutused ja muud valikulised parameetrid lisatakse teemasse nn kasuliku koormusega. Üksikute elementide parameetrid (elemendi ID, nimi, tüüp, funktsioonid)
Peamine erinevus MQTT ja klassikalise klient-serveri mudeli vahel, kus klient küsib ja seejärel andmeid muudab, keskendub tellimise ja avaldamise kontseptsioonidele. Osalejad võivad avaldada andmeid, tehes need kättesaadavaks teistele, kes võivad soovi korral neid tellida. Selline arhitektuur võimaldab minimeerida andmevahetust ja hoida kõiki huvitatud osapooli siiski kursis. Täpsemalt siin: ja siin tuleb kasutada spetsiaalseid parameetreid (uuid, filtrid). Kuigi valikuid on mitu, kuvatakse kasulik koormus selles juhendis JSON-vormingus. JSON kasutab mis tahes struktuuri andmete esitamiseks sulgusid ja komasid ning vähendab seega edastatavate andmepakettide suurust. Lisateavet kasulike koormate kohta leiate juhendist hiljem.
Erieesmärkidel on võimalik filtreerida vastavalt funktsiooni tüübile, nt adresseerida ainult sisse/välja ehk 1-bitiseid lüliteid. Selleks kasutatakse kasuliku koormuse filtrite parameetrit. Filtreerimine on praegu võimalik ainult funktsiooni tüübi järgi.
Üksikute elementide käsitlemiseks on vaja nende elemendi ID-d. Selle leiate VISION-ist elemendi omaduste menüüst või saab lugeda ka otse andmetest, mis kuvatakse MQTT Exploreri üldises tellimuses iga saadaoleva elemendi ees (seal on elemendid loetletud tähestikulises järjekorras elemendi ID järgi).
API juurdepääsu konfiguratsioon
VISIOONI KONFIGUREMINE API KASUTAJA JUURDEPÄÄSUKS
Avage VISIONis administraatorina jaotis Configuration – User/API Access Management, klõpsake Users/API access ja paremklõpsake API kasutajal (või vajutage ja hoidke all), et avada redigeerimisaken. Sealt leiate need parameetrid ja andmed
- Luba (märkeruut)
- Siin on kasutaja esmalt lubatud. Vaikimisi on keelatud
- Kasutajanimi
- See string on vajalik API kaudu juurdepääsuks – kopeerige see siit
- Parool
- See string on vajalik API kaudu juurdepääsuks – kopeerige see siit
- load
- Siin saab määratleda VISION elementide väärtuste lugemise ja kirjutamise vaikimisi õigused, st siin määratletu kehtib kõigi olemasolevate ja tulevaste elementide kohta. Kui soovite lubada juurdepääsu ainult üksikutele elementidele, ei tohiks te neid vaikeõigusi muuta
LUBAD ÜKSIKUD ELEMENDIDELE
Soovitatav on mitte anda API-juurdepääsu kogu projektile, vaid ainult soovitud elementidele. Toimige järgmiselt
- logige VISIONisse administraatorina sisse
- valige soovitud element ja avage selle seadete menüü (paremklõpsake või hoidke all, seejärel Seaded)
- menüükirje General – Permissions all aktiveerige "Alista vaikimisi õigused" ja seejärel minge alamkirjesse Permissions, mis näitab lubade maatriksit.
- aktiveerige siin juhtimisõigus, mis võimaldab ka view luba otse. Kui soovite andmeid lugeda ainult API juurdepääsu kaudu, piisab, kui lubate view luba.
- korrake sama protseduuri kõigi elementide puhul, millele soovite juurde pääseda
Ühendus MQTT kaudu
SISSEJUHATUS
Nagu endineample, demonstreerime juurdepääsu DIVUS KNX IQ MQTT API kaudu suhteliselt lihtsa tasuta tarkvaraga MQTT Explorer (vt ptk 1.1), mis on saadaval Windowsi, Maci ja Linuxi jaoks. Eeldatakse põhiteadmisi ja -kogemust MQTT-ga.
ÜHENDUSEKS VAJALIKUD ANDMED
Nagu varem mainitud (vt jaotis 2.1), on API kasutaja kasutajanimi ja parool nõutavad. Siin on lõppview kõigist andmetest, mis tuleb enne ühenduse loomist koguda:
- Kasutajanimi Lugege ette API kasutaja üksikasjade lehel
- Parool Lugege ette API kasutaja üksikasjade lehel
- IP-aadress Lugege välja käivitusprogrammi sätetes jaotises Üldine – Võrk – Ethernet (või sünkroonija kaudu)
- Port 8884 (see port on selleks otstarbeks reserveeritud)
ESIMENE ÜHENDUS MQTT EXPLORERI JA ÜLDISE TELLIGA
Tavaliselt eristab MQTT tegevusi tellimisel ja avaldamisel. MQTT Explorer lihtsustab seda, tellides esimese ühenduse loomisel automaatselt kõik saadaolevad teemad (teema #). Selle tulemusena on puu, mis viib kõigi saadaolevate elementideni (st API kasutaja juurdepääs antud), on pärast edukat ühendust näha otse MQTT Exploreri akna vasakpoolses osas. Täiendavate tellimisteemade sisestamiseks või # asendamiseks konkreetsema teemaga avage ühendusaknas jaotis Täpsemalt. Paremal ülanurgas olev teema näeb välja umbes selline:
kus 7f4x0607849x444xxx256573x3x9x983 on API kasutajanimi ja objektide_loend sisaldab kõiki saadaolevaid elemente. Seda teemat hoitakse alati ajakohasena, st kõik väärtuste muutused kajastuvad seal reaalajas. Kui soovite tellida ainult üksikuid elemente, sisestage soovitud elemendi ID pärast objects_list/.
Märkus. Seda tüüpi tellimine vastab ligikaudu KNX-i tagasisideaadresside taga olevale loogikale; see näitab elementide hetkeolekut ja seda saab kasutada kontrollimaks, kas soovitud muudatused on edukalt rakendatud. Kui soovite andmeid ainult ette lugeda, kuid mitte muuta, piisab seda tüüpi tellimisest .
Üks lihtne element näeb JSON-i tähistuses välja umbes selline
Märkus. Kõikidel väärtustel on ülaltoodud süntaks, nt { “value”: “1” } tellitavate teemade väljundina, samal ajal kui väärtus kirjutatakse väärtuse muutmiseks otse kasulikku koormusse (st avaldatavate teemade puhul) – sulud ja “väärtus” jäetakse välja, nt “onoff”: “1”.
Täpsemad käsud
SISSEJUHATUS
Üldiselt on 3 tüüpi teemasid:
- Tellige teema(d), et näha saadaolevaid elemente ja saada reaalajas väärtusmuudatusi
- Telli teema(d), et saada vastuseid (kliendid ) avaldada taotlusi
- Avaldage teema(d), et hankida või seada elemente nende väärtustega
Hiljem viitame nendele liikidele, kasutades siin näidatud numeratsiooni (nt 1., 2., 3. tüüpi teemad). Lisateavet järgmistes jaotistes ja peatükis. 4.2.
SAADAVALE ELEMENTIDE NÄEKEMISEKS JA VÄÄRTUSE MUUTUSTE SAAMISEKS TELLIGE TEEMAD
Neid on juba kirjeldatud
TELLI TEEMA, ET SAADA VASTUSED KLIENDI AVALDAMISTAOTLUSELE
Seda tüüpi teemad on valikulised. See võimaldab
- avage MQTT-serveriga ainulaadne sidekanal, kasutades suvalist kliendi_id. Lisateavet selle kohta peatükis. 4.2.2
- saada vastava tellimisteema avaldamistaotluste tulemus: õnnestumine või ebaõnnestumine veakoodi ja teatega.
Avaldamiskäskude saamiseks või määramiseks vastuste saamiseks on erinevaid teemasid. Vastav erinevus sisse
Kui olete oma süsteemi jaoks vajalikud teemad selgeks saanud, võite otsustada selle sammu eemaldada ja kasutada otse avaldamise teemasid.
AVALDAGE TEEMASID, ET SAADA VÕI SEADISTADA ELEMENTE NENDE VÄÄRTUSTEGA
Need teemad kasutavad tellimisega sarnast teed – ainus muudatus on tellimisel kasutatud „staatuse” asemel sõna „taotlus”. Täielikud teemateed on näidatud peatükis hiljem. 4.2.2\ Hangi teema küsib MQTT-serveri elementide ja väärtuste lugemist. Kasulikku koormust saab kasutada filtreerimiseks elementide funktsioonitüübi alusel. Määratud teema taotleb elemendi mõningate osade muutmist, nagu on kirjeldatud selle kasulikus koormuses.
KÄSKUDE JA VASTAVATE VASTUSTE EELLIIDE
LÜHISELGITUS
Kõigil MQTT serverile saadetavatel käskudel on ühine algusosa, nimelt:
ÜKSIKASJALIK SELGITUS
Reaalajas teemadel (tüüp 1) on üldine eesliide (vt ülal), millele järgneb
or
Määratud käskude puhul mängib peamist rolli ilmselt kasulik koormus, kuna see sisaldab soovitud muudatusi (st elemendi funktsioonide muudetud väärtusi). Hoiatus. Ärge kunagi kasutage 3. tüüpi käskudes säilitamisvalikut, kuna see võib põhjustada probleeme KNX-i poolel.
EXAMPLE: AVALDAMINE ÜHE ELEMENTI VÄÄRTUSTE MUUTMISEKS
Lihtsaim juhtum on soov muuta ühe elemendi väärtust, mida näitab üldine tellimine.
Üldiselt koosneb VISION-i funktsiooni muutmine/lülitamine MQTT kaudu kolmest sammust, millest kõik pole absoluutselt vajalikud, kuid soovitame siiski teha need kirjeldatud viisil.
- Teema, mis sisaldab funktsiooni, mida tahame muuta, on tellitud kohandatud kliendi_id abil
- Redigeeritav teema avaldatakse koos kasuliku koormusega koos soovitud muudatustega, kasutades punktis 1 valitud kliendi_id.
- Kontrollimiseks näeb siis vastust teemas (1.) – ehk kas (2.) töötas või mitte
- Üldises tellimises, kus muudatuste tegemisel värskendatakse kõiki väärtusi, näete soovitud väärtuse muutust (muudatusi), kui kõik on hästi toiminud.
Selleks on järgmised sammud.
- vali kliendi_id nt “Divus” ja sisesta see API kasutajanime järele teele
See on täielik teema MQTT serveriga oma suhtluskanali tellimiseks. See annab serverile teada, kuhu ootate vastuseid muudatustele, mida kavatsete saata. Pange tähele oleku/komplekti osa, mis määratleb a. et see on tellimise teema ja b. et see saab vastused tüübikäskude määramiseks. - Avaldamise teema jääb samaks, välja arvatud olekupäringu märksõnade vahetamine
- millest muudatus peaks koosnema, on kirjas kasulikus koormuses. Siin on mõned endisedampvähem.
- Sisse/välja funktsiooniga elemendi väljalülitamine (1 bitt):
- Sisse/välja funktsiooniga elemendi sisselülitamine (1 bitt). Lisaks, kui ühest kliendist käivitatakse mitu sellist käsku, saab parameetri määramiseks kasutada uuid parameetrit (“unikaalne ID”, tavaliselt on 128-bitine string, mis on vormindatud 8-4-4-4-12-kohalise kuueteistkümne numbriga). vastuseks vastavale päringule, kuna selle parameetri – kui see päringus on olemas – võib leida ka vastusest.
- Dimmeri sisselülitamine ja heleduse seadmine 50% peale
- Vastus ülaltoodud ja tellitud teemale (täpsemalt selle kandevõimele) on siis näiteksample.
Ülaltoodud vastus on endineample õige kandevõime korral, kuigi elemendil puudub hämardusfunktsioon. Kui esineb tõsisemaid probleeme, mille tõttu kasulikku koormust ei tõlgendata õigesti, näeb vastus välja järgmine (nt:
veakoodide ja teadete selgitamiseks, kuid üldiselt, nagu http puhul, on 200 koodi positiivsed vastused ja 400 negatiivsed.
- Sisse/välja funktsiooniga elemendi väljalülitamine (1 bitt):
EXAMPLE: AVALDA MITME ELEMENTI VÄÄRTUSTE MUUTMISEKS
Üksiku elemendi muutmise protseduur sarnaneb eelnevalt näidatud protseduuriga. Erinevus seisneb selles, et jätate teemadest välja element_id ja seejärel märgite kasuliku koormuse sees olevate andmete ette element_ids komplekti. Vaata süntaksit ja struktuuri allpool.
FILTER PÄRINGUTES FUNKTSIOONI TÜÜBI JÄRGI
Kasuliku koormuse filtrite parameeter võimaldab käsitleda ainult elemendi soovitud funktsiooni (funktsioone). Lüliti või dimmeri sisse/välja funktsiooni nimetatakse "sisselülitamiseks", näiteksample ja vastav filter määratletakse järgmiselt:
Vastus näeb siis välja selline, näiteksample
Ruudusulg näitab, et saate filtreerida ka mitme funktsiooni järgi, nt
viib sellise vastuseni:
Lisa
VIGAKOODID
MQTT-kommunikatsiooni vead põhjustavad numbrikoodi. Järgnev tabel aitab seda lahti võtta.
KASUTUSKOORMUSE PARAMEETRID
Kasulik koormus toetab olenevalt kontekstist erinevaid parameetreid. Järgmises tabelis on näidatud, millised parameetrid millistes teemades esineda võivad
MÄRKUSED VERSIOON
- 1.00 VERSION
Uudised:
• Esimene väljaanne
Dokumendid / Ressursid
 |
DIVUS VISION API tarkvara [pdfKasutusjuhend VISION API tarkvara, API tarkvara, tarkvara |
 |
DIVUS Vision API tarkvara [pdfKasutusjuhend Vision API tarkvara, Vision, API tarkvara, tarkvara |