¶ Руководство пользователя. IoT Agent
IoT Agent 2.0 — приложение, предназначенное для взаимодействия с системой АС «Андромеда» на уровне IoT-контроллера и обеспечивающее двунаправленную связь между локальными устройствами и внешней системой управления через MQTT-брокеры. Выполняет роль агента сбора данных и управления устройствами.
Приложение предназначено для использования в промышленных IoT-системах, где необходимо обеспечить надежную интеграцию локальных устройств с централизованной системой мониторинга и управления АС «Андромеда». IoT Agent 2.0 поддерживает сбор телеметрических данных с устройств, их обработку и передачу на верхний уровень, а также выполнение команд управления, поступающих из внешней системы.
Приложение обеспечивает возможность буферизации данных для обеспечения надежной доставки, гибкую настройку через YAML-конфигурацию, масштабирование значений с применением коэффициентов, валидацию сообщений управления, а также автоматическое переподключение при сбоях связи.
¶ Назначение
IoT Agent 2.0 решает следующие задачи:
- Сбор телеметрических данных – Автоматический сбор данных с IoT-устройств через локальный MQTT-брокер с возможностью фильтрации топиков по настраиваемым паттернам и правилам.
- Интеграция с АС «Андромеда» – Двунаправленная связь с автоматизированной системой «Андромеда» через глобальный MQTT-брокер для передачи телеметрии и получения команд управления.
- Буферизация и доставка – Обеспечение надежной доставки данных с использованием внутренней буферизации сообщений и автоматического восстановления при сбоях соединения.
- Масштабирование значений – Применение коэффициентов масштабирования к телеметрическим данным для приведения их к требуемым единицам измерения.
- Управление устройствами – Поддержка управления устройствами с обработкой команд, поступающих из АС «Андромеда».
- Инициализация и конфигурация – Автоматическая инициализация параметров контроллера при первом подключении к системе с получением конфигурации устройств и топиков.
- Мониторинг и диагностика – Ведение подробного логирования событий, обработка ошибок и отправка диагностической информации в систему мониторинга.
- Агрегация данных - Сбор и агрегация данных с множественных источников для оптимизации нагрузки на каналы связи.
¶ Ключевые функции
- Двунаправленная MQTT-связь – Приложение работает с двумя MQTT-брокерами одновременно локальным (для сбора данных с устройств) и глобальным (для связи с АС «Андромеда»). Поддерживает автоматическое переподключение при сбоях связи с настраиваемыми интервалами повторных попыток.
- Интеллектуальная буферизация данных – Встроенная система буферизации обеспечивает надежную доставку телеметрических данных даже при временных сбоях связи. Поддерживает настройку размера буфера, размера батча и времени отправки для оптимизации производительности.
- Гибкая фильтрация топиков – Мощная система фильтрации позволяет настраивать сбор данных по wildcard паттернам (например, "/devices/#") и пользовательским правилам фильтрации, включая фильтрацию по окончаниям топиков.
- Масштабирование и обработка значений – Автоматическое применение коэффициентов масштабирования к входящим данным с поддержкой как целых, так и дробных значений (например, 0.1 для деления на 10).
- Управление через АС "Андромеда" – Полная поддержка дистанционного управления устройствами. Обработка команд управления с подтверждением выполнения и обратной связью.
- Автоматическая инициализация – при первом запуске приложение автоматически запрашивает конфигурацию контроллера и параметры устройств из АС "Андромеда", создавая файлы Unit.json и Params.json для последующей работы.
- Агрегация и пакетная обработка – Встроенный агрегатор собирает данные с множественных источников и оптимизирует их передачу, снижая нагрузку на каналы связи и повышая эффективность системы.
- Мониторинг и диагностика – Комплексная система логирования с настраиваемыми уровнями детализации, ротацией логов и возможностью записи в файл. Встроенный мониторинг использования памяти и количества горутин для отладки производительности.
- Отказоустойчивость – Graceful shutdown с корректным завершением, обработка сигналов операционной системы и автоматическое восстановление соединений при сбоях.
¶ Функционал и реализация
¶ Описание параметров конфигурации YAML
¶ Логирование (agent.logger)
| Описание в YAML | Название | Описание | Пример значений | Реализация |
|---|---|---|---|---|
| write_in_logfile | Включение записи в файл | Определяет, будут ли логи записываться в файл или только в консоль; По умолчанию false | true/false | 2.0.0.0 |
| level_log | Уровень логирования | Устанавливает детальность логирования (по умолчанию 1) 1 - INFO , 2 - WARNING, 3 - DEBUG, 4 - ERROR; |
1, 2, 3, 4 | 2.0.0.0 |
| path_log | Путь к файлу логов | Абсолютный или относительный путь к файлу логов; обязателен если writein_logfile=true | Строка с путем к файлу | 2.0.0.0 |
| max_size_log | Максимальный размер файла логов | Максимальный размер файлалогов в мегабайтах до ротации; По умолчанию 2 МБ |
1-5 | 2.0.0.0 |
| max_backups_log | Максимальное количество резервных копий | Количество сохраняемых старых файлов логов; По умолчанию 30 |
1-100 | 2.0.0.0 |
| max_age_log | Максимальный возраст файла логов | Максимальный возраст файла логов в днях до удаления; По умолчанию 10 дней |
1-30 | 2.0.0.0 |
Буферизация
Система буферизации - встроенный (in memory) механизм временного хранения телеметрических данных в памяти агента, который обеспечивает надежную доставку сообщений при нестабильном соединении с глобальным MQTT-брокером АС «Андромеда».
Принцип "store-and-forward":
- При отсутствии соединения с глобальным брокером все исходящие сообщения автоматически сохраняются в кольцевой буфер в памяти.
- При восстановлении соединения накопленные данные отправляются батчами (пакетами) с настраиваемыми интервалами.
- Используется lock-free алгоритм с атомарными операциями для высокой производительности.
Кольцевая структура буфера:
- При переполнении новые сообщения перезаписывают самые старые (FIFO принцип).
- Каждое сообщение занимает фиксированные 256 байт для оптимизации памяти.
Батчевая отправка:
- При восстановлении связи данные извлекаются порциями по batch_size сообщений.
- Между отправкой батчей делается пауза time_send_batch миллисекунд.
- Это предотвращает перегрузку канала связи при восстановлении больших объемов данных.
Обеспечение надежности:
- Предотвращение потери телеметрических данных при временных сбоях связи.
- Автоматическое восстановление всех накопленных сообщений.
- Прозрачная работа для верхнего уровня приложения.
| Описание в YAML | Название | Описание / Допустимые значения | Пример значений | Реализация |
|---|---|---|---|---|
| enabled | Включение буферизации | Включает/выключает внутреннюю буферизацию сообщений для надежной доставки; По умолчанию true |
true/false | 2.0.0.0 |
| total_topic | Размер буфера | Максимальное количество сообщений в кольцевом буфере По умолчанию 5000 |
1000-5000000 | 2.0.0.0 |
| batch_size | Размер батча | Количество сообщений в одном батче при отправке из буфера; По умолчанию 100 |
100-2000 | 2.0.0.0 |
| time_send_batch | Время отправки батча | Таймаут отправки батча в миллисекундах; По умолчанию 500 мс |
10-5000 | 2.0.0.0 |
¶ Основные настройки MQTT (agent.mqtt)
| Описание в YAML | Название | Описание / Допустимые значения | Пример значений | Реализация |
|---|---|---|---|---|
| controllerid | Идентификатор контроллера | Уникальный идентификатор контроллера в системе АС "Андромеда"; обязательный параметр |
Строка, соответствующая правилам валидации ID | 2.0.0.0 |
| global_pub_time | Интервал публикации | Интервал отправки данных в глобальный брокер в секундах; 0 для моментальной отправки; По умолчанию 600 сек |
≥0 | 2.0.0.0 |
| publish_topic_pattern | Шаблон исходящих топиков | Шаблон для формирования топиков отправки сообщений в АС "Андромеда"; По умолчанию "/andromeda/Controller/{controllerId}/In/" |
Строка с {controllerId} плейсхолдером | 2.0.0.0 |
| subscribe_topic_pattern | Шаблон входящих топиков | Шаблон для подписки на топики от АС "Андромеда"; По умолчанию "/andromeda/Controller/{controllerId}/Out/#" |
Строка с {controllerId} плейсхолдером и # в конце | 2.0.0.0 |
| aperture_percent | Процент апертуры | Процентная дельта для фильтрации незначительных изменений значений; 0 для отключения; По умолчанию 2 |
≥0 | 2.0.0.0 |
| apertrure_treshold | Порог апертуры | Абсолютная мертвая зона для фильтрации малых изменений; По умолчанию 0.1 |
≥0 | 2.0.0.0 |
¶ Конфигурация глобального брокера (agent.global_broker)
| Описание в YAML | Название | Описание / Допустимые значения | Пример значений | Реализация |
|---|---|---|---|---|
| host | Адрес брокера | URL глобального MQTT-брокера АС Андромеда; обязательный параметр | tcp://host:port или ssl://host:port для local "unix://var/run/mosquitto/mosquitto.sock" |
2.0.0.0 |
| client_id | Идентификатор клиента | Уникальный идентификатор MQTTклиента; должен отличаться от local_broker.client_id если адреса брокеров совпадают | Строка | 2.0.0.0 |
| keepalive | Интервал Keep-Alive | Интервал отправки ping-сообщений в секундах для поддержания соединения; По умолчанию 60 сек |
5-240 | 2.0.0.0 |
| clean_session | Очистка сессии | Очищать ли сессию при подключении; false для сохранения подписок и сообщений; По умолчанию false |
true/false | 2.0.0.0 |
| autoreconnect | Автоматическое переподключение | Автоматически переподключаться при потере соединения; По умолчанию true |
true/false | 2.0.0.0 |
| *retry_interval | Интервал повторных попыток | Интервал между попытками переподключения в секундах; По умолчанию 5 сек ((см. тут)) |
≥1 | 2.0.0.0 |
| *max_retries | Максимальное количество попыток | Максимальное количество попыток переподключения; По умолчанию 100 (см. тут) |
≥0 | 2.0.0.0 |
| pubQoS | QoS (Качество обслуживания) Используется только для публикации в Глобальный брокер(global_broker) | 0: максимум одна доставка - отправил и забыл, без подтверждения. 1: минимум одна доставка - гарантированная доставка с возможными дубликатами. 2: точно одна доставка - гарантированная однократная доставка (наибольшие накладные расходы по сети). По умолчанию - 0. |
0 - 1 - 2 | 2.1.0.0 |
| retained | Retained (Сохранение) Используется только для публикации в Глобальный брокер(global_broker) | true: Брокер сохраняет последнее сообщение по топику и доставляет его новым подписчика м false: Сообщение доставляется только текущим подключенным подписчикам. По умолчанию - false |
true/false | 2.1.0.0 |
| login | Логин для аутентификации | Имя пользователя для аутентификации на брокере; обязательно при использовании пароля | Строка | 2.0.0.0 |
| password | Пароль для аутентификации | Пароль для аутентификации на брокере; обязательно при использовании логина | Строка | 2.0.0.0 |
¶ Конфигурация локального брокера (agent.local_broker)
| Описание в YAML |
Название | Описание | Пример значений | Реализация |
|---|---|---|---|---|
| host | Адрес брокера | URL глобального MQTT-брокера АС Андромеда; обязательный параметр | tcp://host:port или ssl://host:port для local "unix://var/run/mosquitto/mosquitto.sock" |
2.0.0.0 |
| client_id | Идентификатор клиента | Уникальный идентификатор MQTT клиента; Должен отличаться от global_broker.client_id если адреса брокеров совпадают |
Строка | 2.0.0.0 |
| keepalive | Интервал KeepAlive | Интервал отправки ping сообщений в секундах для поддержания соединения; По умолчанию 120 сек |
5-240 | 2.0.0.0 |
| clean_session | Очистка сессии | Очищать ли сессию при подключении; false для сохранения подписок и сообщений; По умолчанию true |
true/false | 2.0.0.0 |
| autoreconnect | Автоматическое переподключение | Автоматически переподключаться при потере соединения; По умолчанию true |
true/false | 2.0.0.0 |
| *retry_interval | Интервал повторных попыток | Интервал между попытками переподключения в секундах; По умолчанию 5 сек (см. тут) |
≥1 | 2.0.0.0 |
| *max_retries | Максимальное количество попыток | Максимальное количество попыток переподключения; По умолчанию 100 (см. тут) |
≥0 | 2.0.0.0 |
| login | Логин для аутентификации | Имя пользователя для аутентификации на брокере; обязательно при использовании пароля | Строка | 2.1.0.0 |
| password | Пароль для аутентификации | Пароль для аутентификации на брокере; обязательно при использовании логина | Строка | 2.1.0.0 |
¶ Описание процесса переподключения к брокеру MQTT (local / global)
При первой инициализации Агента механизм переподключения к брокеру реализован алгоритмом через параметры retry_interval и max_retries. По достижению количества попыток (если соединение не было установлено), Агент сообщает в лог ошибку и завершает работу (происходит рестарт на уровне systemd).
Если сбой соединения с брокером произошел после инициализации и успешного подключения к брокеру, то механизм ретраев выполняется на уровне библиотеки MQTT - параметр autoreconnect – true.
¶ Конфигурация TLS (agent.*_broker.tls)
| Описание в YAML |
Название | Описание | Пример значений | Реализация |
|---|---|---|---|---|
| ca_cert | Сертификат CA | Путь к файлу корневого сертификата удостоверяющего центра; обязателен если insecure_skip_verify=false Путь по умолчанию /mnt/data/etc/andromeda_embedded/agent/ca.crt |
Путь к файлу .crt | 2.0.0.0 |
| client_cert | Клиентский сертификат | Путь к файлу клиентского сертификата для взаимной аутентификации; обязателен вместе с client_key Путь по умолчанию /mnt/data/etc/andromeda_embedded/agent/client.crt |
Путь к файлу .crt | 2.0.0.0 |
| client_key | Клиентский ключ | Путь к файлу приватного ключа клиента; обязателен вместе с client_cert Путь по умолчанию /mnt/data/etc/andromeda_embedded/agent/client.key |
Путь к файлу .key | 2.0.0.0 |
| insecure_skip_verify | Пропуск проверки сертификата | Пропускать проверку сертификата сервера; true для тестовых сред; По умолчанию false для global_broker, true для local_broker |
true/false | 2.0.0.0 |
¶ Конфигурация Wildcard (agent.*_broker.wildcard)
| Описание в YAML |
Название | Описание | Пример значений | Реализация |
|---|---|---|---|---|
| enabled | Включение wildcard-подписок | Включает подписку на топики по wildcardпаттернам; По умолчанию true |
true/false | 2.0.0.0 |
| patterns | Шаблоны wildcard | Список шаблонов для подписки на топики; поддерживает # (многоуровневый) и + (одноуровневый); По умолчанию ["#"] для local_broker |
Массив строк с wildcard паттернами | 2.0.0.0 |
¶ Конфигурация фильтров топиков (agent.local_broker.topic_filters)
| Описание в YAML |
Название | Описание | Пример значений | Реализация |
|---|---|---|---|---|
| enabled | Включение фильтрации | Включает дополнительную фильтрацию топиков по пользовательским правилам; По умолчанию true |
true/false | 2.0.0.0 |
| starts_with | Фильтр начала топика | Список префиксов для фильтрации топиков по началу; обрабатываются только топики, начинающиеся с указанных строк | Массив строк | 2.0.0.0 |
| end_with | Фильтр окончания топика | Список суффиксов для фильтрации топиков по окончанию; обрабатываются только топики, заканчивающиеся на указанные строки | Массив строк | 2.0.0.0 |
| contains | Фильтр содержимого топика | Список подстрок для фильтрации топиков по содержимому; обрабатываются только топики, содержащие указанные подстроки | Массив строк | 2.0.0.0 |
По дефолту для локального брокера выставлен wildcard "/devices/+/controls/+" Если wildcard изменён или модифицирован ("/devices/+/controls/+") то обязательно указывать фильтр для топиков "управления" для локального брокера
ends_with:
- "/on"
¶ Переменные окружения для настройки секретов
Для безопасного хранения секретов используется ввод через переменные окружения файл Приоритет настроек: Переменные окружения -> параметры из файла конфигурации.
Файл с настройками /mnt/data/etc/andromeda_embedded/configs/agent/.agent.env с правами 600 root:root
GLOBAL_BROKER_LOGIN - Имя пользователя для аутентификации на глобальном брокере (обязательно при использовании пароля).
GLOBAL_BROKER_PASSWORD - Пароль для аутентификации на глобальном брокере (обязательно при использовании логина).
LOCAL_BROKER_LOGIN - Имя пользователя для аутентификации на локальном брокере (обязательно при использовании пароля).
LOCAL_BROKER_PASSWORD - Пароль для аутентификации на локальном брокере (обязательно при использовании логина).
Содержимое файла по дефолту .agent.env :
GLOBAL_BROKER_LOGIN=""
GLOBAL_BROKER_PASSWORD=""
LOCAL_BROKER_LOGIN=""
LOCAL_BROKER_PASSWORD=""
¶ Инструкция по запуску
¶ Флаги запуска
| Флаг | Короткая форма | Тип | Значение по умолчанию | Описание |
|---|---|---|---|---|
| --cfgpath | -c | string | configs/agent/agent_config.yaml | Путь до файла конфигурации |
| --version | bool | false | Вывести версию Agent | |
| --level_log | -l | int | 1 | Уровень логирования Agent (1-4) |
| -- write_in_logfile | -w | bool | false | Запись логов в файл (true / false) |
| --path_log | -p | string | ./log/agent.log | Путь до файла логов |
¶ --cfgpath / -c (Путь к конфигурации)
Назначение: указывает путь к YAML-файлу с конфигурацией агента
Синтаксис:
./agent --cfgpath /path/to/config.yaml
./agent -c /path/to/config.yaml
Особенности:
- Поддерживает как абсолютные, так и относительные пути;
- Файл должен быть в формате YAML;
- При ошибке загрузки или валидации конфигурации приложение завершается с ошибкой.
¶ --version (Версия приложения)
Назначен: выводит информацию о версии и завершает работу.
Синтаксис:
./agent –version
Поведение:
- Выводит в формате: Agent : 2.0.0.0;
- Немедленно завершает работу с кодом 0;
- Не загружает конфигурацию и не инициализирует другие компоненты.
¶ --level_log / -l (Уровень логирования)
Назначение: устанавливает уровень детализации логирования.
Допустимые значения:
- 1 - INFO (информационные сообщения);
- 2 - WARNING (предупреждения);
- 3 - DEBUG (максимальная детализация);
- 4 - ERROR (только ошибки).
Поведение:
- Переопределяет значение из конфигурационного файла;
- Если флаг не указан, используется значение из YAML или значение по умолчанию (1);
- Влияет на количество выводимых в лог сообщений.
¶ --write_in_logfile / -w (Запись в файл)
Назначение: включает/выключает запись логов в файл.
Синтаксис:
./agent --write_in_logfile
./agent -w
./agent --write_in_logfile=false
Поведение:
- При включении логи записываются как в консоль, так и в файл;
- При выключении логи выводятся только в консоль;
- Переопределяет значение из конфигурационного файла;
- Если путь к файлу не указан, используется значение по умолчанию.
¶ --path_log / -p (Путь к файлу логов)
Назначение: указывает путь к файлу для записи логов.
Синтаксис:
./agent --path_log /var/log/agent.log
./agent -p ./logs/debug.log
Особенности:
- Активен только при включенном флаге --write_in_logfile;
- Поддерживает как абсолютные, так и относительные пути;
- Автоматически создает директории, если они не существуют;
- Поддерживает ротацию логов согласно настройкам в конфигурации.
¶ Приоритет настроек
- Командные флаги (высший приоритет);
- Конфигурационный файл YAML;
- Значения по умолчанию (низший приоритет).
Если параметр указан и в флаге, и в конфигурации, используется значение из флага.
¶ Валидация флагов
- Все флаги проходят валидацию при запуске;
- При некорректных значениях приложение завершается с ошибкой;
- Проверяется существование файлов конфигурации и доступность путей для логов;
- Уровень логирования должен быть в диапазоне 1-4.
¶ Установка deb пакетов
Установка deb пакета через пакетный менеджер apt: apt install ./agent_x.x.x.x_linux_x
Файл службы: /etc/systemd/system/
[Unit]
Description=Andromeda IoT Agent embedded service
Wants=mosquitto.service
After=network.target
[Service]
EnvironmentFile=/mnt/data/etc/andromeda_embedded/configs/agent/.agent.env
WorkingDirectory=/mnt/data/etc/andromeda_embedded
ExecStart=/mnt/data/etc/andromeda_embedded/agent --cfgpath configs/agent/agent.yaml
Restart=always
RestartSec=5s
User=root
[Install]
WantedBy=multi-user.target
Если установка в ручном режиме, то обязательно после создания файла службы
Выполнить:
sudo systemctl daemon-reload sudo systemctl enable agent.service
sudo systemctl start agent.service
Запуск в ручном режиме
./agent -c configs/agent/agent.yaml -loglvl x
Перед запуском в ручном режиме необходимо остановить demon, если он был запущен:
systemctl stop agent
¶ Пример запуска
¶ Пример настроек YAML
Пример настройки файла конфигурации инициализации агента - agent.yaml
agent:
logger:
level_log: 1
path_log: logs/agent/agent_iot.log
max_size_log: 1
max_backups_log: 30
max_age_log: 10
buffer:
enabled: true
total_topic: 5000
batch_size: 1000
time_send_batch: 500
mqtt:
controllerid: TESTID # Controller ID заменить на свой
global_pub_time: 600
publish_topic_pattern: /andromeda/Controller/{controllerId}/In/
subscribe_topic_pattern: /andromeda/Controller/{controllerId}/Out/#
aperture_percent: 2
aperture_threshold: 0.1
global_broker:
host: ssl://127.0.0.1:1884 # Адрес брокера заменить на свой
client_id: agent_iot # Сlient_id = Controller ID заменить на свой
keepalive: 120
clean_session: false
autoreconnect: true
retry_interval: 5
max_retries: 200
login: MQTT_GLOBAL_LOGIN
password: MQTT_GLOBAL_PASSWORD
tls:
ca_cert: /etc/mqtt/ca.crt
client_cert: /etc/mqtt/client.crt
client_key: /etc/mqtt/client.key
insecure_skip_verify: false
local_broker:
host: tcp://127.0.0.1:1883
client_id: agent_iot
keepalive: 120
clean_session: true
autoreconnect: true
retry_interval: 5
max_retries: 200
login: MQTT_GLOBAL_LOGIN
password: MQTT_GLOBAL_PASSWORD
tls:
ca_cert: /etc/mqtt/ca.crt
client_cert: /etc/mqtt/client.crt
client_key: /etc/mqtt/client.key
insecure_skip_verify: false
wildcard:
enabled: true
patterns:
- devices/+/status
- sensors/#
- alerts/+/+/critical
topic_filters:
enabled: true
starts_with:
- /device/system/
- /meta/
ends_with:
- /on
- /meta
contains:
- system_networks
- /metrics/
- /set/
¶ Приложение. PDF версия документа
PDF-версия данного руководства пользователя доступна для скачивания и печати. Документ содержит полную информацию по установке, настройке и эксплуатации IoT Agent 2.0, включая все разделы, представленные в данной HTML-версии.
Файл: РП.IoT Агент.pdf