The Things Stack (TTS)

Версия: 1.26.0

Агент TTS позволяет интегрировать устройства LoRaWAN, управляемые The Things Stack (V3).

Как это работает

Агент TTS действует как мост между OpenRemote и сетевым сервером Things Stack, используя два основных канала связи:

Обмен сообщениями (MQTT)

Агент подключается к интеграции TTS MQTT для потока данных в реальном времени:

Сообщения восходящей линии связи. Агент подписывается на события устройства для получения данных датчиков.
Сообщения нисходящей линии связи. Агент публикует сообщения в разделах команд для отправки пакетов конфигурации или управления обратно на конечные устройства.

Управление и обнаружение устройств (gRPC API)

Агент использует The Things Stack gRPC API в качестве основного интерфейса для управления жизненным циклом устройства и метаданными. Это используется для:

Автоматическое обнаружение в режиме реального времени. Вместо периодического опроса агент прослушивает поток событий gRPC. Когда устройство отправляет восходящий канал или выполняет Join, агент мгновенно обнаруживает это.
Идентификация шаблона на основе атрибутов. После обнаружения устройства агент запрашивает API-интерфейс gRPC, чтобы получить конкретные метаданные устройства. Он ищет пользовательский атрибут устройства TTS, который определяет тип ресурса OpenRemote, что позволяет агенту автоматически применять правильный шаблон.

Конфигурация агента

Ниже описаны поддерживаемые атрибуты конфигурации агента:

Атрибут

Описание

Требуется

По умолчанию

MQTTHost

Имя хоста или IP-адрес брокера TTS MQTT.

Да

MQTTPort

Сетевой порт для подключения MQTT.

Да

clientId

Уникальный идентификатор сеанса этого агента в брокере MQTT.

Да

secureMode

Логический флаг, указывающий, должно ли соединение MQTT использовать шифрование TLS/SSL.

ложный

usernamePassword

Учетные данные MQTT (формат JSON — см. ниже)

Да

resumeSession

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

ложный

subscribeQos

Уровень качества обслуживания MQTT для приема восходящих каналов (0, 1, 2).

publishQos

Уровень качества обслуживания MQTT для отправки нисходящих каналов (0, 1, 2).

host

Имя хоста или IP-адрес API TTS gRPC.

Да

port

Сетевой порт для API TTS gRPC.

secureGRPC==true -> 443, secureGRPC==false -> 80

applicationId

Идентификатор приложения TTS, которое необходимо интегрировать.

Да

tenantId

Идентификатор арендатора TTS.

Да

apiKey

Ключ API TTS, используемый для аутентификации соединения gRPC.

Да

secureGRPC

Логический флаг, включающий шифрование gRPC TLS/SSL.

правда

Формат учетных данных MQTT

Агент TTS требует, чтобы атрибут usernamePassword был предоставлен в определенном формате JSON. Обратите внимание, что имя пользователя — это объединенный идентификатор приложения и клиента, а пароль — это ваш ключ API TTS.

Формат:

{  "username": "{applicationId}@{tenantId}",  "password": "{apiKey}"}

Пример:

MQTTHost: eu1.cloud.thethings.networkMQTTPort: 8883clientId: or_tts_agent_1secureMode: trueusernamePassword: >  {    "username": "parking-sensors@ttn",    "password": "NNSXS.FUFJDFQHVP7SRG2FAE3NS26LVDQQMFTKVVBPCGI.YHI2JQ6..."  }resumeSession: truehost: eu1.cloud.thethings.networkport: 443applicationId: parking-sensorstenantId: ttnapiKey: NNSXS.FUFJDFQHVP7SRG2FAE3NS26LVDQQMFTKVVBPCGI.YHI2JQ6... secureGRPC: true

Сопоставление устройств с активами

Чтобы агент TTS мог автоматически создавать и настраивать ресурсы, он должен сопоставить устройство TTS с определенным типом ресурса OpenRemote.

Сопоставление автоматического обнаружения (атрибуты TTS)

Для устройств, обнаруженных через поток событий gRPC, сопоставление определяется в Атрибутах конечного устройства TTS. Добавляя определенный атрибут к устройству в консоли TTS, вы предоставляете агенту шаблон типа актива, необходимый для создания актива в OpenRemote:

Ключ атрибута

Значение атрибута

openremote-asset-type

Точное имя Типа ресурса OpenRemote (например, WeatherStationAsset).Во время автоматического обнаружения агент считывает этот атрибут устройства TTS и создает соответствующий актив в OpenRemote.

Сопоставление импорта CSV

При импорте устройств через файл CSV тип актива определяется непосредственно в файле. CSV-файл должен включать столбец, в котором указано Имя типа актива для каждой записи устройства.

Подробное описание необходимых столбцов и пример файла см. в разделе Формат импорта CSV ниже.

Автоматизация связи агента MQTT

Агент TTS обрабатывает передачу данных датчиков (восходящие каналы) и команд (нисходящие каналы) через протокол MQTT. Чтобы исключить необходимость ручной настройки каждого атрибута, агент автоматически подготавливает эти каналы связи в процессе обнаружения или импорта.

Логика автоматической подготовки

После определения соответствующего шаблона типа актива агент настраивает Ссылки агента MQTT на основе следующего рабочего процесса:

Поиск мета-элемента: агент сканирует атрибуты выбранного типа актива на наличие мета-элемента с именем AGENT_LINK_CONFIG. Подробную информацию о формате этого метаэлемента см. в разделе Типы активов LoRaWAN.
Создание ссылки: агент использует шаблон, определенный в метаэлементе, для создания конкретных тем MQTT и фильтров данных, необходимых для этого отдельного устройства.

Атрибуты настроены

Следующие атрибуты автоматически заполняются в результирующих ссылках агента для обработки логики протокола MQTT:

Специально для MQTT: subscriptionTopic, publishTopic.
Общая обработка данных: valueFilters, messageMatchPredicate, messageMatchFilters, writeValue и writeValueConverter.

Формат импорта CSV

Массовая подготовка позволяет создавать множество ресурсов одновременно. Агент обрабатывает каждую строку для создания экземпляра нового актива, используя указанный assetType, чтобы определить, какой шаблон применить для автоматической настройки связи.

Структура столбца CSV

Примечание. CSV-файл не должен содержать строку заголовка. Агент идентифицирует данные на основе определенного порядка столбцов, определенного ниже.

Кол

Требуется

Атрибут

Описание

ДА

devEUI

16-значный шестнадцатеричный уникальный идентификатор.

deviceName

Отображаемое имя ресурса в OpenRemote.

ДА

assetType

Точное имя шаблона типа актива (с учетом регистра).

vendorId

Производитель устройства.

modelId

Идентификатор конкретной модели оборудования.

firmwareVersion

Версия программного обеспечения на устройстве.

Пример содержимого файла

a84043d8d1842175,Dragino LHT65 1,DraginoLHT65Asset,dragino,lht65,1.8a84043d8d1842176,Dragino LHT65 2,DraginoLHT65Asset,dragino,lht65,1.8

Типы активов LoRaWAN

При использовании агентов LoRaWAN, таких как ChirpStack или The Things Stack, OpenRemote может автоматически предоставлять активы и их каналы связи.

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

Конфигурационные ключи

Метаэлемент AGENT_LINK_CONFIG представляет собой ValueType.ObjectMap, содержащий следующие ключи:

Ключ

Тип

Описание

uplinkPort

Integer

Фильтрует входящие сообщения через LoRaWAN FPort.

valueFilterJsonPath

String

Путь JSON, используемый для извлечения значения из полезных данных (см. Форматы полезных данных).

valueConverter

Map

Определяет карту преобразователя значений для входящих значений.

UMECLOCK51ТОКЕН

Integer

FPort, используемый для отправки команд нисходящей линии связи.

writeValueConverter``Map

Сопоставляет значения атрибутов (например, TRUE/FALSE) с необходимыми полезными данными Base64.

Форматы полезной нагрузки сетевого сервера

valueFilterJsonPath указывает точное расположение данных датчика во входящем сообщении MQTT. Поскольку разные сетевые серверы LoRaWAN помещают декодированные данные устройства в разные конверты JSON, корень вашего пути должен соответствовать вашему конкретному провайдеру:

Сетевой сервер

Корень полезной нагрузки

Пример пути

ЧирпСтек

$.object

$.object.Temperature

Стек вещей

$.uplink_message.decoded_payload

$.uplink_message.decoded_payload.Temperature

Пример типа актива

В примере показано, как сопоставить показания датчика (восходящая линия связи) и командный переключатель (нисходящая линия связи).

@Entity
public class LoRaWanAsset extends Asset<LoRaWanAsset> {
    // Uplink: map temperature from port 2.
    public static final AttributeDescriptor<Double> TEMPERATURE =
        new AttributeDescriptor<>(
            "temperature",
            ValueType.NUMBER,
            new MetaItem<>(MetaItemType.READ_ONLY),
            new MetaItem<>(MetaItemType.AGENT_LINK_CONFIG, new ValueType.ObjectMap() {{
                putAll(Map.of(
                    "uplinkPort", 2,
                    "valueFilterJsonPath", "$.uplink_message.decoded_payload.Temperature"
                ));
            }})
        ).withUnits(UNITS_CELSIUS);

    // Downlink: map a switch to Base64 payloads on port 4.
    public static final AttributeDescriptor<Boolean> SWITCH =
        new AttributeDescriptor<>("switch", ValueType.BOOLEAN,
            new MetaItem<>(MetaItemType.AGENT_LINK_CONFIG, new ValueType.ObjectMap() {
{
putAll(Map.of( "downlinkPort", 4, "writeValueConverter", new ValueType.ObjectMap() {
{
putAll(Map.of( "TRUE", "DAE=", "FALSE", "DAA=" ));
}
}
));
}
}
) );
public static final AttributeDescriptor<String> DEV_EUI = new AttributeDescriptor<>("devEUI", ValueType.TEXT, new MetaItem<>(MetaItemType.READ_ONLY));
public static final AttributeDescriptor<String> VENDOR_ID = new AttributeDescriptor<>("vendorId", ValueType.TEXT, new MetaItem<>(MetaItemType.READ_ONLY));
public static final AttributeDescriptor<String> MODEL_ID = new AttributeDescriptor<>("modelId", ValueType.TEXT, new MetaItem<>(MetaItemType.READ_ONLY));
public static final AttributeDescriptor<String> FIRMWARE_VERSION = new AttributeDescriptor<>("firmwareVersion", ValueType.TEXT, new MetaItem<>(MetaItemType.READ_ONLY));
public static final AttributeDescriptor<Boolean> SUPPORTS_CLASS_C = new AttributeDescriptor<>("supportsClassC", ValueType.BOOLEAN, new MetaItem<>(MetaItemType.READ_ONLY));
public static final AssetDescriptor<LoRaWanAsset> DESCRIPTOR = new AssetDescriptor<>("molecule-co2", "f18546", LoRaWanAsset.class);
protected LoRaWanAsset() {
}
public LoRaWanAsset(String name) {
super(name);
}
}

Кодирование полезной нагрузки нисходящей линии связи

При отправке команд на устройство LoRaWAN сетевой сервер (ChirpStack или The Things Stack) требует, чтобы необработанные двоичные полезные данные были отформатированы как строка в кодировке Base64.

writeValueConverter используется для выполнения этого преобразования данных. Он сопоставляет значения атрибутов OpenRemote высокого уровня с конкретными строками Base64, необходимыми для аппаратных команд устройства.

В приведенном выше примере устройство ожидает 2-байтовую двоичную команду для переключения переключателя:

Значение атрибута

Необработанная шестнадцатеричная команда

Строка Base64

Действие

TRUE

0x0C01

DAE=

Включить

FALSE

0x0C00

DAA=

Выключить

Атрибуты метаданных устройства

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

Обязательно: DevEUI

Атрибут devEUI является обязательным. Агент использует этот уникальный 64-битный идентификатор для сопоставления физического устройства на сетевом сервере (ChirpStack или The Things Stack) с соответствующим активом в OpenRemote.

Необязательные атрибуты

Следующие атрибуты являются необязательными. Обычно они заполняются в процессе импорта CSV:

vendorId: производитель устройства (например, Dragino или Milesight).
modelId: конкретная модель оборудования или номер детали (например, LHT65).
firmwareVersion: версия программного обеспечения, установленного на устройстве.
supportsClassC: логический флаг, указывающий, поддерживает ли устройство связь класса C (всегда включен).

Справочная документация

Обзор агентской ссылки: глубокое погружение в общие атрибуты OpenRemote, такие как фильтры и предикаты.

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

Как это работает​

Обмен сообщениями (MQTT)​

Управление и обнаружение устройств (gRPC API)​

Конфигурация агента​

Формат учетных данных MQTT​

Сопоставление устройств с активами​

Сопоставление автоматического обнаружения (атрибуты TTS)​

Сопоставление импорта CSV​

Автоматизация связи агента MQTT​

Логика автоматической подготовки​

Атрибуты настроены​

Формат импорта CSV​

Структура столбца CSV​

Пример содержимого файла​

Типы активов LoRaWAN​

Конфигурационные ключи​

Форматы полезной нагрузки сетевого сервера​

Пример типа актива​

Кодирование полезной нагрузки нисходящей линии связи​

Атрибуты метаданных устройства​

Обязательно: DevEUI​

Необязательные атрибуты​

Справочная документация​

Как это работает

Обмен сообщениями (MQTT)

Управление и обнаружение устройств (gRPC API)

Конфигурация агента

Формат учетных данных MQTT

Сопоставление устройств с активами

Сопоставление автоматического обнаружения (атрибуты TTS)

Сопоставление импорта CSV

Автоматизация связи агента MQTT

Логика автоматической подготовки

Атрибуты настроены

Формат импорта CSV

Структура столбца CSV

Пример содержимого файла

Типы активов LoRaWAN

Конфигурационные ключи

Форматы полезной нагрузки сетевого сервера

Пример типа актива

Кодирование полезной нагрузки нисходящей линии связи

Атрибуты метаданных устройства

Обязательно: DevEUI

Необязательные атрибуты

Справочная документация