DIVUS VISION API sagteware gebruikershandleiding

DIVUS VISION API sagteware

Spesifikasies

• Produk: DIVUS VISION API
• Vervaardiger: DIVUS GmbH
• Weergawe: 1.00 REV0 1 – 20240528
• Plek: Pillhof 51, Eppan (BZ), Italië

Produk inligting

Die DIVUS VISION API is 'n sagteware-instrument wat ontwerp is vir skakeling met DIVUS VISION-stelsels. Dit laat gebruikers toe om toegang tot verskeie elemente binne die stelsel te verkry en te beheer deur MQTT-protokolle te gebruik.

Gereelde vrae

V: Kan ek die DIVUS VISION API gebruik sonder vooraf kennis van rekenaar of outomatiseringstegnologie?

A: Die handleiding is aangepas vir gebruikers met vorige kennis op hierdie gebiede om doeltreffende gebruik van die API te verseker.

ALGEMENE INLIGTING

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

Bedryfsinstruksies, handleidings en sagteware word deur kopiereg beskerm. Alle regte voorbehou. Kopiëring, duplisering, vertaling, geheel of gedeeltelik vertaal word nie toegelaat nie. 'n Uitsondering is van toepassing op die skep van 'n rugsteunkopie van die sagteware vir persoonlike gebruik.
Die handleiding is onderhewig aan verandering sonder kennisgewing. Ons kan nie waarborg dat die data vervat in hierdie dokument en op die stoormedia wat verskaf word, vry van foute en korrek is nie. Voorstelle vir verbeterings sowel as wenke oor foute is altyd welkom. Die ooreenkomste is ook van toepassing op die spesifieke aanhangsels tot hierdie handleiding. Die benamings in hierdie dokument kan handelsmerke wees waarvan die gebruik deur derde partye vir hul eie doeleindes die regte van hul eienaars kan skend. Gebruikersinstruksies: Lees asseblief hierdie handleiding voordat u dit vir die eerste keer gebruik en hou dit op 'n veilige plek vir toekomstige verwysing. Teikengroep: Die handleiding is geskryf vir gebruikers met vorige kennis van rekenaar- en outomatiseringstegnologie.

AANBIEDINGSKONVENSIES

Inleiding

ALGEMENE INLEIDING

Hierdie handleiding beskryf die VISION API (Application Programming Interface) – 'n koppelvlak waardeur VISION vanaf eksterne stelsels aangespreek en beheer kan word.
In praktiese terme beteken dit dat jy stelsels soos bv

• MQTT Explorer (https://www.microsoft.com/store/... – vir toetsing),
• Huisassistent (https://www.home-assistant.io/) of
• Node-RED (https://nodered.org/)

om die elemente wat deur VISION bestuur word te beheer of hul status uit te lees. Toegang en kommunikasie vind plaas via die MQTT-protokol, wat sogenaamde onderwerpe gebruik om individuele funksies of stelle funksies aan te spreek of om ingelig te word oor veranderinge daaraan. 'n MQTT-bediener (makelaar) word vir hierdie doel gebruik, wat sekuriteit en die bestuur/verspreiding van boodskappe aan die deelnemers hanteer. In hierdie geval is die MQTT-bediener direk op die DIVUS KNX IQ geleë en is spesiaal vir hierdie doel gekonfigureer. Alhoewel die VISION API ook sonder programmeringskennis gebruik kan word, is hierdie funksionaliteit geskik vir gevorderde gebruikers.

VOORVEREISTES

Soos verduidelik in die VISION-handleiding, moet die API-gebruiker by verstek eers geaktiveer word om dit te kan gebruik, die API-toegang werk slegs met behulp van die Api-gebruikers-verifikasiedata. Wat die gebruikersregte betref, kan die aktivering vir hierdie funksionaliteit dan op alle of op individuele elemente gekonfigureer word. Sien hfst.0. U het natuurlik ook 'n VISION-projek nodig waarin die elemente wat u van buite wil beheer volledig gekonfigureer is en die verbinding daarmee suksesvol getoets is. Om individuele elemente via die API te kan aanspreek, moet hul element-ID bekend wees: dit word onderaan die element se instellingsvorm vertoon

SEKURITEIT

Om sekuriteitsredes is API-toegang slegs plaaslik moontlik (dus nie via die wolk nie). Die sekuriteitsrisiko wanneer API-toegang geaktiveer word, is dus laag. Nietemin moet sekuriteitsrelevante elemente nie vir API-toegang geaktiveer of uitdruklik geweier word nie.

MQTT EN SY BEPALINGS – KORT VERDUIDELIKING

• In MQTT is die rol van gesentraliseerde bestuur en verspreiding van alle boodskappe dié van die makelaar. Alhoewel MQTT-bediener en MQTT-makelaar nie sinonieme is nie (bediener is 'n breër term vir 'n rol wat MQTT-kliënte ook kan speel), word die makelaar altyd in hierdie handleiding bedoel wanneer MQTT-bediener genoem word. Die DIVUS KNX IQ self speel die MQTT makelaar / MQTT bediener rol in die konteks van hierdie handleiding.
• 'n MQTT-bediener gebruik sogenaamde onderwerpe: 'n hiërargiese struktuur waarmee data gekategoriseer, bestuur en gepubliseer word.
• Publisering het die primêre doel om data deur middel van onderwerpe aan ander deelnemers beskikbaar te stel. As jy 'n waarde wil verander, skryf jy na die verlangde onderwerp saam met die verlangde waardeverandering, ook deur 'n publiseeraksie te gebruik. Die teikentoestel of die MQTT-bediener lees die gewenste verandering wat dit raak en neem dit dienooreenkomstig aan. Om seker te maak dat die verandering toegepas is, kan jy in die ingetekende intydse onderwerp kyk om te sien of die verandering daar weerspieël word – of alles goed uitgewerk het.
• Kliënte kies die onderwerpe wat hulle interesseer: dit word inteken genoem. Elke keer as 'n waarde in/onder 'n onderwerp verander, word alle ingetekende kliënte ingelig – maw sonder om uitdruklik te vra of iets verander het of wat die huidige waarde is.
• Jy kan 'n aparte kommunikasiekanaal met die MQTT-bediener oopmaak (of aanspreek) deur enige unieke string genaamd client_id in 'n onderwerp in te voer. Die client_id moet in die onderwerp gebruik word om waardes te verwerk. Dit dien om die oorsprong van elke verandering te identifiseer, help met enige foute en beïnvloed nie die ander kliënte nie, aangesien die ooreenstemmende antwoorde van die bediener, insluitend enige foutkodes en boodskappe, ook net die onderwerp met dieselfde client_id bereik (en dus slegs daardie kliënt). Die client_id is 'n unieke karakterstring wat bestaan ​​uit enige kombinasie van die karakters 0-9, az, AZ, "-", "_".
• Oor die algemeen bevat die intekenonderwerpe van die MQTT-bediener van die DIVUS KNX IQ die sleutelwoordstatus, terwyl die publiseeronderwerpe die sleutelwoordversoek bevat. Diegene met status word outomaties opgedateer sodra daar 'n eksterne waardeverandering is of sodra 'n waardeverandering deur die kliënt self via 'n publiseer versoek is en suksesvol toegepas is. Dié vir publisering word verder verdeel in dié van tipe (versoek/)get en dié van tipe (versoek/)stel.
• Waardeveranderinge en ander opsionele parameters word by die onderwerp gevoeg met die sogenaamde loonvrag. Die parameters van die individuele elemente (element-id, naam, tipe, funksies)

Die belangrikste verskil tussen MQTT en die klassieke kliënt-bediener-model, waar die kliënt data versoek en dan verander, is gesentreer op die konsepte van inteken en publiseer. Deelnemers kan data publiseer, wat dit beskikbaar stel aan ander, wat indien belangstel daarop kan inteken. Hierdie argitektuur maak dit moontlik om data-uitruiling te minimaliseer en steeds alle belangstellendes op datum te hou. Meer oor die besonderhede hier: en spesiale parameters (uuid, filters) moet hier gebruik word. Alhoewel daar verskeie opsies is, word die loonvrag geformateer as JSON in hierdie handleiding gewys. JSON gebruik hakies en kommas om data van enige struktuur voor te stel en verminder dus die grootte van die datapakkies wat versend moet word. Meer besonderhede oor loonvragte kan later in die handleiding gevind word.

• Vir spesiale doeleindes is dit moontlik om volgens die tipe funksie te filter, bv om slegs aan/af aan te spreek, dws 1-bis skakelaars. Die filters parameter in die loonvrag word vir hierdie doel gebruik. Filtrering is tans slegs moontlik volgens funksietipe.
• Om individuele elemente te kan aanspreek, word hul element-ID vereis. Dit kan gevind word in VISION in die elementeienskappe-kieslys of kan ook direk gelees word vanaf die data wat voor elke beskikbare element in die algemene inteken van die MQTT Explorer vertoon word (elemente daar word alfabeties volgens element-ID gelys).

Opstelling vir die API-toegang

KONFIGUREER VISIE VIR API-GEBRUIKERSTOEGANG

Gaan in VISION as administrateur na Configuration – User/API Access Management, klik op Users/API access en regskliek op API User (of druk en hou) om die redigeringsvenster oop te maak. Daar sal jy hierdie parameters en data vind

• Aktiveer (merkblokkie)
  • Die gebruiker word eers hier geaktiveer. Verstek is gedeaktiveer
• Gebruikersnaam
  • Hierdie string word benodig vir toegang via API – kopieer dit van hier af
• Wagwoord
  • Hierdie string word benodig vir toegang via API – kopieer dit van hier af
• Toestemmings
  • Die verstekregte vir die lees en skryf van die waardes van die VISIE-elemente kan hier gedefinieer word, dws wat hier gedefinieer word, is van toepassing op alle bestaande en toekomstige elemente. As jy net toegang tot individuele elemente wil toelaat, moet jy nie hierdie verstekregte verander nie

TOESTEMMINGS OP INDIVIDUELE ELEMENTE

Dit word aanbeveel dat u nie API-toegang tot die hele projek verleen nie, maar slegs tot die verlangde elemente. Gaan soos volg voort

1. teken aan by VISION as 'n administrateur
2. kies die gewenste element en maak sy instellingskieslys oop (regskliek of hou ingedruk, dan Instellings)
3. onder die kieslysinskrywing Algemeen – Toestemmings, aktiveer “Oorslaan verstektoestemmings” en gaan dan na die subitem Toestemmings, wat die toestemmingsmatriks wys.
4. aktiveer die beheertoestemming hier, wat ook die view toestemming direk. As jy net data via die API-toegang wil lees, is dit voldoende om die view toestemming.
5. herhaal dieselfde prosedure vir al die elemente waartoe jy toegang wil hê

Verbinding via MQTT

INLEIDING

As eksample, sal ons toegang demonstreer via die MQTT API van die DIVUS KNX IQ met 'n relatief eenvoudige, gratis sagteware genaamd MQTT Explorer (sien hoofstuk 1.1), wat beskikbaar is vir Windows, Mac en Linux. 'n Basiese kennis en ervaring met MQTT word geïmpliseer.

DATA BENODIG VIR DIE VERBINDING

Soos vroeër genoem (sien afdeling 2.1), word die gebruikersnaam en wagwoord van die API-gebruiker vereis. Hier is 'n verbyview van al die data wat ingesamel moet word voordat 'n verbinding tot stand gebring word:

• Gebruikersnaam Lees uit op die besonderhedebladsy van die API-gebruiker
• Wagwoord Lees uit op die besonderhedebladsy van die API-gebruiker
• IP-adres Lees uit in die lanseerderinstellings onder Algemeen – Netwerk – Ethernet (of via Synchronizer)
• Port 8884 (hierdie hawe is vir hierdie doel gereserveer)

EERSTE VERBINDING MET MQTT EXPLORER EN ALGEMENE TEKEN IN

Normaalweg onderskei MQTT tussen die aktiwiteite wat inteken en publiseer. MQTT Explorer vereenvoudig dit deur outomaties in te teken op alle beskikbare onderwerpe (onderwerp #) wanneer die eerste verbinding gemaak word. Gevolglik kan die boom wat na alle beskikbare elemente lei (dws API-gebruikertoegang toegestaan) direk in die linkerkantse area van die MQTT Explorer-venster gesien word na 'n suksesvolle verbinding. Om verdere intekenonderwerpe in te voer of om die # met 'n meer spesifieke onderwerp te vervang, gaan na Gevorderd in die verbindingsvenster. Die onderwerp wat regs bo gewys word, lyk iets soos volg:

waar 7f4x0607849x444xxx256573x3x9x983 die API-gebruikernaam is en objects_list bevat al die beskikbare elemente. Hierdie onderwerp word altyd op datum gehou, maw enige waardeveranderings word intyds daar weerspieël. As jy net op individuele elemente wil inteken, voer die element-ID van die verlangde element in na objects_list/.

Let wel: Hierdie tipe inteken stem min of meer ooreen met die logika agter die KNX-terugvoeradresse; dit wys die huidige status van die elemente en kan gebruik word om te kontroleer of die verlangde veranderinge suksesvol toegepas is. As jy net data wil uitlees, maar dit nie wil verander nie, is hierdie tipe intekening voldoende.

'n Enkele eenvoudige element lyk so in JSON-notasie

Let wel: Alle waardes het die sintaksis wat hierbo gewys word, bv. { “waarde”: “1” } as die uitvoer van die intekenonderwerpe, terwyl die waarde direk in die loonvrag geskryf word om 'n waarde te verander (dws vir publiseer onderwerpe) – die hakies en “waarde” word weggelaat, bv. “aan af”: “1”.

Gevorderde opdragte

INLEIDING

Daar is 3 soorte onderwerpe oor die algemeen:

1. Teken in op onderwerp(e) om die beskikbare elemente te sien en om intydse waardeveranderings te kry
2. Teken in onderwerp(e) om die antwoorde te kry op (die kliënte ) publiseer versoeke
3. Publiseer onderwerp(e) om te kry of om elemente met hul waardes te stel

Ons sal later na hierdie soorte verwys deur die nommering hier te gebruik (bv. onderwerpe van tipe 1, 2, 3). Meer besonderhede in die volgende afdelings en in hfst. 4.2.

TEKEN IN ONDERWERPE OM DIE BESKIKBARE ELEMENTE TE SIEN EN OM INRE TYDSE WAARDEVERANDERINGE TE KRY

Hierdie is reeds beskryf

TEKEN IN ONDERWERPE OM DIE ANTWOORDE VIR DIE KLIËNT SE PUBLISE VERSOEKES TE KRY

Hierdie soort onderwerpe is opsioneel. Dit laat toe om

• maak 'n unieke kommunikasiekanaal met die MQTT-bediener oop deur 'n arbitrêre client_id te gebruik. Meer daaroor in hfst. 4.2.2
• kry die resultaat van publiseerversoeke oor die ooreenstemmende intekenonderwerp: sukses of mislukking met foutkode en boodskap.

Daar is verskillende onderwerpe om antwoorde te kry om te kry of om publiseeropdragte in te stel. Die ooreenstemmende verskil in Sodra jy die nodige onderwerpe vir jou stelsel reguit gekry het, kan jy besluit om hierdie stap te verwyder en publiseer onderwerpe direk te gebruik.

 PUBLISEER ONDERWERPE OM TE KRY OF OM ELEMENTE MET HUL WAARDES TE STEL

Hierdie onderwerpe gebruik 'n pad soortgelyk aan dié om in te teken - die enigste verandering is die woord "versoek" in die plek van die "status" wat gebruik word om in te teken. Volledige onderwerppaaie word later in hfst. 4.2.2\ 'n Get-onderwerp sal versoek om die MQTT-bediener se elemente en waardes te lees. Die loonvrag kan gebruik word om te filter gebaseer op die funksie tipe van die elemente. 'n Vasgestelde onderwerp sal versoek om sommige dele van 'n element te verander, soos uiteengesit in sy loonvrag.

VOORVOGSEL VIR OPDRAGTE EN OOREENSTEMMENDE ANTWOORDE

 KORT VERDUIDELIKING

Alle opdragte wat na die MQTT-bediener gestuur word, het 'n gemeenskaplike aanvanklike deel, naamlik:

GEDETAILLEERDE VERDUIDELIKING

Die intydse onderwerpe (tipe 1) sal die algemene voorvoegsel hê (sien hierbo) dan gevolg deur

or

Vir stel opdragte speel die loonvrag natuurlik die hoofrol aangesien dit die verlangde veranderinge sal bevat (dws veranderde waardes vir die element se funksies). 'n Waarskuwing: Moet nooit die behou-opsie in jou tipe 3-opdragte gebruik nie, aangesien dit probleme aan die KNX-kant kan veroorsaak.

EXAMPLE: PUBLISE VIR DIE VERANDERING VAN 'N ENKEL ELEMENT SE WAARDE(S)

Die eenvoudigste geval is om die waarde van een van die elemente wat deur die algemene inteken gewys word, te wil verander.
Oor die algemeen bestaan ​​die verandering/omskakeling van 'n funksie van VISION via MQTT uit 3 stappe, wat nie almal absoluut noodsaaklik is nie, maar ons beveel nietemin aan om dit uit te voer soos beskryf.

1. Die onderwerp wat die funksie bevat wat ons wil wysig, word ingeteken deur gebruik te maak van 'n persoonlike client_id
2. Die onderwerp vir redigering word saam met die loonvrag gepubliseer met die verlangde veranderinge deur gebruik te maak van die client_id wat in 1 gekies is.
3. Om na te gaan, kan jy dan die antwoord in onderwerp (1.) sien – maw of (2.) gewerk het of nie
4. In die algemene inteken, waar alle waardes opgedateer word wanneer veranderinge aangebring word, kan jy die gewenste waardeverandering(e) sien as alles goed uitgewerk het.

Die stappe om dit te doen is:

1. kies 'n client_id bv. "Divus" en voeg dit in die pad na die API-gebruikernaam in
   Dit is die volledige onderwerp om op jou eie kommunikasiekanaal met die MQTT-bediener in te teken. Dit vertel die bediener waar jy die antwoorde verwag op die veranderinge wat jy van plan is om te stuur. Let op die status/stel deel wat 'n definieer. dat dit 'n intekenonderwerp is en b. dat dit die antwoorde sal kry om tipe opdragte te stel.
2. Die publiseer-onderwerp sal dieselfde wees, behalwe om die statusversoek-sleutelwoorde te verander
3. waaruit die verandering moet bestaan, word in die loonvrag geskryf. Hier is 'n paar examples.
   • Skakel 'n element af wat die aan/af-funksie het (1 bis):
   • Skakel 'n element aan wat die aan/af-funksie het (1 bis). Daarbenewens, as verskeie sulke opdragte vanaf dieselfde kliënt begin word, kan die uuid-parameter ("unieke ID", is gewoonlik 'n 128-bis-string geformateer as 8-4-4-4-12 syfers hex) gebruik word om die antwoord op die ooreenstemmende navraag, aangesien hierdie parameter – indien teenwoordig in die navraag – ook in die antwoord gevind kan word.
   • Skakel aan en stel die helderheid van 'n dimmer op 50%
   • Die antwoord op die onderwerp wat hierbo gewys en waarop ingeteken is (sy loonvrag, om presies te wees) is dan bv.ample.
     Bogenoemde reaksie is 'n example in die geval van 'n korrekte loonvrag, alhoewel die element geen verdoffunksie het nie. As daar ernstiger probleme is wat daartoe lei dat die loonvrag nie korrek geïnterpreteer word nie, sal die reaksie soos volg lyk (bv.):
     vir 'n verduideliking van die foutkodes en boodskappe, maar oor die algemeen, soos vir http, is 200 kodes positiewe antwoorde terwyl 400 negatief is.

EXAMPLE: PUBLISEER VIR DIE VERANDERING VAN MEERVOUDIGE ELEMENTWAARDES

Die prosedure is soortgelyk aan die een wat voorheen gewys is om 'n enkele element te verander. Die verskil is dat jy die element_id uit die onderwerpe weglaat en dan die stel element_ids voor die data binne die loonvrag aandui. Sien die sintaksis en struktuur hieronder.

FILTREER PER FUNKSIE TIPE IN NAVRAE

Die filters parameter in die loonvrag laat slegs die gewenste funksie(s) van 'n element toe om aangespreek te word. Die aan/af-funksie van 'n skakelaar of dimmer word "aan-af" genoem, bvample, en die ooreenstemmende filter word op hierdie manier gedefinieer:

Die antwoord lyk dan so, bvample

Die vierkantige hakie dui aan dat jy ook deur verskeie funksies kan filter, bv

lei tot 'n antwoord soos hierdie:

Bylaag

FOUTKODES

Foute in MQTT-kommunikasie lei tot 'n numeriese kode. Die volgende tabel help om dit af te breek.

PARAMETERS VAN DIE LOONLAS

Die loonvrag ondersteun verskillende parameters afhangende van die konteks. Die volgende tabel wys watter parameters in watter onderwerpe kan voorkom

WEERGAWE NOTAS

• VERSIE 1.00

Nuus:

• Eerste publikasie