Програмне забезпечення DIVUS VISION API

Технічні характеристики

• Продукт: DIVUS VISION API
• Виробник: DIVUS GmbH
• Версія: 1.00 REV0 1 – 20240528
• Розташування: Pillhof 51, Eppan (BZ), Італія

Інформація про продукт

DIVUS VISION API — це програмний інструмент, призначений для взаємодії з системами DIVUS VISION. Це дозволяє користувачам отримувати доступ і контролювати різні елементи всередині системи за допомогою протоколів MQTT.

FAQ

З: Чи можу я використовувати API DIVUS VISION без попереднього знання ПК або технологій автоматизації?

Відповідь: Посібник створено для користувачів із попередніми знаннями в цих областях, щоб забезпечити ефективне використання API.

ЗАГАЛЬНІ ВІДОМОСТІ

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

Інструкції з експлуатації, інструкції та програмне забезпечення захищені авторським правом. Всі права захищені. Копіювання, тиражування, переклад, переклад повністю або частково заборонено. Виняток стосується створення резервної копії програмного забезпечення для особистого використання.
Інструкція може бути змінена без попередження. Ми не можемо гарантувати, що дані, які містяться в цьому документі та на носії, що постачається без помилок, є правильними. Завжди вітаються пропозиції щодо покращення, а також підказки щодо помилок. Угоди також застосовуються до окремих додатків до цього посібника. Позначення в цьому документі можуть бути товарними знаками, використання яких третіми особами для власних цілей може порушувати права їх власників. Інструкції користувача: Будь ласка, прочитайте цей посібник перед першим використанням і зберігайте його в надійному місці для використання в майбутньому. Цільова аудиторія: Посібник написаний для користувачів з попередніми знаннями ПК та техніки автоматизації.

УМОВНОСТІ ПРЕЗЕНТАЦІЇ

вступ

ЗАГАЛЬНИЙ ВСТУП

У цьому посібнику описано VISION API (інтерфейс прикладного програмування) – інтерфейс, за допомогою якого можна звертатися до VISION і керувати ним із зовнішніх систем.
На практиці це означає, що ви можете використовувати такі системи, як

• Провідник MQTT (https://www.microsoft.com/store/… – для перевірки),
• Домашній помічник (https://www.home-assistant.io/) або
• Node-RED (https://nodered.org/)

для керування елементами, якими керує VISION, або зчитування їх стану. Доступ і зв’язок відбуваються через протокол MQTT, який використовує так звані теми для звернення до окремих функцій або наборів функцій або для отримання інформації про зміни в них. Для цього використовується сервер (брокер) MQTT, який забезпечує безпеку та керування/розповсюдження повідомлень учасникам. У цьому випадку сервер MQTT розташований безпосередньо на DIVUS KNX IQ і спеціально налаштований для цієї мети. Хоча API VISION також можна використовувати без знань програмування, ця функція підходить для досвідчених користувачів.

ПРЕДМЕТНІСТЬ

Як пояснюється в посібнику 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.
• Зміни значень та інші необов'язкові параметри додаються до теми з так званим корисним навантаженням. Параметри окремих елементів (ідентифікатор елемента, назва, тип, функції)

Основна відмінність між MQTT і класичною клієнт-серверною моделлю, де клієнт запитує, а потім змінює дані, зосереджена на концепціях підписки та публікації. Учасники можуть публікувати дані, роблячи їх доступними для інших, які, якщо зацікавлені, можуть підписатися на них. Ця архітектура дозволяє звести до мінімуму обмін даними та все одно підтримувати всі зацікавлені сторони в курсі подій. Докладніше про деталі тут: тут потрібно використовувати спеціальні параметри (uuid, filters). Хоча існує кілька варіантів, у цьому посібнику корисне навантаження показано у форматі JSON. JSON використовує дужки та коми для представлення даних будь-якої структури, таким чином мінімізуючи розмір пакетів даних, які потрібно передати. Додаткову інформацію про корисні навантаження можна знайти далі в посібнику.

• Для спеціальних цілей можна фільтрувати за типом функції, наприклад, адресувати лише ввімкнення/вимкнення, тобто 1-бітні перемикачі. Для цього використовується параметр filters у корисному навантаженні. Наразі фільтрація можлива лише за типом функції.
• Щоб мати можливість адресувати окремі елементи, потрібен їхній ідентифікатор елемента. Це можна знайти у VISION у меню властивостей елемента або також можна прочитати безпосередньо з даних, які відображаються перед кожним доступним елементом у загальній підписці MQTT Explorer (там елементи перераховані в алфавітному порядку за ідентифікаторами елемента).

Конфігурація доступу до API

НАЛАШТУВАННЯ VISION ДЛЯ ДОСТУПУ КОРИСТУВАЧІВ API

У VISION як адміністратор перейдіть до Конфігурація – Керування доступом користувачів/API, клацніть Доступ Користувачі/API та клацніть правою кнопкою миші Користувач API (або натисніть і утримуйте), щоб відкрити вікно редагування. Там ви знайдете ці параметри та дані

• Увімкнути (прапорець)
  • Користувач спочатку вмикається тут. За замовчуванням вимкнено
• Ім'я користувача
  • Цей рядок потрібен для доступу через API – скопіюйте його звідси
• Пароль
  • Цей рядок потрібен для доступу через API – скопіюйте його звідси
• Дозволи
  • Тут можна визначити права за замовчуванням для читання та запису значень елементів VISION, тобто те, що тут визначено, застосовується до всіх існуючих і майбутніх елементів. Якщо ви хочете дозволити доступ лише до окремих елементів, вам не слід змінювати ці права за замовчуванням

ДОЗВОЛИ НА ОКРЕМІ ЕЛЕМЕНТИ

Рекомендується не надавати доступ API до всього проекту, а лише до потрібних елементів. Дійте наступним чином

1. увійдіть у VISION як адміністратор
2. виберіть потрібний елемент і відкрийте його меню налаштувань (клацніть правою кнопкою миші або утримуйте натиснутою, а потім Налаштування)
3. у пункті меню Загальні – Дозволи активуйте «Перевизначити дозволи за замовчуванням», а потім перейдіть до підпункту Дозволи, де показано матрицю дозволів.
4. активуйте тут дозвіл на керування, який також увімкне view дозвіл безпосередньо. Якщо ви хочете лише читати дані через доступ до API, достатньо ввімкнути view дозвіл.
5. повторіть ту саму процедуру для всіх елементів, до яких ви хочете отримати доступ

Підключення через MQTT

ВСТУП

Як колишнійampДалі ми продемонструємо доступ через 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

Примітка. Усі значення мають синтаксис, наведений вище, наприклад { “value”: “1” } як вихідні дані тем для підписки, тоді як значення записується безпосередньо в корисному навантаженні, щоб змінити значення (тобто для тем для публікації) – дужки та «value» опущено, наприклад «onoff»: «1».

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

ВСТУП

Загалом існує 3 типи тем:

1. Підпишіться на тему(и), щоб побачити доступні елементи та отримувати зміни вартості в реальному часі
2. Підпишіться на тему(и), щоб отримати відповіді на (клієнти ) опублікувати запити
3. Опублікуйте тему(и), щоб отримати або встановити елементи з їхніми значеннями

Пізніше ми посилатимемося на ці види, використовуючи наведену тут нумерацію (наприклад, теми типу 1, 2, 3). Детальніше в наступних розділах і в гл. 4.2.

ПІДПИШІТЬСЯ НА ТЕМИ, ЩОБ ПЕРЕГЛЯНУТИ ДОСТУПНІ ЕЛЕМЕНТИ І ОТРИМАТИ ЗМІНИ ВАРТОСТІ В РЕАЛЬНОМУ ЧАСІ

Вони вже були описані

ПІДПИШІТЬСЯ НА ТЕМИ, ЩОБ ОТРИМУВАТИ ВІДПОВІДІ НА ЗАПИТКИ КЛІЄНТА НА ПУБЛІКАЦІЮ

Такий тип тем необов’язковий. Це дозволяє

• відкрити унікальний канал зв’язку з сервером MQTT за допомогою довільного client_id. Детальніше про це в розд. 4.2.2
• отримати результат запитів на публікацію у відповідній темі підписки: успіх або невдача з кодом помилки та повідомленням.

Існують різні теми, щоб отримати відповіді або встановити команди публікації. Відповідна різниця в Щойно ви отримаєте чіткі теми, необхідні для вашої системи, ви можете вирішити видалити цей крок і безпосередньо використовувати теми публікації.

 ПУБЛІКУВАЙТЕ ТЕМИ, ЩОБ ОТРИМАТИ АБО ВСТАНОВИТИ ЕЛЕМЕНТИ З ЇХНЯМИ ЗНАЧЕННЯМИ

У цих темах використовується шлях, схожий на шлях для підписки – єдиною зміною є слово «запит» замість «статусу», який використовується для підписки. Повні шляхи до тем показані далі в розділі. 4.2.2\ Тема отримання надсилає запит на читання елементів і значень сервера MQTT. Корисне навантаження може використовуватися для фільтрації на основі типу функції елементів. Набір тем вимагатиме змінити деякі частини елемента, як зазначено в його корисному навантаженні.

ПРЕФІКС ДЛЯ КОМАНД ТА ВІДПОВІДНИХ ВІДПОВІДЕЙ

 КОРОТКЕ ПОЯСНЕННЯ

Усі команди, які надсилаються на сервер MQTT, мають спільну початкову частину, а саме:

ДЕТАЛЬНЕ ПОЯСНЕННЯ

Теми реального часу (тип 1) матимуть загальний префікс (див. вище), а потім наступний

or

Для набір команд корисне навантаження, очевидно, відіграє головну роль, оскільки воно міститиме бажані зміни (тобто змінені значення для функцій елемента). Попередження: ніколи не використовуйте параметр retain у своїх командах типу 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. що він отримає відповіді на команди типу set.
2. Тема публікації буде такою ж, за винятком перемикання ключових слів запиту статусу
3. те, з чого має складатися зміна, написано в корисному навантаженні. Ось деякі ексampлес.
   • Вимкнення елемента, який має функцію включення/вимкнення (1 біт):
   • Вмикання елемента, що має функцію включення/вимкнення (1 біт). Крім того, якщо кілька таких команд запускаються з одного клієнта, параметр uuid («унікальний ідентифікатор», як правило, це 128-бітний рядок, відформатований як 8-4-4-4-12 цифр у шістнадцятковому форматі) можна використовувати для призначення відповідь на відповідний запит, оскільки цей параметр, якщо він присутній у запиті, також можна знайти у відповіді.
   • Увімкнення та встановлення яскравості диммера на 50%
   • Відповідь на тему, показану вище та підписану на неї (її корисне навантаження, якщо бути точним), тоді, напр.ample.
     Наведена вище відповідь є прикладомample у випадку правильного корисного навантаження, хоча елемент не має функції затемнення. Якщо є більш серйозні проблеми, через які корисне навантаження не тлумачиться правильно, відповідь виглядатиме так (наприклад):
     для пояснення кодів помилок і повідомлень, але загалом, як і для http, 200 кодів є позитивними відповідями, а 400 – негативними.

EXAMPLE: ПУБЛІКУВАТИ ДЛЯ ЗМІНИ КІЛЬКОХ ЗНАЧЕНЬ ЕЛЕМЕНТІВ

Процедура подібна до описаної раніше для зміни окремого елемента. Різниця полягає в тому, що ви пропускаєте element_id у темах, а потім вказуєте набір element_ids перед даними всередині корисного навантаження. Перегляньте синтаксис і структуру нижче.

ФІЛЬТР ЗАПИТІВ ЗА ТИПОМ ФУНКЦІЇ

Параметр filters у корисному навантаженні дозволяє адресувати лише бажану функцію(-и) елемента. Функція вмикання/вимкнення вимикача або диммера називається «вмикання», наприкладample, а відповідний фільтр визначається таким чином:

Тоді відповідь виглядає так, наприкладample

Квадратна дужка означає, що ви також можете фільтрувати за кількома функціями, наприклад

призводить до такої відповіді:

Додаток

КОДИ ПОМИЛОК

Помилки в зв’язку MQTT призводять до числового коду. Наступна таблиця допоможе розбити це.

ПАРАМЕТРИ КОРИСНОГО НАВАНТАЖЕННЯ

Корисне навантаження підтримує різні параметри залежно від контексту. У наведеній нижче таблиці показано, які параметри можуть зустрічатися в окремих темах

ПРИМІТКИ ВЕРСІЇ

• 1.00 версія

Новини:

• Перша публікація

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

	Програмне забезпечення DIVUS VISION API [pdfПосібник користувача Програмне забезпечення VISION API, програмне забезпечення API, програмне забезпечення
	Програмне забезпечення DIVUS Vision API [pdfПосібник користувача Програмне забезпечення Vision API, Vision, програмне забезпечення API, програмне забезпечення

Список літератури

• Посібник користувача