DIVUS VISION API Software

spésifikasi

• Produk: DIVUS VISION API
• Produsén: DIVUS GmbH
• Vérsi: 1.00 REV0 1 - 20240528
• lokasi: Pillhof 51, Eppan (BZ), Italia

Émbaran produk

DIVUS VISION API mangrupikeun alat parangkat lunak anu dirancang pikeun ngahubungkeun sareng sistem DIVUS VISION. Hal ieu ngamungkinkeun pamaké pikeun ngakses jeung ngadalikeun sagala rupa elemen dina sistem ngagunakeun protokol MQTT.

FAQ

Q: Dupi abdi tiasa nganggo DIVUS VISION API tanpa pangaweruh sateuacanna ngeunaan PC atawa téhnologi automation?

A: Manual ieu tailored pikeun pamaké kalawan pangaweruh saméméhna di wewengkon ieu pikeun mastikeun pamakéan efisien API.

INPORMASI UMUM

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

Parentah operasi, manual jeung software ditangtayungan ku hak cipta. Sadaya hak disimpen. Niron, duplikasi, narjamahkeun, narjamahkeun sadayana atanapi sabagian henteu diidinan. Pangecualian berlaku pikeun nyiptakeun salinan cadangan parangkat lunak pikeun panggunaan pribadi.
Manual bisa dirobah tanpa aya bewara. Kami henteu tiasa ngajamin yén data anu aya dina dokumén ieu sareng dina média panyimpen anu disayogikeun teu aya kasalahan sareng leres. Saran pikeun perbaikan ogé petunjuk ngeunaan kasalahan sok ditampi. Kasapukan ogé lumaku pikeun annexes husus pikeun manual ieu. Sebutan dina dokumén ieu tiasa janten mérek dagang anu dianggo ku pihak katilu pikeun tujuanana nyalira tiasa ngalanggar hak anu gaduhna. Parentah Pamaké: Mangga baca manual ieu saméméh ngagunakeun pikeun kahiji kalina tur nyimpen dina tempat anu aman pikeun rujukan ka hareup. Grup sasaran: Manual ieu ditulis pikeun pamaké kalawan pangaweruh saméméhna PC na automation téhnologi.

Konvénsi presentasi

Bubuka

PENDAHULUAN UMUM

Manual ieu ngajelaskeun API VISION (Application Programming Interface) - antarbeungeut nu ngaliwatan VISION bisa kajawab tur dikawasa tina sistem éksternal.
Dina istilah praktis, ieu ngandung harti yén anjeun tiasa nganggo sistem sapertos

• MQTT Explorer (https://www.microsoft.com/store/… – pikeun nguji),
• Asisten imah (https://www.home-assistant.io/) atawa
• Node-BEureum (https://nodered.org/)

pikeun ngontrol elemen anu dikelola ku VISI atanapi maca statusna. Aksés jeung komunikasi lumangsung ngaliwatan protokol MQTT, nu ngagunakeun disebut jejer pikeun alamat fungsi individu atawa susunan fungsi atawa jadi informed ngeunaan parobahanana. Hiji server MQTT (calo) dipaké pikeun tujuan ieu, nu handles kaamanan sarta manajemén / distribusi pesen ka pamilon. Dina hal ieu, server MQTT lokasina langsung dina DIVUS KNX IQ sarta husus ngonpigurasi keur kaperluan ieu. Sanajan API VISION ogé bisa dipaké tanpa pangaweruh programming, fungsionalitas ieu cocog pikeun pamaké canggih.

SYARAT

Sakumaha anu dijelaskeun dina manual VISION, pangguna API kedah sacara standar diaktipkeun heula supados tiasa ngagunakeun éta aksés API ngan ukur tiasa dianggo nganggo data auténtikasi pangguna Api. Sajauh hak pamaké prihatin, aktivasina pikeun fungsionalitas ieu lajeng bisa ngonpigurasi boh dina sakabéh atawa dina elemen individu. Tempo Chap.0. Tangtosna, anjeun ogé peryogi proyék VISION dimana unsur-unsur anu anjeun hoyong kendalikeun ti luar parantos dikonpigurasi sareng sambungan ka aranjeunna parantos diuji. Pikeun tiasa alamat elemen individu via API, ID unsur maranéhanana kudu dipikawanoh: ieu dipintonkeun di handapeun formulir setelan unsur.

KAAMANAN

Pikeun alesan kaamanan, aksés API ngan mungkin sacara lokal (ie henteu ngaliwatan awan). Résiko kaamanan nalika ngaktipkeun aksés API jadi low. Tapi, elemen anu aya hubunganana sareng kaamanan henteu kedah diaktipkeun atanapi ditolak sacara eksplisit pikeun aksés API.

MQTT JEUNG SYARAT na - panjelasan singket

• Dina MQTT, peran manajemén terpusat sareng distribusi sadaya pesen nyaéta calo. Sanajan server MQTT na calo MQTT teu sinonim (server mangrupakeun istilah lega pikeun peran anu klien MQTT ogé bisa maénkeun), calo nu salawasna dimaksudkeun dina manual ieu lamun server MQTT disebutkeun. DIVUS KNX IQ sorangan maénkeun peran calo MQTT / server MQTT dina konteks manual ieu.
• Pangladén MQTT nganggo anu disebut topik: struktur hirarki anu datana digolongkeun, dikokolakeun sareng diterbitkeun.
• Publishing boga tujuan utama sangkan data sadia pikeun pamilon séjén ngaliwatan jejer. Upami anjeun hoyong ngarobih nilai, anjeun nyerat kana topik anu dipikahoyong sareng parobahan nilai anu dipikahoyong, ogé nganggo tindakan penerbitan. Alat target atanapi server MQTT maca parobahan anu dipikahoyong anu mangaruhan éta sareng ngadopsi éta sasuai. Pikeun pariksa yén parobihan parantos diterapkeun, anjeun tiasa ningali dina topik real-time anu ngalanggan pikeun ningali naha parobahanana ditingalikeun di dinya - upami sadayana parantos jalan.
• Klién milih topik anu dipikaresep ku aranjeunna: ieu disebut ngalanggan. Unggal waktos nilai robah dina / handap topik, sadaya klien ngalanggan anu informed - ie tanpa kudu eksplisit nanya naha hal geus robah atawa naon nilai ayeuna.
• Anjeun tiasa muka (atawa alamat) saluran komunikasi misah jeung server MQTT ku cara nuliskeun string unik nu disebut client_id dina topik. client_id kedah dianggo dina topik pikeun ngolah nilai. Ieu fungsi pikeun ngaidentipikasi asal unggal robah, mantuan jeung kasalahan naon jeung teu mangaruhan klien sejenna, sakumaha réspon pakait ti server, kaasup sagala Konci kasalahan jeung pesen, ogé ngan ngahontal topik jeung client_id sarua (sahingga ngan klien éta). client_id mangrupakeun string karakter unik diwangun ku sagala kombinasi karakter 0-9, az, AZ, "-", "_".
• Sacara umum, jejer langganan server MQTT DIVUS KNX IQ ngandung status kecap konci, sedengkeun topik publikasi ngandung pamundut kecap konci. Jalma kalawan status otomatis diropéa pas aya parobahan nilai éksternal atawa pas robah nilai geus dipénta ku klien sorangan via nyebarkeun sarta geus hasil dilarapkeun. Pikeun penerbitan dibagi deui kana tipe (request/)get jeung tipe (request/)set.
• Parobihan nilai sareng parameter opsional sanésna ditambah kana topik anu disebut payload. Parameter tina elemen individu (unsur-id, ngaran, tipe, fungsi)

Beda utama antara MQTT sareng modél klien-server klasik, dimana klien naroskeun teras ngarobih data, dipuseurkeun kana konsép ngalanggan sareng nyebarkeun. Pamilon tiasa nyebarkeun data, janten sayogi pikeun batur, anu upami kabetot tiasa ngalanggan éta. Arsitéktur ieu ngamungkinkeun pikeun ngaleutikan bursa data sareng tetep ngamutahirkeun sadaya pihak anu kabetot. Langkung seueur ngeunaan detil di dieu: sareng parameter khusus (uuid, saringan) kedah dianggo di dieu. Sanajan aya sababaraha pilihan, payload ditémbongkeun formatna salaku JSON dina manual ieu. JSON nganggo tanda kurung sareng koma pikeun ngagambarkeun data tina struktur naon waé sahingga ngaminimalkeun ukuran pakét data anu bakal dikirimkeun. Langkung rinci ngeunaan payloads tiasa dipendakan engké dina manual.

• Pikeun tujuan husus, kasebut nyaéta dimungkinkeun pikeun nyaring nurutkeun jenis fungsi, misalna mun alamat ngan on / off ie saklar 1-bit. Parameter saringan dina payload dianggo pikeun tujuan ieu. Nyaring ayeuna ngan mungkin ku jinis fungsi.
• Pikeun tiasa alamat elemen individu, ID elemen maranéhanana diperlukeun. Ieu bisa kapanggih dina VISI dina menu sipat unsur atawa bisa ogé dibaca langsung tina data anu dipintonkeun di hareup unggal unsur sadia dina ngalanggan umum tina MQTT Explorer (elemen aya didaptarkeun alphabetically ku ID unsur).

Konfigurasi pikeun aksés API

Konfigurasi visi pikeun API pamaké AKSES

Dina VISION salaku administrator, buka Konfigurasi - Pamaké / Manajemén Aksés API, klik Pamaké / aksés API sareng klik katuhu dina Pamaké API (atanapi pencét sareng tahan) pikeun muka jandela éditan. Aya anjeun bakal mendakan parameter sareng data ieu

• Aktipkeun (kotak centang)
  • Pangguna diaktipkeun heula di dieu. Default ditumpurkeun
• Ngaran pamaké
  • string ieu diperlukeun pikeun aksés via API - nyalin ti dieu
• Sandi
  • string ieu diperlukeun pikeun aksés via API - nyalin ti dieu
• idin
  • Hak standar pikeun maca sareng nyerat nilai-nilai elemen VISI tiasa didefinisikeun di dieu, nyaéta naon anu didefinisikeun di dieu manglaku ka sadaya elemen anu aya sareng anu bakal datang. Upami anjeun ngan ukur hoyong ngawenangkeun aksés ka elemen individu, anjeun henteu kedah ngarobih hak standar ieu

IZIN ON UNSUR INDIVIDU

Disarankeun yén anjeun henteu masihan aksés API ka sadaya proyék, tapi ngan ukur pikeun elemen anu dipikahoyong. Neruskeun kieu

1. asup ka VISION salaku administrator
2. pilih unsur anu dipikahoyong sareng buka ménu setélanna (klik katuhu atanapi terus pencét, teras Setélan)
3. handapeun Éntri ménu Umum - Idin, aktipkeun "Nimpa idin standar" teras angkat ka sub-item Idin, anu nunjukkeun matriks idin.
4. Aktipkeun idin kontrol dieu, nu ogé ngamungkinkeun para view idin langsung. Upami anjeun ngan ukur hoyong maca data liwat aksés API, éta cekap pikeun ngaktipkeun view idin.
5. malikan prosedur anu sami pikeun sadaya elemen anu anjeun hoyong aksés

Sambungan via MQTT

BUBUKA

Salaku urutample, kami bakal demonstrate aksés via API MQTT tina DIVUS KNX IQ kalawan kawilang basajan, bebas software disebut MQTT Explorer (tingali chap. 1.1), nu sadia pikeun Windows, Mac jeung Linux. Pangaweruh sareng pangalaman dasar sareng MQTT tersirat.

DATA dibutuhkeun pikeun sambungan

Salaku disebutkeun tadi (tingali bagian 2.1), nu ngaran pamaké sarta sandi pamaké API diperlukeun. Di dieu hiji leuwihview sadaya data nu kudu dikumpulkeun saméméh sambungan dijieun:

• Ngaran pamaké Baca kaluar dina kaca detil ngeunaan pamaké API
• Sandi Baca kaluar dina kaca jéntré ngeunaan pamaké API
• Alamat IP Baca kaluar dina setélan launcher handapeun Umum - Network - Ethernet (atawa liwat Synchronizer)
• Port 8884 (port ieu ditangtayungan pikeun tujuan ieu)

Sambungan munggaran sareng MQTT EXPLORER sareng langganan umum

Biasana, MQTT ngabédakeun antara kagiatan ngalanggan sareng nyebarkeun. MQTT Explorer simplifies ieu ku otomatis ngalanggan ka sadaya jejer sadia (topik #) nalika sambungan munggaran dijieun. Hasilna, tangkal anu nuju ka sadaya elemen sadia (ie aksés pamaké API dibere) bisa ditempo langsung di wewengkon kénca-leungeun jandela MQTT Explorer sanggeus sambungan suksés. Pikeun nuliskeun jejer langganan salajengna atawa ngaganti # ku topik nu leuwih husus, buka Advanced dina jandela sambungan. Topik anu dipidangkeun di belah katuhu luhur sigana sapertos kieu:

dimana 7f4x0607849x444xxx256573x3x9x983 nyaéta ngaran pamaké API tur objects_list ngandung sakabéh elemen sadia. Topik ieu salawasna diteundeun up to date ie sagala parobahan nilai reflected aya sacara real-time. Upami anjeun ngan ukur hoyong ngalanggan elemen individu, lebetkeun ID unsur unsur anu dipikahoyong saatos objects_list/.

Catetan: Jenis langganan ieu kira-kira pakait sareng logika di balik alamat eupan balik KNX; eta nembongkeun status kiwari elemen sarta bisa dipaké pikeun pariksa naha parobahan nu dipikahoyong geus hasil dilarapkeun. Upami anjeun ngan ukur hoyong maca data tapi henteu ngarobih, jinis langganan ieu cekap.

Hiji unsur saderhana sigana sapertos kieu dina notasi JSON

Catetan: Sadaya nilai ngagaduhan sintaksis anu dipidangkeun di luhur contona {"nilai": "1" } salaku kaluaran tina jejer langganan, sedengkeun nilaina ditulis langsung dina payload pikeun ngarobih nilai (nyaéta pikeun nyebarkeun topik) - kurung sareng "Nilai" dileungitkeun misalna "onoff": "1".

Paréntah canggih

BUBUKA

Aya 3 rupa topik sacara umum:

1. Ngalanggan topik (s) pikeun ningali elemen sadia tur meunangkeun parobahan nilai real-time
2. Ngalanggan topik (s) pikeun meunangkeun jawaban kana (para klien ) medarkeun pamundut
3. Nyebarkeun topik (s) pikeun meunangkeun atawa nyetel elemen kalawan nilai maranéhanana

Urang engké bakal ngarujuk kana jinis-jinis ieu nganggo panomeran anu dipidangkeun di dieu (contona topik jinis 1, 2, 3). Leuwih jéntré dina bagian handap sarta dina chap. 4.2.

Ngalanggan Topik Pikeun Ningali Elemen Sadia sareng Pikeun Kéngingkeun Parobahan NILAI NYATA

Ieu parantos dijelaskeun

TOPIK SUBSCRIBE Pikeun Kéngingkeun Waleran Paménta Publikasi Klién

Topik jenis ieu opsional. Ieu ngamungkinkeun pikeun

• muka saluran komunikasi unik jeung server MQTT ku ngagunakeun hiji client_id sawenang. Langkung seueur ngeunaan éta dina chap. 4.2.2
• meunangkeun hasil tina medarkeun requests dina jejer ngalanggan pakait: kasuksésan atawa gagal jeung kode kasalahan jeung talatah.

Aya topik anu béda pikeun kéngingkeun jawaban atanapi nyetél paréntah nyebarkeun. Bedana pakait dina Sakali anjeun ngagaduhan topik anu dipikabutuh pikeun sistem anjeun langsung, anjeun tiasa mutuskeun pikeun ngahapus léngkah ieu sareng langsung nganggo nyebarkeun topik.

 Nyebarkeun TOPIK KANGGO ATAWA SET ELEMEN SARENG NILAI NA

Topik ieu nganggo jalur anu sami sareng anu ngalanggan - hiji-hijina parobihan nyaéta kecap "pamundut" dina tempat "status" anu dianggo pikeun ngalanggan. Jalur topik lengkep dipidangkeun engké dina chap. 4.2.2 \ A meunang topik bakal menta maca elemen sarta nilai MQTT server urang. Payload tiasa dianggo pikeun nyaring dumasar kana jinis fungsi unsur. Hiji topik set bakal menta pikeun ngarobah sababaraha bagian tina hiji unsur, sakumaha wincikan dina payload na.

PREFIX Pikeun paréntah jeung RESPONS CORESPONS

 PEDARAN SINGKAT

Sadaya paréntah anu dikirim ka server MQTT gaduh bagian awal anu umum, nyaéta:

PENJELASAN DETAIL

Topik real-time (tipe 1) bakal ngagaduhan awalan umum (tingali di luhur) teras dituturkeun ku

or

Pikeun paréntah set, payload écés maénkeun peran utama sabab bakal ngandung parobahan nu dipikahoyong (ie robah nilai pikeun fungsi unsur urang). Perhatosan: Ulah nganggo pilihan nahan dina paréntah 3 jinis anjeun sabab tiasa nyababkeun masalah di sisi KNX.

EXAMPLE: PENERBITKEUN PIKEUN NGAROBAH NILAI UNSUR TUNGGAL(S)

Kasus pangbasajanna nyaéta hoyong ngarobih nilai salah sahiji elemen anu dipidangkeun ku langganan umum.
Sacara umum, ngarobah / ngalihkeun fungsi VISI via MQTT diwangun ku 3 léngkah, teu sakabéh anu diperlukeun pisan, tapi kami nyarankeun ngalaksanakeun aranjeunna sakumaha ditétélakeun.

1. Topik anu ngandung fungsi anu urang hoyong edit dilanggan nganggo client_id khusus
2. Topik pikeun ngedit diterbitkeun babarengan sareng payload sareng perobahan anu dipikahoyong nganggo client_id anu dipilih dina 1.
3. Pikeun pariksa, Anjeun teras bisa ningali jawaban dina topik (1.) - ie naha (2.) digawé atawa henteu
4. Dina umum ngalanggan, dimana sakabeh nilai diropéa nalika parobahan dijieun, anjeun tiasa ningali robah nilai nu dipikahoyong (e) lamun sagalana geus digarap kaluar rupa.

Léngkah pikeun ngalakukeun ieu nyaéta:

1. pilih client_id misalna "Divus" terus selapkeun dina jalur sanggeus ngaran pamaké API
   Ieu mangrupikeun topik lengkep pikeun ngalanggan saluran komunikasi anjeun sareng server MQTT. Ieu nyarioskeun ka server dimana anjeun ngarepkeun réspon kana parobihan anu anjeun badé kirimkeun. Perhatikeun status / bagian set nu ngahartikeun a. yén éta téh jejer ngalanggan jeung b. yén éta bakal kéngingkeun jawaban pikeun nyetél paréntah jinis.
2. Topik penerbitan bakal sami iwal pikeun ngagentos kecap konci pamundut-status
3. naon robah kudu diwangun ku ditulis dina payload nu. Ieu sababaraha mantanamples.
   • Pareuman unsur nu boga fungsi on/off (1 bit):
   • Ngahurungkeun unsur anu ngagaduhan fungsi on / off (1 bit). Salaku tambahan, upami sababaraha paréntah sapertos dimimitian ti klien anu sami, parameter uuid ("ID unik", biasana mangrupikeun senar 128-bit anu diformat salaku 8-4-4-4-12 digit hex) tiasa dianggo pikeun napelkeun réspon kana pamundut anu saluyu, sabab parameter ieu - upami aya dina pamundut - ogé tiasa dipendakan dina réspon.
   • Ngahurungkeun sareng nyetel kacaangan dimmer ka 50%
   • Jawaban kana topik anu ditampilkeun sareng ngalanggan di luhur (payloadna, janten tepatna) nyaéta, contonaample.
     Respon di luhur mangrupa example dina kasus hiji payload bener, sanajan unsur teu boga fungsi dimming. Upami aya masalah anu langkung serius anu nyababkeun payload henteu diinterpretasi kalayan leres, résponna bakal sapertos kieu (contona):
     pikeun panjelasan ngeunaan kodeu kasalahan sareng pesen tapi sacara umum, sapertos pikeun http, 200 kode mangrupikeun jawaban anu positif sedengkeun 400 négatip.

EXAMPLE: Nyebarkeun pikeun ngarobah sababaraha nilai unsur

Prosedurna sami sareng anu dipidangkeun sateuacan ngarobih hiji unsur. Bédana téh nu ngaleungitkeun element_id tina jejer lajeng nunjukkeun susunan element_ids di hareup data jero payload nu. Tempo sintaksis jeung struktur di handap.

FILTER ku tipe fungsi dina QUERIES

Parameter saringan dina payload ngamungkinkeun ngan fungsi nu dipikahoyong (s) tina hiji unsur bisa kajawab. Fungsi on / off switch atanapi dimmer disebut "onoff", contonaample, sareng saringan anu saluyu didefinisikeun ku cara kieu:

jawaban lajeng Sigana mah kieu, pikeun example

Bracket pasagi nunjukkeun yén anjeun ogé tiasa nyaring ku sababaraha fungsi, contona

ngakibatkeun jawaban kawas kieu:

Lampiran

KODE kasalahan

Kasalahan dina komunikasi MQTT ngahasilkeun kode numerik. tabél di handap mantuan pikeun ngarecahna.

PARAMETER OF PAYLOAD

Payload ngarojong parameter béda gumantung kana konteks. Tabel di handap ieu nunjukkeun parameter mana anu tiasa lumangsung dina topik mana

VERSI CATETAN

• VERSI 1.00

Warta:

• publikasi munggaran

Dokumén / Sumberdaya

	DIVUS VISION API Software [pdf] Manual pamaké Software API VISION, Software API, Software
	DIVUS Visi API Software [pdf] Pituduh pamaké Visi API Software, Visi, API Software, Software

Rujukan

• Manual pamaké