Программное обеспечение DIVUS VISION API

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

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

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

DIVUS VISION API — это программный инструмент, предназначенный для взаимодействия с системами DIVUS VISION. Он позволяет пользователям получать доступ к различным элементам системы и управлять ими с помощью протоколов MQTT.

Часто задаваемые вопросы

Вопрос: Могу ли я использовать DIVUS VISION API без предварительного знания ПК или технологий автоматизации?

О: Руководство предназначено для пользователей, обладающих знаниями в этих областях, чтобы обеспечить эффективное использование API.

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

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

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

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

Введение

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

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

• MQTT-проводник (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, необходимо знать их идентификатор элемента: он отображается внизу формы настроек элемента.

БЕЗОПАСНОСТЬ

По соображениям безопасности доступ к 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.
• Изменения значений и другие необязательные параметры добавляются в тему с так называемой полезной нагрузкой. Параметры отдельных элементов (id элемента, имя, тип, функции)

Основное различие между MQTT и классической моделью клиент-сервер, в которой клиент запрашивает, а затем изменяет данные, основано на концепциях подписки и публикации. Участники могут публиковать данные, делая их доступными для других, которые, если им интересно, могут на них подписаться. Эта архитектура позволяет свести к минимуму обмен данными и при этом держать все заинтересованные стороны в курсе событий. Подробнее здесь: здесь нужно использовать специальные параметры (uuid, фильтры). Хотя существует несколько вариантов, в этом руководстве полезные данные показаны в формате JSON. JSON использует скобки и запятые для представления данных любой структуры и, таким образом, минимизирует размер передаваемых пакетов данных. Более подробную информацию о полезных нагрузках можно найти далее в руководстве.

• Для специальных целей можно фильтровать по типу функции, например, адресовать только включение/выключение, т.е. 1-битные переключатели. Для этой цели используется параметр filter в полезных данных. В настоящее время фильтрация возможна только по типу функции.
• Чтобы иметь возможность обращаться к отдельным элементам, требуется их идентификатор элемента. Это можно найти в 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/.

Примечание. Этот тип подписки примерно соответствует логике адресов обратной связи KNX; он показывает текущее состояние элементов и может использоваться для проверки того, были ли успешно применены желаемые изменения. Если вы хотите только считывать данные, но не изменять их, этого типа подписки достаточно.

Один простой элемент выглядит примерно так в нотации JSON.

Примечание. Все значения имеют синтаксис, показанный выше, например { «value»: «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

Для команд set полезная нагрузка, очевидно, играет основную роль, поскольку она будет содержать желаемые изменения (т.е. измененные значения функций элемента). Предупреждение: никогда не используйте опцию сохранения в командах типа 3, поскольку это может вызвать проблемы на стороне KNX.

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

Самый простой случай — изменить значение одного из элементов, отображаемых общей подпиской.
Вообще говоря, изменение/переключение функции VISION через MQTT состоит из 3 шагов, не все из которых абсолютно необходимы, но мы тем не менее рекомендуем их выполнить, как описано.

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

Для этого необходимо выполнить следующие шаги:

1. выберите client_id, например «Divus», и вставьте его в путь после имени пользователя API.
   Это полная тема по подписке на собственный канал связи с MQTT-сервером. Это сообщает серверу, где вы ожидаете ответов на изменения, которые вы собираетесь отправить. Обратите внимание на часть status/set, которая определяет 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 перед данными внутри полезных данных. См. синтаксис и структуру ниже.

ФИЛЬТР ПО ТИПУ ФУНКЦИИ В ЗАПРОСАХ

Параметр filter в полезных данных позволяет обращаться только к нужным функциям элемента. Функция включения/выключения выключателя или диммера называется «вкл./выкл.», например.ample, а соответствующий фильтр определяется следующим образом:

Тогда ответ выглядит так, напримерample

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

приводит к такому ответу:

Приложение

КОДЫ ОШИБОК

Ошибки в связи MQTT приводят к появлению числового кода. Следующая таблица поможет разобраться в этом.

ПАРАМЕТРЫ ПОЛЕЗНОЙ НАГРУЗКИ

Полезная нагрузка поддерживает разные параметры в зависимости от контекста. В следующей таблице показано, какие параметры могут встречаться в каких темах.

ПРИМЕЧАНИЯ К ВЕРСИИ

• 1.00 версия

Новости:

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

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

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

Ссылки

• Руководство пользователя