Mwongozo wa Mtumiaji wa Programu ya DIVUS VISION API

DIVUS VISION API ni zana ya programu iliyoundwa kwa ajili ya kuingiliana na mifumo ya DIVUS VISION. Inaruhusu watumiaji kufikia na kudhibiti vipengele mbalimbali ndani ya mfumo kwa kutumia itifaki za MQTT.

Maswali Yanayoulizwa Mara kwa Mara

Swali: Je, ninaweza kutumia DIVUS VISION API bila ujuzi wa awali wa Kompyuta au teknolojia ya otomatiki?

J: Mwongozo huu umeundwa kwa ajili ya watumiaji walio na ujuzi wa awali katika maeneo haya ili kuhakikisha matumizi bora ya API.

HABARI YA JUMLA

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

Maagizo ya uendeshaji, miongozo na programu zinalindwa na hakimiliki. Haki zote zimehifadhiwa. Kunakili, kunakili, kutafsiri, kutafsiri nzima au kwa sehemu hairuhusiwi. Isipokuwa inatumika kwa kuunda nakala rudufu ya programu kwa matumizi ya kibinafsi.
Mwongozo unaweza kubadilika bila taarifa. Hatuwezi kuthibitisha kwamba data iliyo katika hati hii na kwenye hifadhi ya maudhui iliyotolewa haina makosa na ni sahihi. Mapendekezo ya uboreshaji pamoja na vidokezo vya makosa yanakaribishwa kila wakati. Mikataba hiyo pia inatumika kwa viambatisho maalum vya mwongozo huu. Majina katika hati hii yanaweza kuwa chapa za biashara ambazo matumizi yake na wahusika wengine kwa madhumuni yao yanaweza kukiuka haki za wamiliki wao. Maagizo ya mtumiaji: Tafadhali soma mwongozo huu kabla ya kuutumia kwa mara ya kwanza na uuweke mahali salama kwa marejeleo ya baadaye. Kikundi lengwa: Mwongozo umeandikwa kwa watumiaji wenye ujuzi wa awali wa PC na teknolojia ya automatisering.

MIKUTANO YA UWASILISHAJI

Utangulizi

UTANGULIZI WA JUMLA

Mwongozo huu unafafanua VISION API (Kiolesura cha Kutayarisha Programu) - kiolesura ambacho MAONO yanaweza kushughulikiwa na kudhibitiwa kutoka kwa mifumo ya nje.
Kwa maneno ya vitendo, hii inamaanisha kuwa unaweza kutumia mifumo kama vile

Mchunguzi wa MQTT (https://www.microsoft.com/store/… - kwa majaribio),

Msaidizi wa Nyumbani (https://www.home-assistant.io/) au
Nodi-NYEKUNDU (https://nodered.org/)

ili kudhibiti vipengele vinavyosimamiwa na MAONO au kusoma hali zao. Ufikiaji na mawasiliano hufanyika kupitia itifaki ya MQTT, ambayo hutumia kinachojulikana mada kushughulikia kazi za kibinafsi au seti za utendakazi au kufahamishwa kuhusu mabadiliko kwao. Seva ya MQTT (dalali) hutumiwa kwa madhumuni haya, ambayo hushughulikia usalama na usimamizi/usambazaji wa ujumbe kwa washiriki. Katika hali hii, seva ya MQTT iko moja kwa moja kwenye DIVUS KNX IQ na imeundwa mahususi kwa madhumuni haya. Ingawa API ya MAONO inaweza pia kutumika bila maarifa ya upangaji, utendakazi huu unafaa kwa watumiaji wa hali ya juu.

MAHITAJI

Kama ilivyoelezwa katika mwongozo wa MAONO, mtumiaji wa API lazima kwa chaguomsingi kwanza awashwe ili aweze kuitumia ufikiaji wa API hufanya kazi tu kwa kutumia data ya uthibitishaji ya watumiaji wa Api. Kwa kadiri haki za mtumiaji zinavyohusika, uwezeshaji wa utendakazi huu unaweza kisha kusanidiwa kwa vipengele vyote au kwa kila mtu. Tazama Sura ya 0. Bila shaka, unahitaji pia mradi wa VISION ambapo vipengele unavyotaka kudhibiti kutoka nje vimesanidiwa kikamilifu na muunganisho navyo vimejaribiwa kwa ufanisi. Ili kuweza kushughulikia vipengele binafsi kupitia API, kitambulisho cha kipengele chao lazima kijulikane: hii inaonyeshwa chini ya fomu ya mipangilio ya kipengele.

USALAMA

Kwa sababu za usalama, ufikiaji wa API unawezekana tu ndani ya nchi (yaani sio kupitia wingu). Hatari ya usalama wakati wa kuwezesha ufikiaji wa API kwa hivyo ni ndogo. Hata hivyo, vipengele vinavyohusiana na usalama havipaswi kuwashwa au kukataliwa waziwazi kwa ufikiaji wa API.

MQTT NA MASHARTI YAKE – MAELEZO MAFUPI

Katika MQTT, jukumu la usimamizi wa kati na usambazaji wa jumbe zote ni la wakala. Ingawa seva ya MQTT na wakala wa MQTT si visawe (seva ni neno pana la jukumu ambalo wateja wa MQTT wanaweza pia kutekeleza), wakala daima humaanishwa katika mwongozo huu seva ya MQTT inapotajwa. DIVUS KNX IQ yenyewe ina jukumu la wakala wa MQTT / seva ya MQTT katika muktadha wa mwongozo huu.
Seva ya MQTT hutumia zinazoitwa mada: muundo wa daraja ambao data huwekwa katika kategoria, kudhibitiwa na kuchapishwa.

Uchapishaji una lengo la msingi la kufanya data ipatikane kwa washiriki wengine kupitia mada. Ikiwa ungependa kubadilisha thamani, unaandika kwa mada unayotaka pamoja na mabadiliko ya thamani unayotaka, pia kwa kutumia kitendo cha uchapishaji. Kifaa kinacholengwa au seva ya MQTT husoma mabadiliko yanayotakiwa ambayo yanakiathiri na kukikubali ipasavyo. Ili kuhakikisha kuwa mabadiliko hayo yametekelezwa, unaweza kuangalia katika mada ya wakati halisi uliyofuatilia ili kuona kama mabadiliko hayo yanaonekana pale - ikiwa kila kitu kimeenda sawa.
Wateja huchagua mada zinazowavutia: hii inaitwa kujiandikisha. Kila wakati thamani inapobadilika katika/chini ya mada, wateja wote waliojisajili wanafahamishwa - yaani bila kuhitaji kuuliza kwa uwazi ikiwa kitu kimebadilika au thamani ya sasa ni nini.

Unaweza kufungua (au kushughulikia) njia tofauti ya mawasiliano na seva ya MQTT kwa kuingiza mfuatano wowote wa kipekee unaoitwa client_id katika mada. Kitambulisho cha mteja lazima kitumike katika mada ili kuchakata thamani. Hii inatumika kutambua asili ya kila badiliko, husaidia kwa makosa yoyote na haiathiri wateja wengine, kwani majibu yanayolingana kutoka kwa seva, pamoja na misimbo na ujumbe wowote wa hitilafu, pia hufikia mada kwa kitambulisho sawa cha mteja (na hivyo tu. mteja huyo). Kitambulisho cha mteja ni mfuatano wa kipekee wa herufi unaojumuisha mchanganyiko wowote wa vibambo 0-9, az, AZ, “-“, “_”.
Kwa ujumla, mada za kujiandikisha za seva ya MQTT ya DIVUS KNX IQ zina hali ya nenomsingi, huku mada za uchapishaji zina ombi la neno kuu. Zile zilizo na hali husasishwa kiotomatiki punde tu kunapokuwa na mabadiliko ya thamani ya nje au mara tu mabadiliko ya thamani yameombwa na mteja mwenyewe kupitia uchapishaji na kutekelezwa. Zile za uchapishaji zimegawanywa zaidi katika zile za aina (ombi/) pata na zile za aina (ombi/) zilizowekwa.

Mabadiliko ya thamani na vigezo vingine vya hiari huongezwa kwenye mada na kinachojulikana kama mzigo wa malipo. Vigezo vya vipengele vya mtu binafsi (kitambulisho cha kipengele, jina, aina, kazi)

Tofauti kuu kati ya MQTT na modeli ya kawaida ya seva-teja, ambapo mteja anaomba na kisha kubadilisha data, inajikita kwenye dhana za kujisajili na kuchapisha. Washiriki wanaweza kuchapisha data, na kuifanya ipatikane kwa wengine, ambao kama wanapenda wanaweza kujiandikisha. Usanifu huu unawezesha kupunguza ubadilishanaji wa data na bado kusasisha wahusika wote wanaovutiwa. Zaidi kuhusu maelezo hapa: na vigezo maalum (uuid, vichungi) vitatumika hapa. Ingawa kuna chaguo kadhaa, upakiaji unaonyeshwa umeumbizwa kama JSON katika mwongozo huu. JSON hutumia mabano na koma kuwakilisha data ya muundo wowote na hivyo kupunguza ukubwa wa pakiti za data zinazopaswa kutumwa. Maelezo zaidi kuhusu upakiaji yanaweza kupatikana baadaye katika mwongozo.

Kwa madhumuni maalum, inawezekana kuchuja kulingana na aina ya kitendakazi, kwa mfano kushughulikia tu kuwasha/kuzima yaani swichi 1-bit. Parameta ya vichungi katika mzigo wa malipo hutumiwa kwa kusudi hili. Kuchuja kwa sasa kunawezekana tu kwa aina ya chaguo la kukokotoa.
Ili kuweza kushughulikia vipengele mahususi, kitambulisho cha kipengele chao kinahitajika. Hii inaweza kupatikana katika MAONO katika menyu ya sifa za kipengele au inaweza pia kusomwa moja kwa moja kutoka kwa data inayoonyeshwa mbele ya kila kipengele kinachopatikana katika usajili wa jumla wa Kichunguzi cha MQTT (vipengee vilivyoorodheshwa kwa herufi kwa Kitambulisho cha kipengele).

Usanidi wa ufikiaji wa API

KUWEKA MAONO YA UPATIKANAJI WA MTUMIAJI API

Katika MAONO kama msimamizi, nenda kwa Usanidi - Usimamizi wa Ufikiaji wa Mtumiaji/API, bofya ufikiaji wa Watumiaji/API na ubofye kulia kwenye Mtumiaji wa API (au bonyeza na ushikilie) ili kufungua dirisha la kuhariri. Huko utapata vigezo na data hizi

Washa (kisanduku cha kuteua)
- Mtumiaji huwashwa hapa kwanza. Chaguo-msingi imezimwa
Jina la mtumiaji
- Mfuatano huu unahitajika kwa ufikiaji kupitia API - nakili kutoka hapa
Nenosiri
- Mfuatano huu unahitajika kwa ufikiaji kupitia API - nakili kutoka hapa
Ruhusa
- Haki chaguo-msingi za kusoma na kuandika thamani za vipengele vya MAONO zinaweza kufafanuliwa hapa, yaani, kinachofafanuliwa hapa kinatumika kwa vipengele vyote vilivyopo na vijavyo. Ikiwa unataka tu kuruhusu ufikiaji wa vipengele vya kibinafsi, hupaswi kubadilisha haki hizi chaguo-msingi

RUHUSA KUHUSU VIPENGELE VYA MTU BINAFSI

Inapendekezwa kwamba usipe ufikiaji wa API kwa mradi mzima, lakini tu kwa vitu vinavyohitajika. Endelea kama ifuatavyo

ingia kwenye VISION kama msimamizi
chagua kipengee unachotaka na ufungue menyu ya mipangilio yake (bonyeza kulia au endelea kubonyeza, kisha Mipangilio)

chini ya ingizo la menyu Jumla - Ruhusa, washa "Batilisha ruhusa chaguo-msingi" kisha uende kwenye kipengee kidogo Ruhusa, ambacho kinaonyesha matrix ya ruhusa.
kuamsha ruhusa ya kudhibiti hapa, ambayo pia inawezesha view ruhusa moja kwa moja. Ikiwa unataka tu kusoma data kupitia ufikiaji wa API, inatosha kuwezesha faili ya view ruhusa.
kurudia utaratibu sawa kwa vipengele vyote unavyotaka kufikia

Muunganisho kupitia MQTT

UTANGULIZI

Kama exampna, tutaonyesha ufikiaji kupitia MQTT API ya DIVUS KNX IQ na programu rahisi, isiyolipishwa iitwayo MQTT Explorer (ona sura ya 1.1), ambayo inapatikana kwa Windows, Mac na Linux. Maarifa ya msingi na uzoefu na MQTT inadokezwa.

DATA INAYOHITAJI KWA MUUNGANISHO

Kama ilivyoelezwa hapo awali (tazama sehemu ya 2.1), jina la mtumiaji na nenosiri la mtumiaji wa API zinahitajika. Hapa ni juuview ya data yote ambayo lazima ikusanywe kabla ya muunganisho kuanzishwa:

Jina la mtumiaji Soma kwenye ukurasa wa kina wa mtumiaji wa API
Nenosiri Soma kwenye ukurasa wa kina wa mtumiaji wa API

Anwani ya IP Soma katika mipangilio ya kizindua chini ya Jumla - Mtandao - Ethernet (au kupitia Kilandanishi)
Bandari 8884 (bandari hii imehifadhiwa kwa madhumuni haya)

MAHUSIANO YA KWANZA NA MQTT EXPLORER NA JUMLA SUBSCRIBE

Kwa kawaida, MQTT hutofautisha kati ya shughuli za kujisajili na kuchapisha. MQTT Explorer hurahisisha hili kwa kujisajili kiotomatiki kwa mada zote zinazopatikana (mada #) wakati muunganisho wa kwanza unafanywa. Kwa hivyo, mti unaoongoza kwa vipengele vyote vinavyopatikana (yaani ufikiaji wa mtumiaji wa API umetolewa) unaweza kuonekana moja kwa moja katika eneo la kushoto la dirisha la MQTT Explorer baada ya muunganisho uliofanikiwa. Ili kuingiza mada zaidi ya kujiandikisha au kubadilisha # na mada maalum zaidi, nenda kwa Kina kwenye kidirisha cha muunganisho. Mada iliyoonyeshwa upande wa juu kulia inaonekana kama hii:

ambapo 7f4x0607849x444xxx256573x3x9x983 ni jina la mtumiaji la API na vitu_orodha ina vipengele vyote vinavyopatikana. Mada hii husasishwa kila mara yaani mabadiliko yoyote ya thamani yanaonyeshwa hapo kwa wakati halisi. Ikiwa unataka tu kujiandikisha kwa vipengele vya kibinafsi, weka kitambulisho cha kipengele cha kipengele unachotaka baada ya objects_list/.

Kumbuka: Aina hii ya usajili inalingana takriban na mantiki nyuma ya anwani za maoni za KNX; inaonyesha hali ya sasa ya vipengele na inaweza kutumika kuangalia kama mabadiliko yanayohitajika yametekelezwa kwa ufanisi. Ikiwa unataka tu kusoma data lakini usiibadilishe, aina hii ya kujisajili inatosha .

Kipengele kimoja rahisi kinaonekana kama hiki katika nukuu ya JSON

Kumbuka: Thamani zote zina sintaksia iliyoonyeshwa hapo juu kwa mfano {"value": "1" } kama matokeo ya mada za kujisajili, huku thamani imeandikwa moja kwa moja kwenye mzigo wa malipo ili kubadilisha thamani (yaani kwa mada za kuchapisha) - mabano na "thamani" imeachwa kwa mfano "off": "1".

Amri za hali ya juu

UTANGULIZI

Kuna aina 3 za mada kwa jumla:

Fuatilia mada ili kuona vipengele vinavyopatikana na kupata mabadiliko ya thamani ya wakati halisi
Fuatilia mada ili kupata majibu ya (wateja ) kuchapisha maombi

Chapisha mada ili kupata au kuweka vipengele vyenye thamani zake

Baadaye tutarejelea aina hizi kwa kutumia nambari zilizoonyeshwa hapa (kwa mfano mada za aina ya 1, 2, 3). Maelezo zaidi katika sehemu zifuatazo na katika sura ya. 4.2.

SUBSCRIBE MADA ILI KUONA VIPENGELE VINAVYOPATIKANA NA KUPATA MABADILIKO HALISI YA THAMANI

Haya tayari yameelezwa

SUBSCRIBE MADA ILI KUPATA MAJIBU YA MAOMBI YA MTEJA KUCHAPISHA

Mada ya aina hii ni ya hiari. Inaruhusu

fungua njia ya kipekee ya mawasiliano na seva ya MQTT kwa kutumia kitambulisho cha mteja_kiholela. Zaidi kuhusu hilo katika chap. 4.2.2
pata matokeo ya ombi la kuchapisha kwenye mada inayolingana ya kujiandikisha: kufaulu au kutofaulu na nambari ya makosa na ujumbe.

Kuna mada tofauti za kupata majibu ya kupata au kuweka amri za uchapishaji. Tofauti inayolingana katika Mara tu unapopata mada zinazohitajika kwa mfumo wako moja kwa moja, unaweza kuamua kuondoa hatua hii na utumie mada za uchapishaji moja kwa moja.

CHAPISHA MADA ILI KUPATA AU KUWEKA VIPENGELE VYENYE MAADILI YAKE

Mada hizi hutumia njia sawa na zile za kujiandikisha - mabadiliko pekee ni neno "ombi" badala ya "hali" inayotumiwa kujiandikisha. Njia kamili za mada zinaonyeshwa baadaye katika sura ya. 4.2.2\ Mada ya kupata itaomba kusoma vipengele na maadili ya seva ya MQTT. Upakiaji unaweza kutumika kuchuja kulingana na aina ya utendakazi wa vipengee. Mada iliyowekwa itaomba kubadilisha baadhi ya sehemu za kipengele, kama inavyofafanuliwa katika mzigo wake wa malipo.

KIAMBATISHO CHA AMRI NA MAJIBU YANAYOENDANA

MAELEZO MAFUPI

Amri zote zinazotumwa kwa seva ya MQTT zina sehemu ya awali ya kawaida, ambayo ni:

UFAFANUZI WA KINA

Mada za wakati halisi (aina ya 1) zitakuwa na kiambishi awali cha jumla (tazama hapo juu) kisha zikifuatiwa na

Kwa amri zilizowekwa, mzigo wa malipo ni dhahiri una jukumu kuu kwani utakuwa na mabadiliko yanayohitajika (yaani, maadili yaliyobadilishwa kwa utendakazi wa kipengele). Onyo: Usiwahi kutumia chaguo la kuhifadhi katika amri zako za aina ya 3 kwani inaweza kusababisha matatizo katika upande wa KNX.

EXAMPLE: CHAPISHA KWA KUBADILISHA THAMANI YA KIPINDI KIMOJA

Kesi rahisi ni kutaka kubadilisha thamani ya mojawapo ya vipengele vilivyoonyeshwa na subscribe general .
Kwa ujumla, kubadilisha/kubadilisha utendaji wa MAONO kupitia MQTT kunajumuisha hatua 3, si zote ambazo ni muhimu kabisa, lakini hata hivyo tunapendekeza zitekelezwe kama ilivyoelezwa.

Mada iliyo na kipengele cha kukokotoa tunachotaka kuhariri imesajiliwa kwa kutumia kitambulisho maalum cha mteja
Mada ya kuhaririwa imechapishwa pamoja na mzigo wa malipo na mabadiliko yanayohitajika kwa kutumia kitambulisho cha mteja kilichochaguliwa katika 1.

Ili kuangalia, unaweza kuona jibu katika mada (1.) - yaani ikiwa (2.) ilifanya kazi au la
Kwa ujumla kujiandikisha, ambapo maadili yote yanasasishwa mabadiliko yanapofanywa, unaweza kuona mabadiliko ya thamani unayotaka ikiwa kila kitu kimeenda vizuri.

Hatua za kufanya hivi ni:

chagua kitambulisho cha mteja kwa mfano "Divus" na uiweke kwenye njia baada ya jina la mtumiaji la API
Hii ndiyo mada kamili ya kujiandikisha kwenye chaneli yako ya mawasiliano na seva ya MQTT. Hii inaiambia seva ambapo unatarajia majibu kwa mabadiliko unayokusudia kutuma. Angalia hali/sehemu iliyowekwa ambayo inafafanua a. kwamba ni mada ya kujiunga na b. kwamba itapata majibu ya kuweka amri za aina.
Mada ya uchapishaji itakuwa sawa isipokuwa kwa kubadilisha maneno muhimu ya ombi la hali
mabadiliko yanapaswa kujumuisha nini imeandikwa kwenye mzigo. Hapa kuna baadhi ya wa zamaniampchini.
- Kuzima kipengele ambacho kina kitendaji cha kuwasha/kuzima (kidogo 1):
- Kuwasha kipengele ambacho kina kitendakazi cha kuwasha/kuzima (kidogo 1). Kwa kuongezea, ikiwa amri kadhaa kama hizo zimeanzishwa kutoka kwa mteja mmoja, kigezo cha uuid ("Kitambulisho cha kipekee", kwa kawaida ni mfuatano wa-bit-128 ulioumbizwa kama heksi ya tarakimu 8-4-4-4-12) inaweza kutumika kugawa jibu kwa swali linalolingana, kwani parameta hii - ikiwa iko katika swali - inaweza pia kupatikana katika jibu.
- Kuwasha na kuweka mwangaza wa dimmer hadi 50%
- Jibu la mada iliyoonyeshwa na kujiandikisha hapo juu (mzigo wake, kuwa sahihi) basi, kwa mfano.ample.
  Jibu hapo juu ni la zamaniample katika kesi ya upakiaji sahihi, ingawa kipengee hakina kazi ya kufifisha. Ikiwa kuna shida kubwa zaidi zinazosababisha upakiaji kutotafsiriwa kwa usahihi, jibu litaonekana kama hii (kwa mfano):
  kwa maelezo ya misimbo na ujumbe wa makosa lakini kwa ujumla, kama kwa http, nambari 200 ni majibu chanya wakati 400 ni hasi.

EXAMPLE: CHAPISHA KWA KUBADILISHA MAADILI YA VIPENGELE NYINGI

Utaratibu ni sawa na ule ulioonyeshwa hapo awali ili kubadilisha kipengele kimoja. Tofauti ni kwamba unaacha kipengele_id kutoka kwa mada na kisha uonyeshe seti ya elementi_id mbele ya data iliyo ndani ya mzigo wa malipo. Tazama sintaksia na muundo hapa chini.

CHUJA KWA AINA YA KAZI KATIKA MASWALI

Kigezo cha vichujio katika upakiaji huruhusu tu kazi (za) zinazohitajika za kipengele kushughulikiwa. Kazi ya kuwasha/kuzima ya swichi au dimmer inaitwa "off", kwa mfanoample, na kichungi kinacholingana kinafafanuliwa kwa njia hii:

Jibu basi linaonekana kama hii, kwa mfanoample

Mabano ya mraba yanaonyesha kuwa unaweza pia kuchuja kwa vitendaji kadhaa, kwa mfano

inaongoza kwa jibu kama hili:

Nyongeza

KOSA ZA KOSA

Hitilafu katika mawasiliano ya MQTT husababisha msimbo wa nambari. Jedwali lifuatalo husaidia kuivunja.

VIGEZO VYA MALIPO

Mzigo wa malipo unaauni vigezo tofauti kulingana na muktadha. Jedwali lifuatalo linaonyesha ni vigezo gani vinaweza kutokea katika mada gani

MAELEZO YA TOLEO

VITI 1.00

Habari:

• Chapisho la kwanza

Nyaraka / Rasilimali

	DIVUS VISION API Programu [pdf] Mwongozo wa Mtumiaji Programu ya API ya VISION, Programu ya API, Programu
	Programu ya API ya Maono ya DIVUS [pdf] Mwongozo wa Mtumiaji Programu ya API ya Maono, Maono, Programu ya API, Programu

Marejeleo

Mwongozo wa Mtumiaji

DIVUS VISION API Programu

Taarifa ya Bidhaa