ChirpStack

Версия: 1.26.0

Агент ChirpStack позволяет интегрировать устройства LoRaWAN, управляемые сетевым сервером ChirpStack.

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

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

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

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

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

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

Агент использует ChirpStack gRPC API для взаимодействия с уровнем управления сетевого сервера. Это специально используется для:

Автоматическое обнаружение: агент запрашивает API, чтобы получить список устройств, зарегистрированных в ChirpStack.
Профили устройств. Для каждого обнаруженного устройства агент получает соответствующий профиль устройства. Это позволяет OpenRemote распознавать тип устройства в процессе автоматического создания ресурса.

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

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

Атрибут

Описание

Требуется

По умолчанию

MQTTHost

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

Да

MQTTPort

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

Да

clientId

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

Да

secureMode

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

ложный

resumeSession

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

ложный

subscribeQos

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

publishQos

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

host

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

Да

port

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

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

applicationId

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

Да

apiKey

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

Да

secureGRPC

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

ложный

Пример:

MQTTHost: 192.168.1.50MQTTPort: 1883clientId: or_chirpstack_agent_1secureMode: falseresumeSession: truehost: 192.168.1.50port: 8080applicationId: 7d809e33-d2ad-4ef1-aac8-2be67501c4d3apiKey: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhd... secureGRPC: false

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

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

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

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

Ключ тега

Значение тега

openremote-asset-type

Точное имя Типа ресурса OpenRemote (например, WeatherStationAsset).

Во время автоматического обнаружения агент считывает этот тег и создает соответствующий актив в OpenRemote.

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

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

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

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

Агент ChirpStack обрабатывает передачу данных датчиков (восходящие каналы) и команд (нисходящие каналы) через протокол 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

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

downlinkPort

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", "$.object.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)​

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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