Software-ul DIVUS VISION API
Specificații
- Produs: DIVUS VISION API
- Producator: DIVUS GmbH
- Versiune: 1.00 REV0 1 – 20240528
- Locație: Pillhof 51, Eppan (BZ), Italia
Informații despre produs
DIVUS VISION API este un instrument software conceput pentru interfața cu sistemele DIVUS VISION. Permite utilizatorilor să acceseze și să controleze diverse elemente din sistem folosind protocoale MQTT.
FAQ
Î: Pot folosi API-ul DIVUS VISION fără cunoștințe prealabile despre PC sau tehnologia de automatizare?
R: Manualul este conceput pentru utilizatorii cu cunoștințe anterioare în aceste domenii pentru a asigura utilizarea eficientă a API-ului.
INFORMAȚII GENERALE
- DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – Italia
Instrucțiunile de utilizare, manualele și software-ul sunt protejate prin drepturi de autor. Toate drepturile rezervate. Copierea, duplicarea, traducerea, traducerea integrală sau parțială nu este permisă. O excepție se aplică pentru crearea unei copii de rezervă a software-ului pentru uz personal.
Manualul poate fi modificat fără notificare. Nu putem garanta că datele conținute în acest document și pe mediile de stocare furnizate sunt lipsite de erori și corecte. Sugestiile de îmbunătățiri, precum și sugestiile privind erorile sunt întotdeauna binevenite. Acordurile se aplică și anexelor specifice la acest manual. Denumirile din acest document pot fi mărci comerciale a căror utilizare de către terți în scopuri proprii poate încălca drepturile proprietarilor lor. Instrucțiuni pentru utilizator: Vă rugăm să citiți acest manual înainte de a-l utiliza pentru prima dată și păstrați-l într-un loc sigur pentru referințe ulterioare. Grup țintă: manualul este scris pentru utilizatorii cu cunoștințe anterioare despre PC și tehnologia de automatizare.
CONVENȚII DE PREZENTARE
Introducere
INTRODUCERE GENERALĂ
Acest manual descrie VISION API (Application Programming Interface) – o interfață prin care VISION poate fi adresat și controlat de la sisteme externe.
În termeni practici, aceasta înseamnă că puteți utiliza sisteme precum
- MQTT Explorer (https://www.microsoft.com/store/… – pentru testare),
- Asistent acasă (https://www.home-assistant.io/) sau
- Nod-RED (https://nodered.org/)
pentru a controla elementele gestionate de VISION sau a citi starea acestora. Accesul și comunicarea au loc prin protocolul MQTT, care utilizează așa-numitele subiecte pentru a aborda funcții individuale sau seturi de funcții sau pentru a fi informat cu privire la modificările aduse acestora. În acest scop este utilizat un server (broker) MQTT, care se ocupă de securitate și de gestionarea/distribuirea mesajelor către participanți. În acest caz, serverul MQTT se află direct pe DIVUS KNX IQ și este configurat special în acest scop. Deși API-ul VISION poate fi folosit și fără cunoștințe de programare, această funcționalitate este potrivită pentru utilizatorii avansați.
CERINTE
După cum se explică în manualul VISION, utilizatorul API trebuie mai întâi activat în mod implicit pentru a-l putea folosi, accesul API funcționează numai folosind datele de autentificare ale utilizatorilor Api. În ceea ce privește drepturile utilizatorului, activarea pentru această funcționalitate poate fi apoi configurată fie pe toate, fie pe elemente individuale. Vezi Cap.0. Desigur, ai nevoie și de un proiect VISION în care elementele pe care vrei să le controlezi din exterior să fie complet configurate și conexiunea la acestea să fie testată cu succes. Pentru a putea adresa elemente individuale prin API, ID-ul elementului lor trebuie să fie cunoscut: acesta este afișat în partea de jos a formularului de setări al elementului
SECURITATE
Din motive de securitate, accesul la API este posibil doar local (adică nu prin cloud). Riscul de securitate la activarea accesului API este, prin urmare, scăzut. Cu toate acestea, elementele relevante pentru securitate nu ar trebui să fie activate sau refuzate în mod explicit pentru accesul API.
MQTT ȘI TERMENII SĂI – SCURTĂ EXPLICAȚIE
În MQTT, rolul de gestionare centralizată și de distribuție a tuturor mesajelor este acela al brokerului. Deși serverul MQTT și brokerul MQTT nu sunt sinonime (server este un termen mai larg pentru un rol pe care îl pot juca și clienții MQTT), brokerul este întotdeauna menționat în acest manual atunci când este menționat serverul MQTT. Însuși DIVUS KNX IQ joacă rolul de broker MQTT / server MQTT în contextul acestui manual.
Un server MQTT folosește așa-numitele subiecte: o structură ierarhică cu care datele sunt clasificate, gestionate și publicate.
Publicarea are scopul principal de a pune datele la dispoziția celorlalți participanți prin intermediul subiectelor. Dacă doriți să schimbați o valoare, scrieți la subiectul dorit împreună cu modificarea valorii dorite, folosind și o acțiune de publicare. Dispozitivul țintă sau serverul MQTT citește modificarea dorită care îl afectează și o adoptă în consecință. Pentru a verifica dacă modificarea a fost aplicată, puteți căuta în subiectul abonat în timp real pentru a vedea dacă modificarea se reflectă acolo – dacă totul a funcționat bine.
Clienții selectează subiectele care îi interesează: aceasta se numește abonare. De fiecare dată când o valoare se schimbă în/sub un subiect, toți clienții abonați sunt informați – adică fără a fi nevoie să întrebați în mod explicit dacă ceva s-a schimbat sau care este valoarea curentă.
Puteți deschide (sau adresa) un canal de comunicare separat cu serverul MQTT introducând orice șir unic numit client_id într-un subiect. Client_id trebuie utilizat în subiect pentru a procesa valori. Aceasta servește la identificarea originii fiecărei modificări, ajută la orice erori și nu afectează ceilalți clienți, deoarece răspunsurile corespunzătoare de la server, inclusiv orice coduri de eroare și mesaje, ajung la subiect doar cu același client_id (și astfel numai acel client). Client_id este un șir de caractere unic format din orice combinație de caractere 0-9, az, AZ, „-“, „_”.
În general, subiectele de abonare ale serverului MQTT al DIVUS KNX IQ conțin starea cuvântului cheie, în timp ce subiectele de publicare conțin cererea de cuvânt cheie. Cele cu statut sunt actualizate automat de îndată ce există o modificare externă a valorii sau de îndată ce o schimbare de valoare a fost solicitată de către client însuși printr-o publicare și a fost aplicată cu succes. Cele pentru publicare sunt împărțite în continuare în cele de tip (request/)get și cele de tip (request/)set.
Modificările de valoare și alți parametri opționali sunt adăugați la subiect cu așa-numita sarcină utilă. Parametrii elementelor individuale (element-id, nume, tip, funcții)
Principala diferență dintre MQTT și modelul clasic client-server, în care clientul solicită și apoi schimbă date, este centrată pe conceptele de abonare și publicare. Participanții pot publica datele, punându-le la dispoziția altora, care, dacă sunt interesați, se pot abona la acestea. Această arhitectură face posibilă minimizarea schimbului de date și menținerea tuturor părților interesate la zi. Mai multe despre detalii aici: și parametri speciali (uuid, filtre) vor fi utilizați aici. Deși există mai multe opțiuni, sarcina utilă este afișată formatat ca JSON în acest manual. JSON folosește paranteze și virgule pentru a reprezenta date de orice structură și astfel minimizează dimensiunea pachetelor de date care trebuie transmise. Mai multe detalii despre încărcături utile pot fi găsite mai târziu în manual.
Pentru scopuri speciale, este posibil să se filtreze în funcție de tipul de funcție, de exemplu să se adreseze doar pornit/oprit, adică comutatoare pe 1 bit. Parametrul filtre din sarcina utilă este utilizat în acest scop. În prezent, filtrarea este posibilă numai după tipul funcției.
Pentru a putea adresa elemente individuale, este necesar ID-ul elementului acestora. Acesta poate fi găsit în VISION în meniul de proprietăți ale elementului sau poate fi citit direct din datele care sunt afișate în fața fiecărui element disponibil în abonamentul general al MQTT Explorer (elementele de acolo sunt listate alfabetic după ID-ul elementului).
Configurare pentru accesul API
CONFIGURARE VISION PENTRU ACCESUL UTILIZATORULUI API
În VISION ca administrator, accesați Configurare – Gestionare acces utilizator/API, faceți clic pe Utilizatori/acces API și faceți clic dreapta pe Utilizator API (sau apăsați lung) pentru a deschide fereastra de editare. Acolo veți găsi acești parametri și date
- Activați (caseta de selectare)
- Utilizatorul este mai întâi activat aici. Implicit este dezactivat
- Nume de utilizator
- Acest șir este necesar pentru acces prin API - copiați-l de aici
- Parolă
- Acest șir este necesar pentru acces prin API - copiați-l de aici
- Permisiuni
- Drepturile implicite pentru citirea și scrierea valorilor elementelor VISION pot fi definite aici, adică ceea ce este definit aici se aplică tuturor elementelor existente și viitoare. Dacă doriți să permiteți doar accesul la elemente individuale, nu ar trebui să modificați aceste drepturi implicite
PERMISIUNI PE ELEMENTE INDIVIDUALE
Este recomandat să nu acordați acces API la întregul proiect, ci doar la elementele dorite. Procedați după cum urmează
- conectați-vă la VISION ca administrator
- selectați elementul dorit și deschideți meniul de setări (dați clic dreapta sau mențineți apăsat, apoi Setări)
- sub intrarea din meniu General – Permisiuni, activați „Înlocuire permisiunile implicite” și apoi accesați sub-elementul Permisiuni, care arată matricea de permisiuni.
- activați aici permisiunea de control, care activează și view permisiunea direct. Dacă doriți să citiți date doar prin accesul API, este suficient să activați view permisiune.
- repetați aceeași procedură pentru toate elementele pe care doriți să le accesați
Conexiune prin MQTT
INTRODUCERE
Ca un example, vom demonstra accesul prin API-ul MQTT al DIVUS KNX IQ cu un software relativ simplu, gratuit, numit MQTT Explorer (vezi cap. 1.1), care este disponibil pentru Windows, Mac și Linux. Sunt implicate cunoștințe și experiență de bază cu MQTT.
DATE NECESARE PENTRU CONECTARE
După cum sa menționat mai devreme (a se vedea secțiunea 2.1), sunt necesare numele de utilizator și parola utilizatorului API. Iată o terminareview dintre toate datele care trebuie colectate înainte de stabilirea unei conexiuni:
- Nume de utilizator Citiți pe pagina de detalii a utilizatorului API
- Parola Citiți pe pagina de detalii a utilizatorului API
- Adresa IP Citiți în setările lansatorului sub General – Rețea – Ethernet (sau prin sincronizator)
- Port 8884 (acest port este rezervat pentru acest scop)
PRIMA CONEXIUNE CU MQTT EXPLORER ȘI SUBSCRIBE GENERAL
În mod normal, MQTT distinge între activitățile de abonare și de publicare. MQTT Explorer simplifică acest lucru prin abonarea automată la toate subiectele disponibile (subiectul #) atunci când se realizează prima conexiune. Drept urmare, arborele care duce la toate elementele disponibile (adică accesul utilizatorului API acordat) poate fi văzut direct în zona din stânga a ferestrei MQTT Explorer după o conexiune reușită. Pentru a introduce subiecte de abonare suplimentare sau pentru a înlocui # cu un subiect mai specific, accesați Avansat în fereastra de conexiune. Subiectul afișat în dreapta sus arată cam așa:
unde 7f4x0607849x444xxx256573x3x9x983 este numele de utilizator API și objects_list conține toate elementele disponibile. Acest subiect este întotdeauna actualizat, adică orice modificare a valorii este reflectată acolo în timp real. Dacă doriți să vă abonați doar la elemente individuale, introduceți ID-ul elementului dorit după listă_obiecte/.
Notă: Acest tip de abonament corespunde aproximativ logicii din spatele adreselor de feedback KNX; arată starea curentă a elementelor și poate fi folosit pentru a verifica dacă modificările dorite au fost aplicate cu succes. Dacă doriți doar să citiți datele, dar nu să le modificați, acest tip de abonament este suficient.
Un singur element simplu arată cam așa în notația JSON
Notă: Toate valorile au sintaxa prezentată mai sus, de exemplu { „valoare”: „1” } ca rezultat al subiectelor de abonare, în timp ce valoarea este scrisă direct în încărcarea utilă pentru a schimba o valoare (adică pentru subiecte de publicare) – parantezele și „valoare” sunt omise, de exemplu, „onoff”: „1”.
Comenzi avansate
INTRODUCERE
Există 3 tipuri de subiecte în general:
- Abonați-vă la subiecte pentru a vedea elementele disponibile și pentru a obține modificări ale valorii în timp real
- Abonați-vă la subiecte pentru a obține răspunsuri la (clientii ) publică cereri
- Publicați subiecte pentru a obține sau pentru a seta elemente cu valorile lor
Mai târziu ne vom referi la aceste tipuri folosind numerotarea prezentată aici (de ex. subiecte de tip 1, 2, 3). Mai multe detalii în secțiunile următoare și în cap. 4.2.
ABONAȚI-VĂ SUBIECTELE PENTRU A VEDE ELEMENTELE DISPONIBILE ȘI PENTRU A OBȚINE MODIFICĂRI DE VALOARE ÎN TIMP REAL
Acestea au fost deja descrise
ABONAȚI-VĂ SUBIECTELE PENTRU A OBȚI RĂSPUNSURILE LA CERERI DE PUBLICARE ALE CLIENTULUI
Acest tip de subiecte este opțional. Acesta permite
- deschideți un canal de comunicare unic cu serverul MQTT utilizând un client_id arbitrar. Mai multe despre asta în cap. 4.2.2
- obțineți rezultatul solicitărilor de publicare pe subiectul de abonare corespunzător: succes sau eșec cu cod de eroare și mesaj.
Există diferite subiecte pentru a obține răspunsuri pentru a obține sau pentru a seta comenzi de publicare. Diferența corespunzătoare în
Odată ce obțineți clar subiectele necesare pentru sistemul dvs., puteți decide să eliminați acest pas și să utilizați direct subiectele de publicare.
PUBLICAȚI SUBIECTE PENTRU A OBȚINE SAU A SETARE ELEMENTE CU VALORILE LOR
Aceste subiecte folosesc o cale similară cu cele pentru abonare – singura modificare este cuvântul „cerere” în locul „starea” folosită pentru abonare. Căile complete ale subiectelor sunt prezentate mai târziu în cap. 4.2.2\ Un subiect get va solicita citirea elementelor și valorilor serverului MQTT. Sarcina utilă poate fi utilizată pentru a filtra în funcție de tipul de funcție al elementelor. Un subiect stabilit va solicita modificarea unor părți ale unui element, așa cum este detaliat în sarcina sa utilă.
PREFIX PENTRU COMENZI ȘI RĂSPUNSURI CORESPONDENTE
SCURTĂ EXPLICAȚIE
Toate comenzile care sunt trimise către serverul MQTT au o parte inițială comună, și anume:
EXPLICAȚIE DETALIATĂ
Subiectele în timp real (tip 1) vor avea prefixul general (vezi mai sus) apoi urmat de
or
Pentru comenzile setate, sarcina utilă joacă, evident, rolul principal, deoarece va conține modificările dorite (adică valorile modificate pentru funcțiile elementului). A Avertisment: Nu utilizați niciodată opțiunea de păstrare în comenzile dvs. de tip 3, deoarece poate cauza probleme în partea KNX.
EXAMPLE: PUBLICAȚI PENTRU SCHIMBAREA VALORILOR UNUI ELEMENT
Cel mai simplu caz este să vrei să schimbi valoarea unuia dintre elementele afișate de abonamentul general.
În general, schimbarea/schimbarea unei funcții a VISION prin MQTT constă din 3 pași, nu toți dintre care sunt absolut necesari, dar totuși recomandăm să le efectuați așa cum este descris.
- Subiectul care conține funcția pe care dorim să o edităm este abonat folosind un client_id personalizat
- Subiectul pentru editare este publicat împreună cu încărcarea utilă cu modificările dorite folosind client_id-ul ales în 1.
- Pentru a verifica, puteți vedea apoi răspunsul în subiectul (1.) – adică dacă (2.) a funcționat sau nu
- În abonamentul general, unde toate valorile sunt actualizate atunci când se fac modificări, puteți vedea modificările dorite ale valorii dacă totul a funcționat bine.
Pașii pentru a face acest lucru sunt:
- selectați un client_id, de exemplu, „Divus” și inserați-l în calea după numele de utilizator API
Acesta este subiectul complet pentru abonamentul la propriul canal de comunicare cu serverul MQTT. Aceasta îi spune serverului unde așteptați răspunsurile la modificările pe care intenționați să le trimiteți. Observați partea de stare/set care definește a. că este un subiect de abonare și b. că va primi răspunsuri pentru a seta comenzi de tip. - Subiectul de publicare va fi același, cu excepția schimbării cuvintelor cheie de solicitare de stare
- în ce ar trebui să constea modificarea este scris în sarcina utilă. Iata cativa examples.
- Oprirea unui element care are funcția de pornire/oprire (1 bit):
- Pornirea unui element care are funcția de pornire/oprire (1 bit). În plus, dacă mai multe astfel de comenzi sunt pornite de la același client, parametrul uuid („ID unic”, este de obicei un șir de 128 de biți formatat ca hex de 8-4-4-4-12 cifre) poate fi folosit pentru a atribui răspuns la interogarea corespunzătoare, deoarece acest parametru – dacă este prezent în interogare – poate fi găsit și în răspuns.
- Pornirea și setarea luminozității unui dimmer la 50%
- Răspunsul la subiectul prezentat și la care s-a abonat mai sus (sarcina sa utilă, mai exact) este atunci, de exempluample.
Răspunsul de mai sus este un example în cazul unei sarcini utile corecte, deși elementul nu are funcție de reglare a luminii. Dacă există probleme mai grave care fac ca sarcina utilă să nu fie interpretată corect, răspunsul va arăta astfel (de exemplu):
pentru o explicație a codurilor de eroare și a mesajelor, dar în general, ca și pentru http, 200 de coduri sunt răspunsuri pozitive, în timp ce 400 sunt negative.
- Oprirea unui element care are funcția de pornire/oprire (1 bit):
EXAMPLE: PUBLICARE PENTRU SCHIMBAREA VALORILOR MULTIPLE ELEMENTE
Procedura este similară cu cea prezentată anterior pentru a schimba un singur element. Diferența este că omiteți element_id din subiecte și apoi indicați setul de element_ids în fața datelor din interiorul încărcăturii utile. Vezi mai jos sintaxa și structura.
FILTRAȚI DUPĂ TIP DE FUNCȚIE ÎN ÎNTREBĂRI
Parametrul de filtre din sarcina utilă permite adresarea numai a funcțiilor dorite ale unui element. Funcția de pornire/oprire a unui comutator sau variator se numește „onoff”, de example, iar filtrul corespunzător este definit în acest fel:
Răspunsul arată astfel, de example
Paranteza pătrată indică faptul că puteți filtra și după mai multe funcții, de ex
duce la un răspuns ca acesta:
Apendice
CODURI DE EROARE
Erorile în comunicarea MQTT au ca rezultat un cod numeric. Următorul tabel ajută la defalcarea acestuia.
PARAMETRII SARCINII UTILE
Sarcina utilă acceptă diferiți parametri în funcție de context. Următorul tabel arată ce parametri pot apărea în ce subiecte
NOTE DE VERSIUNE
- 1.00 VERSIUNEA
Ştiri:
• Prima publicație
Documente/Resurse
 |
Software-ul DIVUS VISION API [pdfManual de utilizare VISION API Software, API Software, Software |
 |
Software-ul DIVUS Vision API [pdfGhid de utilizare Vision API Software, Vision, API Software, Software |