Настройка подключения к MQTT серверу
Для управления устройством может использоваться канал связи с использованием технологии MQTT (Message Queue Telemetry Transport). В интернете можно найти множество статей, объясняющих принципы функционирования этого протокола, дающие понятия о подписках, публикациях и другие основные сведения.
Список публичных MQTT-серверов можно найти в любой поисковой системе по запросу "публичный MQTT брокер". Один из таких списков представлен здесь. Пример обзора публичных MQTT серверов можно изучить на этой странице. Выберите подходящий именно вам MQTT брокер, изучите документацию на него, настройте подключение.
Как правило, сервера отличаются наличием наряду с платными, бесплатных сервисов, которые, однако, могут иметь ограничения на количество одновременных подключений к брокеру, количество разрешенных запросов в период времени, наличие / отсутствие авторизации при подключении, поддержку SSL и так далее. Выбор конкретного брокера зависит от ваших предпочтений и требований по защите канала (авторизация, наличие SSL и т.д). Вместе с тем следует принимать во внимание ряд параметров от которых зависит будет ли вообще устройство нормально работать с управлением по MQTT-каналу.
В процессе коммуникации устройство отправляет вновь подключившемуся клиенту одновременно большое количество сообщений (около 80), содержащих информацию о текущем состоянии устройства, актуальные значения его параметров. Далее при смене режимов отправляются одновременно от 3 до 8 сообщений об изменившихся параметрах. По этой причине для нормальной работы критически важно выбрать брокер не имеющий ограничений на количество передаваемых сообщений в единицу времени - все отправленные сообщения должны без задержек доходить до заинтересованных клиентов. Если бесплатный публичный MQTT-брокер имеет ограничение на отправку - "не более 1 сообщения в секунду" - он нам не подходит.
Выбранный MQTT-брокер должен поддерживать функцию LWT (Last Will and Testament). После физического отключения устройства от сети или потери устройством связи с MQTT-сервером, брокер автоматически рассылает всем подключившимся клиентам сообщение, что устройство более недоступно. Получив это сообщение, клиент (программа на смартфоне) понимает, что устройство более не доступно и деактивирует элементы управления с соответствующим сообщением о недоступности устройства.
Выполнение двух этих обязательных требований обеспечивает доступность управления устройством через MQTT-канал. Если вам не удалось подобрать подходящий сервер из доступных бесплатных - подумайте о покупке платного тарифа MQTT-брокера или установите и настройте свой собственный брокер для вашей локальной сети.
ВНИМАНИЕ! В связи с изменением у брокера mqtt.by формата префикса, в приведенных ниже примерах везде вместо строки "af7cd12a" требуется использовать "user/<имя пользователя>/af7cd12a". Так же требуется задать имя пользователя и пароль. Подробности настройки подключения см. на странице брокера "Профиль".
Для пробного упрощенного использования управления по каналу MQTT в проекте используется бесплатный общедоступный брокер - mqtt.by. Зарегистрируйтесь на сервере mqtt.by, в личном кабинете получите пароль для подключения к брокеру.
Передача сообщений для конкретного устройства обеспечиваются уникальностью топика сообщения - задайте для вашего устройства гарантированный уникальный префикс. Например, используйте для префикса набор символов, формируемый из GUID - Globally Unique Identifier, сгенерированного специальной утилитой, буквенно-цифровой идентификатор из MAC-адреса микроконтроллера вашего устройства, его ID или придумайте набор символов сами. Длина сформированного префикса не должна превышать 30 символов.
Примеры префиксов:
'3db46032'
'ESP-EA4774'
'gy-lamp-e5zs8d'
'MyPanel-4'
Откройте в Arduino IDE файл прошивки "a_def_soft.h". Найдите строки 325-343.
Строки указаны для версии скетча WiFiPanel-v.1.10.2021.0325. Если у вас другая версия - найдите строки, соответствующие строкам на картинке.
Строка 326 - DEFAULT_MQTT_SERVER - укажите URL подключения к MQTT-серверу
Строка 330 - DEFAULT_MQTT_USER - укажите имя пользователя (логин)
Строка 334 - DEFAULT_MQTT_PASS - укажите пароль
Строка 338 - DEFAULT_MQTT_PORT - укажите порт MQTT сервера
Строка 338 - DEFAULT_MQTT_PREFIX - укажите префикс топика сообщений
#define DEFAULT_MQTT_SERVER "mqtt.by" // MQTT сервер
#define DEFAULT_MQTT_USER "" // Имя mqtt-пользователя (укажите имя пользователя для вашего соединения)
#define DEFAULT_MQTT_PASS "" // Пароль mqtt-пользователя (укажите пароль вашего соединения)
#define DEFAULT_MQTT_PORT 1883 // Порт mqtt-соединения
#define DEFAULT_MQTT_PREFIX "af7cd12a" // Префикс топика сообщения уникальный для вашего устройства
Обратите внимание на строку #define A_DEF_PASS 1 определенную в выбранном вами профиле устройства в файле a_def_hard.ino
Если параметр A_DEF_PASS определен как 1 - это означает, что ваши настройки с чувствительными данными хранятся в отдельном
файле с именем "a_def_pass.h", который не включен в состав исходников.
Вам нужно будет создать этот файл и перенести в него настройки с вашими персональными учетными данными.
Если параметр A_DEF_PASS определен как 0 - это означает, что настройки вашего аккаунта для подключения к MQTT-серверу
задаются непосредственно в строках 325-343 скетча в файле "a_def_soft.h".
Итак, параметры соединения определены, прошивку можно загружать в устройство.
После того как прошивка загружена и стартовала, в мониторе порта будет виден лог подключения.
Если все прошло успешно, вы увидите примерно следующее:
На этом настройка устройства для управления по каналу MQTT завершена.
Если у вас есть соответствующие знания - вы можете настроить управление устройством через голосовые помощники, например - Яндекс Алиса или Google Assistant.
На данный момент есть несколько реализаций интеграции устройства в систему управления умным домом с помощью Home Assistant. Одна из реализаций описана тут.
ВНИМАНИЕ! В связи с изменением у брокера mqtt.by формата префикса, в приведенных ниже примерах везде вместо строки "af7cd12a" требуется использовать "user/<имя пользователя>/af7cd12a". Так же требуется задать имя пользователя и пароль. Подробности настройки подключения см. на странице брокера "Профиль".
Настройки соединения с MQTT-сервером, сделанные в скетче по описанию выше, используются как значения по-умолчанию и сохраняются в энергонезависимой памяти при первой загрузке прошивки в микроконтроллер. При дальнейших запусках микроконтроллера настройки считываются из EEPROM и используются при подключении к серверу. В любой момент настройки соединения можно изменить в программе на смартфоне.
Откройте приложение, подключитесь к устройству и перейдите на страницу "Настройки соединения"
Чекбокс "Использовать MQTT" позволяет временно включать и отключать канал управления MQTT.
Ниже расположены поля ввода значений настроек соединения:
- Имя сервера
- Имя пользователя
- Пароль
- Порт
- Префикс
- Интервал отправки сообщений 'uptime'
Некоторые параметры очевидны - имя сервера, имя пользователя, пароль и порт.
Другие требуют некоторого объяснения:
Для формирования топика, в который отправляются сообщения брокеру и ожидается поступление команд от брокера используется префикс, указанный в этом поле. Полный топик сообщения формируется путем присоединения содержательной части топика к префиксу.
Пример - для префикса в поле "Префикс", указанном как af7cd12a:
| Топик | Полный топик | Назначение |
|---|---|---|
| cmd | af7cd12a/cmd | получение команды управления от клиента |
| dta | af7cd12a/dta | отправка запрошенных данных клиенту, в ответ на полученную команду, например '$6 7 |
| err | af7cd12a/err | уведомления об ошибке клиенту |
| sta | af7cd12a/sta | уведомление о старте прошивки (перезапуск микроконтроллера) |
| alm | af7cd12a/alm | сообщения о событиях будильника |
| amd | af7cd12a/amd | сообщения о наступлении событий авторежимов по времени |
| wtr | af7cd12a/wtr | сообщения о получении актуальной погоды |
| tme | af7cd12a/tme | сообщения о синхронизации времени |
| pwr | af7cd12a/pwr | сообщения о включении/выключении устройства |
| sdc | af7cd12a/sdc | сообщения о событиях SD-карты (загрузка файла эффекта) |
| txt | af7cd12a/txt | сообщения о событиях бегущей строки - запуск, окончание |
| stt/xx | af7cd12a/stt/xx | сообщения о текущем статусе параметров устройства - индивидуальный режим, где 'xx' - имя (ключ) параметра |
Полная документация по MQTT API и назначениям топика описана здесь
Если данное поле содержит значение, отличное от нуля, устройство будет с указанным интервалом в секундах отправлять брокеру в топик <prefix>/stt/UP сообщение,
содержащее количество секунд, прошедших с момента запуска микроконтроллера устройства - время бесперебойной работы.
После того, как параметры сервера были сконфигурированы, нажмите кнопку "Сохранить". Новые значения параметров вступают в силу немедленно после сохранения.
Для того, чтобы приложение на смартфоне могло подключаться к устройству через MQTT-канал, требуется сконфигурировать параметры соединения.
После запуска приложения вы увидите страницу настройки подключения к устройству:
Нажмите на круглую кнопку "Добавить" для создания нового подключения или кнопку "Редактировать" для изменения настроек существующего подключения. После этого откроется панель редактирования параметров соединения.
Панель содержит следующие поля:
-
Имя- наименование подключения, как вы его видите в комбобоксе выбора на предыдущем изображении. - Чекбокс
Локальная сеть- при активированном чекбоксе будет выполняться подключение в локальной WiFi сети по указанному адресу с использованием UDP-протокола передачи данных -
IP адрес- IP адрес устройство к которому выполняется подключение -
Порт- порт подключения по протоколу UDP. Значение по умолчанию - 2390, задается в скетче константой - Чекбокс
MQTT канал-при активированном чекбоксе будет выполняться подключение к устройству через указанный MQTT-брокер -
Сервер- URL сервера на котором работает MQTT-брокер -
Порт- порт подключения к MQTT-брокеру -
Логин- имя пользователя, если MQTT-сервер требует авторизации при подключении -
Пароль- пароль, если MQTT-сервер требует авторизации при подключении -
Префикс- уникальный префикс устройства, указанный при настройке MQTT-канала в приложении на предыдущем шаге
После заполнения полей формы, нажмите на кнопку "Сохранить" в верхней части страницы или на кнопку "Подключить" для выполнения попытки соединения с устройством. Все значения, указанные в полях, при этом будут сохранены автоматически.