DIVUS VISION API softwarearen erabiltzailearen eskuliburua

DIVUS VISION API softwarea

Zehaztapenak

• Produktua: DIVUS VISION API
• Fabrikatzailea: DIVUS GmbH
• Bertsioa: 1.00 REV0 1 – 20240528
• Kokapena: Pillhof 51, Epan (BZ), Italia

Produktuaren informazioa

DIVUS VISION API DIVUS VISION sistemekin konektatzeko diseinatutako software-tresna bat da. Erabiltzaileei MQTT protokoloak erabiliz sistemako hainbat elementu sartzeko eta kontrolatzeko aukera ematen die.

Ohiko galderak

G: Erabili al dezaket DIVUS VISION APIa ordenagailu edo automatizazio teknologiari buruzko ezagutzarik gabe?

E: Eskuliburua arlo hauetan aurretiko ezagutzak dituzten erabiltzaileentzat egokituta dago, APIaren erabilera eraginkorra ziurtatzeko.

INFORMAZIO OROKORRA

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

Funtzionamendu-argibideak, eskuliburuak eta softwarea copyright-aren bidez babestuta daude. Eskubide guztiak erreserbatuak. Ezin da kopiatu, bikoiztu, itzultzea, osorik edo zati batean itzultzea. Salbuespen bat aplikatzen da erabilera pertsonalerako softwarearen babeskopia bat sortzeari.
Eskuliburua abisurik gabe alda daiteke. Ezin dugu bermatu dokumentu honetan eta hornitutako biltegiratze euskarrian dauden datuak akatsik eta zuzenak direnik. Hobekuntza-iradokizunak eta akatsei buruzko aholkuak beti ongi etorriak dira. Akordioak eskuliburu honen berariazko eranskinei ere aplikatzen zaizkie. Dokumentu honetako izendapenak marka komertzialak izan daitezke, hirugarrenek euren helburuetarako erabiltzeak euren jabeen eskubideak urratu ditzaketenak. Erabiltzailearen argibideak: Mesedez, irakurri eskuliburu hau lehen aldiz erabili aurretik eta gorde leku seguru batean etorkizunean erreferentzia izateko. Xede-taldea: eskuliburua ordenagailu eta automatizazio teknologiari buruz aurretiko ezagutzak dituzten erabiltzaileentzat idatzita dago.

AURKEZPEN JARDUNALDIAK

Sarrera

SARRERA OROKORRA

Eskuliburu honek VISION APIa (Application Programming Interface) deskribatzen du - VISION kanpoko sistemetatik zuzendu eta kontrolatu daitekeen interfazea.
Termino praktikoetan, horrek esan nahi du, esaterako, sistemak erabil ditzakezula

• MQTT Explorer (https://www.microsoft.com/store/… – probak egiteko),
• Etxeko Laguntzailea (https://www.home-assistant.io/) edo
• Nodo-GORRIA (https://nodered.org/)

VISIONek kudeatutako elementuak kontrolatzeko edo haien egoera irakurtzeko. Sarbidea eta komunikazioa MQTT protokoloaren bidez egiten da, zeinak gaiak deiturikoak erabiltzen dituen funtzio indibidualak edo funtzio multzoak jorratzeko edo horien aldaketen berri izateko. Horretarako MQTT zerbitzari bat (broker) erabiltzen da, segurtasuna eta parte-hartzaileei mezuen kudeaketa/banatzeaz arduratzen dena. Kasu honetan, MQTT zerbitzaria DIVUS KNX IQ-en zuzenean dago eta horretarako bereziki konfiguratuta dago. VISION APIa programazio ezagutzarik gabe ere erabil daitekeen arren, funtzionalitate hau erabiltzaile aurreratuentzat egokia da.

AURRETIKO

VISION eskuliburuan azaltzen den bezala, lehenik eta behin API erabiltzailea aktibatu egin behar da hura erabili ahal izateko, API sarbideak Api erabiltzaileen autentifikazio-datuak erabiliz soilik funtzionatzen du. Erabiltzaile-eskubideei dagokienez, funtzionalitate horren aktibazioa elementu guztietan edo banakakoetan konfigura daiteke. Ikus 0. kap. Jakina, VISION proiektu bat ere behar duzu, non kanpotik kontrolatu nahi dituzun elementuak guztiz konfiguratuta dauden eta haiekiko konexioa ongi probatu den. APIaren bidez elementu indibidualak zuzendu ahal izateko, haien elementuaren IDa ezagutu behar da: elementuaren ezarpenen inprimakiaren behealdean bistaratzen da.

SEGURTASUNA

Segurtasun arrazoiengatik, API sarbidea lokalean bakarrik da posible (hau da, ez hodei bidez). API sarbidea aktibatzen denean segurtasun arriskua baxua da, beraz. Hala ere, segurtasunerako garrantzitsuak diren elementuak ez dira gaitu edo esplizituki ukatu behar APIrako sarbidea izateko.

MQTT ETA BERE BALDINTZAK – AZALPEN LABURRA

• MQTTn, mezu guztien kudeaketa zentralizatuaren eta banaketaren eginkizuna brokerrena da. MQTT zerbitzaria eta MQTT bitartekaria sinonimoak ez diren arren (zerbitzaria MQTT bezeroek ere jokatu dezaketen rola izendatzeko termino zabalagoa da), eskuliburu honetan artekaria beti esan nahi da MQTT zerbitzaria aipatzen denean. DIVUS KNX IQ-k berak MQTT broker / MQTT zerbitzariaren papera betetzen du eskuliburu honen testuinguruan.
• MQTT zerbitzari batek topics izenekoak erabiltzen ditu: datuak sailkatu, kudeatu eta argitaratzen dituen egitura hierarkikoa.
• Argitalpenak gaien bidez datuak beste partaideen eskura jartzea du helburu nagusia. Balio bat aldatu nahi baduzu, nahi duzun gaira idazten duzu nahi duzun balio-aldaketarekin batera, argitalpen-ekintza bat erabiliz. Helburuko gailuak edo MQTT zerbitzariak eragiten dion aldaketa irakurri eta horren arabera hartzen du. Aldaketa aplikatu dela egiaztatzeko, harpidetutako denbora errealeko gaian begiratu dezakezu aldaketa bertan islatzen den ikusteko, dena ondo atera bada.
• Bezeroek interesatzen zaizkien gaiak hautatzen dituzte: harpidetza deitzen zaio horri. Gai batean/gai baten azpian balio bat aldatzen den bakoitzean, harpidetutako bezero guztiei jakinarazten zaie, hau da, zerbait aldatu den edo egungo balioa zein den esplizituki galdetu beharrik gabe.
• MQTT zerbitzariarekin komunikazio kanal bereizi bat ireki (edo zuzendu) dezakezu gai batean client_id izeneko edozein kate esklusibo idatzita. Gaian bezero_id erabili behar da balioak prozesatzeko. Honek aldaketa bakoitzaren jatorria identifikatzeko balio du, edozein akatsekin laguntzen du eta ez die eragiten gainerako bezeroei, zerbitzariaren erantzunak, errore-kode eta mezuak barne, gaira bezero_id berdinarekin soilik iristen baitira (eta, beraz, soilik). bezero hori). Client_id 0-9, az, AZ, “-“, “_” karaktereen edozein konbinazioz osatutako karaktere-kate bakarra da.
• Oro har, DIVUS KNX IQ-ren MQTT zerbitzariaren harpidetza-gaiek gako-egoera dute, eta argitaratze-gaiek, berriz, gako-eskaera. Egoera dutenak automatikoki eguneratzen dira kanpoko balio-aldaketa bat dagoen bezain laster edo bezeroak berak argitalpen baten bidez balio-aldaketa eskatu eta behar bezala aplikatu bezain laster. Argitaratzekoak (request/)get motakoak eta (request/)set motakoak bereizten dira.
• Balio aldaketak eta aukerako beste parametro batzuk gehitzen zaizkio gaiari karga deritzonarekin. Elementu indibidualen parametroak (element-id, izena, mota, funtzioak)

MQTT eta bezero-zerbitzari eredu klasikoaren arteko desberdintasun nagusia, non bezeroak datuak eskatu eta gero aldatzen dituena, harpidetza eta argitaratze kontzeptuetan oinarritzen da. Parte-hartzaileek datuak argitaratu ahal izango dituzte, beste batzuen eskura jarriz, eta interesa izanez gero harpidetu ahal izango dute. Arkitektura honek datu-trukea minimizatzea eta interesdun guztiak eguneratuta mantentzea ahalbidetzen du. Xehetasunei buruz gehiago hemen: eta parametro bereziak (uuid, iragazkiak) hemen erabili behar dira. Hainbat aukera egon arren, eskuliburu honetan JSON moduan formateatutako karga erabilgarria agertzen da. JSONek kortxeteak eta komak erabiltzen ditu edozein egituratako datuak irudikatzeko eta, horrela, transmititu beharreko datu-paketeen tamaina murrizten du. Kargei buruzko xehetasun gehiago eskuliburuan aurki daitezke.

• Xede berezietarako, funtzio motaren arabera iragazi daiteke, adibidez, aktibatu/desaktibatu bakarrik zuzentzea, hau da, biteko etengailuak. Horretarako kargako iragazkien parametroa erabiltzen da. Funtzio motaren arabera soilik iragaztea posible da.
• Elementu indibidualak zuzendu ahal izateko, haien elementuaren IDa beharrezkoa da. Elementuaren propietateen menuan VISION-en aurki daiteke edo MQTT Explorer-en harpidetza orokorrean eskuragarri dauden elementu bakoitzaren aurrean bistaratzen diren datuetatik zuzenean irakur daiteke (elementuak alfabetikoki zerrendatuta daude elementu IDaren arabera).

APIrako sarbidearen konfigurazioa

API ERABILTZAILEEN SARBIDEKO IKUSMENA KONFIGURATZEA

VISION-en administratzaile gisa, joan Konfigurazioa - Erabiltzaile/API Sarbideen Kudeaketa, egin klik Erabiltzaileak/API sarbidean eta egin klik eskuineko botoiarekin API Erabiltzailean (edo eduki sakatuta) editatzeko leihoa irekitzeko. Bertan aurkituko dituzu parametro eta datu hauek

• Gaitu (kontrol-laukia)
  • Erabiltzailea lehenik hemen gaituta dago. Lehenetsia desgaituta dago
• Erabiltzaile izena
  • Kate hau beharrezkoa da API bidez sartzeko; kopiatu hemendik
• Pasahitza
  • Kate hau beharrezkoa da API bidez sartzeko; kopiatu hemendik
• Baimenak
  • VISION elementuen balioak irakurtzeko eta idazteko lehenetsitako eskubideak hemen defini daitezke, hau da, hemen definitutakoak dauden eta etorkizuneko elementu guztiei aplikatzen zaie. Elementu indibidualetarako sarbidea bakarrik baimendu nahi baduzu, ez dituzu lehenetsitako eskubide hauek aldatu behar

ELEMENTU BANAKAKO BAIMENAK

Gomendagarria da ez ematea proiektu osorako APIrako sarbidea, nahi diren elementuei baizik. Jarraitu honela

1. hasi saioa VISION-en administratzaile gisa
2. hautatu nahi duzun elementua eta ireki bere ezarpenen menua (egin klik eskuineko botoiarekin edo mantendu sakatuta, gero Ezarpenak)
3. menuko Orokorra - Baimenak atalean, aktibatu "Gaiztu baimenak lehenetsiak" eta, ondoren, joan Baimenak azpi-elementura, baimenen matrizea erakusten duena.
4. aktibatu hemen kontrol-baimena, eta horrek ere gaitzen du view baimena zuzenean. API sarbidearen bidez datuak soilik irakurri nahi badituzu, nahikoa da gaitzea view baimena.
5. errepikatu prozedura bera sartu nahi dituzun elementu guztietan

MQTT bidezko konexioa

SARRERA

Example, DIVUS KNX IQ-ren MQTT APIaren bidez sarbidea erakutsiko dugu MQTT Explorer izeneko software nahiko sinple eta doako batekin (ikus 1.1. kap.), Windows, Mac eta Linuxentzat eskuragarri dagoena. MQTT-rekin oinarrizko ezagutza eta esperientzia bat inplikatuta dago.

KONEXIOA EGITEKO BEHARREZKO DATUAK

Lehen esan bezala (ikus 2.1 atala), API erabiltzailearen erabiltzaile-izena eta pasahitza beharrezkoak dira. Hona hemen amaiera batview Konexioa ezarri aurretik bildu behar diren datu guztien artean:

• Erabiltzaile-izena Irakurri API erabiltzailearen xehetasun-orrian
• Pasahitza Irakurri API erabiltzailearen xehetasun-orrian
• IP helbidea Irakurri abiarazlearen ezarpenetan Orokorra - Sarea - Ethernet (edo sinkronizatzaile bidez)
• 8884 portua (portu hau horretarako gordeta dago)

MQTT EXPLORERAREKIN LEHENENGO KONEXIOA ETA HARPIDETZA OROKORRA

Normalean, MQTT-k harpidetza eta argitaratze jarduerak bereizten ditu. MQTT Explorer-ek hori errazten du, lehen konexioa egiten denean eskuragarri dauden gai guztietara automatikoki harpidetuz (# gaia). Ondorioz, erabilgarri dauden elementu guztietara eramaten duen zuhaitza (hau da, API erabiltzaileen sarbidea eman zaio) zuzenean ikus daiteke MQTT Explorer leihoaren ezkerreko eremuan konektatu ondoren. Harpidetza-gai gehiago sartzeko edo # gai zehatzago batekin ordezkatzeko, joan Aurreratua atalera konexio-leihoan. Goiko eskuinaldean agertzen den gaiak honelako itxura du:

non 7f4x0607849x444xxx256573x3x9x983 da API erabiltzaile-izena eta objects_list eskuragarri dauden elementu guztiak ditu. Gai hau beti eguneratuta dago, hau da, edozein balio-aldaketa denbora errealean islatzen da. Elementu indibidualetara soilik harpidetu nahi baduzu, idatzi nahi duzun elementuaren IDa objektuak_zerrenda/ ondoren.

Oharra: harpidetza mota hau gutxi gorabehera KNX feedback helbideen atzean dagoen logikarekin bat dator; elementuen uneko egoera erakusten du eta nahi diren aldaketak behar bezala aplikatu diren egiaztatzeko erabil daiteke. Datuak bakarrik irakurri nahi badituzu baina aldatu ez badituzu, nahikoa da harpidetza mota hau.

Elementu sinple bakar batek antzeko zerbait du JSON idazkeran

Oharra: balio guztiek goian agertzen den sintaxia dute, adibidez, { “balioa”: “1” } harpidetza-gaien irteera gisa, eta balioa kargan zuzenean idazten den bitartean balio bat aldatzeko (hau da, gaiak argitaratzeko) – parentesiak eta “balioa” baztertzen da, adibidez, “onoff”: “1”.

Komando aurreratuak

SARRERA

3 gai mota daude orokorrean:

1. Harpidetu gaia(k) erabilgarri dauden elementuak ikusteko eta denbora errealeko balio-aldaketak lortzeko
2. Harpidetu gaia(k) erantzunak jasotzeko (bezeroak ) eskaerak argitaratzea
3. Argitaratu gaia(k) elementuak beren balioekin lortzeko edo ezartzeko

Aurrerago mota hauei erreferentzia egingo diegu hemen agertzen den zenbakia erabiliz (adibidez, 1, 2, 3 motako gaiak). Xehetasun gehiago hurrengo ataletan eta kap. 4.2.

HARPIDETU GAIAK ESKURAGARRIKO ELEMENTUAK IKUSTEKO ETA BALIO-ALDAKETAK ERABILERA LORTZEKO

Hauek dagoeneko deskribatu dira

HARPIDETU GAIAK BEZEROAREN ARGITALPEN ESKUEREN ERANTZUNAK LORTZEKO

Gai mota hau hautazkoa da. ahalbidetzen du

• ireki MQTT zerbitzariarekin komunikazio kanal esklusibo bat client_id arbitrarioa erabiliz. Horri buruz gehiago kap. 4.2.2
• lortu dagokion harpidetza-gaiari buruzko argitaratze-eskaeren emaitza: arrakasta edo porrota errore-kode eta mezuarekin.

Hainbat gai daude erantzunak lortzeko edo argitaratzeko aginduak ezartzeko. Dagokion aldea Zure sistemarako beharrezko gaiak zuzen jasotzen dituzunean, urrats hau kentzea erabaki dezakezu eta zuzenean argitaratzeko gaiak erabiltzea.

 BALIOEKIN ELEMENTUAK LORTZEKO EDO EZARTZEKO GAIAK ARGITARATZEA

Gai hauek harpidetzeko moduko bide bat erabiltzen dute; aldaketa bakarra "eskaera" hitza da harpidetzeko erabiltzen den "egoera"ren ordez. Gaiaren bide osoak geroago erakusten dira kap. 4.2.2\ Get gai batek MQTT zerbitzariaren elementuak eta balioak irakurtzea eskatuko du. Karga erabilgarria elementuen funtzio motaren arabera iragazteko erabil daiteke. Ezarritako gai batek elementu baten atal batzuk aldatzeko eskatuko du, bere kargan zehazten den moduan.

KOMANDUEN ETA DAGOZION ERANTZUNEN AURRIFIXOA

 AZALPEN LABURRA

MQTT zerbitzarira bidaltzen diren komando guztiek hasierako zati komun bat dute, hau da:

AZALPEN ZEHATZA

Denbora errealeko gaiek (1 mota) aurrizki orokorra izango dute (ikus goian) eta ondoren

or

Ezarri komandoetarako, karga kargak paper nagusia betetzen du, nahi diren aldaketak (hau da, elementuaren funtzioetarako balioak aldatuak) edukiko dituelako. Abisua: ez erabili inoiz gordetzeko aukera zure 3 motako komandoetan, KNX aldean arazoak sor ditzakeelako.

EXAMPLE: ELEMENTU BAKARREN BALIOA(K) ALDATZEKO ARGITARATZEA

Kasurik errazena harpidetza orokorrak erakusten duen elementuetako baten balioa aldatu nahi izatea da.
Oro har, MQTT bidez VISION-en funtzio bat aldatzea/aldatzeak 3 urrats ditu, guztiak ez dira guztiz beharrezkoak, baina hala ere deskribatutako moduan egitea gomendatzen dugu.

1. Editatu nahi dugun funtzioa duen gaia bezero_id pertsonalizatua erabiliz harpidetuta dago
2. Editatzeko gaia kargarekin batera argitaratzen da nahi diren aldaketekin batera 1. atalean aukeratutako client_id erabiliz.
3. Egiaztatzeko, (1.) gaian erantzuna ikus dezakezu, hau da, (2.) funtzionatu duen ala ez.
4. Harpidetza orokorrean, non balio guztiak eguneratzen diren aldaketak egiten direnean, nahi dituzun balio-aldaketak ikus ditzakezu, dena ondo joan bada.

Horretarako urratsak hauek dira:

1. hautatu client_id bat, adibidez, "Divus" eta txertatu API erabiltzaile-izenaren ondoko bidean
   Hau da MQTT zerbitzariarekin zure komunikazio kanalera harpidetzeko gai osoa. Honek zerbitzariari bidali nahi dituzun aldaketen erantzunak non espero dituzun esaten dio. Kontuan izan a definitzen duen egoera/multzoaren zatia. harpidedun gaia dela eta b. motako komandoak ezartzeko erantzunak jasoko dituela.
2. Argitaratzeko gaia bera izango da egoera-eskaera gako-hitzak aldatzea izan ezik
3. aldaketak zertan izan behar duen idatzita dago kargan. Hona hemen examples.
   • On/off funtzioa duen elementu bat itzaltzea (bit 1):
   • On/off funtzioa duen elementu bat piztea (1 bit). Horrez gain, bezero beretik horrelako hainbat komando abiarazten badira, uuid parametroa ("ID bakarra", normalean 128-8-4-4-4 digituko hex formatua den 12 biteko katea da) erabil daiteke esleitzeko. dagokion kontsultari erantzuna, parametro hau –kontsultan badago– erantzunean ere aurki baitaiteke.
   • Dimmer baten distira piztea eta %50ean ezartzea
   • Goian erakutsitako eta harpidetutako gaiaren erantzuna (bere karga, zehatz esateko) da, adibidezample.
     Goiko erantzuna adibide bat daample karga zuzenaren kasuan, elementuak iluntzeko funtziorik ez duen arren. Arazo larriagoak badaude karga behar bezala ez interpretatzeko, erantzuna honela izango da (adibidez):
     errore-kodeen eta mezuen azalpenerako baina, oro har, http-rako bezala, 200 kodeak erantzun positiboak dira eta 400 negatiboak.

EXAMPLE: ELEMENTU ANITZAK BALIOAK ALDATZEKO ARGITARATZEA

Prozedura elementu bakar bat aldatzeko lehen erakutsitakoaren antzekoa da. Ezberdintasuna da gaietatik elementu_id-a baztertzen duzula eta, ondoren, elementu_id-en multzoa kargaren barruan dauden datuen aurrean adierazten duzula. Ikus behean sintaxia eta egitura.

IRAGARZI FUNTZIO MOTAREN ARABERA KONTSULTETAN

Kargako iragazkien parametroak elementu baten nahi diren funtzioak soilik bideratzeko aukera ematen du. Etengailu edo dimmer baten pizteko/itzaltzeko funtzioari "onoff" deitzen zaio, adibidezample, eta dagokion iragazkia honela definitzen da:

Erantzuna honelakoa da, adibidezample

Kortxeteek hainbat funtzioren arabera iragaz dezakezula adierazten dute, adibidez

honelako erantzuna dakar:

eranskina

AKATS KODEAK

MQTT komunikazioan akatsek zenbakizko kode bat sortzen dute. Ondorengo taulak apurtzen laguntzen du.

ORDAINAREN PARAMETROAK

Zamak parametro desberdinak onartzen ditu testuinguruaren arabera. Hurrengo taulak zein parametro zein gaitan gerta daitezkeen erakusten du

BERTSIO OHARRAK

• BIZI 1.00

Berriak:

• Lehen argitalpena