DIVUS VISION API programvarebrukerhåndbok

DIVUS VISION API-programvare

Spesifikasjoner

• Produkt: DIVUS VISION API
• Produsent: DIVUS GmbH
• Versjon: 1.00 REV0 1 – 20240528
• Sted: Pillhof 51, Eppan (BZ), Italia

Produktinformasjon

DIVUS VISION API er et programvareverktøy utviklet for grensesnitt med DIVUS VISION-systemer. Den lar brukere få tilgang til og kontrollere ulike elementer i systemet ved hjelp av MQTT-protokoller.

FAQ

Spørsmål: Kan jeg bruke DIVUS VISION API uten forkunnskaper om PC eller automatiseringsteknologi?

A: Håndboken er skreddersydd for brukere med tidligere kunnskap på disse områdene for å sikre effektiv bruk av API.

GENERELL INFORMASJON

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

Bruksanvisning, manualer og programvare er beskyttet av opphavsrett. Alle rettigheter forbeholdt. Det er ikke tillatt å kopiere, kopiere, oversette, oversette helt eller delvis. Et unntak gjelder for opprettelse av en sikkerhetskopi av programvaren for personlig bruk.
Håndboken kan endres uten varsel. Vi kan ikke garantere at dataene i dette dokumentet og på lagringsmediene som følger med er feilfrie og korrekte. Forslag til forbedringer samt tips om feil er alltid velkomne. Avtalene gjelder også for de spesifikke vedleggene til denne håndboken. Betegnelsene i dette dokumentet kan være varemerker hvis bruk av tredjeparter til egne formål kan krenke rettighetene til deres eiere. Brukerinstruksjoner: Les denne håndboken før du bruker den for første gang og oppbevar den på et trygt sted for fremtidig referanse. Målgruppe: Manualen er skrevet for brukere med tidligere kunnskap om PC og automasjonsteknologi.

PRESENTASJONSKONVENSJONER

Introduksjon

GENERELL INTRODUKSJON

Denne håndboken beskriver VISION API (Application Programming Interface) – et grensesnitt der VISION kan adresseres og kontrolleres fra eksterne systemer.
Rent praktisk betyr det at du kan bruke systemer som f.eks

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

for å kontrollere elementene som administreres av VISION eller lese opp deres status. Tilgang og kommunikasjon skjer via MQTT-protokollen, som bruker såkalte emner for å adressere individuelle funksjoner eller sett med funksjoner eller for å bli informert om endringer i disse. Til dette formål benyttes en MQTT-server (megler), som håndterer sikkerhet og håndtering/distribusjon av meldinger til deltakerne. I dette tilfellet er MQTT-serveren plassert direkte på DIVUS KNX IQ og er spesielt konfigurert for dette formålet. Selv om VISION API også kan brukes uten programmeringskunnskap, er denne funksjonaliteten egnet for avanserte brukere.

FORUTSETNINGER

Som forklart i VISION-manualen, må API-brukeren som standard først aktiveres for å kunne bruke den, API-tilgangen fungerer kun ved å bruke autentiseringsdataene for API-brukere. Når det gjelder brukerrettighetene, kan aktiveringen for denne funksjonaliteten konfigureres enten på alle eller på enkeltelementer. Se kap.0. Selvfølgelig trenger du også et VISION-prosjekt der elementene du ønsker å kontrollere utenfra er fullt konfigurert og forbindelsen til dem har blitt testet. For å kunne adressere individuelle elementer via API, må deres element-ID være kjent: denne vises nederst i elementets innstillingsskjema

SIKKERHET

Av sikkerhetsgrunner er API-tilgang kun mulig lokalt (dvs. ikke via skyen). Sikkerhetsrisikoen ved aktivering av API-tilgang er derfor lav. Sikkerhetsrelevante elementer bør likevel ikke aktiveres eller eksplisitt nektes for API-tilgang.

MQTT OG DETS VILKÅR – KORT FORKLARING

• I MQTT er rollen til sentralisert styring og distribusjon av alle meldinger meglerens. Selv om MQTT-server og MQTT-megler ikke er synonymer (server er en bredere betegnelse for en rolle som MQTT-klienter også kan spille), menes alltid megleren i denne håndboken når MQTT-server er nevnt. DIVUS KNX IQ selv spiller rollen som MQTT-megler/MQTT-server i sammenheng med denne håndboken.
• En MQTT-server bruker såkalte emner: en hierarkisk struktur som data blir kategorisert, administrert og publisert med.
• Publisering har som hovedmål å gjøre data tilgjengelig for andre deltakere gjennom emner. Ønsker du å endre en verdi, skriver du til ønsket emne sammen med ønsket verdiendring, også ved hjelp av en publiseringshandling. Målenheten eller MQTT-serveren leser den ønskede endringen som påvirker den og adopterer den deretter. For å sjekke at endringen er tatt i bruk, kan du se i det abonnerte sanntidsemnet for å se om endringen gjenspeiles der – om alt har fungert bra.
• Kunder velger emnene som interesserer dem: dette kalles å abonnere. Hver gang en verdi endres i/under et emne, informeres alle abonnenter – altså uten å eksplisitt spørre om noe har endret seg eller hva den aktuelle verdien er.
• Du kan åpne (eller adressere) en egen kommunikasjonskanal med MQTT-serveren ved å skrive inn en hvilken som helst unik streng kalt client_id i et emne. Client_id må brukes i emnet for å behandle verdier. Dette tjener til å identifisere opprinnelsen til hver endring, hjelper med eventuelle feil og påvirker ikke de andre klientene, da de tilsvarende svarene fra serveren, inkludert eventuelle feilkoder og meldinger, også bare når emnet med samme client_id (og dermed bare den klienten). Client_id er en unik tegnstreng som består av en hvilken som helst kombinasjon av tegnene 0-9, az, AZ, "-", "_".
• Generelt inneholder abonnensemnene til MQTT-serveren til DIVUS KNX IQ nøkkelordstatusen, mens publiseringsemnene inneholder nøkkelordforespørselen. De med status oppdateres automatisk så snart det er en ekstern verdiendring eller så snart en verdiendring er forespurt av klienten selv via en publisering og har blitt implementert. De for publisering er videre delt inn i de av typen (request/)get og de av typen (request/)set.
• Verdiendringer og andre valgfrie parametere legges til emnet med den såkalte nyttelasten. Parametrene til de enkelte elementene (element-id, navn, type, funksjoner)

Hovedforskjellen mellom MQTT og den klassiske klient-server-modellen, der klienten ber om og deretter endrer data, er sentrert om konseptene abonnere og publisere. Deltakere kan publisere data, gjøre dem tilgjengelige for andre, som hvis interesserte kan abonnere på dem. Denne arkitekturen gjør det mulig å minimere datautveksling og fortsatt holde alle interesserte parter oppdatert. Mer om detaljene her: og spesielle parametere (uuid, filtre) skal brukes her. Selv om det er flere alternativer, vises nyttelasten formatert som JSON i denne håndboken. JSON bruker parenteser og kommaer for å representere data av enhver struktur og minimerer dermed størrelsen på datapakkene som skal overføres. Flere detaljer om nyttelast finner du senere i håndboken.

• For spesielle formål er det mulig å filtrere etter type funksjon, f.eks. adressere kun på/av, dvs. 1-bits brytere. Filterparameteren i nyttelasten brukes til dette formålet. Filtrering er foreløpig kun mulig etter funksjonstype.
• For å kunne adressere individuelle elementer, kreves deres element-ID. Dette finner du i VISION i elementegenskaper-menyen eller kan også leses direkte fra dataene som vises foran hvert tilgjengelige element i det generelle abonnementet til MQTT Explorer (elementene der er oppført alfabetisk etter element-ID).

Konfigurasjon for API-tilgang

KONFIGURERE VISJON FOR API-BRUKERTILGANG

I VISION som administrator, gå til Konfigurasjon – Bruker/API-tilgangsadministrasjon, klikk på Brukere/API-tilgang og høyreklikk på API-bruker (eller trykk og hold) for å åpne redigeringsvinduet. Der finner du disse parameterne og dataene

• Aktiver (avmerkingsboks)
  • Brukeren aktiveres først her. Standard er deaktivert
• Brukernavn
  • Denne strengen kreves for tilgang via API – kopier den herfra
• Passord
  • Denne strengen kreves for tilgang via API – kopier den herfra
• Tillatelser
  • Standardrettighetene for å lese og skrive verdiene til VISION-elementene kan defineres her, det vil si at det som er definert her gjelder for alle eksisterende og fremtidige elementer. Hvis du kun vil tillate tilgang til individuelle elementer, bør du ikke endre disse standardrettighetene

TILLATELSER PÅ INDIVIDUELLE ELEMENTER

Det anbefales at du ikke gir API-tilgang til hele prosjektet, men kun til de ønskede elementene. Fortsett som følger

1. logg inn på VISION som administrator
2. velg ønsket element og åpne innstillingsmenyen (høyreklikk eller hold inne, deretter Innstillinger)
3. under menyoppføringen Generelt – Tillatelser, aktiver «Overstyr standardtillatelser» og gå deretter til underpunktet Tillatelser, som viser tillatelsesmatrisen.
4. aktiver kontrolltillatelsen her, som også aktiverer view tillatelse direkte. Hvis du kun ønsker å lese data via API-tilgangen, er det tilstrekkelig å aktivere view tillatelse.
5. gjenta samme prosedyre for alle elementene du vil ha tilgang til

Tilkobling via MQTT

INTRODUKSJON

Som eksample, vil vi demonstrere tilgang via MQTT API til DIVUS KNX IQ med en relativt enkel, gratis programvare kalt MQTT Explorer (se kap. 1.1), som er tilgjengelig for Windows, Mac og Linux. En grunnleggende kunnskap og erfaring med MQTT er underforstått.

DATA KREVES FOR TILKOBLING

Som nevnt tidligere (se avsnitt 2.1), kreves brukernavnet og passordet til API-brukeren. Her er en overview av alle dataene som må samles inn før en tilkobling opprettes:

• Brukernavn Les opp på detaljsiden til API-brukeren
• Passord Les opp på detaljsiden til API-brukeren
• IP-adresse Les opp i launcher-innstillingene under Generelt – Nettverk – Ethernet (eller via Synchronizer)
• Port 8884 (denne porten er reservert for dette formålet)

FØRSTE TILKOBLING MED MQTT EXPLORER OG GENERELL ABONNEMENT

Normalt skiller MQTT mellom aktivitetene som abonnerer på og publiserer. MQTT Explorer forenkler dette ved automatisk å abonnere på alle tilgjengelige emner (emnenummer) når den første tilkoblingen er opprettet. Som et resultat kan treet som fører til alle tilgjengelige elementer (dvs. API-brukertilgang gitt) sees direkte i venstre område av MQTT Explorer-vinduet etter en vellykket tilkobling. For å legge inn flere abonnementsemner eller erstatte # med et mer spesifikt emne, gå til Avansert i tilkoblingsvinduet. Emnet som vises øverst til høyre ser omtrent slik ut:

der 7f4x0607849x444xxx256573x3x9x983 er API-brukernavnet og objects_list inneholder alle de tilgjengelige elementene. Dette emnet holdes alltid oppdatert, dvs. eventuelle verdiendringer reflekteres der i sanntid. Hvis du kun ønsker å abonnere på individuelle elementer, skriv inn element-IDen til ønsket element etter objects_list/.

Merk: Denne typen abonnement tilsvarer omtrent logikken bak KNX-tilbakemeldingsadressene; den viser gjeldende status for elementene og kan brukes til å sjekke om de ønskede endringene har blitt implementert. Hvis du kun ønsker å lese opp data, men ikke endre det, er denne typen abonnement tilstrekkelig.

Et enkelt enkelt element ser omtrent slik ut i JSON-notasjon

Merk: Alle verdier har syntaksen vist ovenfor, f.eks. { “verdi”: “1” } som utdata fra abonnentemnene, mens verdien skrives direkte i nyttelasten for å endre en verdi (dvs. for publiseringsemner) – parentesene og "verdi" er utelatt, f.eks. "på": "1".

Avanserte kommandoer

INTRODUKSJON

Det er 3 typer emner generelt:

1. Abonner på emne(r) for å se de tilgjengelige elementene og for å få sanntidsverdiendringer
2. Abonner på emne(r) for å få svar på (klientene ) publisere forespørsler
3. Publiser emne(r) for å få eller sette elementer med verdiene deres

Vi skal senere referere til disse typene ved hjelp av nummereringen vist her (f.eks. emner av type 1, 2, 3). Flere detaljer i de følgende avsnittene og i kap. 4.2.

ABONNER EMNER FOR Å SE DE TILGJENGELIGE ELEMENTENE OG FOR Å FÅ VERDIENDRINGER I SANNTID

Disse er allerede beskrevet

ABONNER EMNER FOR Å FÅ SVARENE PÅ KLIENTENS PUBLISERINGSFORSPØRSEL

Denne typen emner er valgfrie. Det tillater

• åpne en unik kommunikasjonskanal med MQTT-serveren ved å bruke en vilkårlig client_id. Mer om det i kap. 4.2.2
• få resultatet av publiseringsforespørsler om det tilsvarende abonnementsemnet: suksess eller fiasko med feilkode og melding.

Det er forskjellige emner å få svar å få eller å angi publiseringskommandoer. Den tilsvarende forskjellen i Når du har fått de nødvendige emnene for systemet ditt rett, kan du bestemme deg for å fjerne dette trinnet og bruke publiseringsemner direkte.

 PUBLISERE EMNER FOR Å FÅ ELLER FOR Å SETTE ELEMENTER MED VERDENE DERES

Disse emnene bruker en bane som ligner på de for å abonnere - den eneste endringen er ordet "forespørsel" i stedet for "statusen" som brukes til å abonnere. Fullstendige emnestier vises senere i kap. 4.2.2\ Et get-emne vil be om å lese MQTT-serverens elementer og verdier. Nyttelasten kan brukes til å filtrere basert på funksjonstypen til elementene. Et angitt emne vil be om å endre noen deler av et element, som beskrevet i nyttelasten.

PREFIKS FOR KOMMANDOER OG TILSVARENDE SVAR

 KORT FORKLARING

Alle kommandoer som sendes til MQTT-serveren har en felles innledende del, nemlig:

DETALJERT FORKLARING

Sanntidsemnene (type 1) vil ha det generelle prefikset (se ovenfor) etterfulgt av

or

For innstilte kommandoer spiller nyttelasten selvsagt hovedrollen da den vil inneholde de ønskede endringene (dvs. endrede verdier for elementets funksjoner). En advarsel: Bruk aldri beholde-alternativet i type 3-kommandoer, da det kan forårsake problemer på KNX-siden.

EXAMPLE: PUBLISERE FOR ENDRING AV ET ENKELT ELEMENTS VERDI(ER)

Det enkleste tilfellet er å ønske å endre verdien på et av elementene som vises av den generelle abonnementet.
Generelt sett består endring/bytte av en funksjon av VISION via MQTT av 3 trinn, som ikke alle er absolutt nødvendige, men vi anbefaler likevel å utføre dem som beskrevet.

1. Emnet som inneholder funksjonen vi ønsker å redigere, abonneres med en tilpasset client_id
2. Emnet for redigering publiseres sammen med nyttelasten med de ønskede endringene ved å bruke client_id valgt i 1.
3. For å sjekke kan du så se svaret i emne (1.) – altså om (2.) fungerte eller ikke
4. I det generelle abonnementet, hvor alle verdier oppdateres når det gjøres endringer, kan du se ønsket(e) verdiendring(er) dersom alt har fungert bra.

Fremgangsmåten for å gjøre dette er:

1. velg en client_id, f.eks. "Divus", og sett den inn i banen etter API-brukernavnet
   Dette er det komplette emnet for å abonnere på din egen kommunikasjonskanal med MQTT-serveren. Dette forteller serveren hvor du forventer svar på endringene du har tenkt å sende. Legg merke til status/sett-delen som definerer en. at det er et abonnentemne og b. at den vil få svar på innstilte typekommandoer.
2. Publiseringsemnet vil være det samme bortsett fra at du bytter statusforespørselsøkeord
3. hva endringen skal bestå av står skrevet i nyttelasten. Her er noen eksamples.
   • Slå av et element som har av/på-funksjonen (1 bit):
   • Slå på et element som har av/på-funksjon (1 bit). I tillegg, hvis flere slike kommandoer startes fra samme klient, kan uuid-parameteren ("unik ID", er vanligvis en 128-bits streng formatert som 8-4-4-4-12 siffer hex) brukes til å tilordne svar på den tilsvarende spørringen, da denne parameteren – hvis den er til stede i spørringen – også finnes i svaret.
   • Slå på og stille inn lysstyrken til en dimmer til 50 %
   • Svaret på emnet som er vist og abonnert på ovenfor (nyttelasten, for å være presis) er da f.eks.ample.
     Svaret ovenfor er et eksample ved riktig nyttelast, selv om elementet ikke har noen dimmefunksjon. Hvis det er mer alvorlige problemer som fører til at nyttelasten ikke tolkes riktig, vil svaret se slik ut (f.eks.):
     for en forklaring av feilkoder og meldinger, men generelt, som for http, er 200 koder positive svar mens 400 er negative.

EXAMPLE: PUBLISERE FOR ENDRING AV FLERE ELEMENTVERDIER

Prosedyren er lik den som er vist før for å endre et enkelt element. Forskjellen er at du utelater element_id fra emnene og deretter angir settet med element_ids foran dataene inne i nyttelasten. Se syntaks og struktur nedenfor.

FILTER ETTER FUNKSJONSTYPE I SPØRSMÅL

Filterparameteren i nyttelasten tillater at bare ønsket funksjon(er) til et element adresseres. På/av-funksjonen til en bryter eller dimmer kalles "onoff", for eksempelample, og det tilsvarende filteret er definert på denne måten:

Svaret ser da slik ut, f.eksample

Den firkantede parentesen indikerer at du også kan filtrere etter flere funksjoner, f.eks

fører til et svar som dette:

Vedlegg

FEILKODER

Feil i MQTT-kommunikasjon resulterer i en numerisk kode. Følgende tabell hjelper til med å bryte den ned.

PARAMETRE FOR NYTTELAST

Nyttelasten støtter forskjellige parametere avhengig av konteksten. Tabellen nedenfor viser hvilke parametere som kan forekomme i hvilke emner

VERSJONSMERKER

• 1.00 VERSJON

Nyheter:

• Første utgivelse