DIVUS VISION API Software brugermanual

DIVUS VISION API-software

Specifikationer

• Produkt: DIVUS VISION API
• Producent: DIVUS GmbH
• Version: 1.00 REV0 1 – 20240528
• Beliggenhed: Pillhof 51, Eppan (BZ), Italien

Produktinformation

DIVUS VISION API er et softwareværktøj designet til at interface med DIVUS VISION-systemer. Det giver brugerne mulighed for at få adgang til og kontrollere forskellige elementer i systemet ved hjælp af MQTT-protokoller.

FAQ

Q: Kan jeg bruge DIVUS VISION API uden forudgående kendskab til pc eller automationsteknologi?

A: Manualen er skræddersyet til brugere med tidligere viden på disse områder for at sikre effektiv brug af API'en.

GENEREL INFORMATION

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

Betjeningsvejledninger, manualer og software er beskyttet af copyright. Alle rettigheder forbeholdes. Det er ikke tilladt at kopiere, kopiere, oversætte, oversætte helt eller delvist. En undtagelse gælder for oprettelse af en sikkerhedskopi af softwaren til personlig brug.
Manualen kan ændres uden varsel. Vi kan ikke garantere, at dataene i dette dokument og på det medfølgende lagringsmedie er fejlfri og korrekte. Forslag til forbedringer samt tip om fejl er altid velkomne. Aftalerne gælder også for de specifikke bilag til denne manual. Betegnelserne i dette dokument kan være varemærker, hvis brug af tredjeparter til deres egne formål kan krænke deres ejeres rettigheder. Brugervejledning: Læs venligst denne vejledning, før du bruger den første gang, og opbevar den et sikkert sted til fremtidig brug. Målgruppe: Manualen er skrevet til brugere med tidligere kendskab til pc og automationsteknologi.

PRÆSENTATIONSKONVENTIONER

Indledning

GENEREL INTRODUKTION

Denne manual beskriver VISION API (Application Programming Interface) – en grænseflade, hvorigennem VISION kan adresseres og styres fra eksterne systemer.
Rent praktisk betyder det, at du kan bruge systemer som f.eks

• MQTT Explorer (https://www.microsoft.com/store/... – til test),
• Hjemmeassistent (https://www.home-assistant.io/) eller
• Node-RED (https://nodered.org/)

at kontrollere de elementer, der administreres af VISION, eller læse deres status op. Adgang og kommunikation foregår via MQTT-protokollen, som bruger såkaldte emner til at adressere individuelle funktioner eller funktionssæt eller til at blive informeret om ændringer i dem. Til dette formål anvendes en MQTT-server (mægler), som varetager sikkerhed og håndtering/distribution af beskeder til deltagerne. I dette tilfælde er MQTT-serveren placeret direkte på DIVUS KNX IQ og er specielt konfigureret til dette formål. Selvom VISION API også kan bruges uden programmeringskendskab, er denne funktionalitet velegnet til avancerede brugere.

FORUDSÆTNINGER

Som forklaret i VISION-manualen skal API-brugeren som standard først aktiveres for at kunne bruge den, API-adgangen virker kun ved at bruge API-brugernes autentificeringsdata. For så vidt angår brugerrettighederne, kan aktiveringen af ​​denne funktionalitet så konfigureres enten på alle eller på enkelte elementer. Se kap.0. Du har selvfølgelig også brug for et VISION-projekt, hvor de elementer, du vil styre udefra, er fuldt konfigureret, og forbindelsen til dem er blevet testet med succes. For at kunne adressere individuelle elementer via API'en, skal deres element-id være kendt: dette vises nederst i elementets indstillingsformular

SIKKERHED

Af sikkerhedsmæssige årsager er API-adgang kun mulig lokalt (dvs. ikke via skyen). Sikkerhedsrisikoen ved aktivering af API-adgang er derfor lav. Ikke desto mindre bør sikkerhedsrelevante elementer ikke aktiveres eller eksplicit nægtes for API-adgang.

MQTT OG DETS VILKÅR – KORT FORKLARING

• I MQTT er mæglerens rolle som centraliseret styring og distribution af alle beskeder. Selvom MQTT-server og MQTT-mægler ikke er synonymer (server er en bredere betegnelse for en rolle, som MQTT-klienter også kan spille), menes mægleren altid i denne manual, når MQTT-server er nævnt. DIVUS KNX IQ selv spiller rollen som MQTT-mægler/MQTT-server i forbindelse med denne manual.
• En MQTT-server bruger såkaldte topics: en hierarkisk struktur, hvormed data kategoriseres, administreres og publiceres.
• Udgivelse har det primære mål at gøre data tilgængelige for andre deltagere gennem emner. Ønsker du at ændre en værdi, skriver du til det ønskede emne sammen med den ønskede værdiændring, også ved hjælp af en publiceringshandling. Målenheden eller MQTT-serveren læser den ønskede ændring, der påvirker den, og adopterer den i overensstemmelse hermed. For at kontrollere, at ændringen er blevet anvendt, kan du se i det tilmeldte realtidsemne for at se, om ændringen afspejles der - om alt har fungeret fint.
• Kunder vælger de emner, der interesserer dem: dette kaldes at abonnere. Hver gang en værdi ændres i/under et emne, informeres alle tilmeldte kunder – altså uden at man skal spørge eksplicit, om noget har ændret sig, eller hvad den aktuelle værdi er.
• Du kan åbne (eller adressere) en separat kommunikationskanal med MQTT-serveren ved at indtaste en hvilken som helst unik streng kaldet client_id i et emne. Client_id skal bruges i emnet for at behandle værdier. Dette tjener til at identificere oprindelsen af ​​hver ændring, hjælper med eventuelle fejl og påvirker ikke de andre klienter, da de tilsvarende svar fra serveren, inklusive eventuelle fejlkoder og meddelelser, også kun når emnet med samme client_id (og dermed kun denne klient). Client_id er en unik tegnstreng bestående af enhver kombination af tegnene 0-9, az, AZ, "-", "_".
• Generelt indeholder abonnensemnerne på MQTT-serveren på DIVUS KNX IQ nøgleordsstatus, mens publiceringsemnerne indeholder søgeordsanmodningen. Dem med status opdateres automatisk, så snart der er en ekstern værdiændring, eller så snart en værdiændring er blevet anmodet af klienten selv via en publicering og er blevet anvendt med succes. Dem til udgivelse er yderligere opdelt i dem af typen (request/)get og dem af typen (request/)set.
• Værdiændringer og andre valgfrie parametre tilføjes til emnet med den såkaldte nyttelast. Parametrene for de enkelte elementer (element-id, navn, type, funktioner)

Hovedforskellen mellem MQTT og den klassiske klient-server-model, hvor klienten anmoder om og derefter ændrer data, er centreret om begreberne abonner og udgiver. Deltagerne kan offentliggøre data og gøre dem tilgængelige for andre, som, hvis de er interesserede, kan abonnere på dem. Denne arkitektur gør det muligt at minimere dataudveksling og stadig holde alle interesserede parter opdateret. Mere om detaljerne her: og specielle parametre (uuid, filtre) skal bruges her. Selvom der er flere muligheder, vises nyttelasten formateret som JSON i denne manual. JSON bruger parenteser og kommaer til at repræsentere data af enhver struktur og minimerer dermed størrelsen af ​​de datapakker, der skal transmitteres. Flere detaljer om nyttelast kan findes senere i manualen.

• Til specielle formål er det muligt at filtrere efter funktionstype, f.eks. kun at adressere on/off, dvs. 1-bit switches. Filterparameteren i nyttelasten bruges til dette formål. Filtrering er i øjeblikket kun mulig efter funktionstype.
• For at kunne adressere individuelle elementer kræves deres element-id. Dette kan findes i VISION i elementegenskabsmenuen eller kan også læses direkte fra de data, der vises foran hvert tilgængeligt element i det generelle abonnement på MQTT Explorer (elementer der er listet alfabetisk efter element-ID).

Konfiguration for API-adgang

KONFIGURERING AF VISION FOR API-BRUGERADGANG

I VISION som administrator, gå til Konfiguration – Bruger/API Adgangsstyring, klik på Brugere/API-adgang og højreklik på API-bruger (eller tryk og hold) for at åbne redigeringsvinduet. Der finder du disse parametre og data

• Aktiver (afkrydsningsfelt)
  • Brugeren aktiveres først her. Standard er deaktiveret
• Brugernavn
  • Denne streng er påkrævet for adgang via API – kopier den herfra
• Adgangskode
  • Denne streng er påkrævet for adgang via API – kopier den herfra
• Tilladelser
  • Standardrettighederne til at læse og skrive værdierne for VISION-elementerne kan defineres her, dvs. det, der er defineret her, gælder for alle eksisterende og fremtidige elementer. Hvis du kun ønsker at tillade adgang til individuelle elementer, bør du ikke ændre disse standardrettigheder

TILLADELSER TIL INDIVIDUELLE ELEMENTER

Det anbefales, at du ikke giver API-adgang til hele projektet, men kun til de ønskede elementer. Fortsæt som følger

1. log ind på VISION som administrator
2. vælg det ønskede element og åbn dets indstillingsmenu (højreklik eller hold nede, derefter Indstillinger)
3. under menupunktet Generelt – Tilladelser skal du aktivere “Tilsidesæt standardtilladelser” og derefter gå til underpunktet Tilladelser, som viser tilladelsesmatrixen.
4. aktivere kontroltilladelsen her, som også aktiverer view tilladelse direkte. Hvis du kun ønsker at læse data via API-adgangen, er det tilstrækkeligt at aktivere view tilladelse.
5. gentag den samme procedure for alle de elementer, du vil have adgang til

Tilslutning via MQTT

INDLEDNING

Som eksampvi vil demonstrere adgang via MQTT API'en til DIVUS KNX IQ med en forholdsvis enkel, gratis software kaldet MQTT Explorer (se kap. 1.1), som er tilgængelig til Windows, Mac og Linux. En grundlæggende viden og erfaring med MQTT er underforstået.

DATA KRÆVES TIL FORBINDELSEN

Som nævnt tidligere (se afsnit 2.1), kræves brugernavn og adgangskode for API-brugeren. Her er en overview af alle de data, der skal indsamles, før en forbindelse etableres:

• Brugernavn Læs op på API-brugerens detaljeside
• Adgangskode Læs op på API-brugerens detaljeside
• IP-adresse Læs op i launcher-indstillingerne under Generelt – Netværk – Ethernet (eller via Synchronizer)
• Port 8884 (denne port er reserveret til dette formål)

FØRSTE FORBINDELSE MED MQTT EXPLORER OG GENERELT ABONNER

Normalt skelner MQTT mellem de aktiviteter, der abonnerer på og udgiver. MQTT Explorer forenkler dette ved automatisk at abonnere på alle tilgængelige emner (emne #), når den første forbindelse er oprettet. Som et resultat kan træet, der fører til alle tilgængelige elementer (dvs. API-brugeradgang givet) ses direkte i venstre side af MQTT Explorer-vinduet efter en vellykket forbindelse. For at indtaste yderligere abonnensemner eller erstatte # med et mere specifikt emne, gå til Avanceret i forbindelsesvinduet. Emnet vist øverst til højre ser nogenlunde sådan ud:

hvor 7f4x0607849x444xxx256573x3x9x983 er API-brugernavnet, og objects_list indeholder alle de tilgængelige elementer. Dette emne holdes altid opdateret, dvs. eventuelle værdiændringer afspejles der i realtid. Hvis du kun ønsker at abonnere på individuelle elementer, skal du indtaste element-ID'et for det ønskede element efter objects_list/.

Bemærk: Denne type abonnement svarer nogenlunde til logikken bag KNX-feedback-adresserne; den viser den aktuelle status for elementerne og kan bruges til at kontrollere, om de ønskede ændringer er blevet anvendt. Hvis du kun vil udlæse data, men ikke ændre dem, er denne type abonnement tilstrækkelig .

Et enkelt enkelt element ser sådan ud i JSON-notation

Bemærk: Alle værdier har den ovenfor viste syntaks, f.eks. { “værdi”: “1” } som output af abonnentemnerne, mens værdien skrives direkte i nyttelasten for at ændre en værdi (dvs. for publiceringsemner) – parentes og "værdi" udelades f.eks. "onoff": "1".

Avancerede kommandoer

INDLEDNING

Der er 3 slags emner generelt:

1. Abonner på emne(r) for at se de tilgængelige elementer og få værdiændringer i realtid
2. Abonner på emne(r) for at få svar på (kunderne ) offentliggør anmodninger
3. Udgiv emne(r) for at få eller for at sætte elementer med deres værdier

Vi skal senere henvise til disse typer ved hjælp af nummereringen vist her (f.eks. emner af type 1, 2, 3). Flere detaljer i de følgende afsnit og i kap. 4.2.

ABONNER EMNER FOR AT SE DE TILGÆNGELIGE ELEMENTER OG FÅ REALTIDSVÆRDIÆNDRINGER

Disse er allerede blevet beskrevet

ABONNER EMNER FOR AT FÅ SVARENE PÅ KUNDENS OFFENTLIGGØRELSER

Denne form for emner er valgfri. Det giver mulighed for

• åbne en unik kommunikationskanal med MQTT-serveren ved at bruge et vilkårligt client_id. Mere herom i kap. 4.2.2
• få resultatet af udgivelsesanmodninger om det tilsvarende abonnementsemne: succes eller fiasko med fejlkode og meddelelse.

Der er forskellige emner for at få svar for at få eller til at indstille udgivelseskommandoer. Den tilsvarende forskel i Når du har fået de nødvendige emner til dit system på det rene, kan du beslutte at fjerne dette trin og direkte bruge publiceringsemner.

 UDGIV EMNER FOR AT FÅ ELLER FOR AT INDSTILLE ELEMENTER MED DERES VÆRDIER

Disse emner bruger en sti, der ligner dem til at abonnere - den eneste ændring er ordet "anmodning" i stedet for den "status", der bruges til at abonnere. Fuldstændige emnestier er vist senere i kap. 4.2.2\ Et get-emne vil anmode om at læse MQTT-serverens elementer og værdier. Nyttelasten kan bruges til at filtrere baseret på elementernes funktionstype. Et sæt emne vil anmode om at ændre nogle dele af et element, som beskrevet i dets nyttelast.

PREFIX FOR KOMMANDOER OG TILSVARENDE SVAR

 KORT FORKLARING

Alle kommandoer, der sendes til MQTT-serveren, har en fælles indledende del, nemlig:

DETALJERET FORKLARING

Realtidsemnerne (type 1) vil have det generelle præfiks (se ovenfor) og derefter efterfulgt af

or

For sæt kommandoer spiller nyttelasten naturligvis hovedrollen, da den vil indeholde de ønskede ændringer (dvs. ændrede værdier for elementets funktioner). En advarsel: Brug aldrig retain-indstillingen i dine type 3-kommandoer, da det kan forårsage problemer på KNX-siden.

EXAMPLE: PUBLICER FOR ÆNDRING AF ET ENKELTE ELEMENTS VÆRDI(ER)

Det enkleste tilfælde er at ønske at ændre værdien af ​​et af de elementer, der vises af det generelle abonnement.
Generelt set består ændring/skift af en funktion af VISION via MQTT af 3 trin, som ikke alle er absolut nødvendige, men vi anbefaler ikke desto mindre at udføre dem som beskrevet.

1. Emnet, der indeholder den funktion, vi ønsker at redigere, abonneres ved hjælp af et brugerdefineret client_id
2. Emnet til redigering offentliggøres sammen med nyttelasten med de ønskede ændringer ved hjælp af client_id valgt i 1.
3. For at tjekke, kan du så se svaret i emne (1.) – altså om (2.) virkede eller ej
4. I det generelle abonnement, hvor alle værdier opdateres, når der foretages ændringer, kan du se den/de ønskede værdiændring(er), hvis alt har fungeret fint.

Trinene til at gøre dette er:

1. vælg et client_id f.eks. "Divus", og indsæt det i stien efter API-brugernavnet
   Dette er det komplette emne for at abonnere på din egen kommunikationskanal med MQTT-serveren. Dette fortæller serveren, hvor du forventer svarene på de ændringer, du har til hensigt at sende. Bemærk status/sæt-delen, som definerer en. at det er et abonnementsemne og b. at den vil få svarene på indstillede typekommandoer.
2. Udgivelsesemnet vil være det samme, bortset fra at skifte statusanmodningsnøgleord
3. hvad ændringen skal bestå af står skrevet i nyttelasten. Her er nogle examples.
   • Sluk for et element, der har tænd/sluk-funktionen (1 bit):
   • Tænd for et element, der har tænd/sluk-funktionen (1 bit). Derudover, hvis flere sådanne kommandoer startes fra den samme klient, kan uuid-parameteren ("unik ID", er normalt en 128-bit streng formateret som 8-4-4-4-12 cifre hex) bruges til at tildele svar på den tilsvarende forespørgsel, da denne parameter – hvis den findes i forespørgslen – også kan findes i svaret.
   • Tænd og indstilling af lysstyrken på en lysdæmper til 50 %
   • Svaret på det emne, der er vist og abonneret på ovenfor (dets nyttelast, for at være præcis) er så f.eks.ample.
     Ovenstående svar er et example i tilfælde af en korrekt nyttelast, selvom elementet ikke har nogen dæmpningsfunktion. Hvis der er mere alvorlige problemer, der fører til, at nyttelasten ikke fortolkes korrekt, vil svaret se således ud (f.eks.):
     for en forklaring af fejlkoder og meddelelser, men generelt, ligesom for http, er 200 koder positive svar, mens 400 er negative.

EXAMPLE: PUBLICER FOR ÆNDRING AF FLERE ELEMENTEVÆRDIER

Fremgangsmåden ligner den, der er vist før, for at ændre et enkelt element. Forskellen er, at du udelader element_id fra emnerne og derefter angiver sættet af element_id'er foran dataene inde i nyttelasten. Se syntaks og struktur nedenfor.

FILTER EFTER FUNKTIONSTYPE I FORESPØRGSEL

Filterparameteren i nyttelasten tillader kun at adressere den eller de ønskede funktion(er) af et element. Tænd/sluk-funktionen på en kontakt eller lysdæmper kaldes "onoff", f.eksample, og det tilsvarende filter er defineret på denne måde:

Svaret ser så således ud, f.eksample

Den firkantede parentes angiver, at du også kan filtrere efter flere funktioner, f.eks

fører til et svar som dette:

Tillæg

FEJLKODER

Fejl i MQTT-kommunikation resulterer i en numerisk kode. Følgende tabel hjælper med at opdele det.

PARAMETRE FOR NYTTESTILLINGEN

Nyttelasten understøtter forskellige parametre afhængigt af konteksten. Følgende tabel viser, hvilke parametre der kan forekomme i hvilke emner

VERSION NOTER

• 1.00 VERSION

Nyheder:

• Første udgivelse