Manyèl Itilizatè lojisyèl DIVUS VISION API

DIVUS VISION API se yon zouti lojisyèl ki fèt pou entèfas ak sistèm DIVUS VISION. Li pèmèt itilizatè yo jwenn aksè ak kontwole divès eleman nan sistèm nan lè l sèvi avèk pwotokòl MQTT.

FAQ

K: Èske mwen ka itilize DIVUS VISION API a san mwen pa konnen alavans PC oswa teknoloji automatisation?

A: Manyèl la pwepare pou itilizatè ki gen konesans anvan nan domèn sa yo pou asire itilizasyon efikas API a.

ENFÒMASYON JENERAL

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

Enstriksyon operasyon, manyèl ak lojisyèl yo pwoteje pa copyright. Tout dwa rezève. Kopi, kopi, tradui, tradui an antye oswa an pati pa pèmèt. Yon eksepsyon aplike nan kreyasyon yon kopi backup nan lojisyèl an pou itilizasyon pèsonèl.
Manyèl la ka chanje san avètisman. Nou pa ka garanti ke done ki genyen nan dokiman sa a ak sou medya depo yo bay yo pa gen erè epi yo kòrèk. Sijesyon pou amelyorasyon ak sijesyon sou erè yo toujou akeyi. Akò yo aplike tou pou anèks espesifik nan manyèl sa a. Deziyasyon yo nan dokiman sa a ka mak komèsyal ki itilize pa twazyèm pati pou pwòp rezon yo ka vyole dwa pwopriyetè yo. Enstriksyon itilizatè: Tanpri li manyèl sa a anvan ou itilize li pou premye fwa epi kenbe li nan yon kote ki an sekirite pou referans nan lavni. Gwoup sib: Manyèl la ekri pou itilizatè ki gen konesans anvan sou PC ak teknoloji automatisation.

KONVANSYON PREZANTASYON

Entwodiksyon

ENTWODIKSYON JENERAL

Manyèl sa a dekri VISION API (Application Programming Interface) - yon koòdone nan ki VISION ka adrese ak kontwole nan sistèm ekstèn.
An tèm pratik, sa vle di ke ou ka itilize sistèm tankou

MQTT Explorer (https://www.microsoft.com/store/… – pou tès),

Asistan Lakay (https://www.home-assistant.io/) oswa
Node-RED (https://nodered.org/)

kontwole eleman ki jere pa VISION oswa li estati yo. Aksè ak kominikasyon fèt atravè pwotokòl MQTT, ki sèvi ak sa yo rele sijè pou adrese fonksyon endividyèl oswa ansanm fonksyon oswa pou enfòme sou chanjman nan yo. Yo itilize yon sèvè MQTT (koutye) pou objektif sa a, ki okipe sekirite ak jesyon/distribisyon mesaj bay patisipan yo. Nan ka sa a, sèvè MQTT la sitiye dirèkteman sou DIVUS KNX IQ a epi li se espesyalman konfigirasyon pou objektif sa a. Malgre ke VISION API a ka itilize tou san yo pa konnen pwogramasyon, fonksyonalite sa a apwopriye pou itilizatè avanse.

KONDISYON

Jan yo eksplike sa nan manyèl VISION la, itilizatè API a dwe aktive an premye pou yo ka itilize li aksè API sèlman ap travay lè l sèvi avèk done otantifikasyon itilizatè Api yo. Osi lwen ke dwa itilizatè yo konsène, aktivasyon an pou fonksyonalite sa a ka Lè sa a, dwe configuré swa sou tout oswa sou eleman endividyèl yo. Gade Chap.0. Natirèlman, ou bezwen tou yon pwojè VISION nan ki eleman yo ke ou vle kontwole soti nan deyò yo konplètman configuré ak koneksyon an yo te avèk siksè teste. Pou kapab adrese eleman endividyèl yo atravè API a, yo dwe konnen ID eleman yo: sa a parèt nan pati anba fòm paramèt eleman yo.

SEKIRITE

Pou rezon sekirite, aksè API se sèlman posib lokalman (sa vle di pa atravè nwaj la). Risk sekirite a lè aktive aksè API se poutèt sa ba. Men, eleman ki enpòtan pou sekirite yo pa ta dwe aktive oswa refize klèman pou aksè API.

MQTT AK KONDISYON LI A – BÈT EKKSPLIKASYON

Nan MQTT, wòl nan jesyon santralize ak distribisyon tout mesaj se sa ki nan koutye a. Malgre ke sèvè MQTT ak koutye MQTT yo pa sinonim (sèvè se yon tèm pi laj pou yon wòl ke kliyan MQTT ka jwe tou), koutye a toujou vle di nan manyèl sa a lè yo mansyone sèvè MQTT. DIVUS KNX IQ tèt li jwe wòl koutye MQTT / sèvè MQTT nan kontèks manyèl sa a.
Yon sèvè MQTT sèvi ak sa yo rele sijè: yon estrikti yerarchize ak ki done yo klase, jere ak pibliye.

Piblikasyon gen objektif prensipal pou fè done disponib pou lòt patisipan yo atravè sijè. Si ou vle chanje yon valè, ou ekri nan sijè a vle ansanm ak chanjman valè a vle, tou lè l sèvi avèk yon aksyon piblikasyon. Aparèy la sib oswa sèvè MQTT la li chanjman an vle ki afekte li epi li adopte li kòmsadwa. Pou tcheke si chanjman an te aplike, ou ka gade nan sijè abònman an tan reyèl pou wè si chanjman an reflete la - si tout bagay te mache byen.
Kliyan yo chwazi sijè ki enterese yo: yo rele sa abònman. Chak fwa yon valè chanje nan/anba yon sijè, tout kliyan abònman yo enfòme - sa vle di san yo pa oblije mande klèman si yon bagay te chanje oswa ki valè aktyèl la.

Ou ka ouvri (oswa adrese) yon kanal kominikasyon separe ak sèvè MQTT la lè w antre nan nenpòt kòd inik ki rele client_id nan yon sijè. Client_id dwe itilize nan sijè a pou trete valè yo. Sa a sèvi yo idantifye orijin nan chak chanjman, ede ak nenpòt erè epi yo pa afekte lòt kliyan yo, kòm repons ki koresponn yo soti nan sèvè a, ki gen ladan nenpòt kòd erè ak mesaj, tou sèlman rive nan sijè a ak menm client_id la (e konsa sèlman kliyan sa a). Client_id la se yon seri karaktè inik ki fòme ak nenpòt konbinezon karaktè 0-9, az, AZ, "-", "_".
An jeneral, sijè abònman nan sèvè MQTT nan DIVUS KNX IQ a gen estati mo kle a, pandan y ap sijè yo pibliye gen demann mo kle a. Moun ki gen estati yo otomatikman mete ajou le pli vit ke gen yon chanjman valè ekstèn oswa le pli vit ke yon chanjman valè te mande pa kliyan an li menm atravè yon pibliye epi li te aplike avèk siksè. Sa yo ki pou pibliye yo plis divize an sa yo ki nan kalite (demann /) jwenn ak sa yo ki nan kalite (demann /) mete.

Chanjman valè ak lòt paramèt opsyonèl yo ajoute nan sijè a ak sa yo rele chaj la. Paramèt eleman endividyèl yo (eleman-id, non, kalite, fonksyon)

Diferans prensipal ant MQTT ak modèl klasik kliyan-sèvè a, kote kliyan an mande epi chanje done yo, konsantre sou konsèp abònman ak pibliye. Patisipan yo ka pibliye done, fè yo disponib pou lòt moun, ki moun ki si enterese ka abònman ak li. Achitekti sa a fè li posib pou minimize echanj done epi toujou kenbe tout pati ki enterese yo ajou. Plis sou detay yo isit la: ak paramèt espesyal (uuid, filtè) yo dwe itilize isit la. Malgre ke gen plizyè opsyon, chaj la yo montre fòma kòm JSON nan manyèl sa a. JSON sèvi ak parantèz ak vigil pou reprezante done nenpòt estrikti epi konsa minimize gwosè pake done yo dwe transmèt. Ou ka jwenn plis detay sou chaj yo pita nan manyèl la.

Pou rezon espesyal, li posib pou filtre selon kalite fonksyon, pa egzanp pou adrese sèlman on/off, sa vle di switch 1-bit. Se paramèt filtè ki nan chaj la itilize pou objektif sa a. Kounye a, filtraj posib sèlman selon kalite fonksyon.
Pou kapab adrese eleman endividyèl yo, se ID eleman yo obligatwa. Ou ka jwenn sa a nan VISION nan meni pwopriyete eleman oswa ou ka li tou dirèkteman nan done ki parèt devan chak eleman ki disponib nan abònman jeneral nan MQTT Explorer a (eleman yo gen nan lis alfabetik pa ID eleman).

Konfigirasyon pou aksè a API

Konfigirasyon vizyon pou aksè itilizatè API

Nan VISION kòm yon administratè, ale nan Konfigirasyon - Itilizatè/Jesyon Aksè API, klike sou Itilizatè/Aksè API epi klike sou dwa-klike sou Itilizatè API (oswa peze epi kenbe) pou ouvri fenèt koreksyon an. La w ap jwenn paramèt ak done sa yo

Pèmèt (kaz)
- Itilizatè a premye pèmèt isit la. Default se enfim
Non itilizatè
- Se fisèl sa a obligatwa pou aksè atravè API - kopye li soti isit la
Modpas
- Se fisèl sa a obligatwa pou aksè atravè API - kopye li soti isit la
Otorizasyon
- Dwa default pou lekti ak ekri valè eleman VISION yo ka defini isit la, sa vle di sa ki defini la a aplike a tout eleman ki deja egziste ak nan lavni. Si ou vle sèlman pèmèt aksè nan eleman endividyèl yo, ou pa ta dwe chanje dwa default sa yo

OMISYON SOU ELEMENT ENDIVIDYEL

Li rekòmande pou ou pa bay API aksè a tout pwojè a, men sèlman nan eleman yo vle. Kontinye jan sa a

konekte nan VISION kòm yon administratè
chwazi eleman vle a epi ouvri meni anviwònman li yo (klike sou dwa oswa kenbe peze, Lè sa a, Anviwònman)

Anba meni an Jeneral - Otorizasyon, aktive "Anlanse otorizasyon default" ak Lè sa a, ale nan sub-atik Otorizasyon, ki montre matris la otorizasyon.
aktive pèmisyon kontwòl isit la, ki pèmèt tou view pèmisyon dirèkteman. Si ou vle sèlman li done atravè aksè API a, li ase pou pèmèt view pèmisyon.
repete menm pwosedi a pou tout eleman ou vle jwenn aksè

Koneksyon atravè MQTT

ENTWODIKSYON

Kòm yon ansyenample, nou pral demontre aksè atravè API MQTT nan DIVUS KNX IQ a ak yon relativman senp, lojisyèl gratis ki rele MQTT Explorer (gade chap. 1.1), ki disponib pou Windows, Mac ak Linux. Yon konesans debaz ak eksperyans ak MQTT enplike.

DONE OBLIJE POU KONEKSYON AN

Kòm mansyone pi bonè (gade seksyon 2.1), non itilizatè a ak modpas itilizatè API a obligatwa. Isit la se yon finiview nan tout done ki dwe kolekte anvan yon koneksyon etabli:

Non itilizatè Li sou paj detay itilizatè API a
Modpas Li sou paj detay itilizatè API a

Adrès IP Li nan paramèt lans yo anba Jeneral - Rezo - Ethernet (oswa atravè Synchronizer)
Port 8884 (pò sa a rezève pou objektif sa a)

PREMYE KONEKSYON AK MQTT EXPLORER AK Abònman JENERAL

Nòmalman, MQTT fè distenksyon ant aktivite yo abònman ak pibliye. MQTT Explorer senplifye sa a pa otomatikman abònman nan tout sijè ki disponib (sijè #) lè premye koneksyon an fèt. Kòm yon rezilta, pye bwa a ki mennen nan tout eleman ki disponib (sa vle di aksè itilizatè API akòde) ka wè dirèkteman nan zòn gòch la nan fenèt MQTT Explorer apre yon koneksyon siksè. Pou antre plis sijè abònman oswa ranplase # a ak yon sijè ki pi espesifik, ale nan Avanse nan fenèt koneksyon an. Sijè yo montre sou bò dwat anwo a sanble yon bagay tankou sa a:

kote 7f4x0607849x444xxx256573x3x9x983 se non itilizatè API a ak objects_list gen tout eleman ki disponib yo. Sijè sa a toujou kenbe ajou sa vle di nenpòt chanjman valè yo reflete la an tan reyèl. Si ou vle sèlman abònman nan eleman endividyèl yo, antre ID eleman nan eleman vle a apre objects_list/.

Remak: Kalite abònman sa a apeprè koresponn ak lojik ki dèyè adrès fidbak KNX yo; li montre estati aktyèl la nan eleman yo epi yo ka itilize yo tcheke si chanjman yo vle yo te aplike avèk siksè. Si ou vle sèlman li done men ou pa chanje yo, kalite abònman sa a ase.

Yon sèl eleman senp sanble yon bagay tankou sa a nan notasyon JSON

Remak: Tout valè yo gen sentaks yo montre pi wo a egzanp { "valè": "1" } kòm pwodiksyon sijè abònman yo, pandan y ap valè a ekri dirèkteman nan chaj la pou chanje yon valè (sa vle di pou pibliye sijè) - parantèz yo ak "valè" yo omisyon egzanp "onoff": "1".

Kòmandman avanse

ENTWODIKSYON

Gen 3 kalite sijè an jeneral:

Abònman sijè (yo) pou wè eleman ki disponib yo epi pou jwenn chanjman valè an tan reyèl
Abònman sijè (yo) pou jwenn repons pou (kliyan yo ) pibliye demann yo

Pibliye sijè (yo) pou jwenn oswa pou mete eleman ak valè yo

Nou pral refere pita nan kalite sa yo lè l sèvi avèk nimero yo montre isit la (egzanp sijè ki nan kalite 1, 2, 3). Plis detay nan seksyon sa yo ak nan chap. 4.2.

ABONNE SIJÈ POU WÈ Eleman ki disponib yo epi pou w jwenn CHANJMAN VALÈ A TAN REYÈL

Sa yo te deja dekri

ABONE SIJÈ POU JWENN REPONS POU DEMANN PIBLIKE KLIYAN AN

Kalite sijè sa a opsyonèl. Li pèmèt

ouvri yon kanal kominikasyon inik ak sèvè MQTT la lè l sèvi avèk yon client_id abitrè. Plis sou sa nan chap. 4.2.2
jwenn rezilta a nan pibliye demann sou sijè a abònman korespondan: siksè oswa echèk ak kòd erè ak mesaj.

Gen diferan sijè pou jwenn repons pou jwenn oswa pou mete kòmandman pibliye. Diferans ki koresponn lan nan Yon fwa ou jwenn sijè ki nesesè pou sistèm ou an tou dwat, ou ka deside retire etap sa a epi itilize dirèkteman sijè pibliye.

PILIYE SIJÈ POU JWENN OSWA POU METE ELEMENT AK VALÈ YO

Sijè sa yo itilize yon chemen ki sanble ak sa yo pou abònman - chanjman nan sèlman se mo "demann" nan plas "estati" yo itilize abònman. Chemen sijè konplè yo montre pita nan chap. 4.2.2\ Yon sijè get pral mande pou li eleman ak valè sèvè MQTT la. Yo ka itilize chaj la pou filtre dapre kalite fonksyon eleman yo. Yon sijè seri pral mande pou chanje kèk pati nan yon eleman, jan sa detaye nan chaj li yo.

PREFIKS POU KÒMAND AK REPONS KORESPONDAN

KOUT EKKSPLIKASYON

Tout kòmandman yo voye bay sèvè MQTT la gen yon pati inisyal komen, sètadi:

EKSPLIKASYON DETAYE

Sijè yo an tan reyèl (kalite 1) pral gen prefiks jeneral la (gade pi wo a) epi swiv pa

Pou kòmandman mete, chaj la evidamman jwe wòl prensipal la paske li pral genyen chanjman yo vle (sa vle di valè chanje pou fonksyon eleman an). Yon avètisman: Pa janm sèvi ak opsyon kenbe nan kòmandman tip 3 ou yo paske li ka lakòz pwoblèm sou bò KNX.

EXAMPLE: PIBLYE POU CHANJE VALÈ YON SEL Eleman

Ka ki pi senp la se vle chanje valè youn nan eleman yo montre nan abònman jeneral la.
Anjeneral pale, chanje/chanje yon fonksyon VISION atravè MQTT konsiste de 3 etap, se pa tout nan yo ki absoliman nesesè, men nou sepandan rekòmande pote yo soti jan sa dekri.

Sijè a ki gen fonksyon nou vle edite a abònman lè l sèvi avèk yon client_id koutim
Sijè a pou koreksyon pibliye ansanm ak chaj la ak chanjman yo vle lè l sèvi avèk client_id la chwazi nan 1.

Pou tcheke, ou ka wè repons lan nan sijè (1.) - sa vle di si (2.) te travay oswa ou pa
Nan abònman jeneral la, kote tout valè yo mete ajou lè chanjman yo fèt, ou ka wè chanjman valè vle a (yo) si tout bagay te mache byen.

Etap yo pou fè sa yo se:

chwazi yon client_id egzanp "Divus" epi mete li nan chemen an apre non itilizatè API a
Sa a se sijè konplè pou abònman nan pwòp chanèl kominikasyon ou ak sèvè MQTT la. Sa a di sèvè a ki kote ou espere repons a chanjman ou gen entansyon voye yo. Remake estati/ansanm pati ki defini a. ke li se yon sijè abònman ak b. ke li pral jwenn repons yo mete kòmandman kalite.
Sijè piblikasyon an ap menm eksepte pou chanje mo kle demann estati yo
kisa chanjman an ta dwe konpoze ekri nan chaj la. Men kèk ansyenamples.
- Etenn yon eleman ki gen fonksyon on/off (1 bit):
- Chanje sou yon eleman ki gen fonksyon on/off (1 bit). Anplis de sa, si plizyè kòmandman sa yo te kòmanse nan menm kliyan an, paramèt uuid ("ID inik", se nòmalman yon fisèl 128-bit fòma kòm 8-4-4-4-12 chif hex) ka itilize repons a rechèch korespondan an, kòm paramèt sa a - si prezan nan rechèch la - ka jwenn tou nan repons lan.
- Chanje sou ak mete klète yon gradateur a 50%
- Repons lan nan sijè ki montre ak abònman pi wo a (chaj li yo, yo dwe egzak) se lè sa a, pou egzanpample.
  Repons ki anwo a se yon ansyenample nan ka a nan yon chaj ki kòrèk, byenke eleman nan pa gen okenn fonksyon gradyasyon. Si gen pwoblèm ki pi grav ki fè chaj la pa entèprete kòrèkteman, repons lan ap parèt tankou sa a (egzanp):
  pou yon eksplikasyon sou kòd erè yo ak mesaj men an jeneral, tankou pou http, 200 kòd yo se repons pozitif pandan y ap 400 yo negatif.

EXAMPLE: PIBLYE POU CHANJE VALÈ ELEMENT MILTIPL

Pwosedi a sanble ak sa yo montre anvan pou chanje yon sèl eleman. Diferans lan se ke ou soti element_id nan sijè yo epi Lè sa a, endike seri a nan element_ids devan done yo andedan chaj la. Gade sentaks ak estrikti ki anba a.

FILTRE PAR TAP FONCTION NAN KÈT

Paramèt filtè yo nan chaj la pèmèt sèlman fonksyon an vle (yo) nan yon eleman yo dwe adrese. Fonksyon on/off yon switch oswa gradateur yo rele "onoff", pou egzanpample, ak filtè ki koresponn lan defini nan fason sa a:

Lè sa a, repons lan sanble tankou sa a, pou egzanpample

Parantèz kare a endike ke ou ka filtre tou pa plizyè fonksyon, pa egzanp

mennen nan yon repons tankou sa a:

Apendis

KODD ERÈ

Erè nan kominikasyon MQTT lakòz yon kòd nimerik. Tablo ki anba la a ede kraze li.

PARAMÈT CHAJ LA

Chaj la sipòte paramèt diferan depann sou kontèks la. Tablo ki anba la a montre ki paramèt ka rive nan ki sijè

NÒT VÈSYON

VÈSYON 1.00

Nouvèl:

• Premye piblikasyon

Dokiman / Resous

	DIVUS VISION API lojisyèl [pdfManyèl Itilizatè VISION API lojisyèl, API lojisyèl, lojisyèl
	DIVUS Vision API lojisyèl [pdfGid Itilizatè Vizyon API lojisyèl, Vizyon, API lojisyèl, lojisyèl

Referans

Manyèl itilizatè

DIVUS VISION API lojisyèl

Enfòmasyon sou pwodwi

FAQ