Документация

Полное руководство по настройке и использованию MQTT Dashboard Client

Содержание

  1. Подключение брокера
  2. Адреса подключения брокера
  3. Виджеты
  4. Настройка параметров виджета
  5. Обработка данных (JsonPath, Regex)
  6. Префикс и постфикс
  1. Группы виджетов
  2. Скрипты и автоматизация
  3. Сцены
  4. SSL/TLS сертификаты
  5. Резервное копирование
  6. Обмен конфигурациями по MQTT
  7. Настройки интерфейса

1. Подключение брокера

MQTT-брокер — сервер, через который устройства обмениваются сообщениями. Чтобы начать работу, добавьте хотя бы один брокер.

Как добавить брокер
  1. Откройте вкладку Брокеры (нижнее меню)
  2. Нажмите кнопку + в правом верхнем углу
  3. Заполните обязательные поля:
    • Название — произвольное название (например, «Домашний сервер»)
    • URL — IP-адрес или домен брокера
    • Порт — порт (1883 для TCP, 8883 для SSL)
    • Протокол — выберите tcp://, ssl://, ws:// или wss://
  4. При необходимости включите Авторизация и укажите логин/пароль
  5. Настройте дополнительные параметры (ID клиента, Очистка сессии, Интервал Keep Alive, Автоподключение)
  6. Нажмите Готово
Совет: Включите Автоподключение, чтобы брокер подключался автоматически при запуске приложения.

2. Адреса подключения брокера

Брокер может иметь несколько адресов подключения. Это удобно, когда брокер доступен по разным адресам — например, локальный IP дома и облачный домен через интернет. Если текущий адрес недоступен, приложение автоматически переключится на следующий.

Добавление адреса

Основной адрес задаётся при создании брокера. Чтобы добавить ещё один — в редакторе брокера нажмите Добавить адрес подключения и укажите:

  1. Хост — IP-адрес или домен
  2. Протокол — tcp://, ssl://, ws:// или wss://
  3. Порт — порт подключения
  4. SSL — для ssl:///wss://: самоподписанный сертификат или файл кастомного CA-сертификата

Дополнительные настройки:

  • Приоритет — Высокий / Средний / Низкий. Адреса с высоким приоритетом пробуются первыми.
  • Сеть — для каких сетей подходит адрес: Любая / Только Wi-Fi / Только моб. сеть.
  • Включён — отключённые адреса не используются. Переключить или удалить адрес можно из меню на экране редактирования.
Совет: Первый адрес — бесплатно, дополнительные адреса — подписка Premium.
Как это работает
  • При подключении перебираются включённые адреса по приоритету (Высокий → Средний → Низкий)
  • Если адрес недоступен — автоматический переход к следующему
  • После перебора всех адресов пауза между попытками растёт (2 с → 4 с → … → 60 с)
  • При смене сети (Wi-Fi ↔ мобильный интернет) перебор начинается с приоритетного адреса
  • В карточке брокера виден активный адрес и ошибки по каждому адресу
  • Должен быть включён хотя бы один адрес
  • Адреса подключения входят в резервную копию данных

3. Виджеты

Виджеты — основные элементы интерфейса для отображения данных с брокера и отправки команд.

Создание виджета
  1. На главном экране нажмите кнопку + в правом нижнем углу и выберите Создать виджет
  2. Заполните Название виджета и выберите Группу, в которую он будет добавлен
  3. Выберите количество параметров (от 1 до 4) с помощью горизонтального пейджера — каждый параметр может иметь свой тип, топик и настройки
  4. Нажмите на параметр в списке, чтобы настроить его тип, топики и обработку данных — подробнее в разделе «Настройка параметров виджета»
  5. Нажмите Готово для завершения создания
Один виджет может содержать до 4 параметров разного типа (например, текст + кнопка + переключатель).
Управление виджетами
  • Перетаскивание: зажмите виджет и перетащите на новое место. Свободные ячейки подсвечиваются.
  • Контекстное меню: долгое нажатие на виджет открывает меню (Редактировать, Удалить)
  • Редактирование: нажмите на виджет → откроется окно с детальной информацией и настройками
  • Смена группы: откройте виджет на редактирование и выберите другую Группу виджетов
  • Блокировка: долгое нажатие можно отключить целиком — см. Блокировка главного экрана

4. Настройка параметров виджета

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

Экран параметра
  • Название и Тип данных — первая карточка экрана. Тип выбирается в шторке: у каждого типа живое превью — ровно то, что появится на плитке, — и короткое описание, что он умеет.
  • Иконка — иконка и цвет параметра, выбираются в диалоге «Иконка и цвет». У типов Логический и Кнопка вид задаётся отдельно для включённого и выключенного состояния, у Переключателя и Выпадающего списка — для каждого состояния в списке состояний.
  • Топики, обработка данных и остальные настройки зависят от выбранного типа — см. описания ниже.
Тип можно поменять и после создания: заданные топики, состояния и обработка данных переносятся настолько, насколько их поддерживает новый тип.

Виджет Текст отображает произвольные текстовые данные из MQTT-топика: статусы, сообщения, показания датчиков.

Настройка:

  1. Топик подписки — укажите топик, из которого приходят данные
  2. JsonPath / Regex — если данные в JSON, настройте извлечение нужного поля
  3. Префикс / постфикс — добавьте текст до и после значения
Пример: Датчик публикует {"status": "Дверь открыта"}. JsonPath: $.status → отобразится «Дверь открыта».

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

Основные настройки:

  1. Топик подписки — получение состояния устройства
  2. Топик отправки — отправка команд включения/выключения
  3. Значения — укажите, какое сообщение считается «Включено» (например 1) и «Выключено» (например 0)
  4. JsonPath / Regex — для извлечения состояния из JSON

Режим подтверждения:

Без подтверждения: Приложение отправляет команду и сразу переключает виджет. Если входящее сообщение совпадает с «Включено» — виджет включён, иначе выключен.
Пример: «Включено» = 1. При получении 1 → включено, при 0 или другом значении → выключено.
С подтверждением: Используются разные топики для отправки команды и получения подтверждения. Приложение ждёт ответа от устройства.
Настройка: Топик отправки home/light/set, топик подписки home/light/status.
Цикл: Нажатие → команда в .../set → устройство подтверждает в .../status → виджет обновляется.
Диагностика: Если переключатель сразу после включения переходит в выключенное состояние — проверьте входящие сообщения в Терминале. Возможно, по топику публикуются не только ожидаемые значения. Также убедитесь, что топик отправки и подписки не совпадают.

Виджет Переключатель отображает и задаёт состояние устройства. Состояний может быть от 2 до 4 — например, «Выкл / Авто / Турбо» для вентиляции или «Стоп / Открыть / Закрыть» для ворот.

Основные настройки:

  1. Топик подписки — получение состояния устройства
  2. Топик отправки — отправка команд
  3. JsonPath / Regex — извлечение состояния из payload

Список состояний (блок «Парсинг данных»). Для каждого состояния задаются:

  • Подпись — текст, который видит пользователь на виджете
  • MQTT-значение — что отправляется в топик и что распознаётся во входящем сообщении
  • Иконка и цвет — индивидуально для каждого состояния

Кнопка Добавить состояние становится неактивной на четвёртом состоянии; удалить состояние можно, пока их больше двух.

На плитке состояния показываются сегментированным переключателем. Если состояния не помещаются в одну строку — переносятся в две, а на самых маленьких плитках остаётся индикатор активного состояния, и выбор открывается меню.

Ждать подтверждение от устройства — отдельный тумблер под списком состояний. Когда включён, приложение публикует команду и показывает индикатор загрузки, пока устройство не подтвердит новое состояние в топике подписки. Отключите, если брокер отвечает нестабильно — тогда виджет переключится сразу.

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

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

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

Настройка:

  1. Топик подписки — получение текущего состояния
  2. Топик отправки — отправка выбранного значения
  3. JsonPath / Regex — извлечение состояния из payload
  4. Список состояний — подпись, MQTT-значение, иконка и цвет для каждого варианта; минимум два, максимума нет
  5. Ждать подтверждение от устройства — работает так же, как у Переключателя
Пример: кондиционер публикует в home/ac/mode значения AUTO, COOL, HEAT, DRY, FAN. Создайте пять состояний с этими MQTT-значениями и понятными подписями — виджет будет и показывать текущий режим, и переключать его.

Если во входящем сообщении приходит значение, которого нет в списке состояний, виджет покажет «Нет данных».

Виджет Кнопка отправляет заданное сообщение в указанный топик при каждом нажатии.

Настройка:

  1. Топик отправки — топик, в который отправляется сообщение
  2. Значение — фиксированное сообщение (например RESET или {"command": "reboot"})
  3. QoS — уровень качества обслуживания (0, 1, 2)
  4. Префикс / постфикс — для формирования сложных сообщений
Пример: Кнопка «Перезагрузить роутер». Топик: home/router/command, значение: reboot.

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

Настройка:

  1. Топик подписки — получение числовых данных
  2. Знаки после запятой — количество отображаемых десятичных знаков
  3. JsonPath / Regex — извлечение числа из payload
  4. Префикс / постфикс — для единиц измерения (например °C)
Пример: Датчик публикует {"temperature": 25.5}. JsonPath: $.temperature, знаков после запятой: 1, постфикс: °C → «25.5°C».

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

Настройка:

  1. Топик отправки — отправка значения ползунка
  2. Топик подписки — получение текущего значения (опционально, для синхронизации)
  3. Мин / Макс — диапазон значений (например 0–100). Мин и Макс можно задать отрицательными, например −50–50 с нулём посередине
  4. Знаки после запятой — точность значения: 0 даёт целые числа, 1 и больше — дробный шаг
  5. Префикс / постфикс — для форматирования исходящих данных
Заливка дуги теперь выполняется от 0, а не от Мин — при диапазоне с отрицательными и положительными значениями заливка растёт от центра к текущему значению в обе стороны.
Пример: Диммер с диапазоном 0–255. Топик отправки: home/light/dimmer/set, топик подписки: home/light/dimmer/status.

Виджет Цвет позволяет выбирать и отправлять цвета для RGB-лент и ламп.

Настройка:

  1. Топик отправки — отправка выбранного цвета
  2. Топик подписки — получение текущего цвета устройства
  3. Формат — HEX (#FF5A30), RGB ([255, 90, 48]) или HSV ([12, 0.81, 1.00])
  4. JsonPath — извлечение цвета из JSON

Виджет URL изображения загружает и отображает изображение по URL из MQTT-сообщения.

Настройка:

  1. Топик подписки — получение URL изображения
  2. JsonPath — извлечение URL из JSON (если сообщение в формате JSON)
Пример: Камера публикует {"image": "http://cam.local/snapshot.jpg"}. JsonPath: $.image.

Виджет Местоположение отображает координаты на карте. Функция находится в разработке и пока недоступна для выбора в списке типов параметра — описание ниже приведено для справки.

  1. Топик подписки — получение координат
  2. JsonPath — извлечение координат из JSON

5. Обработка данных (JsonPath, Regex)

Приложение поддерживает несколько способов извлечения данных из MQTT-payload.

JsonPath БЕСПЛАТНО

Извлекает значение из JSON-сообщения.

Пример:
Payload: {"temperature": 25.5, "humidity": 60}
JsonPath: $.temperature → 25.5

Поддерживаются dot-нотация ($.object.array[0].value) и bracket-нотация ($[\'store\'][\'book\'][0][\'title\']).

Regex ПРЕМИУМ

Извлекает данные с помощью регулярных выражений. Работает как второй этап после JsonPath.

Трёхшаговый pipeline:

  1. JsonPath → извлечение поля из JSON
  2. Regex (основной) → извлечение данных из строки
  3. Regex (вторичный) → постобработка результата
Пример:
Payload: {"data": "temp: 25.5C hum: 60%"}
1. JsonPath $.data → "temp: 25.5C hum: 60%"
2. Regex temp:\s*([\d.]+)C → 25.5

Regex времени — отдельное выражение для извлечения временной метки из payload.

JsonPath для времени БЕСПЛАТНО

Извлекает временную метку из отдельного JSON-поля.

  • Укажите JsonPath до поля с временем
  • Доступна коррекция часового пояса — слайдер от -12 до +12
  • Поддерживаются различные форматы даты/времени

6. Префикс и постфикс

Позволяют добавлять текст до и после значения для форматирования.

Исходящие данные БЕСПЛАТНО

Форматирование данных перед отправкой на брокер.

Пример: ползунок = 1
Префикс: {"command": "
Постфикс: "}
Результат: {"command": "1"}

Полезно для формирования JSON-команд.

Входящие данные ПРЕМИУМ

Форматирование полученных данных перед отображением на виджете.

Пример: датчик = 42
Постфикс: °C
Результат: 42°C

Удобно для добавления единиц измерения.

7. Группы виджетов

Группы помогают организовать виджеты по смыслу — например, «Датчики», «Управление светом», «Температура».

  1. Откройте вкладку Группы (нижнее меню) и нажмите + в правом верхнем углу — или на главном экране нажмите + и выберите Создать группу
  2. Введите Название группы и нажмите Готово
  3. Чтобы перенести виджет в другую группу, откройте виджет на редактирование и выберите нужную Группу виджетов

На главном экране группы отображаются заголовками-разделами: нажатие на заголовок сворачивает и разворачивает группу. На вкладке Группы список можно отсортировать вручную, по названию или по количеству виджетов.

8. Скрипты и автоматизация ПРЕМИУМ

Скрипты позволяют автоматизировать действия: отправлять сообщения по условию, выполнять сценарии при запуске и многое другое.

Создание скрипта
  1. Откройте вкладку Сценарии (нижнее меню)
  2. Нажмите + в правом верхнем углу и выберите Создать сценарий
  3. Настройте триггеры срабатывания:
    • Виджет — срабатывает по значению выбранного параметра виджета: равно, не равно, больше, меньше. Топик берётся из настроек самого параметра
    • Приложение запускается — выполняется при запуске приложения или при его появлении на экране
    • Логический блок — объединяет несколько условий
  4. В Логическом блоке доступны операторы И, ИЛИ, НЕ ВЫПОЛНЕНО НИ ОДНО и НЕ ВСЕ; блоки можно вкладывать друг в друга
  5. Настройте действия:
    • Виджет — Отправить сообщение через параметр виджета или Мигать виджетом выбранным цветом
    • Push-уведомление — показать уведомление с вашим текстом
    • Воспроизводить звук ПРЕМИУМ — системный или собственный звуковой файл
  6. Включите скрипт — переключатель в карточке скрипта. Выключенные скрипты не выполняются, но доступны для редактирования
Пример: «Если температура > 30°C И влажность < 20% → отправить команду на включение увлажнителя и показать уведомление»

Выключенный скрипт можно открыть и отредактировать — изменения сохранятся и вступят в силу после включения.

9. Сцены

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

Создание сцены
  1. Откройте вкладку Сценарии (нижнее меню)
  2. Нажмите + в правом верхнем углу и выберите Создать сцену
  3. Укажите Название сцены и Группу виджетов, к которой она относится
  4. Для состояния «Включено» выберите иконку и цвет, затем в блоке Сообщения для «Включено» добавьте действия
  5. То же самое настройте для состояния «Выключено»
  6. Нажмите Готово
Список сообщений для состояния «Включено» обязателен — без него сцену сохранить нельзя. Список для «Выключено» можно оставить пустым.
Добавление действия

Сцена работает не с «сырыми» топиками, а с уже настроенными виджетами: топик, QoS, префикс и постфикс берутся из параметра виджета. Поэтому перед созданием сцены нужен хотя бы один виджет.

  1. Нажмите + в нужном списке сообщений
  2. Выберите Группу виджетов
  3. Выберите Виджет
  4. Выберите Параметр виджета
  5. Укажите Отправить значение — для переключателей, выпадающих списков, кнопок и регуляторов подставляются подсказки из настроек параметра
  6. Нажмите Готово
Запуск сцены

Готовая сцена появляется на вкладке Сценарии в виде переключателя. Включение отправляет все сообщения из списка «Включено», выключение — из списка «Выключено». Иконка и цвет меняются в зависимости от состояния.

Пример: Сцена «Уход из дома»: в списке «Выключено» — команды на отключение света, закрытие жалюзи и выключение кондиционера; в списке «Включено» — обратные команды на возвращение домой.

10. SSL/TLS сертификаты ПРЕМИУМ

Подключайтесь к брокерам с шифрованием и собственными сертификатами.

Самоподписанный сертификат
  1. При создании брокера выберите протокол ssl:// или wss://
  2. Включите Самоподписанный сертификат
  3. Приложение будет доверять любому сертификату этого брокера

Подходит для локальных серверов (Raspberry Pi, домашний сервер).

Кастомный CA-сертификат
  1. Выберите протокол ssl:// или wss://
  2. Опция Self-Signed должна быть выключена
  3. Нажмите Выберите файл сертификата
  4. Выберите файл .pem через файловый менеджер

Для корпоративных и облачных MQTT-брокеров.

11. Резервное копирование

Сохраняйте и восстанавливайте полную конфигурацию приложения — все настройки, виджеты, брокеры, скрипты и сцены.

Создать резервную копию
  1. Настройки → Резервное копирование конфигурации
  2. При желании включите сохранение логов данных (история значений датчиков)
  3. Нажмите Создать и выберите место сохранения
Что сохраняется

Виджеты

  • Тип, иконка, цвет, стиль оформления
  • Список состояний переключателей и выпадающих списков (подпись, MQTT-значение, иконка, цвет)
  • Надпись и отображаемые данные
  • Позиция на главном экране (отдельно для портретной и ландшафтной ориентации)
  • Топики подписки, JsonPath, Regex, префикс/суффикс
  • Настройки отправки данных (топик, QoS, формат)

Брокеры

  • Адрес и порт подключения
  • Логин и пароль
  • Настройки SSL/TLS и сертификаты
  • Дополнительные адреса подключения с приоритетом и требованием к сети

Группы виджетов

  • Название, порядок групп и состояние «свёрнута/развёрнута»

Скрипты и автоматизация

  • Все скрипты с названиями и состоянием (вкл/выкл)
  • Триггеры — по значению параметра виджета и при запуске приложения
  • Логические блоки (И / ИЛИ / НЕ ВЫПОЛНЕНО НИ ОДНО / НЕ ВСЕ)
  • Действия — отправка сообщения, push-уведомление, звук, мигание виджетом

Сцены

  • Сцены с иконками и цветами для состояний «Включено» и «Выключено»
  • Списки сообщений обоих состояний (параметр виджета + отправляемое значение)

Настройки приложения

  • Все общие настройки, избранные цвета, порядок виджетов
  • Отложенные (pending) сообщения
  • История данных датчиков (опционально)
Восстановить
  1. Настройки → Восстановление конфигурации
  2. Выберите файл резервной копии
  3. После восстановления приложение перезапустится. ID клиента изменятся, чтобы избежать конфликтов подключения
Восстановление заменяет все текущие данные приложения. Рекомендуется перед восстановлением создать свежую резервную копию.

12. Обмен конфигурациями по MQTT ПРЕМИУМ

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

Экспорт (отправка)
  1. Настройки → Обмен конфигурациями по MQTT → Экспорт конфигурации
  2. При желании укажите Название конфигурации
  3. Выберите, что включить: Сцены, Скрипты, Учётные данные брокеров (последнее — только с паролем шифрования)
  4. При желании задайте Пароль шифрования и Срок хранения конфигураций (1, 3, 7, 14 или 30 дней; по умолчанию 7)
  5. Выберите брокера и нажмите Опубликовать

Конфигурация публикуется в топик {префикс}/{id} и хранится на брокере. Без пароля данные только сжимаются (не шифруются), пароли брокеров не включаются.

Отзыв: у конфигурации, которую опубликовали вы сами, кнопка Скрыть становится Отозвать — она стирает конфигурацию на брокере, и другие устройства её больше не увидят.
Приём (импорт)
  1. Настройки → Обмен конфигурациями по MQTT
  2. Включите Получать конфигурации — приложение подпишется на {префикс}/+ (по умолчанию config/share/+)
  3. Полученные конфигурации появляются карточками: Подробнее (что изменится), Применить, Отклонить

Режимы импорта:

  • Объединить — обновить существующие элементы и добавить новые
  • Заменить всё — удалить текущие виджеты, группы, сцены и скрипты и импортировать новые. Требует повторного подтверждения с чекбоксом.

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

Префикс топика по умолчанию — config/share. Его можно изменить — например, чтобы разделить конфигурации между группами устройств.

13. Настройки интерфейса

Настройки → Интерфейс: оформление приложения и всё, что относится к главному экрану.

Тема и язык
  • Тема — Системная, Светлая или Тёмная. По умолчанию приложение следует за темой устройства.
  • Язык — язык интерфейса приложения. Значение Системный берёт язык устройства.
Блокировка главного экрана НОВОЕ

Настройки → Интерфейс → Главный экран → Блокировка главного экрана. По умолчанию выключена.

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

  • Короткие нажатия работают как обычно: переключатели, кнопки, регуляторы и выпадающие списки продолжают управлять устройствами
  • Блокировка действует и внутри группы виджетов
  • Редактирование, клонирование и удаление остаются доступны обычным путём: нажатие на виджет → экран виджета → нужное действие
Блокировка не защищена паролем и снимается тем же переключателем — это защита от случайного жеста, а не родительский контроль.
Размеры виджетов и шрифтов

Настройки → Интерфейс → Главный экран. Семь размеров, каждый настраивается отдельно:

  • Размер виджета — размер плитки на главном экране
  • Значение (Текст) — шрифт значения параметра
  • Название виджета — шрифт подписи виджета
  • Время последнего сообщения — шрифт отметки времени
  • Иконка параметра — размер иконки
  • Значение — только для типов Логический и Цвет
  • Кнопка — только для типа Кнопка

Каждый пункт открывает экран с бегунком и предпросмотром главного экрана: изменения сразу видно на своих же виджетах. Значение Авто означает, что размер подбирает приложение; заданное вручную значение показывается в dp рядом с названием настройки.

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