DIVUS VISION API hugbúnaðarhandbók

DIVUS VISION API er hugbúnaðarverkfæri hannað fyrir samskipti við DIVUS VISION kerfi. Það gerir notendum kleift að fá aðgang að og stjórna ýmsum þáttum innan kerfisins með því að nota MQTT samskiptareglur.

Algengar spurningar

Sp.: Get ég notað DIVUS VISION API án fyrri þekkingar á tölvu eða sjálfvirknitækni?

A: Handbókin er sniðin fyrir notendur með fyrri þekkingu á þessum sviðum til að tryggja skilvirka notkun á API.

ALMENNAR UPPLÝSINGAR

DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – Ítalía

Notkunarleiðbeiningar, handbækur og hugbúnaður eru vernduð af höfundarrétti. Allur réttur áskilinn. Óheimilt er að afrita, fjölfalda, þýða, þýða í heild eða að hluta. Undantekning gildir um gerð öryggisafrits af hugbúnaðinum til einkanota.
Handbókin getur breyst án fyrirvara. Við getum ekki ábyrgst að gögnin sem eru í þessu skjali og á meðfylgjandi geymslumiðlum séu villulaus og réttar. Ábendingar um úrbætur sem og ábendingar um villur eru alltaf vel þegnar. Samningarnir eiga einnig við um sérstaka viðauka við þessa handbók. Tilnefningarnar í þessu skjali geta verið vörumerki þar sem notkun þriðju aðila í eigin tilgangi getur brotið gegn réttindum eigenda þeirra. Notendaleiðbeiningar: Vinsamlegast lestu þessa handbók áður en þú notar hana í fyrsta skipti og geymdu hana á öruggum stað til að geta notað hana í framtíðinni. Markhópur: Handbókin er skrifuð fyrir notendur með fyrri þekkingu á tölvu- og sjálfvirknitækni.

KYNNINGARSAMNINGAR

Inngangur

ALMENN KYNNING

Þessi handbók lýsir VISION API (Application Programming Interface) – viðmóti þar sem hægt er að taka á VISION og stjórna frá utanaðkomandi kerfum.
Í raun þýðir þetta að þú getur notað kerfi eins og

MQTT Explorer (https://www.microsoft.com/store/… – til prófunar),

Aðstoðarmaður heima (https://www.home-assistant.io/) eða
Node-RED (https://nodered.org/)

að stjórna þeim þáttum sem VISION stýrir eða lesa upp stöðu þeirra. Aðgangur og samskipti fara fram í gegnum MQTT samskiptareglur, sem notar svokölluð efni til að taka á einstökum aðgerðum eða aðgerðum eða til að fá upplýsingar um breytingar á þeim. Í þessu skyni er notaður MQTT netþjónn (miðlari) sem sér um öryggi og stjórnun/dreifingu skilaboða til þátttakenda. Í þessu tilviki er MQTT þjónninn staðsettur beint á DIVUS KNX IQ og er sérstaklega stilltur fyrir þetta. Þótt VISION API sé einnig hægt að nota án forritunarþekkingar, hentar þessi virkni fyrir lengra komna notendur.

Forsendur

Eins og útskýrt er í VISION handbókinni, verður API notandinn sjálfgefið fyrst að vera virkur til að geta notað hann, API aðgangur virkar aðeins með því að nota auðkenningargögn Api notenda. Að því er varðar notendaréttindi er hægt að stilla virkjunina fyrir þessa virkni annað hvort á öllum eða einstökum þáttum. Sjá kafla 0. Auðvitað þarftu líka VISION verkefni þar sem þættirnir sem þú vilt stjórna utan frá eru fullstilltir og tengingin við þá hefur verið prófuð með góðum árangri. Til að hægt sé að takast á við einstaka þætti í gegnum API verður auðkenni þeirra að vera þekkt: þetta er birt neðst á stillingaformi frumefnisins

ÖRYGGI

Af öryggisástæðum er API aðgangur aðeins mögulegur á staðnum (þ.e. ekki í gegnum skýið). Öryggisáhættan við að virkja API aðgang er því lítil. Engu að síður ætti ekki að virkja þætti sem skipta máli fyrir öryggi eða neita þeim sérstaklega fyrir API aðgang.

MQTT OG SKILMÁLAR ÞESS – STUTTA SKÝRINGAR

Í MQTT er hlutverk miðlægrar stjórnun og dreifingar allra skilaboða hlutverk miðlarans. Þó að MQTT miðlari og MQTT miðlari séu ekki samheiti (miðlari er víðtækara orð yfir hlutverk sem MQTT viðskiptavinir geta líka gegnt) er alltaf átt við miðlarann í þessari handbók þegar minnst er á MQTT miðlara. DIVUS KNX IQ sjálft gegnir hlutverki MQTT miðlara / MQTT miðlara í tengslum við þessa handbók.
MQTT netþjónn notar svokölluð topics: stigveldisskipulag þar sem gögn eru flokkuð, stjórnað og birt.

Útgáfa hefur það meginmarkmið að gera gögn aðgengileg öðrum þátttakendum í gegnum efni. Ef þú vilt breyta gildi, skrifar þú á viðkomandi efni ásamt viðeigandi gildisbreytingu, einnig með útgáfuaðgerð. Marktækið eða MQTT þjónninn les æskilega breytingu sem hefur áhrif á það og samþykkir hana í samræmi við það. Til að ganga úr skugga um að breytingunni hafi verið beitt geturðu skoðað rauntímaþráðinn sem þú ert áskrifandi að til að sjá hvort breytingin endurspeglast þar – hvort allt hafi gengið vel.
Viðskiptavinir velja efni sem vekur áhuga þeirra: þetta er kallað að gerast áskrifandi. Í hvert skipti sem gildi breytist í/undir efni er öllum viðskiptavinum í áskrift upplýst – þ.e. án þess að þurfa að spyrja beinlínis hvort eitthvað hafi breyst eða hvert núverandi gildi er.

Þú getur opnað (eða heimilisfang) sérstaka samskiptarás með MQTT þjóninum með því að slá inn hvaða einstaka streng sem kallast client_id í efni. Nota þarf client_id í umræðuefninu til að vinna úr gildi. Þetta þjónar til að bera kennsl á uppruna hverrar breytingar, hjálpar við allar villur og hefur ekki áhrif á aðra viðskiptavini, þar sem samsvarandi svör frá þjóninum, þar með talið villukóða og skilaboð, ná líka aðeins til umræðuefnisins með sama client_id (og þar með aðeins þann viðskiptavin). Client_id er einstakur stafastrengur sem samanstendur af hvaða samsetningu sem er af stöfunum 0-9, az, AZ, „-“, „_“.
Almennt séð innihalda áskriftarefni MQTT netþjónsins DIVUS KNX IQ lykilorðastöðuna, en birtingarefnin innihalda leitarorðabeiðnina. Þeir sem eru með stöðu eru uppfærðir sjálfkrafa um leið og ytri gildisbreyting verður eða um leið og viðskiptavinurinn sjálfur hefur óskað eftir gildisbreytingu í gegnum útgáfu og hefur verið beitt. Þeim til birtingar er frekar skipt í þær af gerðinni (request/)get og þær af tegundinni (request/)set.

Gildibreytingum og öðrum valkvæðum breytum er bætt við efnið með svokölluðu gagnálagi. Færibreytur einstakra þátta (eindarkenni, nafn, tegund, aðgerðir)

Helsti munurinn á MQTT og klassíska biðlara-miðlara líkaninu, þar sem viðskiptavinurinn biður um og breytir síðan gögnum, snýst um hugtökin að gerast áskrifandi og birta. Þátttakendur geta birt gögn og gera þau aðgengileg öðrum, sem ef áhugi er fyrir hendi geta gerst áskrifandi að þeim. Þessi arkitektúr gerir það mögulegt að lágmarka gagnaskipti og halda samt öllum hagsmunaaðilum uppfærðum. Meira um smáatriðin hér: og sérstakar breytur (uuid, filters) á að nota hér. Þó að það séu nokkrir möguleikar, þá er farmurinn sýndur sem JSON í þessari handbók. JSON notar sviga og kommur til að tákna gögn af hvaða uppbyggingu sem er og lágmarkar þannig stærð gagnapakkana sem á að senda. Frekari upplýsingar um hleðslu er að finna síðar í handbókinni.

Í sérstökum tilgangi er hægt að sía eftir tegund aðgerða, td að taka aðeins á kveikt/slökkt, þ.e. 1-bita rofa. Síufæribreytan í hleðslunni er notuð í þessu skyni. Sía er sem stendur aðeins möguleg eftir aðgerðategund.
Til að geta tekið á einstökum þáttum þarf auðkenni þeirra. Þetta er að finna í VISION í valmynd þáttaeiginleika eða einnig er hægt að lesa það beint úr gögnunum sem birtast fyrir framan hvern tiltækan þátt í almennri áskrift MQTT Explorer (þættir þar eru skráðir í stafrófsröð eftir auðkenni frumeininga).

Stillingar fyrir API aðgang

STILLA SÍN FYRIR API NOTANDA AÐGANG

Í VISION sem stjórnandi, farðu í Configuration – User/API Access Management, smelltu á Users/API access og hægrismelltu á API User (eða haltu inni) til að opna klippigluggann. Þar finnur þú þessar breytur og gögn

Virkja (gátreitur)
- Notandinn er fyrst virkjaður hér. Sjálfgefið er óvirkt
Notandanafn
- Þessi strengur er nauðsynlegur fyrir aðgang í gegnum API - afritaðu hann héðan
Lykilorð
- Þessi strengur er nauðsynlegur fyrir aðgang í gegnum API - afritaðu hann héðan
Heimildir
- Sjálfgefin réttindi til að lesa og skrifa gildi VISION þáttanna er hægt að skilgreina hér, þ.e. það sem er skilgreint hér á við um alla núverandi og framtíðarþætti. Ef þú vilt aðeins leyfa aðgang að einstökum þáttum ættirðu ekki að breyta þessum sjálfgefna réttindum

LEYFI Á EINSTAKUM ÞÁTTUM

Mælt er með því að þú veitir ekki API aðgang að öllu verkefninu, heldur aðeins þeim þáttum sem óskað er eftir. Haltu áfram sem hér segir

skráðu þig inn á VISION sem stjórnandi
veldu viðkomandi þátt og opnaðu stillingavalmyndina (hægrismelltu eða haltu inni, síðan Stillingar)

undir valmyndarfærslunni Almennt – Heimildir, virkjaðu „Hanka sjálfgefnar heimildir“ og farðu síðan í undirliðinn Heimildir, sem sýnir heimildafylki.
virkjaðu stjórnunarheimildina hér, sem gerir einnig kleift view leyfi beint. Ef þú vilt aðeins lesa gögn í gegnum API aðganginn er nóg að virkja view leyfi.
endurtaktu sömu aðferð fyrir alla þá þætti sem þú vilt fá aðgang að

Tenging í gegnum MQTT

INNGANGUR

Sem fyrrverandiample, við munum sýna aðgang í gegnum MQTT API DIVUS KNX IQ með tiltölulega einföldum, ókeypis hugbúnaði sem heitir MQTT Explorer (sjá kafla 1.1), sem er fáanlegur fyrir Windows, Mac og Linux. Grunnþekking og reynsla af MQTT er gefin í skyn.

GÖGN ÞARF FYRIR TENGINGINU

Eins og fyrr segir (sjá kafla 2.1), þarf notandanafn og lykilorð API notanda. Hér er lokiðview af öllum gögnum sem þarf að safna áður en tenging er komið á:

Notandanafn Lesið upp á upplýsingasíðu API notanda
Lykilorð Lesið upp á upplýsingasíðu API notanda

IP tölu Lesið upp í ræsistillingum undir Almennt – Netkerfi – Ethernet (eða í gegnum samstillingu)
Höfn 8884 (þessi höfn er frátekin í þessum tilgangi)

FYRSTA TENGING VIÐ MQTT EXPLORER OG ALMENN ÁSKRIFT

Venjulega gerir MQTT greinarmun á starfseminni sem gerist áskrifandi og birtir. MQTT Explorer einfaldar þetta með því að gerast sjálfkrafa áskrifandi að öllum tiltækum efnisþáttum (efni #) þegar fyrsta tengingin er gerð. Þar af leiðandi er hægt að sjá tréð sem leiðir til allra tiltækra þátta (þ.e. API notendaaðgangur veittur) beint á vinstri svæði MQTT Explorer gluggans eftir árangursríka tengingu. Til að slá inn frekari áskriftarefni eða til að skipta út # fyrir sértækara efni, farðu í Ítarlegt í tengingarglugganum. Efnið sem sýnt er efst til hægri lítur einhvern veginn svona út:

þar sem 7f4x0607849x444xxx256573x3x9x983 er API notendanafnið og objects_list inniheldur alla tiltæka þætti. Þessu efni er alltaf uppfært þ.e. allar gildisbreytingar endurspeglast þar í rauntíma. Ef þú vilt aðeins gerast áskrifandi að einstökum þáttum skaltu slá inn auðkenni þáttar sem óskað er eftir á eftir objects_list/.

Athugið: Þessi tegund áskriftar samsvarar nokkurn veginn rökfræðinni á bak við KNX endurgjöf vistföngin; það sýnir núverandi stöðu þáttanna og má nota til að athuga hvort tilætluðum breytingum hafi tekist. Ef þú vilt aðeins lesa upp gögn en ekki breyta þeim nægir þessi tegund af áskrift .

Einfaldur þáttur lítur svona út í JSON nótnaskrift

Athugið: Öll gildi hafa setningafræðina sem sýnd er hér að ofan, td { “gildi”: “1” } sem úttak áskriftarefnis, á meðan gildið er skrifað beint í hleðsluna til að breyta gildi (þ.e. fyrir birtingarefni) – sviga og „gildi“ er sleppt, td „onoff“: „1“.

Ítarlegar skipanir

INNGANGUR

Það eru 3 tegundir af efni almennt:

Gerast áskrifandi að efni (um) til að sjá tiltæka þætti og fá rauntíma gildisbreytingar
Gerast áskrifandi að efni til að fá svör við (viðskiptavinirnir ) birta beiðnir

Birtu efni til að fá eða stilla þætti með gildum þeirra

Við munum síðar vísa til þessara tegunda með því að nota tölurnar sem sýndar eru hér (td efni af gerðinni 1, 2, 3). Nánari upplýsingar í eftirfarandi köflum og í kap. 4.2.

GERIST Áskrifandi að efni til að sjá tiltæka þætti og fá rauntíma gildisbreytingar

Þessum hefur þegar verið lýst

GERIST Áskrifandi að efni til að FÁ SVAR VIÐ ÚTGÁFU BEÐINUM VIÐSKIPTI

Svona umræðuefni eru valfrjáls. Það leyfir að

opnaðu einstaka samskiptarás við MQTT netþjóninn með því að nota handahófskennt client_id. Nánar um það í kap. 4.2.2
fá niðurstöðu birtingarbeiðna um samsvarandi áskriftarefni: árangur eða mistök með villukóða og skilaboðum.

Það eru mismunandi efni til að fá svör til að fá eða stilla birtingarskipanir. Samsvarandi munur á Þegar þú hefur fengið nauðsynleg efni fyrir kerfið þitt á hreinu gætirðu ákveðið að fjarlægja þetta skref og nota beint birtingarefni.

BILUTA ÞÉR SEM TIL AÐ FÁ EÐA TIL AÐ SETJA ÞATIR MEÐ GILDI SÍN

Þessi efni nota svipaða slóð og þeir fyrir áskrift - eina breytingin er orðið „beiðni“ í stað „stöðu“ sem notuð er til að gerast áskrifandi. Heildar efnisleiðir eru sýndar síðar í kafla. 4.2.2\ Get topic mun biðja um að lesa þætti og gildi MQTT þjónsins. Nota má hleðsluna til að sía út frá aðgerðagerð þáttanna. Ákveðið efni mun biðja um að breyta sumum hlutum þáttar, eins og tilgreint er í hleðslu þess.

FORSKEYTI fyrir skipanir og samsvarandi svör

STUTT SKÝRING

Allar skipanir sem eru sendar á MQTT þjóninn hafa sameiginlegan upphafshluta, þ.e.

ÍTARLEG ÚTSKÝRING

Rauntímaefnin (tegund 1) munu hafa almenna forskeytið (sjá hér að ofan) og síðan fylgt eftir

Fyrir stilltar skipanir gegnir burðargetan augljóslega aðalhlutverkinu þar sem það mun innihalda þær breytingar sem óskað er eftir (þ.e. breytt gildi fyrir aðgerðir frumefnisins). Viðvörun: Notaðu aldrei retain valkostinn í tegund 3 skipunum þínum þar sem það getur valdið vandamálum á KNX hliðinni.

EXAMPLE: PUBLISH TIL AÐ BREYTA GILDUM EINKINS ÞÁTTAR

Einfaldasta tilvikið er að vilja breyta gildi eins af þáttunum sem almennur áskrifandi sýnir.
Almennt séð, að breyta/skipta um fall VISION í gegnum MQTT samanstendur af 3 skrefum, sem ekki eru öll nauðsynleg, en við mælum engu að síður með því að framkvæma þau eins og lýst er.

Efnið sem inniheldur aðgerðina sem við viljum breyta er áskrifandi með því að nota sérsniðið client_id
Efnið til að breyta er birt ásamt farmálaginu með tilætluðum breytingum með því að nota client_id sem valið er í 1.

Til að athuga geturðu síðan séð svarið í efni (1.) – þ.e. hvort (2.) virkaði eða ekki
Í almennu áskriftinni, þar sem öll gildi eru uppfærð þegar breytingar eru gerðar, er hægt að sjá þær gildisbreytingar sem óskað er eftir ef allt hefur gengið vel.

Skrefin til að gera þetta eru:

veldu client_id td „Divus“ og settu það inn í slóðina á eftir API notandanafninu
Þetta er allt efni til að gerast áskrifandi að eigin samskiptarás með MQTT þjóninum. Þetta segir þjóninum hvar þú býst við svörunum við breytingunum sem þú ætlar að senda. Taktu eftir stöðu/sett hlutanum sem skilgreinir a. að það sé áskriftarefni og b. að það fái svör við að stilla tegundarskipanir.
Birtingarefnið verður það sama að því undanskildu að skipta um stöðubeiðnilykilorð
í hverju breytingin á að felast er skrifað í farminn. Hér eru nokkur examples.
- Slökkt á þætti sem hefur kveikt/slökkva aðgerðina (1 biti):
- Kveikt er á þætti sem hefur kveikt/slökkvaaðgerðina (1 bita). Þar að auki, ef nokkrar slíkar skipanir eru ræstar frá sama biðlara, er hægt að nota uuid færibreytuna („einstakt auðkenni“ er venjulega 128 bita strengur sem er sniðinn sem 8-4-4-4-12 tölustafir hex) til að úthluta svar við samsvarandi fyrirspurn, þar sem þessa breytu – ef hún er til staðar í fyrirspurninni – er einnig að finna í svarinu.
- Kveikt á og stillt birtustig dimmer á 50%
- Svarið við efninu sem sýnt er og er áskrifandi að hér að ofan (hagnaður þess, til að vera nákvæmur) er þá td.ample.
  Ofangreint svar er fyrrverandiample ef um er að ræða rétta hleðslu, þó að þátturinn hafi enga dimmuvirkni. Ef það eru alvarlegri vandamál sem leiða til þess að farmið sé ekki túlkað rétt mun svarið líta svona út (td):
  til að útskýra villukóðana og skilaboðin en almennt, eins og fyrir http, eru 200 kóðar jákvæð svör á meðan 400 eru neikvæð.

EXAMPLE: PUBLISH TIL AÐ BREYTA MÖRGUM ÞÁTTUM GILDUM

Aðferðin er svipuð þeirri sem sýnd var áður til að breyta einum þætti. Munurinn er sá að þú sleppir element_id úr efnisatriðum og gefur síðan til kynna mengið element_id fyrir framan gögnin inni í farmloadinu. Sjá setningafræði og uppbyggingu hér að neðan.

SÍA EFTIR AÐGERÐARGERÐ Í FYRIRFRÆÐUR

Síufæribreytan í hleðslunni gerir aðeins kleift að takast á við æskilega aðgerð(ir) þáttar. Kveikja/slökkva aðgerð rofa eða dimmer er kölluð „onoff“, til dæmisample, og samsvarandi sía er skilgreind á þennan hátt:

Svarið lítur þá svona út, tdample

Ferhyrningurinn gefur til kynna að þú getur einnig síað eftir nokkrum aðgerðum, td

leiðir til svars eins og þetta:

Viðauki

VILLAKÓÐAR

Villur í MQTT samskiptum leiða til talnakóða. Eftirfarandi tafla hjálpar til við að sundurliða það.

FRÆÐIR BYLAÐS

Burðargetan styður mismunandi breytur eftir samhengi. Eftirfarandi tafla sýnir hvaða færibreytur geta komið fyrir í hvaða efni

ÚTGÁFUATHUGASEMDIR

Útgáfa 1.00

Fréttir:

• Fyrsta útgáfa

Skjöl / auðlindir

	DIVUS VISION API hugbúnaður [pdfNotendahandbók VISION API hugbúnaður, API hugbúnaður, hugbúnaður
	DIVUS Vision API hugbúnaður [pdfNotendahandbók Vision API hugbúnaður, Vision, API hugbúnaður, hugbúnaður

Heimildir

Notendahandbók

DIVUS VISION API hugbúnaður

Upplýsingar um vöru