DIVUS VISION API -ohjelmiston käyttöopas

DIVUS VISION API -ohjelmisto

Tekniset tiedot

• Tuote: DIVUS VISION API
• Valmistaja: DIVUS GmbH
• Versio: 1.00 REV0 1 – 20240528
• Sijainti: Pillhof 51, Eppan (BZ), Italia

Tuotetiedot

DIVUS VISION API on ohjelmistotyökalu, joka on suunniteltu liitäntään DIVUS VISION -järjestelmien kanssa. Sen avulla käyttäjät voivat käyttää ja ohjata järjestelmän eri elementtejä MQTT-protokollien avulla.

FAQ

K: Voinko käyttää DIVUS VISION API:ta ilman aiempaa tietoa PC:stä tai automaatiotekniikasta?

V: Käsikirja on räätälöity käyttäjille, joilla on aikaisempaa tietoa näiltä alueilta API:n tehokkaan käytön varmistamiseksi.

YLEISTIETOJA

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

Käyttöohjeet, käsikirjat ja ohjelmistot ovat tekijänoikeudella suojattuja. Kaikki oikeudet pidätetään. Kopioiminen, monistaminen, kääntäminen, kääntäminen kokonaan tai osittain ei ole sallittua. Poikkeus koskee ohjelmiston varmuuskopion luomista henkilökohtaiseen käyttöön.
Käsikirjaa voidaan muuttaa ilman erillistä ilmoitusta. Emme voi taata, että tämän asiakirjan ja toimitettujen tallennusvälineiden sisältämät tiedot ovat virheettömiä ja oikeita. Parannusehdotukset sekä vihjeet virheistä ovat aina tervetulleita. Sopimukset koskevat myös tämän käsikirjan erityisiä liitteitä. Tässä asiakirjassa olevat nimitykset voivat olla tavaramerkkejä, joiden käyttö kolmansien osapuolten toimesta omiin tarkoituksiinsa voi loukata niiden omistajien oikeuksia. Käyttöohjeet: Lue tämä opas ennen kuin käytät sitä ensimmäistä kertaa ja säilytä se turvallisessa paikassa tulevaa tarvetta varten. Kohderyhmä: Käsikirja on kirjoitettu käyttäjille, joilla on aikaisempaa tietoa PC- ja automaatiotekniikasta.

ESITTELYYHTEYDET

Johdanto

YLEINEN JOHDANTO

Tässä oppaassa kuvataan VISION API (Application Programming Interface) – käyttöliittymä, jonka kautta VISIONia voidaan osoittaa ja ohjata ulkoisista järjestelmistä.
Käytännössä tämä tarkoittaa, että voit käyttää järjestelmiä, kuten

• MQTT Explorer (https://www.microsoft.com/store/… - kokeiluun),
• Kotiavustaja (https://www.home-assistant.io/) tai
• Solmu-PUNAINEN (https://nodered.org/)

hallita VISIONin hallinnoimia elementtejä tai lukea niiden tila. Pääsy ja viestintä tapahtuu MQTT-protokollan kautta, joka käyttää ns. aiheita yksittäisten toimintojen tai toimintokokonaisuuksien käsittelemiseen tai niiden muutoksista tiedottamiseen. Tätä tarkoitusta varten käytetään MQTT-palvelinta (välittäjä), joka hoitaa turvallisuuden ja viestien hallinnan/jakelun osallistujille. Tässä tapauksessa MQTT-palvelin sijaitsee suoraan DIVUS KNX IQ:ssa ja on määritetty erityisesti tätä tarkoitusta varten. Vaikka VISION API:ta voidaan käyttää myös ilman ohjelmointiosaamista, tämä toiminto sopii kokeneille käyttäjille.

ESITIEDOT

Kuten VISION-käsikirjassa selitetään, API-käyttäjä on oletuksena ensin aktivoitava, jotta se voi käyttää sitä. API-käyttö toimii vain käyttämällä Api-käyttäjien todennustietoja. Mitä tulee käyttöoikeuksiin, tämän toiminnon aktivointi voidaan sitten konfiguroida joko kaikille tai yksittäisille elementeille. Katso luku 0. Tietenkin tarvitset myös VISION-projektin, jossa ulkopuolelta ohjattavat elementit on täysin konfiguroitu ja yhteys niihin on testattu onnistuneesti. Jotta yksittäisiä elementtejä voidaan käsitellä API:n kautta, niiden elementtitunnus on tiedettävä: tämä näkyy elementin asetuslomakkeen alaosassa.

TURVALLISUUS

Turvallisuussyistä API-käyttö on mahdollista vain paikallisesti (eli ei pilven kautta). Turvallisuusriski API-käyttöä aktivoitaessa on siis pieni. Turvallisuuden kannalta tärkeitä elementtejä ei kuitenkaan pitäisi ottaa käyttöön tai nimenomaisesti evätä API-käyttöä varten.

MQTT JA SEN EHDOT – LYHYT SELITYS

• MQTT:ssä kaikkien viestien keskitetyn hallinnan ja jakelun rooli on välittäjällä. Vaikka MQTT-palvelin ja MQTT-välittäjä eivät ole synonyymejä (palvelin on laajempi termi roolille, jota myös MQTT-asiakkaat voivat pelata), välittäjää tarkoitetaan tässä käsikirjassa aina, kun MQTT-palvelin mainitaan. DIVUS KNX IQ itse toimii MQTT-välittäjänä / MQTT-palvelimena tämän oppaan yhteydessä.
• MQTT-palvelin käyttää ns. aiheita: hierarkkista rakennetta, jonka avulla tiedot luokitellaan, hallitaan ja julkaistaan.
• Julkaisemisen ensisijaisena tavoitteena on tuoda tietoja muiden osallistujien saataville aiheiden kautta. Jos haluat muuttaa arvoa, kirjoitat haluttuun aiheeseen yhdessä halutun arvonmuutoksen kanssa, myös julkaisutoiminnolla. Kohdelaite tai MQTT-palvelin lukee siihen vaikuttavan halutun muutoksen ja ottaa sen käyttöön sen mukaisesti. Tarkistaaksesi, että muutos on otettu käyttöön, voit katsoa tilatusta reaaliaikaisesta aiheesta, näkyykö muutos siellä – jos kaikki on toiminut hyvin.
• Asiakkaat valitsevat heitä kiinnostavat aiheet: tätä kutsutaan tilaamiseksi. Joka kerta kun jokin arvo muuttuu aiheessa/alapuolella, kaikille tilaajille tiedotetaan – eli ilman, että heidän tarvitsee erikseen kysyä, onko jokin muuttunut tai mikä on nykyinen arvo.
• Voit avata (tai osoittaa) erillisen viestintäkanavan MQTT-palvelimen kanssa syöttämällä aiheeseen minkä tahansa ainutlaatuisen merkkijonon, jonka nimi on client_id. Asiakastunnusta on käytettävä aiheessa arvojen käsittelyyn. Tämä auttaa tunnistamaan jokaisen muutoksen alkuperän, auttaa mahdollisissa virheissä eikä vaikuta muihin asiakkaisiin, koska vastaavat palvelimen vastaukset, mukaan lukien mahdolliset virhekoodit ja viestit, saapuvat myös aiheeseen vain samalla asiakastunnuksella (ja siten vain tuo asiakas). Asiakastunnus on ainutlaatuinen merkkijono, joka koostuu mistä tahansa merkkien 0-9, az, AZ, "-", "_" yhdistelmästä.
• Yleensä DIVUS KNX IQ:n MQTT-palvelimen tilausaiheet sisältävät avainsanan tilan, kun taas julkaisuaiheet sisältävät avainsanapyynnön. Ne, joilla on tila, päivittyvät automaattisesti heti, kun tapahtuu ulkoinen arvonmuutos tai heti, kun asiakas on itse pyytänyt arvonmuutosta julkaisun kautta ja se on otettu käyttöön. Julkaisettavat jaetaan edelleen tyyppisiin (request/)get ja tyyppisiin (request/)set.
• Arvomuutokset ja muut valinnaiset parametrit lisätään aiheeseen ns. hyötykuormalla. Yksittäisten elementtien parametrit (element-id, name, type, functions)

Suurin ero MQTT:n ja perinteisen asiakas-palvelin-mallin välillä, jossa asiakas pyytää ja sitten muuttaa tietoja, keskittyy tilauksen ja julkaisun käsitteisiin. Osallistujat voivat julkaista tietoja ja asettaa ne muiden saataville, jotka voivat halutessaan tilata ne. Tämä arkkitehtuuri mahdollistaa tiedonvaihdon minimoimisen ja pitää silti kaikki kiinnostuneet osapuolet ajan tasalla. Lisätietoa yksityiskohdista täällä: ja erikoisparametreja (uuid, suodattimet) tulee käyttää tässä. Vaikka vaihtoehtoja on useita, hyötykuorma näytetään tässä oppaassa JSON-muodossa. JSON käyttää sulkuja ja pilkkuja edustamaan minkä tahansa rakenteen dataa ja minimoi siten lähetettävien datapakettien koon. Lisätietoja hyötykuormista löytyy myöhemmin käsikirjasta.

• Erikoistarkoituksiin on mahdollista suodattaa toimintotyypin mukaan, esim. osoitetaan vain päälle/pois eli 1-bittiset kytkimet. Hyötykuorman suodatinparametria käytetään tähän tarkoitukseen. Suodatus on tällä hetkellä mahdollista vain funktiotyypin mukaan.
• Jotta yksittäisiä elementtejä voidaan käsitellä, niiden elementtitunnus vaaditaan. Tämä löytyy VISIONista elementin ominaisuudet -valikosta tai se voidaan lukea myös suoraan tiedoista, jotka näkyvät jokaisen saatavilla olevan elementin edessä MQTT Explorerin yleisessä tilauksessa (elementit on listattu aakkosjärjestyksessä elementtitunnuksen mukaan).

Määritys API-käyttöä varten

VISION MÄÄRITTÄMINEN API-KÄYTTÄJÄLLE

Mene VISIONissa järjestelmänvalvojana kohtaan Kokoonpano – Käyttäjä/API-käyttöoikeus, napsauta Käyttäjät/API-käyttöoikeus ja napsauta hiiren kakkospainikkeella API-käyttäjää (tai paina pitkään) avataksesi muokkausikkunan. Sieltä löydät nämä parametrit ja tiedot

• Ota käyttöön (valintaruutu)
  • Käyttäjä otetaan ensin käyttöön täällä. Oletusasetus on poistettu käytöstä
• Käyttäjätunnus
  • Tämä merkkijono vaaditaan pääsyyn API:n kautta – kopioi se täältä
• Salasana
  • Tämä merkkijono vaaditaan pääsyyn API:n kautta – kopioi se täältä
• Käyttöoikeudet
  • Tässä voidaan määritellä oletusoikeudet VISION-elementtien arvojen lukemiseen ja kirjoittamiseen, eli tässä määritellyt koskevat kaikkia olemassa olevia ja tulevia elementtejä. Jos haluat sallia pääsyn vain yksittäisiin elementteihin, sinun ei pitäisi muuttaa näitä oletusoikeuksia

YKSITTÄISIIN ELEMENTEISIIN LIITTYVÄT LUVAT

On suositeltavaa, että et myönnä API-käyttöoikeutta koko projektille, vaan vain halutuille elementeille. Toimi seuraavasti

1. kirjaudu VISIONiin järjestelmänvalvojana
2. valitse haluamasi elementti ja avaa sen asetusvalikko (napsauta hiiren kakkospainiketta tai pidä painettuna ja sitten Asetukset)
3. Aktivoi valikon kohdassa Yleiset – Käyttöoikeudet ”Ohita oletusoikeudet” ja siirry sitten alakohtaan Oikeudet, joka näyttää käyttöoikeusmatriisin.
4. aktivoi ohjauslupa täällä, mikä mahdollistaa myös view lupa suoraan. Jos haluat lukea tietoja vain API-käytön kautta, riittää, että otat käyttöön view lupa.
5. toista sama toimenpide kaikille elementeille, joita haluat käyttää

Yhteys MQTT:n kautta

JOHDANTO

Exänäample, esittelemme pääsyn DIVUS KNX IQ:n MQTT API:n kautta suhteellisen yksinkertaisella, ilmaisella ohjelmistolla nimeltä MQTT Explorer (katso luku 1.1), joka on saatavilla Windowsille, Macille ja Linuxille. Perustiedot ja -kokemus MQTT:stä edellyttää.

YHTEYTTÄ VAADITTAVAT TIEDOT

Kuten aiemmin mainittiin (katso kohta 2.1), API-käyttäjän käyttäjätunnus ja salasana vaaditaan. Tässä on loppuview kaikista tiedoista, jotka on kerättävä ennen yhteyden muodostamista:

• Käyttäjätunnus Lue API-käyttäjän tietosivulta
• Salasana Lue API-käyttäjän tietosivulta
• IP-osoite Lue aloitusohjelman asetuksista Yleiset – Verkko – Ethernet (tai Synchronizerin kautta)
• Portti 8884 (tämä portti on varattu tähän tarkoitukseen)

ENSIMMÄINEN YHTEYS MQTT EXPLORERIN JA YLEISEN TILAAMISEEN

Normaalisti MQTT tekee eron tilauksen ja julkaisun välillä. MQTT Explorer yksinkertaistaa tätä tilaamalla automaattisesti kaikki saatavilla olevat aiheet (aihe #), kun ensimmäinen yhteys muodostetaan. Tämän seurauksena puu, joka johtaa kaikkiin käytettävissä oleviin elementteihin (eli API-käyttäjän käyttöoikeudet myönnetty), näkyy suoraan MQTT Explorer -ikkunan vasemmalla puolella onnistuneen yhteyden jälkeen. Jos haluat kirjoittaa lisää tilausaiheita tai korvata #-merkin tarkemmalla aiheella, siirry yhteysikkunan Lisäasetukset-kohtaan. Oikeassa yläkulmassa näkyvä aihe näyttää tältä:

jossa 7f4x0607849x444xxx256573x3x9x983 on API-käyttäjänimi ja objektiluettelo sisältää kaikki saatavilla olevat elementit. Tämä aihe pidetään aina ajan tasalla eli mahdolliset arvojen muutokset näkyvät siellä reaaliajassa. Jos haluat tilata vain yksittäisiä elementtejä, syötä haluamasi elementin elementtitunnus objects_list/ perään.

Huomautus: Tämäntyyppinen tilaus vastaa suunnilleen KNX-palauteosoitteiden takana olevaa logiikkaa; se näyttää elementtien nykyisen tilan, ja sitä voidaan käyttää tarkistamaan, onko halutut muutokset toteutettu onnistuneesti. Jos haluat vain lukea tietoja, mutta et muuttaa niitä, tämäntyyppinen tilaus riittää .

Yksi yksinkertainen elementti näyttää suunnilleen tältä JSON-merkinnöissä

Huomautus: Kaikilla arvoilla on yllä näkyvä syntaksi, esim. { “value”: “1” } tilattavien aiheiden ulostulona, ​​kun taas arvo kirjoitetaan suoraan hyötykuormaan arvon muuttamiseksi (eli julkaisuaiheille) – suluissa ja "arvo" jätetään pois, esim. "onoff": "1".

Lisäkomennot

JOHDANTO

Yleisesti ottaen on olemassa kolmenlaisia ​​aiheita:

1. Tilaa aihe(t) nähdäksesi saatavilla olevat elementit ja saadaksesi reaaliaikaisia ​​arvomuutoksia
2. Tilaa aihe(t) saadaksesi vastauksia (asiakkaita ) julkaista pyyntöjä
3. Julkaise aihe(t) saadaksesi tai asettaaksesi elementtejä niiden arvoineen

Myöhemmin viitataan näihin käyttämällä tässä esitettyä numerointia (esim. tyypin 1, 2, 3 aiheet). Tarkemmat tiedot seuraavissa osioissa ja luvussa. 4.2.

TILAA AIHEITA NÄHDÄksesi SAATAVILLA OLEVAT ELEMENTIT JA SAADAAT REAALIAIKAISET ARVONMUUTOKSET

Nämä on jo kuvattu

TILAA AIHEITA saadaksesi VASTAUKSET ASIAKKAAN JULKAISUPYYNTÖIHIN

Tällaiset aiheet ovat valinnaisia. Se sallii

• avaa ainutlaatuinen viestintäkanava MQTT-palvelimen kanssa käyttämällä mielivaltaista asiakastunnusta. Siitä lisää luvussa. 4.2.2
• saada julkaisupyyntöjen tulos vastaavasta tilausaiheesta: onnistuminen tai epäonnistuminen virhekoodin ja viestin kanssa.

On olemassa erilaisia ​​​​aiheita, joihin voit saada vastauksia julkaisukomentojen saamiseksi tai asettamiseen. Vastaava ero Kun saat järjestelmällesi tarvittavat aiheet suoraan, voit päättää poistaa tämän vaiheen ja käyttää suoraan julkaisuaiheita.

 JULKAISEMME AIHEITA SAADAKSI TAI ASETTAAksesi ELEMENTIT ARVOIHIN

Nämä aiheet käyttävät samaa polkua kuin tilaamiseen - ainoa muutos on sana "pyyntö" tilauksessa käytetyn "tilan" tilalle. Täydelliset aihepolut näytetään myöhemmin luvussa. 4.2.2\ Get-aihe pyytää lukemaan MQTT-palvelimen elementit ja arvot. Hyötykuormaa voidaan käyttää suodatukseen elementtien toimintotyypin perusteella. Asetettu aihe pyytää muuttamaan joitakin elementin osia sen hyötykuorman mukaisesti.

ETULIITE KOMENTOILLE JA VASTAAVIA VASTAUKSIA

 LYHYT SELITYS

Kaikilla MQTT-palvelimelle lähetetyillä komennoilla on yhteinen alkuosa, nimittäin:

YKSITYISKOHTAINEN SELITYS

Reaaliaikaisilla aiheilla (tyyppi 1) on yleinen etuliite (katso yllä), jota seuraa sitten

or

Set-komennoissa hyötykuorma on luonnollisesti päärooli, sillä se sisältää halutut muutokset (eli elementin toimintojen muuttuneet arvot). A Varoitus: Älä koskaan käytä säilytysvaihtoehtoa tyypin 3 komentoissa, koska se voi aiheuttaa ongelmia KNX-puolella.

EXAMPLE: JULKAISEMINEN YKSI ELEMENTIN ARVOJEN MUUTTAMISTA VARTEN

Yksinkertaisin tapaus on haluta muuttaa jonkin yleisen tilauksen osoittaman elementin arvoa.
Yleisesti ottaen VISION-toiminnon muuttaminen/vaihtaminen MQTT:n kautta koostuu kolmesta vaiheesta, joista kaikki eivät ole ehdottoman välttämättömiä, mutta suosittelemme kuitenkin suorittamaan ne kuvatulla tavalla.

1. Aihe, joka sisältää muokattavan funktion, tilataan mukautetulla client_id-tunnisteella
2. Muokattava aihe julkaistaan ​​yhdessä hyötykuorman kanssa halutuilla muutoksilla kohdassa 1 valitulla client_id:llä.
3. Tarkistaaksesi, voit katsoa vastauksen aiheessa (1.) – eli onko (2.) toiminut vai ei
4. Yleisessä tilauksessa, jossa kaikki arvot päivitetään muutosten yhteydessä, näet halutun arvomuutoksen, jos kaikki on toiminut hyvin.

Toimi seuraavasti:

1. valitse client_id esim. “Divus” ja lisää se polkuun API-käyttäjänimen jälkeen
   Tämä on täydellinen aihe oman viestintäkanavan tilaamiseen MQTT-palvelimen kanssa. Tämä kertoo palvelimelle, minne odotat vastaukset muutoksiin, jotka aiot lähettää. Huomaa tila/setin osa, joka määrittää a. että se on tilausaihe ja b. että se saa vastaukset tyyppikomentoihin.
2. Julkaisuaihe on sama paitsi tilapyyntöavainsanojen vaihtaminen
3. hyötykuormaan kirjoitetaan se, mistä muutoksen tulisi koostua. Tässä muutama examples.
   • On/off-toiminnon (1 bitti) sisältävän elementin kytkeminen pois päältä:
   • Käynnistetään elementti, jossa on on/off-toiminto (1 bitti). Lisäksi, jos samasta asiakkaasta käynnistetään useita tällaisia ​​komentoja, uuid-parametria ("yksilöllinen tunnus" on yleensä 128-bittinen merkkijono, joka on muotoiltu 8-4-4-4-12 numeron heksadesimaaliksi) voidaan määrittää vastaus vastaavaan kyselyyn, koska tämä parametri – jos se on kyselyssä – löytyy myös vastauksesta.
   • Himmennin päälle kytkeminen ja kirkkauden asettaminen 50 %:iin
   • Vastaus yllä esitettyyn ja tilattuun aiheeseen (tarkemmin sanottuna sen hyötykuormaan) on siis esimample.
     Yllä oleva vastaus on example oikean hyötykuorman tapauksessa, vaikka elementillä ei ole himmennystoimintoa. Jos on vakavampia ongelmia, joiden vuoksi hyötykuormaa ei tulkita oikein, vastaus näyttää tältä (esim.):
     Virhekoodien ja viestien selitykseksi, mutta yleensä, kuten http:lle, 200 koodia ovat myönteisiä vastauksia ja 400 negatiivisia vastauksia.

EXAMPLE: JULKAISEMINEN USEIN ELEMENTIN ARVOJEN MUUTTAMISTA VARTEN

Menettely on samanlainen kuin edellä esitetty yksittäisen elementin muuttaminen. Erona on, että jätät element_id:n pois aiheista ja ilmoitat sitten element_ids-joukon hyötykuorman sisällä olevien tietojen eteen. Katso syntaksi ja rakenne alta.

SUODATA KYSYMYKSESSÄ TOIMINTOTYYPIN MUKAAN

Hyötykuorman suodatinparametri sallii vain elementin halutun toiminnon/toimintojen osoittamisen. Kytkimen tai himmentimen päälle/pois-toimintoa kutsutaan “onoff”, esimample, ja vastaava suodatin määritellään seuraavasti:

Vastaus näyttää sitten tältä, esimample

Hakasulke osoittaa, että voit myös suodattaa useiden funktioiden mukaan, esim

johtaa tällaiseen vastaukseen:

Liite

VIRHEKOODIT

Virheet MQTT-tiedonsiirrossa johtavat numerokoodiin. Seuraava taulukko auttaa sen purkamisessa.

Hyötykuorman PARAMETRIT

Hyötykuorma tukee erilaisia ​​parametreja kontekstista riippuen. Seuraava taulukko näyttää, mitkä parametrit voivat esiintyä missäkin aiheissa

VERSIO HUOMAUTUKSIA

• 1.00 VERSION

Uutiset:

• Ensimmäinen julkaisu