Обзор

Версия: 1.26.0

Агенты — это особый тип ресурсов, который связывает внешние службы/устройства с вашей системой OpenRemote через протоколы; агентов можно разделить на следующие категории:

• Специализированные агенты (Velbus, Z-Wave, KNX и т.д.)
• Общие агенты (HTTP, TCP, UDP, WS, MQTT и т. д.)

Агент <-> Связь протокола

Каждый тип агента имеет соответствующую реализацию Protocol; Агент сохраняет конфигурацию, которая затем передается экземпляру реализации протокола агента, поэтому существует связь «один к одному». Следующие атрибуты необходимы для всех типов агентов:

Атрибут

Описание

Тип значения

agentDisabled

Отключить агент

логическое значение

agentStatus

Текущий статус агента

Состояние соединения

Специализированные агенты

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

Универсальные агенты (агенты ввода-вывода)

Универсальные агенты ничего не понимают о базовых устройствах/службах и поэтому обычно требуют дополнительной настройки для их использования. Это дает большую гибкость с точки зрения того, с какими устройствами/службами вы можете взаимодействовать, а атрибуты Agent и параметры конфигурации Agent Link позволяют легко настроить общую обработку входящих/исходящих значений (преобразование типа данных, вставка значения в более крупную полезную нагрузку сообщения и т. д.), в общих агентах ввода-вывода можно использовать следующие атрибуты:

Атрибут

Описание

Тип значения

messageConvertHex

Может использоваться протоколами, которые его поддерживают, для указания того, что строковые значения должны быть преобразованы в/из байтов из/в строковое представление HEX (например, 34FD87).

логическое значение

messageConvertBinary

Может использоваться поддерживающими его протоколами для указания того, что строковые значения должны быть преобразованы в/из байтов из/в представление двоичной строки (например, 1001010111).

логическое значение

messageCharset

Кодировка, используемая при преобразовании byte[] в строку (по умолчанию должно быть UTF8, если не указано); значения должны быть строкой, соответствующей типу кодировки

Текст

messageMaxLength

Максимальная длина сообщений, получаемых протоколом; то, что это на самом деле означает, будет зависеть от протокола, т.е. для строковых протоколов это может быть количество символов, а для байтовых протоколов это может быть количество байтов. Обычно это используется для протоколов на основе ввода-вывода.

Положительное целое число

messageDelimiters

Определяет набор разделителей для сообщений, полученных протоколом; первый совпавший разделитель должен использоваться для создания кратчайшего возможного совпадения (это обычно используется для протоколов на основе ввода-вывода).

Текст[]

messageStripDelimiter

Для протоколов, использующих messageDelimiters, это указывает, следует ли удалить из сообщения соответствующий разделитель.

логическое значение

Ссылки на агентов

Обычные активы подключаются к агентам путем добавления элемента конфигурации Agent Link к атрибутам, которые необходимо подключить. Агенты могут иметь свои собственные параметры конфигурации Agent Link, но ниже приведены общие для всех параметры, которые можно найти в классе Agent link; агенты, у которых нет настраиваемых параметров, используют тип связи агента Default.

Поле

Описание

Тип значения

Требуется

id

Идентификатор агента, который является целью для этой ссылки на агента.

Актив ID

Да

type

Тип агентской связи; должен быть правильным типом для связываемого агента/протокола. Агенты, у которых нет специального типа связи агента, используют значение type Default.

Текст

Да

valueFiltersКогда протокол агента обновляет значение связанного атрибута, может быть желательно отфильтровать это значение, чтобы извлечь конкретную часть информации, которая фактически должна быть записана в связанный атрибут; эта опция определяет серию фильтров значений, через которые должны пройти входящие сообщения перед передачей протоколу агента. Входящее сообщение передается каждому фильтру в порядке массива, а результат одного является входными данными для следующего (т. е. они являются составными). Доступные фильтры значений можно найти среди известных типов в Javadoc, но доступные типы на момент написания можно найти ниже.

ФильтрЗначений

Н

valueConverter

Определяет карту преобразователя значений, позволяющую выполнять преобразование базового типа значения; входящее значение будет преобразовано в JSON, и если эта строка соответствует ключу в конвертере, значение этого ключа будет передано в атрибут. Примером использования является API, который возвращает текст ACTIVE/DISABLED, но вы хотите связать его с логическим атрибутом true/false.

JSON-объект

Н

writeValueConverter

Аналогично valueConverter, но для исходящих сообщений (Атрибут -> Протокол агента).

JSON-объект

Н

writeValue

Текстовое значение, которое будет использоваться для исходящих сообщений; может использоваться с любым типом атрибута в сочетании с динамическим заполнителем (см. ниже) или может использоваться с атрибутом типа ExecutionStatus (т. е. исполняемыми атрибутами) для определения значения, отправляемого в протокол агента, когда начинается выполнение атрибута.

Текст (JSON и т. д.)

Н

messageMatchPredicate

Используется в сочетании с messageMatchFilters; предикат применяется к входящим сообщениям (после применения messageMatchFilters), и если предикат совпадает, то считается, что сообщение соответствует атрибуту, и атрибут будет обновлен путем передачи исходного сообщения через фильтр(ы) значений и преобразователь.

ValuePredicate

Н

messageMatchFilters

Используется в сочетании с messageMatchPredicate, чтобы обеспечить фильтрацию входящего сообщения до оценки предиката соответствия.

ValueFilter[]

Н

Динамическое внедрение значений

Динамическое внедрение записанного или текущего значения атрибута поддерживается в общих протоколах с использованием заполнителя динамического значения %VALUE[:FORMAT]%. Его можно использовать в writeValue AgentLink, а также в других поддерживаемых местах в зависимости от протокола, например, протокол HTTP поддерживает использование этого в заголовках, параметрах запроса и/или пути. :FORMAT не является обязательным и использует java.util.Formatter. Если он не указан, то для преобразования значения в строковое представление JSON используется встроенное преобразование значений. например %VALUE:%.2f%, %VALUE%

Динамическое внедрение времени

Динамическое внедрение текущего времени поддерживается в общих протоколах с использованием заполнителя динамического времени %TIME[+/-PnDTnHnMn.nS][:FORMAT]%. Его можно использовать в writeValue из AgentLink, а также в других поддерживаемых местах в зависимости от протокола, например, протокол HTTP поддерживает использование этого в заголовках, параметрах запроса и/или пути. +/-PnDTnHnMn.nS и :FORMAT являются необязательными, если +/-PnDTnHnMn.nS использует java.time.Duration.parse(), а :FORMAT использует DateTimeFormatter с добавленной поддержкой EPOCH_MILLIS и EPOCH_SECONDS, если :FORMAT не указан, то предполагается ISO_INSTANT. например %TIME%, %TIME-PT1H%, %TIME+P20D:yyyy-dd-mm%, %TIME:EPOCH_MILLIS%

Известные типы фильтров значений

• RegexValueFilter
• SubStringValueFilter
• JSONPathFilter

[    {        "type": "jsonPath",        "path": "$..events[?(@.attributeState.ref.name == "targetTemperature").attributeState.value"    },    {        "type": "regex",        "pattern": ".*(\\d)$",        "matchGroup": 1    },    {       "type": "substring",       "beginIndex": 10,       "endIndex": 15    }]

Исполняемые связанные атрибуты

Атрибуты имеют тип Attribute Execute Status. Если в атрибут записано значение REQUEST_START, система будет искать поле writeValue в агентской ссылке, и если оно будет найдено, то это значение будет записано в протокол (обратите внимание, что динамическое внедрение значений не работает в этом сценарии, поскольку динамическое значение отсутствует).

Обнаружение/импорт агентов и активов

Обнаружение относится к поиску агентов/активов способом, специфичным для протокола, то есть обнаружению того, какие устройства подключены.

Импорт означает загрузку файла проекта конкретного протокола (Velbus .vlp, KNX .etsproj и т. д.) и извлечение набора ресурсов изнутри.

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

ProtocolInstanceDiscovery

Указывает, что данный протокол поддерживает обнаружение экземпляра/агента. Чтобы протокол поддерживал это, класс реализации должен быть указан в AgentDescriptor.

ProtocolAssetDiscovery

Указывает, что данный протокол поддерживает обнаружение дочерних активов. Чтобы протокол поддерживал это, он должен реализовать этот интерфейс. Если протокол поддерживает это, можно инициировать импорт, выбрав Agent в средстве просмотра ресурсов и найдя файл проекта для конкретного протокола с помощью средства выбора файла импорта, а затем инициировав импорт; любые активы, сгенерированные протоколом, будут автоматически добавлены как дочерние элементы Agent.

ProtocolAssetImport

Указывает, что данный протокол поддерживает импорт дочерних активов. Чтобы протокол поддерживал это, он должен реализовать этот интерфейс. Если протокол поддерживает это, можно инициировать импорт, выбрав Agent в средстве просмотра активов и найдя файл проекта для конкретного протокола с помощью средства выбора файла импорта, а затем инициировав импорт; любые активы, сгенерированные протоколом, будут автоматически добавлены как дочерние элементы Agent.

---

Уведомление о лицензии: атрибуция документации OpenRemote