Упатство за корисникот на софтверот DIVUS VISION API

DIVUS VISION API е софтверска алатка дизајнирана за поврзување со DIVUS VISION системите. Тоа им овозможува на корисниците пристап и контрола на различни елементи во системот користејќи MQTT протоколи.

Најчесто поставувани прашања

П: Дали можам да користам DIVUS VISION API без претходно познавање на компјутер или технологија за автоматизација?

О: Прирачникот е прилагоден за корисници со претходно знаење во овие области за да се обезбеди ефикасно користење на API.

ОПШТИ ИНФОРМАЦИИ

DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – Италија

Упатствата за работа, прирачниците и софтверот се заштитени со авторски права. Сите права се задржани. Не е дозволено копирање, дуплирање, преведување, преведување во целина или делумно. Исклучок се однесува на создавање резервна копија на софтверот за лична употреба.
Упатството може да се промени без претходна најава. Не можеме да гарантираме дека податоците содржани во овој документ и на доставените медиуми за складирање се без грешки и точни. Предлозите за подобрувања, како и советите за грешки се секогаш добредојдени. Договорите се однесуваат и на специфичните анекси на овој прирачник. Ознаките во овој документ може да бидат заштитни знаци чија употреба од трети лица за свои цели може да ги наруши правата на нивните сопственици. Упатства за користење: Ве молиме прочитајте го ова упатство пред да го користите за прв пат и чувајте го на безбедно место за идна референца. Целна група: Прирачникот е напишан за корисници со претходно познавање на компјутер и технологија за автоматизација.

КОНВЕНЦИИ ЗА ПРЕЗЕНТАЦИЈА

Вовед

ОПШТ ВОВЕД

Овој прирачник го опишува VISION API (Application Programming Interface) – интерфејс преку кој VISION може да се адресира и контролира од надворешни системи.
Во практична смисла, тоа значи дека можете да користите системи како што се

MQTT Explorer (https://www.microsoft.com/store/… – за тестирање),

Домашен асистент (https://www.home-assistant.io/) или
Јазол-ЦРВЕНО (https://nodered.org/)

да ги контролира елементите управувани од VISION или да го прочита нивниот статус. Пристапот и комуникацијата се одвиваат преку протоколот MQTT, кој користи таканаречени теми за да се осврне на поединечни функции или множества на функции или да се информира за промените во нив. За таа цел се користи MQTT сервер (брокер), кој се справува со безбедноста и управувањето/дистрибуцијата на пораките до учесниците. Во овој случај, серверот MQTT се наоѓа директно на DIVUS KNX IQ и е специјално конфигуриран за оваа намена. Иако VISION API може да се користи и без знаење за програмирање, оваа функционалност е погодна за напредни корисници.

Предуслови

Како што е објаснето во прирачникот VISION, корисникот на API стандардно мора прво да се активира за да може да го користи, пристапот до API работи само со помош на податоците за автентикација на корисниците на Api. Што се однесува до корисничките права, активирањето за оваа функционалност потоа може да се конфигурира или на сите или на поединечни елементи. Види Поглавје.0. Секако, потребен ви е и проект VISION во кој елементите што сакате да ги контролирате однадвор се целосно конфигурирани и врската со нив е успешно тестирана. За да може да се адресираат поединечни елементи преку API, мора да се знае нивниот ID на елементот: ова се прикажува на дното на формуларот за поставки на елементот

БЕЗБЕДНОСТ

Од безбедносни причини, пристапот до API е можен само локално (т.е. не преку облакот). Затоа, безбедносниот ризик при активирање на пристапот до API е низок. Сепак, елементите релевантни за безбедноста не треба да бидат овозможени или експлицитно одбиени за пристап до API.

MQTT И НЕГОВИ УСЛОВИ – КРАТКО ОБЈАСНУВАЊЕ

Во MQTT, улогата на централизирано управување и дистрибуција на сите пораки е на брокерот. Иако MQTT серверот и MQTT брокерот не се синоними (серверот е поширок поим за улогата што може да ја играат и клиентите на MQTT), брокерот секогаш се мисли во овој прирачник кога се споменува MQTT серверот. Самиот DIVUS KNX IQ ја игра улогата на брокерот MQTT / серверот MQTT во контекст на овој прирачник.
MQTT серверот користи таканаречени теми: хиерархиска структура со која податоците се категоризираат, управуваат и објавуваат.

Објавувањето има примарна цел да ги направи податоците достапни за другите учесници преку теми. Ако сакате да промените вредност, пишувате на саканата тема заедно со саканата промена на вредноста, исто така користејќи дејство за објавување. Целниот уред или серверот MQTT ја чита саканата промена што влијае на него и соодветно ја прифаќа. За да проверите дали промената е применета, можете да погледнете во претплатената тема во реално време за да видите дали промената се рефлектира таму - дали сè функционира добро.
Клиентите ги избираат темите што ги интересираат: ова се нарекува претплата. Секогаш кога некоја вредност се менува во/под темата, се информираат сите претплатени клиенти – т.е. без потреба експлицитно да се прашуваат дали нешто се променило или која е моменталната вредност.

Можете да отворите (или адресирате) посебен канал за комуникација со серверот MQTT со внесување на која било единствена низа наречена client_id во темата. Клиентот_ид мора да се користи во темата за да се обработат вредностите. Ова служи за да се идентификува потеклото на секоја промена, помага при какви било грешки и не влијае на другите клиенти, бидејќи соодветните одговори од серверот, вклучувајќи ги сите кодови за грешка и пораки, исто така допираат до темата само со истиот клиент_ид (и со тоа само тој клиент). Клиент_ид е уникатна низа на знаци која се состои од која било комбинација на знаците 0-9, az, AZ, “-”, “_”.
Општо земено, темите за претплата на MQTT серверот на DIVUS KNX IQ го содржат статусот на клучниот збор, додека темите за објавување го содржат барањето за клучни зборови. Оние со статус автоматски се ажурираат веднаш штом има надворешна промена на вредноста или штом промената на вредноста е побарана од самиот клиент преку објавување и е успешно применета. Оние за објавување понатаму се поделени на оние од типот (барање/)get и оние од типот (барање/)сет.

Промените на вредностите и другите опционални параметри се додаваат на темата со т.н. носивост. Параметрите на поединечните елементи (елемент-ид, име, тип, функции)

Главната разлика помеѓу MQTT и класичниот модел клиент-сервер, каде клиентот бара, а потоа менува податоци, е фокусирана на концептите на претплата и објавување. Учесниците можат да објават податоци, правејќи ги достапни за други, кои доколку се заинтересирани можат да се претплатат на нив. Оваа архитектура овозможува да се минимизира размената на податоци и сепак да се одржуваат ажурирани сите заинтересирани страни. Повеќе за деталите овде: и тука треба да се користат специјални параметри (uuid, филтри). Иако има неколку опции, товарот е прикажан форматиран како JSON во овој прирачник. JSON користи загради и запирки за да ги претстави податоците од која било структура и на тој начин ја минимизира големината на пакетите со податоци што треба да се пренесат. Повеќе детали за носивоста може да се најдат подоцна во прирачникот.

За посебни намени, можно е да се филтрира според типот на функцијата, на пр. да се адресира само вклучување/исклучување, односно 1-битни прекинувачи. За таа цел се користи параметарот филтри во носивоста. Филтрирањето моментално е можно само според типот на функцијата.
За да може да се адресираат поединечни елементи, потребен е нивниот ID на елементот. Ова може да се најде во VISION во менито со својства на елементот или може да се чита директно од податоците што се прикажани пред секој достапен елемент во општата претплата на MQTT Explorer (елементите таму се наведени по азбучен ред по ID на елементот).

Конфигурација за пристап до API

КОНФИГУРИРАЊЕ ВИЗИЈА ЗА ПРИСТАП НА КОРИСНИК НА API

Во VISION како администратор, одете во Конфигурација – Управување со пристап на корисник/API, кликнете на Users/API пристап и кликнете со десното копче на API User (или притиснете и задржете) за да го отворите прозорецот за уредување. Таму ќе ги најдете овие параметри и податоци

Овозможи (поле за избор)
- Корисникот прво е овозможен овде. Стандардно е оневозможено
Корисничко име
- Оваа низа е потребна за пристап преку API - копирајте ја од овде
Лозинка
- Оваа низа е потребна за пристап преку API - копирајте ја од овде
Дозволи
- Овде може да се дефинираат стандардните права за читање и запишување на вредностите на елементите VISION, односно она што е дефинирано овде важи за сите постоечки и идни елементи. Ако сакате да дозволите пристап само до поединечни елементи, не треба да ги менувате овие стандардни права

ДОЗВОЛИ ЗА ПОЕДИНЕЧНИ ЕЛЕМЕНТИ

Препорачливо е да не дозволувате API пристап до целиот проект, туку само до саканите елементи. Постапете на следниов начин

најавете се на VISION како администратор
изберете го саканиот елемент и отворете го менито за поставки (десен-клик или држете го притиснато, потоа Settings)

под записот од менито Општо – Дозволи, активирајте „Одредување на стандардните дозволи“ и потоа одете во под-точка Дозволи, која ја прикажува матрицата за дозволи.
активирајте ја контролната дозвола овде, која исто така го овозможува view дозвола директно. Ако сакате само да читате податоци преку пристапот API, доволно е да го овозможите view дозвола.
повторете ја истата постапка за сите елементи до кои сакате да пристапите

Поврзување преку MQTT

ВОВЕД

Како ексampле, ќе демонстрираме пристап преку MQTT API на DIVUS KNX IQ со релативно едноставен, бесплатен софтвер наречен MQTT Explorer (види поглавје 1.1), кој е достапен за Windows, Mac и Linux. Се подразбира основно знаење и искуство со MQTT.

ПОТРЕБНИ ПОДАТОЦИ ЗА ПОВРЗУВАЊЕТО

Како што беше споменато претходно (види дел 2.1), потребни се корисничкото име и лозинката на корисникот на API. Еве крајview од сите податоци што мора да се соберат пред да се воспостави врска:

Корисничко име Прочитајте на страницата со детали на корисникот на API
Лозинка Прочитајте ја на страницата со детали на корисникот на API

IP адреса Прочитајте во поставките за фрлач под Општо – Мрежа – Етернет (или преку Синхронизатор)
Порта 8884 (оваа порта е резервирана за оваа намена)

ПРВА ВРСКА СО MQTT EXPLORER И ОПШТА ПРЕТПЛАТА

Нормално, MQTT прави разлика помеѓу активностите што се претплатите и објавувате. MQTT Explorer го поедноставува ова со автоматско претплата на сите достапни теми (тема #) кога ќе се направи првата врска. Како резултат на тоа, дрвото што води до сите достапни елементи (т.е. доделен пристап на корисникот на API) може да се види директно во левата област на прозорецот MQTT Explorer по успешното поврзување. За да внесете дополнителни теми за претплати или да го замените # со поконкретна тема, одете во Напредно во прозорецот за поврзување. Темата прикажана на горниот десен дел изгледа отприлика вака:

каде што 7f4x0607849x444xxx256573x3x9x983 е корисничкото име на API и листата на објекти ги содржи сите достапни елементи. Оваа тема секогаш се одржува ажурирана, т.е. сите промени на вредностите се рефлектираат таму во реално време. Ако сакате да се претплатите само на поединечни елементи, внесете го ID на елементот на саканиот елемент по objects_list/.

Забелешка: Овој тип на претплата приближно одговара на логиката зад адресите за повратни информации на KNX; го прикажува моменталниот статус на елементите и може да се користи за да се провери дали саканите промени се успешно применети. Ако сакате само да ги читате податоците, но не и да ги менувате, овој тип на претплата е доволен.

Еден едноставен елемент изгледа вака во нотацијата JSON

Забелешка: Сите вредности ја имаат синтаксата прикажана погоре, на пр. { „вредност“: „1“ } како излез од темите за претплата, додека вредноста е напишана директно во товарот за промена на вредност (т.е. за објавување теми) - заградите и „вредноста“ е испуштена на пр. „вклучено“: „1“.

Advanced commands

ВОВЕД

Општо земено, постојат 3 типа на теми:

Претплатете се тема(и) за да ги видите достапните елементи и да ги добивате промените на вредноста во реално време
Претплатете се теми(и) за да ги добиете одговорите на (the clients ) објавува барања

Објавувајте тема(и) за да добиете или да поставите елементи со нивните вредности

Подоцна ќе се осврнеме на овие видови користејќи го нумерирањето прикажано овде (на пр. теми од типот 1, 2, 3). Повеќе детали во следните делови и во погл. 4.2.

ПРЕТПЛАТЕТЕ СЕ ТЕМИ ЗА ДА ГИ ВИДИТЕ ДОСТАПНИТЕ ЕЛЕМЕНТИ И ДА ДОБИЕТЕ ПРОМЕНИ НА ВРЕДНОСТА ВО РЕАЛНО ВРЕМЕ

Овие се веќе опишани

ПРЕТПЛАТЕТЕ СЕ ТЕМИ ЗА ДА ГИ ДОБИВАТЕ ОДГОВОРИТЕ НА БАРАЊАТА ЗА ОБЈАВУВАЊЕ НА КЛИЕНТОТ

Овој вид на теми е изборен. Тоа овозможува да

отворете единствен канал за комуникација со серверот MQTT со користење на произволен клиент_ид. Повеќе за тоа во поглавје. 4.2.2
добијте го резултатот од барањата за објавување на соодветната тема за претплата: успех или неуспех со код за грешка и порака.

Постојат различни теми за да добиете одговори за да добиете или да поставите команди за објавување. Соодветната разлика во Откако ќе ги исправите потребните теми за вашиот систем, може да одлучите да го отстраните овој чекор и директно да ги користите темите за објавување.

ОБЈАВЕТЕ ТЕМИ ЗА ДОБИВАЊЕ ИЛИ ДА ПОСТАВИТЕ ЕЛЕМЕНТИ СО НИВНИТЕ ВРЕДНОСТИ

Овие теми користат патека слична на оние за претплата - единствената промена е зборот „барање“ наместо „статусот“ што се користи за претплата. Целосните патеки на темата се прикажани подоцна во поглавје. 4.2.2\ Темата за добивање ќе бара да се прочитаат елементите и вредностите на серверот MQTT. Товарот може да се користи за филтрирање врз основа на типот на функцијата на елементите. Поставената тема ќе бара да се сменат некои делови од елементот, како што е наведено во неговата носивост.

ПРЕФИКС ЗА НАРЕДИ И СООДВЕТНИ ОДГОВОРИ

КРАТКО ОБЈАСНУВАЊЕ

Сите команди што се испраќаат до серверот MQTT имаат заеднички почетен дел, имено:

DETAILED EXPLANATION

Темите во реално време (тип 1) ќе имаат општ префикс (види погоре), а потоа следат

За сет команди, носивоста очигледно ја игра главната улога бидејќи ќе ги содржи саканите промени (т.е. променетите вредности за функциите на елементот). Предупредување: Никогаш не користете ја опцијата за задржување во командите од тип 3 бидејќи може да предизвика проблеми на страната KNX.

EXAMPLE: ОБЈАВИ ЗА ПРОМЕНА НА ВРЕДНОСТИ НА ЕДЕН ЕЛЕМЕНТ

Наједноставниот случај е да сакате да ја смените вредноста на еден од елементите прикажани со општата претплата.
Општо земено, менувањето/префрлањето на функцијата на VISION преку MQTT се состои од 3 чекори, од кои сите не се апсолутно неопходни, но сепак препорачуваме да ги извршите како што е опишано.

Темата што ја содржи функцијата што сакаме да ја уредиме е претплатана со помош на прилагоден клиент_ид
Темата за уредување се објавува заедно со носивоста со саканите промени со користење на клиент_ид избран во 1.

За да проверите, потоа можете да го видите одговорот во темата (1.) – т.е. дали (2.) функционираше или не
Во општата претплата, каде што сите вредности се ажурираат кога се прават промени, можете да ја видите саканата промена(и) на вредноста ако сè функционира добро.

The steps to do this are:

изберете клиент_ид на пр. „Divus“ и вметнете го во патеката по корисничкото име на API
Ова е комплетната тема за претплата на вашиот сопствен канал за комуникација со серверот MQTT. Ова му кажува на серверот каде ги очекувате одговорите на промените што имате намера да ги испратите. Забележете го делот за статус/сет кој дефинира a. дека е тема за претплата и б. дека ќе ги добие одговорите за поставување команди за тип.
Темата за објавување ќе биде иста, освен за префрлување на клучните зборови за барање статус
во што треба да се состои промената е запишано во товарот. Еве некои бившиampлес.
- Исклучување на елемент што има функција за вклучување/исклучување (1 бит):
- Вклучување на елемент кој има функција за вклучување/исклучување (1 бит). Дополнително, ако неколку такви команди се стартуваат од ист клиент, параметарот uuid („уникатен ID“, обично е 128-битна низа форматирана како 8-4-4-4-12 цифри хексадецимален) може да се користи за доделување на одговор на соодветното барање, бидејќи овој параметар - доколку е присутен во барањето - може да се најде и во одговорот.
- Вклучување и поставување на осветленоста на придушувачот на 50%
- Одговорот на темата прикажана и претплатена погоре (нејзината носивост, поточно) е тогаш, на прampле.
  Горенаведениот одговор е прample во случај на правилна носивост, иако елементот нема функција за затемнување. Ако има посериозни проблеми поради кои товарот не се толкува правилно, одговорот ќе изгледа вака (на пр.):
  за објаснување на кодовите за грешки и пораките, но генерално, како и за http, 200 кодови се позитивни одговори додека 400 се негативни.

EXAMPLE: ОБЈАВУВАЊЕ ЗА ПРОМЕНА НА ВРЕДНОСТИ НА ПОВЕЌЕ ЕЛЕМЕНТИ

Постапката е слична на онаа прикажана претходно за промена на еден елемент. Разликата е во тоа што го испуштате елементот_ид од темите, а потоа го означувате множеството елемент_иди пред податоците во товарот. Погледнете ја синтаксата и структурата подолу.

ФИЛТРИРАЈ ПО ТИП ФУНКЦИЈА ВО ПРАШАЊАТА

Параметарот на филтри во носивото дозволува да се адресира само саканата(и) функција(и) на елементот. Функцијата за вклучување/исклучување на прекинувачот или затемнувачот се нарекува „исклучување“, на прample, а соодветниот филтер е дефиниран на овој начин:

Одговорот тогаш изгледа вака, на прample

Квадратната заграда покажува дека можете да филтрирате и по неколку функции, на пр

води до одговор како овој:

Додаток

КОДИ ЗА ГРЕШКИ

Грешките во комуникацијата MQTT резултираат со нумерички код. Следната табела помага да се разложи.

ПАРАМЕТРИ НА ПЛАЌАЊЕТО

Товарот поддржува различни параметри во зависност од контекстот. Следната табела покажува кои параметри може да се појават во кои теми

VERSION NOTES

1.00 ВЕРЗИЈА

Вести:

• Прво објавување

Документи / ресурси

	Софтвер DIVUS VISION API [pdf] Упатство за користење VISION API софтвер, API софтвер, софтвер
	Софтвер DIVUS Vision API [pdf] Упатство за корисникот Vision API софтвер, Vision, API софтвер, софтвер

Референци

Упатство за употреба

Софтвер DIVUS VISION API

Информации за производот