DIVUS VISION API софтуер

Спецификации

• Продукт: DIVUS VISION API
• Производител: DIVUS GmbH
• Версия: 1.00 REV0 1 – 20240528
• Местоположение: Pillhof 51, Eppan (BZ), Италия

Информация за продукта

DIVUS VISION API е софтуерен инструмент, предназначен за взаимодействие със системи DIVUS VISION. Той позволява на потребителите да имат достъп и да контролират различни елементи в системата, използвайки MQTT протоколи.

ЧЗВ

В: Мога ли да използвам DIVUS VISION API без предварителни познания за компютър или технология за автоматизация?

О: Наръчникът е пригоден за потребители с предишни познания в тези области, за да се гарантира ефективно използване на API.

ОБЩА ИНФОРМАЦИЯ

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

Инструкциите за работа, ръководствата и софтуерът са защитени с авторски права. Всички права запазени. Копирането, дублирането, преводът, преводът изцяло или частично не е разрешено. Изключение важи за създаването на резервно копие на софтуера за лична употреба.
Ръководството подлежи на промяна без предупреждение. Не можем да гарантираме, че данните, съдържащи се в този документ и на доставения носител за съхранение, са без грешки и са правилни. Винаги са добре дошли предложения за подобрения, както и съвети за грешки. Споразуменията важат и за конкретните приложения към това ръководство. Обозначенията в този документ може да са търговски марки, чието използване от трети страни за техни собствени цели може да наруши правата на техните собственици. Инструкции за потребителя: Моля, прочетете това ръководство, преди да го използвате за първи път, и го запазете на сигурно място за бъдещи справки. Целева група: Ръководството е написано за потребители с предишни познания за компютър и технологии за автоматизация.

КОНВЕНЦИИ ЗА ПРЕДСТАВЯНЕ

Въведение

ОБЩО ВЪВЕДЕНИЕ

Това ръководство описва VISION API (Интерфейс за програмиране на приложения) – интерфейс, чрез който VISION може да бъде адресиран и управляван от външни системи.
На практика това означава, че можете да използвате системи като напр

• MQTT Explorer (https://www.microsoft.com/store/… – за тестване),
• Домашен асистент (https://www.home-assistant.io/) или
• Node-RED (https://nodered.org/)

за управление на елементите, управлявани от VISION, или за прочитане на състоянието им. Достъпът и комуникацията се осъществяват чрез протокола MQTT, който използва така наречените теми, за да адресира отделни функции или набори от функции или да бъде информиран за промени в тях. За тази цел се използва MQTT сървър (брокер), който се грижи за сигурността и управлението/разпределението на съобщения до участниците. В този случай MQTT сървърът се намира директно на DIVUS KNX IQ и е специално конфигуриран за тази цел. Въпреки че VISION API може да се използва и без познания по програмиране, тази функционалност е подходяща за напреднали потребители.

ПРЕДПОСТАВКИ

Както е обяснено в ръководството на VISION, API потребителят трябва по подразбиране първо да бъде активиран, за да може да го използва. API достъпът работи само с помощта на данните за удостоверяване на потребителите на API. Що се отнася до потребителските права, активирането на тази функционалност може да бъде конфигурирано за всички или за отделни елементи. Вижте Глава 0. Разбира се, имате нужда и от VISION проект, в който елементите, които искате да контролирате отвън, са напълно конфигурирани и връзката към тях е успешно тествана. За да можете да адресирате отделни елементи чрез API, техният идентификатор на елемент трябва да се знае: това се показва в долната част на формуляра за настройки на елемента

СИГУРНОСТ

От съображения за сигурност достъпът до API е възможен само локално (т.е. не през облака). Следователно рискът за сигурността при активиране на API достъп е нисък. Въпреки това елементите, свързани със сигурността, не трябва да се активират или изрично отказват за достъп до API.

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

• В MQTT ролята на централизирано управление и разпространение на всички съобщения е тази на брокера. Въпреки че MQTT сървърът и MQTT брокерът не са синоними (сървърът е по-широк термин за роля, която MQTT клиентите също могат да играят), брокерът винаги се има предвид в това ръководство, когато се споменава MQTT сървър. Самият DIVUS KNX IQ играе ролята на MQTT брокер/MQTT сървър в контекста на това ръководство.
• MQTT сървърът използва така наречените теми: йерархична структура, с която данните се категоризират, управляват и публикуват.
• Публикуването има основната цел да направи данните достъпни за други участници чрез теми. Ако искате да промените стойност, пишете в желаната тема заедно с желаната промяна на стойността, също като използвате действие за публикуване. Целевото устройство или MQTT сървърът чете желаната промяна, която го засяга, и я приема съответно. За да проверите дали промяната е приложена, можете да погледнете в темата в реално време, за която сте се абонирали, за да видите дали промяната е отразена там – дали всичко е работило добре.
• Клиентите избират темите, които ги интересуват: това се нарича абониране. Всеки път, когато се промени стойност в/под тема, всички абонирани клиенти биват информирани – т.е. без да се налага изрично да питат дали нещо се е променило или каква е текущата стойност.
• Можете да отворите (или адресирате) отделен комуникационен канал с MQTT сървъра, като въведете всеки уникален низ, наречен client_id в тема. client_id трябва да се използва в темата за обработка на стойности. Това служи за идентифициране на произхода на всяка промяна, помага при всякакви грешки и не засяга другите клиенти, тъй като съответните отговори от сървъра, включително всички кодове за грешки и съобщения, също достигат до темата само със същия client_id (и следователно само този клиент). client_id е уникален символен низ, състоящ се от произволна комбинация от знаците 0-9, az, AZ, „-“, „_“.
• По принцип темите за абониране на MQTT сървъра на DIVUS KNX IQ съдържат състоянието на ключовата дума, докато темите за публикуване съдържат заявката за ключова дума. Тези със статус се актуализират автоматично веднага щом има външна промяна на стойността или веднага след като промяна на стойността е заявена от самия клиент чрез публикуване и е успешно приложена. Тези за публикуване се разделят допълнително на такива от тип (request/)get и такива от тип (request/)set.
• Промените на стойностите и други незадължителни параметри се добавят към темата с така наречения полезен товар. Параметрите на отделните елементи (element-id, name, type, functions)

Основната разлика между MQTT и класическия модел клиент-сървър, където клиентът изисква и след това променя данните, е съсредоточена върху концепциите за абониране и публикуване. Участниците могат да публикуват данни, като ги направят достъпни за други, които при интерес могат да се абонират за тях. Тази архитектура позволява да се сведе до минимум обменът на данни и въпреки това да се поддържат всички заинтересовани страни актуални. Повече за подробностите тук: и тук трябва да се използват специални параметри (uuid, филтри). Въпреки че има няколко опции, полезният товар се показва форматиран като JSON в това ръководство. JSON използва скоби и запетаи, за да представи данни с всякаква структура и по този начин минимизира размера на пакетите данни, които трябва да бъдат предадени. Повече подробности за полезните товари могат да бъдат намерени по-късно в ръководството.

• За специални цели е възможно да се филтрира според вида на функцията, напр. да се адресира само вкл./изкл., т.е. 1-битови превключватели. За тази цел се използва параметърът filters в полезния товар. В момента филтрирането е възможно само по тип функция.
• За да можете да адресирате отделни елементи, е необходим техният идентификатор на елемент. Това може да бъде намерено във VISION в менюто със свойства на елемента или също може да бъде прочетено директно от данните, които се показват пред всеки наличен елемент в общия абонамент на MQTT Explorer (елементите там са изброени по азбучен ред по идентификатор на елемент).

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

КОНФИГУРИРАНЕ НА VISION ЗА ПОТРЕБИТЕЛСКИ ДОСТЪП НА API

Във VISION като администратор отидете на Configuration – User/API Access Management, щракнете върху Users/API access и щракнете с десния бутон върху API User (или натиснете и задръжте), за да отворите прозореца за редактиране. Там ще намерите тези параметри и данни

• Активиране (квадратче за отметка)
  • Потребителят първо е активиран тук. По подразбиране е деактивирано
• Потребителско име
  • Този низ е необходим за достъп чрез API – копирайте го от тук
• Парола
  • Този низ е необходим за достъп чрез API – копирайте го от тук
• Разрешения
  • Правата по подразбиране за четене и писане на стойностите на VISION елементите могат да бъдат дефинирани тук, т.е. дефинираното тук се отнася за всички съществуващи и бъдещи елементи. Ако искате да разрешите достъп само до отделни елементи, не трябва да променяте тези права по подразбиране

РАЗРЕШЕНИЯ ЗА ОТДЕЛНИ ЕЛЕМЕНТИ

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

1. влезте във VISION като администратор
2. изберете желания елемент и отворете менюто с настройките му (щракнете с десния бутон или задръжте натиснат, след това Настройки)
3. под елемента от менюто Общи – Разрешения, активирайте „Замяна на разрешенията по подразбиране“ и след това отидете на подпозицията Разрешения, която показва матрицата на разрешенията.
4. активирайте разрешението за контрол тук, което също позволява на view разрешение директно. Ако искате само да четете данни чрез API достъп, достатъчно е да активирате view разрешение.
5. повторете същата процедура за всички елементи, до които искате да получите достъп

Връзка чрез MQTT

ВЪВЕДЕНИЕ

Като бившample, ние ще демонстрираме достъп чрез MQTT API на DIVUS KNX IQ със сравнително прост, безплатен софтуер, наречен MQTT Explorer (вижте глава 1.1), който е достъпен за Windows, Mac и Linux. Подразбират се основни познания и опит с MQTT.

ДАННИ, НЕОБХОДИМИ ЗА ВРЪЗКАТА

Както бе споменато по-рано (вижте раздел 2.1), потребителското име и паролата на потребителя на API са необходими. Ето един надписview от всички данни, които трябва да бъдат събрани преди установяване на връзка:

• Потребителско име Прочетете на страницата с подробности за потребителя на API
• Парола Прочетете на страницата с подробности на потребителя на API
• IP адрес Прочетете в настройките на стартовия панел под Общи – Мрежа – Ethernet (или чрез синхронизатор)
• Порт 8884 (този порт е запазен за тази цел)

ПЪРВА ВРЪЗКА С MQTT EXPLORER И ОБЩ АБОНАНТ

Обикновено MQTT прави разлика между дейностите абониране и публикуване. MQTT Explorer опростява това, като автоматично се абонира за всички налични теми (тема #), когато се направи първата връзка. В резултат на това дървото, което води до всички налични елементи (т.е. предоставен потребителски достъп на API), може да се види директно в лявата част на прозореца на MQTT Explorer след успешно свързване. За да въведете допълнителни теми за абониране или да замените # с по-конкретна тема, отидете на Разширени в прозореца за връзка. Темата, показана горе вдясно, изглежда така:

където 7f4x0607849x444xxx256573x3x9x983 е потребителското име на API, а objects_list съдържа всички налични елементи. Тази тема винаги се поддържа актуална, т.е. всички промени в стойността се отразяват там в реално време. Ако искате да се абонирате само за отделни елементи, въведете идентификатора на желания елемент след objects_list/.

Забележка: Този тип абониране приблизително съответства на логиката зад адресите за обратна връзка на KNX; показва текущото състояние на елементите и може да се използва за проверка дали желаните промени са приложени успешно. Ако искате само да четете данни, но не и да ги променяте, този тип абониране е достатъчно.

Единичен прост елемент изглежда така в JSON нотация

Забележка: Всички стойности имат синтаксиса, показан по-горе, напр. { “стойност”: “1” } като резултат от темите за абониране, докато стойността се записва директно в полезния товар за промяна на стойност (т.е. за теми за публикуване) – скобите и „стойност“ се пропускат, напр. „onoff“: „1“.

Разширени команди

ВЪВЕДЕНИЕ

Като цяло има 3 вида теми:

1. Абонирайте се за тема(и), за да видите наличните елементи и да получите промени в стойността в реално време
2. Абонирайте се за тема(и), за да получите отговорите на (клиентите ) публикувайте заявки
3. Публикувайте тема(и), за да получите или зададете елементи с техните стойности

По-късно ще се позоваваме на тези видове, като използваме номерацията, показана тук (напр. теми от тип 1, 2, 3). Повече подробности в следващите раздели и в гл. 4.2.

АБОНИРАЙТЕ СЕ ЗА ТЕМИ, ЗА ДА ВИДИТЕ НАЛИЧНИТЕ ЕЛЕМЕНТИ И ЗА ДА ПОЛУЧИТЕ ПРОМЕНИ НА СТОЙНОСТИТЕ В РЕАЛНО ВРЕМЕ

Те вече са описани

АБОНИРАЙТЕ СЕ ЗА ТЕМИ, ЗА ДА ПОЛУЧИТЕ ОТГОВОРИ НА ЗАЯВКИ ЗА ПУБЛИКУВАНЕ НА КЛИЕНТА

Този тип теми не са задължителни. Позволява да се

• отворете уникален комуникационен канал с MQTT сървъра, като използвате произволен client_id. Повече за това в гл. 4.2.2
• вземете резултата от заявките за публикуване на съответната тема за абониране: успех или неуспех с код за грешка и съобщение.

Има различни теми за получаване на отговори или за задаване на команди за публикуване. Съответната разлика в След като разберете необходимите теми за вашата система, може да решите да премахнете тази стъпка и директно да използвате темите за публикуване.

 ПУБЛИКУВАЙТЕ ТЕМИ, ЗА ДА ПОЛУЧИТЕ ИЛИ ЗАДАДЕТЕ ЕЛЕМЕНТИ С ТЕХНИТЕ СТОЙНОСТИ

Тези теми използват път, подобен на този за абониране – единствената промяна е думата „заявка“ на мястото на „статус“, използвана за абониране. Пълните пътища на теми са показани по-късно в гл. 4.2.2\ Get тема ще поиска да прочете елементите и стойностите на MQTT сървъра. Полезният товар може да се използва за филтриране въз основа на функционалния тип на елементите. Зададена тема ще поиска промяна на някои части от елемент, както е описано в неговия полезен товар.

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

 КРАТКО ОБЯСНЕНИЕ

Всички команди, които се изпращат към MQTT сървъра, имат обща начална част, а именно:

ПОДРОБНО ОБЯСНЕНИЕ

Темите в реално време (тип 1) ще имат общия префикс (вижте по-горе), последван от

or

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

EXAMPLE: ПУБЛИКУВАЙТЕ ЗА ПРОМЯНА НА СТОЙНОСТТА(ИТЕ) НА ЕДИН ЕЛЕМЕНТ

Най-простият случай е да искате да промените стойността на един от елементите, показани от общия абонат.
Най-общо казано, промяната/превключването на функция на VISION чрез MQTT се състои от 3 стъпки, не всички от които са абсолютно необходими, но въпреки това препоръчваме да ги извършите, както е описано.

1. Темата, която съдържа функцията, която искаме да редактираме, е абонирана с персонализиран client_id
2. Темата за редактиране се публикува заедно с полезния товар с желаните промени, като се използва client_id, избран в 1.
3. За да проверите, след това можете да видите отговора в тема (1.) – т.е. дали (2.) работи или не
4. В общия абонамент, където всички стойности се актуализират, когато се правят промени, можете да видите желаната промяна(и) на стойността, ако всичко работи добре.

Стъпките за това са:

1. изберете client_id, напр. „Divus“ и го вмъкнете в пътя след потребителското име на API
   Това е пълната тема за абониране за вашия собствен комуникационен канал с MQTT сървъра. Това казва на сървъра къде очаквате отговорите на промените, които възнамерявате да изпратите. Обърнете внимание на частта за статус/набор, която определя a. че е тема за абониране и b. че ще получи отговорите на командите за задаване на тип.
2. Темата за публикуване ще бъде същата, с изключение на превключването на ключовите думи за заявка за състояние
3. в какво трябва да се състои промяната е написано в полезния товар. Ето някои бившиampлес.
   • Изключване на елемент, който има функция за включване/изключване (1 бит):
   • Включване на елемент, който има функция за включване/изключване (1 бит). Освен това, ако няколко такива команди се стартират от един и същи клиент, параметърът uuid („уникален идентификатор“, обикновено е 128-битов низ, форматиран като 8-4-4-4-12 цифри шестнадесетичен) може да се използва за присвояване на отговор на съответната заявка, тъй като този параметър – ако присъства в заявката – може да бъде намерен и в отговора.
   • Включване и настройка на яркостта на димера на 50%
   • Отговорът на темата, показана и за която сте се абонирали по-горе (полезният й товар, за да бъдем точни), е тогава, напр.ampле.
     Горният отговор е изхample в случай на правилен полезен товар, въпреки че елементът няма функция за затъмняване. Ако има по-сериозни проблеми, водещи до това, че полезният товар не се интерпретира правилно, отговорът ще изглежда така (напр.):
     за обяснение на кодовете за грешки и съобщенията, но като цяло, както за http, 200 кода са положителни отговори, докато 400 са отрицателни.

EXAMPLE: ПУБЛИКУВАЙТЕ ЗА ПРОМЯНА НА МНОГО ЕЛЕМЕНТНИ СТОЙНОСТИ

Процедурата е подобна на тази, показана преди, за промяна на един елемент. Разликата е, че пропускате element_id от темите и след това посочвате набора от element_ids пред данните в полезния товар. Вижте синтаксиса и структурата по-долу.

ФИЛТРИРАНЕ ПО ТИП ФУНКЦИЯ В ЗАЯВКИ

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

Тогава отговорът изглежда така, напрample

Квадратната скоба показва, че можете също да филтрирате по няколко функции, напр

води до отговор като този:

Приложение

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

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

ПАРАМЕТРИ НА ПОЛЕЗНИЯ ТОВАР

Полезният товар поддържа различни параметри в зависимост от контекста. Следната таблица показва кои параметри могат да се появят в кои теми

БЕЛЕЖКИ ЗА ВЕРСИЯТА

• ВЕРСИЯ 1.00

Новини:

• Първа публикация

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

	DIVUS VISION API софтуер [pdf] Ръководство за потребителя VISION API софтуер, API софтуер, софтуер
	DIVUS Vision API софтуер [pdf] Ръководство за потребителя Vision API софтуер, Vision, API софтуер, софтуер

Референции

• Ръководство за потребителя