DIVUS VISION API Software User Manual

DIVUS VISION API Software

Spesifikaasjes

• Produkt: DIVUS VISION API
• Makker: DIVUS GmbH
• Ferzje: 1.00 REV0 1 – 20240528
• Lokaasje: Pillhof 51, Eppan (BZ), Itaalje

Produkt ynformaasje

De DIVUS VISION API is in software-ark ûntworpen foar ynterfacing mei DIVUS VISION-systemen. It lit brûkers tagong krije ta en kontrolearje ferskate eleminten binnen it systeem mei MQTT-protokollen.

FAQ

F: Kin ik de DIVUS VISION API brûke sûnder foarôfgeande kennis fan PC of automatisearringstechnology?

A: De hantlieding is oanpast foar brûkers mei foarige kennis op dizze gebieten om effisjint gebrûk fan 'e API te garandearjen.

ALGEMENE YNFORMAASJE

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

Bedriuwsinstruksjes, hantliedingen en software wurde beskerme troch auteursrjocht. Alle rjochten foarbehâlden. Kopiearjen, duplikearjen, oersetten, oersetten hielendal of foar in part is net tastien. In útsûndering jildt foar it meitsjen fan in reservekopy fan 'e software foar persoanlik gebrûk.
De hânlieding is ûnderwerp te feroarjen sûnder notice. Wy kinne net garandearje dat de gegevens yn dit dokumint en op 'e levere opslachmedia frij binne fan flaters en korrekt binne. Suggestjes foar ferbetteringen lykas oanwizings oer flaters binne altyd wolkom. De ôfspraken jilde ek foar de spesifike bylagen by dit hantlieding. De oantsjuttingen yn dit dokumint kinne hannelsmerken wêze wêrfan it gebrûk troch tredden foar har eigen doelen de rjochten fan har eigners ynbreuk meitsje kin. Brûkersynstruksjes: Lês dizze hantlieding asjebleaft foardat jo it foar it earst brûke en bewarje it op in feilich plak foar takomstige referinsje. Doelgroep: De hânlieding is skreaun foar brûkers mei eardere kennis fan PC en automatisearring technology.

PRESENTASJE KONVENTIONS

Ynlieding

ALGEMENE YNLEIDING

Dizze hantlieding beskriuwt de VISION API (Application Programming Interface) - in ynterface wêrtroch VISION kin wurde oanpakt en kontroleare fan eksterne systemen.
Yn praktyske termen betsjut dit dat jo systemen brûke kinne lykas

• MQTT Explorer (https://www.microsoft.com/store/... – foar testen),
• Home Assistant (https://www.home-assistant.io/) of
• Node-RED (https://nodered.org/)

om de eleminten beheard troch VISION te kontrolearjen of har status út te lêzen. Tagong en kommunikaasje fynt plak fia it MQTT-protokol, dat saneamde ûnderwerpen brûkt om yndividuele funksjes of sets fan funksjes oan te pakken of te ynformearjen oer feroaringen dêryn. In MQTT-tsjinner (broker) wurdt foar dit doel brûkt, dy't de feiligens en it behear / distribúsje fan berjochten oan 'e dielnimmers behannelet. Yn dit gefal leit de MQTT-tsjinner direkt op 'e DIVUS KNX IQ en is spesjaal foar dit doel konfigureare. Hoewol de VISION API kin ek brûkt wurde sûnder programmearkennis, dizze funksjonaliteit is geskikt foar avansearre brûkers.

FEREISTEN

Lykas útlein yn 'e VISION-hantlieding, moat de API-brûker standert earst aktivearre wurde om it te kinnen brûke, wurket de API-tagong allinich mei de autentikaasjegegevens fan Api-brûkers. Wat de brûkersrjochten oanbelanget, kin de aktivearring foar dizze funksjonaliteit dan op alle of op yndividuele eleminten ynsteld wurde. Sjoch Haadstik 0. Fansels hawwe jo ek in VISION-projekt nedich wêryn de eleminten dy't jo fan bûten kontrolearje wolle folslein konfigureare binne en de ferbining dêrmei mei sukses hifke is. Om yndividuele eleminten fia de API oan te pakken, moat har elemint ID bekend wêze: dit wurdt werjûn ûnderoan it ynstellingsformulier fan it elemint

FEILIGENS

Om feiligensredenen is API-tagong allinnich lokaal mooglik (dus net fia de wolk). It feiligensrisiko by it aktivearjen fan API-tagong is dêrom leech. Dochs moatte feiligens-relevante eleminten net ynskeakele of eksplisyt wegere wurde foar API-tagong.

MQTT EN SY BETINGINGEN - KORTE TALEKELING

• Yn MQTT is de rol fan sintralisearre behear en distribúsje fan alle berjochten dy fan 'e brokker. Hoewol't MQTT tsjinner en MQTT makelder binne gjin synonimen (tsjinner is in bredere term foar in rol dy't MQTT kliïnten kinne ek spylje), de makelder wurdt altyd bedoeld yn dizze hânboek doe't MQTT tsjinner wurdt neamd. De DIVUS KNX IQ sels spilet de rol fan MQTT-broker / MQTT-tsjinner yn 'e kontekst fan dizze hantlieding.
• In MQTT-tsjinner brûkt saneamde ûnderwerpen: in hiërargyske struktuer wêrmei't gegevens wurde kategorisearre, beheard en publisearre.
• Publisearjen hat it primêre doel om gegevens beskikber te stellen foar oare dielnimmers fia ûnderwerpen. As jo ​​in wearde feroarje wolle, skriuwe jo tegearre mei de winske weardeferoaring nei it winske ûnderwerp, ek mei in publisearjende aksje. It doelapparaat as de MQTT-tsjinner lêst de winske feroaring dy't it beynfloedet en nimt it dêrmei oan. Om te kontrolearjen dat de wiziging is tapast, kinne jo yn it ynskreaune realtime-ûnderwerp sjen oft de wiziging dêr wjerspegele wurdt - as alles goed wurke is.
• Klanten selektearje de ûnderwerpen dy't har ynteressearje: dit hjit ynskriuwe. Elke kear as in wearde feroaret yn/ûnder in ûnderwerp, wurde alle ynskreaune kliïnten op 'e hichte brocht - dus sûnder dat se eksplisyt moatte freegje oft der wat feroare is of wat de hjoeddeistige wearde is.
• Jo kinne iepenje (of adres) in apart kommunikaasje kanaal mei de MQTT tsjinner troch it ynfieren fan in unike tekenrige neamd client_id yn in ûnderwerp. De client_id moat brûkt wurde yn it ûnderwerp om wearden te ferwurkjen. Dit tsjinnet om de oarsprong fan elke feroaring te identifisearjen, helpt by eventuele flaters en hat gjin ynfloed op de oare kliïnten, om't de korrespondearjende antwurden fan 'e tsjinner, ynklusyf eventuele flaterkoades en berjochten, ek allinich it ûnderwerp berikke mei deselde client_id (en dus allinich dy klant). De client_id is in unike tekenrige besteande út elke kombinaasje fan de tekens 0-9, az, AZ, "-", "_".
• Yn 't algemien befetsje de subscribe-ûnderwerpen fan' e MQTT-tsjinner fan 'e DIVUS KNX IQ de kaaiwurdstatus, wylst de publisearjende ûnderwerpen it trefwurdfersyk befetsje. Dy mei status wurde automatysk bywurke sa gau as der in eksterne wearde feroaring of sa gau as in wearde feroaring is oanfrege troch de klant sels fia in publisearje en is mei súkses tapast. Dy foar it publisearjen binne fierder ferdield yn dy fan type (request/)get en dy fan type (request/)set.
• Wearde feroarings en oare opsjonele parameters wurde tafoege oan it ûnderwerp mei de saneamde payload. De parameters fan 'e yndividuele eleminten (elemint-id, namme, type, funksjes)

It wichtichste ferskil tusken MQTT en it klassike client-server-model, wêrby't de kliïnt gegevens freget en dan feroaret, is sintraal op 'e begripen fan abonnearje en publisearje. Dielnimmers meie gegevens publisearje, dy't beskikber stelle foar oaren, dy't har as ynteresse kinne har ynskriuwe. Dizze arsjitektuer makket it mooglik om gegevens útwikseling te minimalisearjen en dochs alle belangstellenden op 'e hichte te hâlden. Mear oer de details hjir: en spesjale parameters (uuid, filters) moatte hjir brûkt wurde. Hoewol d'r ferskate opsjes binne, wurdt de loadload yn dizze hantlieding opmakke as JSON werjûn. JSON brûkt heakjes en komma's om gegevens fan elke struktuer foar te stellen en sa minimearret de grutte fan 'e gegevenspakketten dy't moatte wurde oerdroegen. Mear details oer payloads kinne letter fûn wurde yn 'e hantlieding.

• Foar spesjale doelen is it mooglik om te filterjen neffens it type funksje, bygelyks om allinich oan/út te adressearjen, dws 1-bit switches. De filterparameter yn 'e lading wurdt foar dit doel brûkt. Filtering is op it stuit allinnich mooglik per funksje type.
• Om yndividuele eleminten oan te pakken, is har elemint ID nedich. Dit is te finen yn VISION yn it elemint eigenskippen menu of kin ek lêzen wurde direkt út de gegevens dy't wurdt werjûn foar elk beskikber elemint yn de algemiene abonnemint fan de MQTT Explorer (eleminten dêr wurde listed alfabetysk troch elemint ID).

Konfiguraasje foar de API tagong

CONFIGURING VISION FOAR API USER TAEGANG

Gean yn VISION as behearder nei Konfiguraasje - Brûkers-/API-tagongsbehear, klikje op Brûkers/API-tagong en klik mei de rjochter-klik op API-brûker (of drukke en hâld) om it bewurkingsfinster te iepenjen. Dêr fine jo dizze parameters en gegevens

• Aktivearje (karkje)
  • De brûker wurdt hjir earst ynskeakele. Standert is útskeakele
• Brûkersnamme
  • Dizze tekenrige is nedich foar tagong fia API - kopiearje it hjirwei
• Wachtwurd
  • Dizze tekenrige is nedich foar tagong fia API - kopiearje it hjirwei
• Permissions
  • De standertrjochten foar it lêzen en skriuwen fan de wearden fan de VISION-eleminten kinne hjir definiearre wurde, dat wol sizze wat hjir definiearre is jildt foar alle besteande en takomstige eleminten. As jo ​​allinich tagong ta yndividuele eleminten tastean wolle, moatte jo dizze standertrjochten net feroarje

Fergunningen ON YNDIVIDUELE ELEMENTEN

It is oan te rieden dat jo gjin API tagong jouwe ta it hiele projekt, mar allinich foar de winske eleminten. Trochgean as folget

1. oanmelde by VISION as behearder
2. selektearje it winske elemint en iepenje it ynstellingsmenu (rjochtsklikke of hâld yndrukt, dan Ynstellings)
3. ûnder it menu-yngong Algemien - Fergunningen, aktivearje "Standert tagongsrjochten oerskriuwe" en gean dan nei it sub-item Fergunningen, dy't de tastimmingsmatrix toant.
4. aktivearje de kontrôle tastimming hjir, dêr't ek mooglik makket de view tastimming direkt. As jo ​​allinne wolle lêze gegevens fia de API tagong, it is genôch om te skeakeljen de view tastimming.
5. werhelje deselde proseduere foar alle eleminten dy't jo tagong wolle

Ferbining fia MQTT

YNLIEDING

As eksample, wy sille demonstrearje tagong fia de MQTT API fan de DIVUS KNX IQ mei in relatyf ienfâldige, frije software neamd MQTT Explorer (sjoch haadstik 1.1), dat is beskikber foar Windows, Mac en Linux. In basiskennis en ûnderfining mei MQTT wurdt ymplisearre.

GEGEVENS FERGESE FOAR DE Ferbining

Lykas earder neamd (sjoch paragraaf 2.1), binne de brûkersnamme en wachtwurd fan 'e API-brûker fereaske. Hjir is in oerview fan alle gegevens dy't moatte wurde sammele foardat in ferbining wurdt makke:

• Brûkersnamme Lês út op 'e detailside fan' e API-brûker
• Wachtwurd Lês út op 'e detailside fan' e API-brûker
• IP-adres Lês út yn 'e launcher ynstellings ûnder Algemien - Netwurk - Ethernet (of fia Synchronizer)
• Port 8884 (dizze haven is reservearre foar dit doel)

EARSTE Ferbining mei MQTT EXPLORER EN ALGEMIEN ABONNJE

Normaal, MQTT ûnderskiedt tusken de aktiviteiten ynskriuwe en publisearje. MQTT Explorer simplifies dit troch automatysk ynskriuwe op alle beskikbere ûnderwerpen (ûnderwerp #) as de earste ferbining wurdt makke. As gefolch, de beam dy't liedt ta alle beskikbere eleminten (dat wol sizze API brûker tagong ferliend) kin sjoen wurde direkt yn de lofterhân gebiet fan de MQTT Explorer finster nei in suksesfolle ferbining. Om fierdere subsydzje-ûnderwerpen yn te fieren of de # te ferfangen troch in mear spesifyk ûnderwerp, gean nei Avansearre yn it ferbiningsfinster. It ûnderwerp werjûn rjochts boppe sjocht der sa út:

wêr 7f4x0607849x444xxx256573x3x9x983 de API-brûkersnamme is en objects_list befettet alle beskikbere eleminten. Dit ûnderwerp wurdt altyd by de tiid hâlden, dws alle weardeferoarings wurde dêr yn real-time wjerspegele. As jo ​​​​allinich wolle abonnearje op yndividuele eleminten, fier dan it elemint ID fan it winske elemint yn nei objects_list/.

Opmerking: dit type abonnemint komt rûchwei oerien mei de logika efter de KNX-feedbackadressen; it toant de aktuele status fan de eleminten en kin brûkt wurde om te kontrolearjen oft de winske wizigingen mei súkses tapast binne. As jo ​​​​allinich gegevens wolle útlêze, mar se net feroarje, is dit type abonnemint genôch.

In inkeld ienfâldich elemint sjocht der sa út yn JSON-notaasje

Opmerking: Alle wearden hawwe de syntaksis werjûn hjirboppe, bygelyks { "wearde": "1" } as de útfier fan 'e abonnemintûnderwerpen, wylst de wearde direkt yn' e lading skreaun wurdt om in wearde te feroarjen (dus foar publisearjen fan ûnderwerpen) - de heakjes en "wearde" wurde weilitten, bygelyks "onoff": "1".

Avansearre kommando's

YNLIEDING

D'r binne yn 't algemien 3 soarten ûnderwerpen:

1. Abonnearje ûnderwerp(en) om de beskikbere eleminten te sjen en wizigingen yn echte tiid te krijen
2. Abonnearje ûnderwerp(en) om de antwurden te krijen op (de kliïnten ) publisearje fersiken
3. Underwerp(en) publisearje om eleminten te krijen of yn te stellen mei har wearden

Wy sille letter nei dizze soarten ferwize mei de hjir te sjen nûmering (bgl. ûnderwerpen fan type 1, 2, 3). Mear details yn 'e folgjende seksjes en yn haadstik. 4.2.

SUBSCRIBE ONDERWERPEN OM DE BESKIKBARE ELEMENTEN TE SJIEN EN REAL-TIME WAARDEFANDERINGEN TE KRIJGEN

Dy binne al beskreaun

SUBSCRIBE ONDERWERPEN OM DE ANTWOORDEN TE KRIJGEN OP DE PUBLISH FAN DE KLIINTEN

Dit soarte fan ûnderwerpen is opsjoneel. It makket it mooglik om

• iepenje in unyk kommunikaasjekanaal mei de MQTT-tsjinner troch in willekeurige client_id te brûken. Dêroer mear yn kap. 4.2.2
• krije it resultaat fan publisearjen fan oanfragen oer it korrespondearjende subsydzjeûnderwerp: súkses as mislearring mei flaterkoade en berjocht.

D'r binne ferskate ûnderwerpen om antwurden te krijen om te krijen of publisearjende kommando's yn te stellen. It oerienkommende ferskil yn Sadree't jo de nedige ûnderwerpen foar jo systeem direkt krije, kinne jo beslute dizze stap te ferwiderjen en publisearje ûnderwerpen direkt te brûken.

 PUBLISH Ûnderwerpen OM TE KRIJGEN OF ELEMENTEN TE SETJE MEI HAR WAARDEN

Dizze ûnderwerpen brûke in paad fergelykber mei dy foar ynskriuwen - de ienige feroaring is it wurd "fersyk" yn plak fan 'e "status" brûkt om yn te abonnearjen. Folsleine ûnderwerppaden wurde letter werjûn yn haadstik. 4.2.2\ In get-ûnderwerp sil freegje om de eleminten en wearden fan de MQTT-tsjinner te lêzen. De lading kin brûkt wurde om te filterjen basearre op it funksjetype fan 'e eleminten. In ynsteld ûnderwerp sil fersykje om guon dielen fan in elemint te feroarjen, lykas detaillearre yn syn payload.

PREFIX FOAR KOMMANDOEN EN oerienkommende RESPONS

 KORTE TALEKELING

Alle kommando's dy't stjoerd wurde nei de MQTT-tsjinner hawwe in mienskiplik earste diel, nammentlik:

DETAILDE TAKELING

De real-time ûnderwerpen (type 1) sille it algemiene foarheaksel hawwe (sjoch hjirboppe) dan folge troch

or

Foar ynstelde kommando's spilet de loadload fansels de haadrol, om't it de winske feroarings sil befetsje (dus feroare wearden foar de funksjes fan it elemint). In warskôging: Brûk de opsje foar behâld nea yn jo type 3-kommando's, om't it problemen kin feroarsaakje oan 'e KNX-kant.

EXAMPLE: PUBLISH FOAR DE WAARDE(S) VAN IN INKEL ELEMENT TE feroarjen

It ienfâldichste gefal is om de wearde te feroarjen fan ien fan 'e eleminten werjûn troch it algemiene abonnemint.
Algemien sprutsen, it feroarjen / wikseljen fan in funksje fan VISION fia MQTT bestiet út 3 stappen, net allegear binne absolút nedich, mar wy riede lykwols oan om se út te fieren lykas beskreaun.

1. It ûnderwerp dat de funksje befettet dy't wy wolle bewurkje, wurdt ynskreaun mei in oanpaste client_id
2. It ûnderwerp foar bewurkjen wurdt publisearre tegearre mei de lading mei de winske feroarings mei de client_id keazen yn 1.
3. Om te kontrolearjen kinne jo dan it antwurd sjen yn ûnderwerp (1.) - dus oft (2.) wurke of net
4. Yn 'e algemiene abonnemint, wêr't alle wearden wurde bywurke as feroarings wurde makke, kinne jo de winske weardeferoaring(en) sjen as alles goed wurke is.

De stappen om dit te dwaan binne:

1. selektearje in client_id bygelyks "Divus" en ynfoegje it yn it paad nei de API brûkersnamme
   Dit is it folsleine ûnderwerp foar it ynskriuwen fan jo eigen kommunikaasjekanaal mei de MQTT-tsjinner. Dit fertelt de tsjinner wêr't jo de antwurden ferwachtsje op 'e wizigingen dy't jo fan doel binne te stjoeren. Merk op it status / set diel dat definiearret a. dat it is in abonnemint ûnderwerp en b. dat it de antwurden sil krije om type kommando's yn te stellen.
2. It publisearjende ûnderwerp sil itselde wêze, útsein foar it wikseljen fan de status-fersyk-kaaiwurden
3. wêrút de wiziging bestean moat, stiet yn de lading skreaun. Hjir binne guon eksamples.
   • In elemint útskeakelje dat de oan/út-funksje hat (1 bit):
   • Ynskeakelje op in elemint dat hat de oan / út funksje (1 bit). Derneist, as ferskate soksoarte kommando's binne begon fan deselde kliïnt, kin de uuid-parameter ("unike ID", is normaal in 128-bit tekenrige opmakke as 8-4-4-4-12 sifers hex) brûkt wurde om de antwurd op de korrespondearjende query, lykas dizze parameter - as oanwêzich yn 'e query - kin ek fûn wurde yn it antwurd.
   • Ynskeakelje en de helderheid fan in dimmer ynstelle op 50%
   • It antwurd op it hjirboppe werjûn en ûndertekene ûnderwerp (syn lading, om krekt te wêzen) is dan bgl.ample.
     It boppesteande antwurd is in eksample yn it gefal fan in korrekte lading, hoewol't it elemint hat gjin dimming funksje. As d'r serieuze problemen binne dy't liede dat de lading net goed ynterpretearre wurdt, sil it antwurd der sa útsjen (bygelyks):
     foar in útlis fan de flater koades en berjochten, mar yn it algemien, lykas foar http, 200 koades binne positive antwurden wylst 400 binne negatyf.

EXAMPLE: PUBLISH FOAR it feroarjen fan meardere eleminten WAARDEN

De proseduere is fergelykber mei de earder werjûn om in inkeld elemint te feroarjen. It ferskil is dat jo it element_id út 'e ûnderwerpen weilitte en dan de set fan element_ids oanjaan foar de gegevens binnen de loadload. Sjoch de syntaksis en struktuer hjirûnder.

FILTERE BY FUNKSJE TYPE YN QUERIES

De filtersparameter yn 'e loadload lit allinich de winske funksje(n) fan in elemint oanpakt wurde. De oan/út-funksje fan in skeakel of dimmer wurdt "oan-út" neamd, bygelyksample, en it oerienkommende filter wurdt op dizze manier definiearre:

It antwurd sjocht der dan sa út, bglample

De fjouwerkante beugel jout oan dat jo ek filterje kinne op ferskate funksjes, bgl

liedt ta in antwurd as dit:

Taheakke

FOUTKODES

Flaters yn MQTT kommunikaasje resultearje yn in numerike koade. De folgjende tabel helpt om it te brekken.

PARAMETERS FAN DE BELASTING

De lading stipet ferskate parameters ôfhinklik fan 'e kontekst. De folgjende tabel lit sjen hokker parameters kinne foarkomme yn hokker ûnderwerpen

VERSJON NOTES

• FERSJE 1.00

Nijs:

• Earste publikaasje