DIVUS VISION API programinė įranga
Specifikacijos
- Produktas: DIVUS VISION API
- Gamintojas: DIVUS GmbH
- Versija: 1.00 REV0 1 – 20240528
- Vieta: Pillhof 51, Eppan (BZ), Italija
Informacija apie produktą
DIVUS VISION API yra programinės įrangos įrankis, skirtas sąsajai su DIVUS VISION sistemomis. Tai leidžia vartotojams pasiekti ir valdyti įvairius sistemos elementus naudojant MQTT protokolus.
DUK
Kl.: Ar galiu naudoti DIVUS VISION API be išankstinių žinių apie asmeninį kompiuterį ar automatikos technologijas?
A: Vadovas pritaikytas naudotojams, turintiems ankstesnių žinių šiose srityse, siekiant užtikrinti efektyvų API naudojimą.
BENDRA INFORMACIJA
- DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – Italija
Naudojimo instrukcijos, vadovai ir programinė įranga yra saugoma autorių teisių. Visos teisės saugomos. Visiškai ar iš dalies kopijuoti, dauginti, versti, versti neleidžiama. Išimtis taikoma atsarginės programinės įrangos kopijos kūrimui asmeniniam naudojimui.
Instrukcija gali būti keičiama be įspėjimo. Negalime garantuoti, kad šiame dokumente ir pateiktose laikmenose esantys duomenys yra be klaidų ir teisingi. Visada laukiami pasiūlymai dėl patobulinimų ir užuominų apie klaidas. Susitarimai taip pat taikomi konkretiems šio vadovo priedams. Šiame dokumente esantys pavadinimai gali būti prekių ženklai, kurių naudojimas trečiosioms šalims savo tikslams gali pažeisti jų savininkų teises. Naudojimo instrukcijos: Prieš naudodami pirmą kartą, perskaitykite šį vadovą ir laikykite jį saugioje vietoje, kad galėtumėte pasinaudoti ateityje. Tikslinė grupė: vadovas skirtas vartotojams, turintiems ankstesnių kompiuterių ir automatikos technologijų žinių.
PRISTATYMO KONVENCIJOS
Įvadas
BENDRASIS ĮVADAS
Šiame vadove aprašoma VISION API (Application Programming Interface) – sąsaja, per kurią VISION galima adresuoti ir valdyti iš išorinių sistemų.
Praktiškai tai reiškia, kad galite naudoti tokias sistemas kaip
- MQTT Explorer (https://www.microsoft.com/store/… – bandymams),
- Namų asistentas (https://www.home-assistant.io/) arba
- Mazgas-RED (https://nodered.org/)
valdyti VISION valdomus elementus arba nuskaityti jų būseną. Prieiga ir bendravimas vyksta per MQTT protokolą, kuriame naudojamos vadinamosios temos, skirtos atskiroms funkcijoms ar funkcijų rinkiniams aptarti arba informuoti apie jų pasikeitimus. Tam naudojamas MQTT serveris (brokeris), kuris rūpinasi saugumu ir pranešimų valdymu/platinimu dalyviams. Šiuo atveju MQTT serveris yra tiesiai ant DIVUS KNX IQ ir yra specialiai tam sukonfigūruotas. Nors VISION API galima naudotis ir be programavimo žinių, ši funkcija tinka pažengusiems vartotojams.
REIKALAVIMAI
Kaip paaiškinta VISION vadove, pagal numatytuosius nustatymus pirmiausia turi būti suaktyvintas API vartotojas, kad galėtų juo naudotis. API prieiga veikia tik naudojant Api naudotojų autentifikavimo duomenis. Kalbant apie vartotojo teises, šios funkcijos aktyvinimas gali būti sukonfigūruotas arba visuose, arba atskiruose elementuose. Žr.0 skyrių. Žinoma, reikalingas ir VISION projektas, kuriame elementai, kuriuos norite valdyti iš išorės, būtų pilnai sukonfigūruoti ir sėkmingai išbandytas ryšys su jais. Kad būtų galima kreiptis į atskirus elementus per API, turi būti žinomas jų elemento ID: jis rodomas elemento nustatymų formos apačioje.
SAUGUMAS
Saugumo sumetimais API prieiga galima tik vietoje (ty ne per debesį). Todėl saugumo rizika aktyvinant API prieigą yra maža. Nepaisant to, su sauga susiję elementai neturėtų būti įjungti arba aiškiai uždrausti pasiekti API.
MQTT IR JO SĄLYGOS – TRUMPAS PAAIŠKINIMAS
MQTT centralizuoto valdymo ir visų pranešimų platinimo vaidmuo yra tarpininko vaidmuo. Nors MQTT serveris ir MQTT brokeris nėra sinonimai (serveris yra platesnis terminas, reiškiantis vaidmenį, kurį gali atlikti ir MQTT klientai), šiame vadove tarpininkas visada turi omenyje, kai minimas MQTT serveris. Pats DIVUS KNX IQ atlieka MQTT brokerio / MQTT serverio vaidmenį šio vadovo kontekste.
MQTT serveryje naudojamos vadinamosios temos: hierarchinė struktūra, pagal kurią duomenys skirstomi į kategorijas, tvarkomi ir skelbiami.
Pagrindinis leidybos tikslas yra padaryti duomenis prieinamus kitiems dalyviams per temas. Jei norite pakeisti reikšmę, į pageidaujamą temą rašote kartu su norimu reikšmės pakeitimu, taip pat naudodami paskelbimo veiksmą. Tikslinis įrenginys arba MQTT serveris nuskaito norimą pakeitimą, kuris jį paveikia, ir atitinkamai jį priima. Norėdami patikrinti, ar pakeitimas pritaikytas, prenumeruojamoje realiojo laiko temoje galite pažiūrėti, ar pakeitimas ten atsispindi – ar viskas pavyko.
Klientai pasirenka juos dominančias temas: tai vadinama prenumerata. Kiekvieną kartą, kai pasikeičia reikšmė temoje/žemiau, visi užsiprenumeravę klientai yra informuojami – ty nereikia aiškiai klausti, ar kažkas pasikeitė, ar kokia yra dabartinė vertė.
Galite atidaryti (arba adresuoti) atskirą ryšio kanalą su MQTT serveriu, temoje įvesdami bet kokią unikalią eilutę, vadinamą client_id. Client_id turi būti naudojamas temoje norint apdoroti reikšmes. Tai padeda nustatyti kiekvieno pakeitimo kilmę, padeda pašalinti klaidas ir neturi įtakos kitiems klientams, nes atitinkami serverio atsakymai, įskaitant klaidų kodus ir pranešimus, temą pasiekia tik su tuo pačiu kliento_id (taigi tik tas klientas). Kliento_id yra unikali simbolių eilutė, kurią sudaro bet koks simbolių derinys nuo 0 iki 9, az, AZ, „-“, „_“.
Paprastai DIVUS KNX IQ MQTT serverio prenumeratos temose yra raktinio žodžio būsena, o publikavimo temose yra raktinio žodžio užklausa. Tie, kurių būsena yra, automatiškai atnaujinami, kai tik įvyksta išorinis vertės pasikeitimas arba kai tik pats klientas paprašo vertės pakeitimo paskelbdamas ir sėkmingai pritaikytas. Skelbtini yra dar skirstomi į tipo (request/)get ir tipo (request/)set.
Reikšmės pakeitimai ir kiti pasirenkami parametrai pridedami prie temos su vadinamuoju naudinguoju krūviu. Atskirų elementų parametrai (element-id, name, type, functions)
Pagrindinis skirtumas tarp MQTT ir klasikinio kliento-serverio modelio, kai klientas prašo ir tada keičia duomenis, yra susijęs su prenumeratos ir paskelbimo sąvokomis. Dalyviai gali skelbti duomenis, sudarydami juos prieinamus kitiems, kurie susidomėję gali juos prenumeruoti. Ši architektūra leidžia sumažinti keitimąsi duomenimis ir vis tiek informuoti visas suinteresuotas šalis. Plačiau apie detales čia: čia turi būti naudojami specialūs parametrai (uuid, filtrai). Nors yra keletas parinkčių, naudingas krovinys šiame vadove rodomas suformatuotas kaip JSON. JSON naudoja skliaustus ir kablelius bet kokios struktūros duomenims pavaizduoti ir taip sumažina perduodamų duomenų paketų dydį. Daugiau informacijos apie naudingus krovinius rasite vėliau vadove.
Specialiems tikslams galima filtruoti pagal funkcijos tipą, pvz., adresuoti tik įjungimo/išjungimo, ty 1 bito jungiklius. Šiuo tikslu naudojamas naudingosios apkrovos filtrų parametras. Filtruoti šiuo metu galima tik pagal funkcijos tipą.
Kad būtų galima kreiptis į atskirus elementus, būtinas jų elemento ID. Tai galima rasti VISION elemento ypatybių meniu arba nuskaityti tiesiogiai iš duomenų, rodomų prieš kiekvieną galimą elementą bendrojoje MQTT Explorer prenumeratos dalyje (ten elementai išvardyti abėcėlės tvarka pagal elemento ID).
API prieigos konfigūracija
API VARTOTOJŲ PRIEIGOS VIZIJOS KONFIGŪRUMAS
VISION kaip administratorius eikite į Konfigūracija – Vartotojo/API prieigos valdymas, spustelėkite Vartotojai/API prieiga ir dešiniuoju pelės mygtuku spustelėkite API naudotoją (arba paspauskite ir palaikykite), kad atidarytumėte redagavimo langą. Ten rasite šiuos parametrus ir duomenis
- Įgalinti (žymimasis laukelis)
- Pirmiausia čia įjungiamas vartotojas. Numatytasis išjungtas
- Vartotojo vardas
- Ši eilutė reikalinga norint pasiekti per API – nukopijuokite ją iš čia
- Slaptažodis
- Ši eilutė reikalinga norint pasiekti per API – nukopijuokite ją iš čia
- Leidimai
- Čia galima apibrėžti numatytąsias VISION elementų reikšmių skaitymo ir rašymo teises, ty tai, kas čia apibrėžta, taikoma visiems esamiems ir būsimiems elementams. Jei norite leisti prieigą tik prie atskirų elementų, neturėtumėte keisti šių numatytųjų teisių
LEIDIMAI DĖL ATSKIRŲ ELEMENTŲ
Rekomenduojama API prieigos nesuteikti visam projektui, o tik norimiems elementams. Tęskite taip
- prisijunkite prie VISION kaip administratorius
- pasirinkite norimą elementą ir atidarykite jo nustatymų meniu (dešiniuoju pelės mygtuku spustelėkite arba laikykite nuspaudę, tada Nustatymai)
- meniu įraše Bendra – Leidimai suaktyvinkite „Nepaisyti numatytųjų leidimų“ ir eikite į antrinį elementą Leidimai, kuriame rodoma leidimų matrica.
- čia suaktyvinkite valdymo leidimą, kuris taip pat įgalina view leidimas tiesiogiai. Jei norite tik skaityti duomenis naudodami API prieigą, pakanka įjungti view leidimas.
- pakartokite tą pačią procedūrą visiems elementams, kuriuos norite pasiekti
Ryšys per MQTT
ĮVADAS
Kaip buvęsample, pademonstruosime prieigą per DIVUS KNX IQ MQTT API su gana paprasta nemokama programine įranga, vadinama MQTT Explorer (žr. 1.1 skyrių), kuri yra prieinama Windows, Mac ir Linux. Numanomos pagrindinės žinios ir patirtis dirbant su MQTT.
PRIJUNGIMUI REIKALINGI DUOMENYS
Kaip minėta anksčiau (žr. 2.1 skyrių), būtinas API vartotojo vartotojo vardas ir slaptažodis. Čia yra pabaigaview visų duomenų, kuriuos reikia surinkti prieš užmezgant ryšį:
- Vartotojo vardas Perskaitykite API naudotojo išsamios informacijos puslapyje
- Slaptažodis Perskaitykite API naudotojo išsamios informacijos puslapyje
- IP adresas Nuskaitykite paleidimo priemonės nustatymuose, skiltyje „Bendra“ – „Tinklas“ – „Ethernet“ (arba per sinchronizatorių)
- Prievadas 8884 (šis prievadas yra rezervuotas šiam tikslui)
PIRMASIS PRISIJUNGIMAS SU MQTT EXPLORER IR BENDRA PRENUMERUOTI
Paprastai MQTT išskiria prenumeratos ir publikavimo veiklą. MQTT Explorer tai supaprastina automatiškai užsiprenumeruodama visas galimas temas (tema #), kai pirmą kartą prisijungiate. Dėl to medis, vedantis į visus galimus elementus (ty suteiktą API vartotojo prieigą), po sėkmingo prisijungimo gali būti matomas tiesiai kairiojoje MQTT Explorer lango srityje. Norėdami įvesti daugiau prenumeratos temų arba pakeisti # konkretesne tema, ryšio lange eikite į Išplėstinė. Viršutiniame dešiniajame kampe rodoma tema atrodo maždaug taip:
kur 7f4x0607849x444xxx256573x3x9x983 yra API naudotojo vardas, o objektų_sąraše yra visi galimi elementai. Ši tema visada atnaujinama, ty bet kokie reikšmių pakeitimai ten atsispindi realiuoju laiku. Jei norite užsiprenumeruoti tik atskirus elementus, po objects_list/ įveskite norimo elemento elemento ID.
Pastaba: šio tipo prenumerata maždaug atitinka KNX grįžtamojo ryšio adresų logiką; ji rodo esamą elementų būseną ir gali būti naudojama norint patikrinti, ar norimi pakeitimai buvo sėkmingai pritaikyti. Jei norite tik nuskaityti duomenis, bet jų nekeisti, užtenka tokio tipo prenumeratos .
Vienas paprastas elementas JSON žymėjime atrodo maždaug taip
Pastaba: visų reikšmių sintaksė yra aukščiau, pvz., { "value": "1" } kaip prenumeruojamų temų išvestis, o reikšmė įrašoma tiesiai į naudingą apkrovą, kad būtų pakeista reikšmė (ty paskelbimo temoms) – skliausteliuose ir „reikšmė“ praleidžiama, pvz., „onoff“: „1“.
Išplėstinės komandos
ĮVADAS
Apskritai yra 3 rūšių temos:
- Prenumeruokite temą (-as), kad pamatytumėte galimus elementus ir gautumėte vertės pokyčius realiuoju laiku
- Prenumeruokite temą (-as), kad gautumėte atsakymus į (klientų ) skelbti užklausas
- Paskelbkite temą (-as), kad gautumėte arba nustatytumėte elementus su jų reikšmėmis
Vėliau šiuos tipus kalbėsime naudodami čia pateiktą numeraciją (pvz., 1, 2, 3 tipo temos). Daugiau informacijos tolesniuose skyriuose ir skyriuje. 4.2.
PRENUMERUOKITE TEMAS, kad pamatytumėte GALIMI ELEMENTUS IR GAUTI VERTĖS POKYČIUS REALIU LAIKU
Jie jau buvo aprašyti
PRENUMERUOKITE TEMAS, KAD GAUTI ATSAKYMUS Į KLIENTO SKELBIMO UŽklausas
Tokios temos yra neprivalomos. Tai leidžia
- atidarykite unikalų ryšio kanalą su MQTT serveriu naudodami savavališką kliento_id. Daugiau apie tai skyriuje. 4.2.2
- gauti paskelbimo užklausų atitinkamoje prenumeratos temoje rezultatą: sėkmė arba nesėkmė su klaidos kodu ir pranešimu.
Yra įvairių temų, kaip gauti atsakymus ir nustatyti paskelbimo komandas. Atitinkamas skirtumas tarp
Kai gausite savo sistemai reikalingas temas, galite nuspręsti pašalinti šį veiksmą ir tiesiogiai naudoti paskelbimo temas.
SKELBTI TEMAS, KAD GAUTI ARBA NUSTATYTI ELEMENTUS SU JŲ VERTYBĖMIS
Šiose temose naudojamas kelias, panašus į prenumeratos kelią – vienintelis pakeitimas yra žodis „užklausa“ vietoj prenumeruojant naudojamo „būsenos“. Išsami temų keliai rodomi vėliau skyriuje. 4.2.2\ Gavimo tema paprašys perskaityti MQTT serverio elementus ir reikšmes. Naudingoji apkrova gali būti naudojama filtruojant pagal elementų funkcijos tipą. Nustatyta tema paprašys pakeisti kai kurias elemento dalis, kaip nurodyta jo naudingojoje apkrovoje.
KOMANDŲ IR ATITINKAMŲ ATSAKYMŲ PREFIDAS
TRUMPAS PAAIŠKINIMAS
Visos komandos, siunčiamos į MQTT serverį, turi bendrą pradinę dalį, būtent:
IŠSAMUS PAAIŠKINIMAS
Realaus laiko temos (1 tipas) turės bendrąjį priešdėlį (žr. aukščiau), po kurio eina
or
Nustatant komandas, naudingoji apkrova, be abejo, atlieka pagrindinį vaidmenį, nes joje bus norimi pakeitimai (ty pakeistos elemento funkcijų reikšmės). A Įspėjimas: Niekada nenaudokite išlaikymo parinkties 3 tipo komandose, nes tai gali sukelti problemų KNX pusėje.
EXAMPLE: SKELBTI, KAD PAKEISTI VIENO ELEMENTO VERTĖ (-ES)
Paprasčiausias atvejis yra noras pakeisti vieno iš elementų, rodomų bendruoju abonementu, reikšmę.
Paprastai tariant, VISION funkcijos keitimas/perjungimas naudojant MQTT susideda iš 3 žingsnių, iš kurių ne visi yra absoliučiai būtini, tačiau rekomenduojame juos atlikti taip, kaip aprašyta.
- Tema, kurioje yra funkcija, kurią norime redaguoti, prenumeruojama naudojant tinkintą kliento_id
- Redaguotina tema skelbiama kartu su naudingu kroviniu su norimais pakeitimais naudojant kliento ID, pasirinktą 1.
- Norėdami patikrinti, galite pamatyti atsakymą temoje (1.) – ty ar (2.) pavyko, ar ne
- Bendrajame prenumerata, kur visos reikšmės atnaujinamos, kai atliekami pakeitimai, galite pamatyti norimą (-us) reikšmės pasikeitimą (-us), jei viskas pavyko gerai.
Veiksmai, kaip tai padaryti, yra šie:
- pasirinkite kliento ID, pvz., „Divus“ ir įterpkite jį į kelią po API vartotojo vardo
Tai yra visa tema, skirta užsiprenumeruoti savo ryšio kanalą su MQTT serveriu. Tai nurodo serveriui, kur tikitės atsakymų į pakeitimus, kuriuos ketinate siųsti. Atkreipkite dėmesį į būsenos / rinkinio dalį, kuri apibrėžia a. kad tai prenumeruojama tema ir b. kad gaus atsakymus į nustatyti tipo komandas. - Paskelbimo tema bus ta pati, išskyrus būsenos užklausos raktinių žodžių perjungimą
- iš ko turėtų sudaryti pakeitimas, parašyta naudingojoje apkrovoje. Štai keletas buvusiųamples.
- Elemento, turinčio įjungimo/išjungimo funkciją, išjungimas (1 bitas):
- Elemento, turinčio įjungimo/išjungimo funkciją, įjungimas (1 bitas). Be to, jei kelios tokios komandos paleidžiamos iš to paties kliento, uuid parametras ("unikalus ID", paprastai yra 128 bitų eilutė, suformatuota kaip 8-4-4-4-12 skaitmenų šešioliktainis) gali būti naudojamas priskirti atsakymas į atitinkamą užklausą, nes šį parametrą – jei yra užklausoje – taip pat galima rasti atsakyme.
- Pritemdiklio įjungimas ir ryškumo nustatymas iki 50 %
- Atsakymas į aukščiau rodomą ir prenumeruojamą temą (tiksliau, jos naudingoji apkrova), pvzample.
Aukščiau pateiktas atsakymas yra buvęsample teisingos naudingosios apkrovos atveju, nors elementas neturi pritemdymo funkcijos. Jei yra rimtesnių problemų, dėl kurių naudingasis krovinys negali būti interpretuojamas teisingai, atsakymas atrodys taip (pvz.,):
klaidų kodų ir pranešimų paaiškinimui, tačiau apskritai, kaip ir http, 200 kodų yra teigiami atsakymai, o 400 – neigiami.
- Elemento, turinčio įjungimo/išjungimo funkciją, išjungimas (1 bitas):
EXAMPLE: SKELBTI, KAD KEIČIUOTI KELIŲ ELEMENTŲ VERTES
Vieno elemento pakeitimo procedūra yra panaši į anksčiau parodytą. Skirtumas yra tas, kad praleidžiate element_id iš temų ir nurodote element_ids rinkinį prieš naudingojo krovinio duomenis. Žemiau žr. sintaksę ir struktūrą.
FILTRAS PAGAL FUNKCIJOS TIPĄ UŽKLAUSOSE
Naudingosios apkrovos filtrų parametras leidžia spręsti tik pageidaujamą (-as) elemento funkciją (-as). Jungiklio arba reguliatoriaus įjungimo/išjungimo funkcija vadinama „įjungimu“, pvzample, o atitinkamas filtras apibrėžiamas taip:
Tada atsakymas atrodo taip, pvzample
Kvadratiniai skliaustai rodo, kad taip pat galite filtruoti pagal kelias funkcijas, pvz
veda prie tokio atsakymo:
Priedas
KLAIDOS KODAI
MQTT ryšio klaidos sukelia skaitmeninį kodą. Toliau pateikta lentelė padeda ją suskaidyti.
NAUDINGOS APkrovos PARAMETRAI
Naudingoji apkrova palaiko skirtingus parametrus, priklausomai nuo konteksto. Toliau pateiktoje lentelėje parodyta, kurie parametrai gali atsirasti konkrečiose temose
VERSIJA PASTABOS
- 1.00 VERSIJA
Naujienos:
• Pirmasis leidinys
Dokumentai / Ištekliai
 |
DIVUS VISION API programinė įranga [pdf] Naudotojo vadovas VISION API programinė įranga, API programinė įranga, programinė įranga |
 |
DIVUS Vision API programinė įranga [pdfVartotojo vadovas Vision API programinė įranga, vizija, API programinė įranga, programinė įranga |