DIVUS VISION API Software User Manual

API DIVUS VISION minangka piranti lunak sing dirancang kanggo antarmuka karo sistem DIVUS VISION. Iki ngidini pangguna ngakses lan ngontrol macem-macem unsur ing sistem nggunakake protokol MQTT.

FAQ

P: Apa aku bisa nggunakake API DIVUS VISION tanpa kawruh sadurunge babagan teknologi PC utawa otomatisasi?

A: Manual dirancang kanggo pangguna sing duwe kawruh sadurunge ing wilayah kasebut kanggo mesthekake panggunaan API sing efisien.

INFORMASI UMUM

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

Pandhuan operasi, manual lan piranti lunak dilindhungi hak cipta. Kabeh hak dilindhungi undhang-undhang. Nyalin, duplikat, nerjemahake, nerjemahake kabeh utawa sebagean ora diidini. Pangecualian ditrapake kanggo nggawe salinan serep piranti lunak kanggo panggunaan pribadi.
Manual bisa diganti tanpa kabar. Kita ora bisa njamin yen data sing ana ing dokumen iki lan ing media panyimpenan sing diwenehake bebas saka kesalahan lan bener. Saran kanggo perbaikan uga pitunjuk babagan kesalahan tansah ditampani. Perjanjian kasebut uga ditrapake kanggo lampiran khusus ing manual iki. Sebutan ing dokumen iki bisa uga merek dagang sing digunakake dening pihak katelu kanggo tujuane dhewe bisa nglanggar hak sing nduweni. Pandhuan pangguna: Waca manual iki sadurunge digunakake kanggo pisanan lan simpen ing papan sing aman kanggo referensi ing mangsa ngarep. Klompok target: Manual ditulis kanggo pangguna sing duwe kawruh babagan PC lan teknologi otomatisasi sadurunge.

KONVENSI PRESENTASI

Pambuka

PENDAHULUAN UMUM

Manual iki njlèntrèhaké VISION API (Application Programming Interface) - antarmuka sing VISION bisa ditangani lan dikontrol saka sistem eksternal.
Ing istilah praktis, iki tegese sampeyan bisa nggunakake sistem kayata

MQTT Explorer (https://www.microsoft.com/store/… – kanggo testing),

Asisten omah (https://www.home-assistant.io/) utawa
Node-RED (https://nodered.org/)

kanggo ngontrol unsur sing dikelola dening VISION utawa maca statuse. Akses lan komunikasi ditindakake liwat protokol MQTT, sing nggunakake topik sing diarani kanggo ngatasi fungsi individu utawa set fungsi utawa diwenehi informasi babagan owah-owahan kasebut. Server MQTT (broker) digunakake kanggo tujuan iki, sing nangani keamanan lan manajemen / distribusi pesen menyang peserta. Ing kasus iki, server MQTT dumunung langsung ing DIVUS KNX IQ lan diatur khusus kanggo maksud iki. Senajan API VISION uga bisa digunakake tanpa kawruh program, fungsi iki cocok kanggo pangguna majeng.

KEBUTUHAN

Kaya sing diterangake ing manual VISION, pangguna API kudu diaktifake kanthi standar supaya bisa nggunakake akses API mung bisa nggunakake data otentikasi pangguna Api. Ing babagan hak pangguna, aktivasi kanggo fungsi iki banjur bisa dikonfigurasi ing kabeh utawa ing unsur individu. Waca Bab 0. Mesthi, sampeyan uga butuh proyek VISION sing unsur-unsur sing pengin dikontrol saka njaba wis dikonfigurasi kanthi lengkap lan sambungan kasebut wis diuji kanthi sukses. Kanggo bisa ngatasi unsur individu liwat API, ID unsur kasebut kudu dingerteni: iki ditampilake ing sisih ngisor formulir setelan unsur.

KEAMANAN

Kanggo alasan keamanan, akses API mung bisa ditindakake sacara lokal (ora liwat awan). Risiko keamanan nalika ngaktifake akses API mulane kurang. Nanging, unsur sing relevan karo keamanan ora kudu diaktifake utawa ditolak kanthi jelas kanggo akses API.

MQTT lan SYARAT - panjelasan singkat

Ing MQTT, peran manajemen terpusat lan distribusi kabeh pesen yaiku broker. Sanajan server MQTT lan broker MQTT ora sinonim (server minangka istilah sing luwih jembar kanggo peran sing uga bisa dimainake klien MQTT), makelar kasebut mesthi ana ing manual iki nalika server MQTT kasebut. DIVUS KNX IQ dhewe main peran broker MQTT / server MQTT ing konteks manual iki.
Server MQTT nggunakake topik sing diarani: struktur hirarkis sing data dikategorikaké, dikelola lan diterbitake.

Publishing nduweni tujuan utama nggawe data kasedhiya kanggo peserta liyane liwat topik. Yen sampeyan pengin ngganti nilai, sampeyan nulis menyang topik sing dikarepake bebarengan karo owah-owahan nilai sing dikarepake, uga nggunakake tumindak nerbitake. Piranti target utawa server MQTT maca owah-owahan sing dikarepake sing kena pengaruh lan diadopsi. Kanggo mriksa manawa owah-owahan wis ditrapake, sampeyan bisa ndeleng ing topik wektu nyata sing langganan kanggo ndeleng apa owah-owahan kasebut katon ing kana - yen kabeh wis rampung.
Klien milih topik sing disenengi: iki diarani langganan. Saben nilai owah-owahan ing / ing ngisor topik, kabeh klien sing langganan dilaporake - yaiku tanpa kudu takon kanthi jelas apa ana owah-owahan utawa apa nilai saiki.

Sampeyan bisa mbukak (utawa alamat) saluran komunikasi sing kapisah karo server MQTT kanthi ngetik string unik sing diarani client_id ing topik. client_id kudu digunakake ing topik kanggo ngolah nilai. Iki serves kanggo ngenali asal saka saben owah-owahan, mbantu karo kasalahan lan ora mengaruhi klien liyane, minangka respon sing cocog saka server, kalebu kode kesalahan lan pesen, uga mung tekan topik karo client_id padha (lan mangkono mung klien kasebut). client_id minangka string karakter unik sing kasusun saka kombinasi karakter 0-9, az, AZ, "-", "_".
Umumé, topik langganan server MQTT saka DIVUS KNX IQ ngemot status tembung kunci, nalika topik nerbitake ngemot panjaluk tembung kunci. Sing duwe status kanthi otomatis dianyari sanalika ana owah-owahan nilai eksternal utawa sanalika owah-owahan nilai wis dijaluk dening klien dhewe liwat nerbitake lan wis kasil diterapake. Sing kanggo nerbitake luwih dipérang dadi jinis (request/)get lan jinis (request/)set.

Owah-owahan nilai lan paramèter opsional liyane ditambahake menyang topik kanthi muatan sing disebut. Parameter saka unsur individu (elemen-id, jeneng, jinis, fungsi)

Bentenipun utama antarane MQTT lan model klien-server klasik, ing ngendi klien njaluk lan banjur ngganti data, dipusatake ing konsep langganan lan nerbitake. Peserta bisa nerbitake data, supaya kasedhiya kanggo wong liya, sing yen kasengsem bisa langganan. Arsitektur iki ndadekake iku bisa kanggo nyilikake ijol-ijolan data lan isih tetep kabeh pihak sing kasengsem. Luwih lengkap babagan rincian ing kene: lan paramèter khusus (uuid, saringan) bakal digunakake ing kene. Sanajan ana sawetara opsi, muatan kasebut ditampilake kanthi format JSON ing manual iki. JSON nggunakake kurung lan koma kanggo makili data saka struktur apa wae lan kanthi mangkono nyilikake ukuran paket data sing bakal dikirim. Rincian liyane babagan muatan bisa ditemokake mengko ing manual.

Kanggo tujuan khusus, sampeyan bisa nyaring miturut jinis fungsi, contone, kanggo ngatasi mung on/off yaiku switch 1-bit. Parameter saringan ing muatan digunakake kanggo tujuan iki. Nyaring saiki mung bisa ditindakake miturut jinis fungsi.
Kanggo bisa ngatasi unsur individu, ID unsur kasebut dibutuhake. Iki bisa ditemokaké ing VISION ing menu sifat unsur utawa uga bisa maca langsung saka data sing ditampilake ing ngarepe saben unsur kasedhiya ing langganan umum MQTT Explorer (elemen ana kadhaptar abjad dening ID unsur).

Konfigurasi kanggo akses API

KONFIGURING VISION FOR API USER ACCESS

Ing VISION minangka administrator, pindhah menyang Konfigurasi - Panganggo / Manajemen Akses API, klik Pangguna / akses API lan klik-tengen ing Pangguna API (utawa penet terus) kanggo mbukak jendhela panyuntingan. Ing kana sampeyan bakal nemokake paramèter lan data kasebut

Aktifake (kotak centhang)
- Pangguna pisanan diaktifake ing kene. Default dipateni
Jeneng panganggo
- String iki dibutuhake kanggo akses liwat API - nyalin saka kene
Sandi
- String iki dibutuhake kanggo akses liwat API - nyalin saka kene
Idin
- Hak standar kanggo maca lan nulis nilai-nilai saka unsur VISION bisa ditetepake ing kene, yaiku apa sing ditetepake ing kene ditrapake kanggo kabeh unsur sing ana lan sing bakal teka. Yen sampeyan mung pengin ngidini akses menyang unsur individu, sampeyan ora kudu ngganti hak gawan iki

IZIN ING UNSUR INDIVIDU

Disaranake sampeyan ora menehi akses API kanggo kabeh project, nanging mung kanggo unsur sing dikarepake. Terusake kaya ing ngisor iki

mlebu menyang VISION minangka administrator
pilih unsur sing dikarepake lan bukak menu setelan (klik-tengen utawa terus dipencet, banjur Setelan)

ing entri menu Umum - Idin, aktifake "Timpa ijin standar" banjur pindhah menyang sub-item Idin, sing nuduhake matriks ijin.
ngaktifake ijin kontrol kene, kang uga mbisakake ing view izin langsung. Yen sampeyan mung pengin maca data liwat akses API, iku cukup kanggo ngaktifake view ijin.
baleni prosedur sing padha kanggo kabeh unsur sing pengin diakses

Sambungan liwat MQTT

PAMBUKA

Minangka mantanample, kita bakal nduduhake akses liwat MQTT API saka DIVUS KNX IQ karo relatif prasaja, free lunak disebut MQTT Explorer (ndeleng chap. 1.1), kang kasedhiya kanggo Windows, Mac lan Linux. A kawruh dhasar lan pengalaman karo MQTT diwenehake.

DATA sing dibutuhake kanggo sambungan

Kaya sing wis kasebut sadurunge (pirsani bagean 2.1), jeneng pangguna lan sandhi pangguna API dibutuhake. Punika rampungview kabeh data sing kudu diklumpukake sadurunge sambungan digawe:

Jeneng pangguna Waca ing kaca rinci pangguna API
Sandi Waca metu ing kaca rinci pangguna API

Alamat IP Waca ing setelan peluncur ing Umum - Jaringan - Ethernet (utawa liwat Sinkronisasi)
Port 8884 (port iki dilindhungi undhang-undhang kanggo tujuan iki)

Sambungan pisanan karo MQTT EXPLORER lan SUBSCRIBE UMUM

Biasane, MQTT mbedakake antarane aktivitas langganan lan nerbitake. MQTT Explorer nyederhanakake iki kanthi otomatis langganan kabeh topik sing kasedhiya (topik #) nalika sambungan pisanan digawe. Akibaté, wit sing ndadékaké kanggo kabeh unsur sing kasedhiya (yaiku akses pangguna API sing diwenehake) bisa dideleng langsung ing sisih kiwa jendhela MQTT Explorer sawise sambungan sukses. Kanggo ngetik topik langganan luwih lanjut utawa ngganti # karo topik sing luwih spesifik, pindhah menyang Advanced ing jendhela sambungan. Topik sing ditampilake ing sisih tengen ndhuwur katon kaya iki:

ngendi 7f4x0607849x444xxx256573x3x9x983 iku jeneng panganggo API lan objects_list ngemot kabeh unsur kasedhiya. Topik iki tansah katahan munggah kanggo tanggal IE sembarang owah-owahan nilai sing dibayangke ana ing wektu nyata. Yen sampeyan mung pengin langganan unsur individu, ketik ID unsur unsur sing dikarepake sawise objects_list/.

Cathetan: Jinis langganan iki kira-kira cocog karo logika ing mburi alamat umpan balik KNX; nuduhake status unsur saiki lan bisa digunakake kanggo mriksa apa owah-owahan sing dikarepake wis kasil ditrapake. Yen sampeyan mung pengin maca data nanging ora ngganti, jinis langganan iki cukup.

Unsur prasaja siji katon kaya iki ing notasi JSON

Cathetan: Kabeh nilai duwe sintaks sing dituduhake ing ndhuwur, contone {"nilai": "1" } minangka output saka topik langganan, dene nilai kasebut ditulis langsung ing muatan kanggo ngganti nilai (yaiku kanggo nerbitake topik) - kurung lan "Nilai" diilangi contone "onoff": "1".

printah majeng

PAMBUKA

Ana 3 jinis topik umume:

Langganan topik kanggo ndeleng unsur sing kasedhiya lan entuk owah-owahan nilai wektu nyata
Langganan topik kanggo njaluk jawaban kanggo (para klien ) nerbitake panjalukan

Nerbitake topik kanggo entuk utawa nyetel unsur kanthi nilai

Kita bakal ngrujuk marang jinis kasebut kanthi nggunakake nomer sing dituduhake ing kene (umpamane topik jinis 1, 2, 3). Rincian liyane ing bagean ing ngisor iki lan ing bab. 4.2.

LANGGANAN TOPIK kanggo ndeleng ELEMEN sing kasedhiya lan entuk owah-owahan nilai nyata

Iki wis diterangake

TOPIK SUBSCRIBE kanggo njaluk jawaban kanggo panjalukan publikasi klien

Topik kaya iki opsional. Iku ngidini kanggo

mbukak saluran komunikasi unik karo server MQTT kanthi nggunakake client_id sing sewenang-wenang. Liyane babagan ing bab. 4.2.2
entuk asil nerbitake panjalukan ing topik langganan sing cocog: sukses utawa gagal kanthi kode kesalahan lan pesen.

Ana macem-macem topik kanggo njaluk jawaban utawa nyetel printah nerbitake. Bedane sing cocog ing Sawise sampeyan entuk topik sing dibutuhake kanggo sistem sampeyan kanthi langsung, sampeyan bisa mutusake kanggo mbusak langkah iki lan langsung nggunakake topik nerbitake.

Nerbitake TOPIK kanggo njaluk utawa nyetel unsur-unsur karo nilai-nilai

Topik-topik iki nggunakake path sing padha karo sing kanggo langganan - mung owah-owahan tembung "request" ing panggonan "status" digunakake kanggo langganan. Path topik lengkap ditampilake mengko ing bab. 4.2.2 \ A njaluk topik bakal njaluk maca unsur lan nilai server MQTT. Muatan bisa digunakake kanggo nyaring adhedhasar jinis fungsi unsur kasebut. A topik pesawat bakal njaluk kanggo ngganti sawetara bagéan saka unsur, minangka rinci ing payload sawijining.

PREFIX FOR Prentah lan RESPONSE

PEDARAN SINGKAT

Kabeh prentah sing dikirim menyang server MQTT duwe bagean awal sing umum, yaiku:

PENJELASAN DETAIL

Topik wektu nyata (jinis 1) bakal duwe awalan umum (ndeleng ndhuwur) banjur diterusake

Kanggo printah pesawat, payload temenan muter peran utama minangka bakal ngemot owah-owahan sing dipengini (IE diganti Nilai kanggo fungsi unsur kang). A Pènget: Aja nggunakake pilihan makaryakke ing jinis 3 printah amarga bisa nimbulaké masalah ing sisih KNX.

EXAMPLE: PUBLISH kanggo ngganti nilai ELEMEN SATU (S)

Kasus sing paling gampang yaiku pengin ngganti nilai salah sawijining unsur sing dituduhake dening langganan umum.
Umumé, ngganti / ngalih fungsi VISION liwat MQTT kasusun saka 3 langkah, ora kabeh area pancen perlu, nanging kita nyaranake nindakake minangka diterangake.

Topik sing ngemot fungsi sing pengin diowahi wis langganan nggunakake client_id khusus
Topik kanggo nyunting diterbitake bebarengan karo muatan kanthi owah-owahan sing dikarepake nggunakake client_id sing dipilih ing 1.

Kanggo mriksa, sampeyan bisa ndeleng jawaban ing topik (1.) - IE apa (2.) bisa utawa ora
Ing langganan umum, ngendi kabeh nilai dianyari nalika owah-owahan sing digawe, sampeyan bisa ndeleng pangowahan Nilai dikarepake (e) yen kabeh wis bisa metu nggoleki.

Langkah-langkah kanggo nindakake iki yaiku:

pilih client_id eg "Divus" lan lebokake ing path sawise jeneng panganggo API
Iki minangka topik lengkap kanggo langganan saluran komunikasi sampeyan karo server MQTT. Iki ngandhani server ing ngendi sampeyan ngarepake respon kanggo owah-owahan sing arep dikirim. Wigati status / bagean nyetel sing nemtokake a. yaiku topik langganan lan b. sing bakal entuk jawaban kanggo nyetel printah jinis.
Topik nerbitake bakal padha kajaba kanggo ngganti tembung kunci panjalukan status
apa owah-owahan kudu kalebu ditulis ing payload. Kene sawetara mantanamples.
- Mateni unsur sing nduweni fungsi on/off (1 bit):
- Ngaktifake unsur sing nduweni fungsi on/off (1 bit). Kajaba iku, yen sawetara printah kasebut diwiwiti saka klien sing padha, parameter uuid ("ID unik", biasane string 128-bit sing diformat minangka 8-4-4-4-12 digit hex) bisa digunakake kanggo nemtokake nanggepi pitakonan sing cocog, amarga parameter iki - yen ana ing pitakonan - uga bisa ditemokake ing respon.
- Ngaktifake lan nyetel padhange dimmer dadi 50%
- Jawaban kanggo topik sing ditampilake lan langganan ing ndhuwur (payloade, tepate) yaiku, contoneample.
  Wangsulan ing ndhuwur yaiku eksample ing cilik saka payload bener, sanajan unsur ora fungsi dimming. Yen ana masalah sing luwih serius sing nyebabake muatan ora bisa diinterpretasikake kanthi bener, respon bakal katon kaya iki (contone):
  kanggo panjelasan kode kesalahan lan pesen nanging umume, kaya kanggo http, 200 kode minangka jawaban positif nalika 400 negatif.

EXAMPLE: PUBLISH kanggo ngganti sawetara nilai ELEMENTS

Prosedure padha karo sing ditampilake sadurunge kanggo ngganti unsur siji. Bentenipun sampeyan ngilangi element_id saka topik lan banjur nunjukaké pesawat saka element_ids ing ngarepe data nang payload. Deleng sintaksis lan struktur ing ngisor iki.

FILTER BY FUNGSI JENIS IN QUERIES

Parameter saringan ing muatan ngidini mung fungsi sing dipengini (e) saka unsur bisa ditangani. Fungsi on / off switch utawa dimmer diarani "onoff", contoneample, lan filter sing cocog ditetepake kanthi cara iki:

Jawaban banjur katon kaya iki, kanggo Example

Kurung kothak nuduhake yen sampeyan uga bisa nyaring kanthi sawetara fungsi, contone

ndadékaké kanggo jawaban kaya iki:

Lampiran

KODE kesalahan

Kasalahan ing komunikasi MQTT nyebabake kode numerik. Tabel ing ngisor iki mbantu kanggo break mudhun.

PARAMETER PAYLOAD

Muatan ndhukung paramèter sing beda-beda gumantung saka konteks. Tabel ing ngisor iki nuduhake paramèter sing bisa kedadeyan ing topik

CATETAN VERSI

VERSI 1.00

Kabar:

• Publikasi pisanan

Dokumen / Sumber Daya

	Piranti Lunak API DIVUS VISION [pdf] Manual pangguna VISION API Software, API Software, Software
	Piranti Lunak DIVUS Vision API [pdf] Pandhuan pangguna Vision API Software, Vision, API Software, Software

Referensi

Manual pangguna

Piranti Lunak API DIVUS VISION

Informasi produk

FAQ