API управления устройством по каналу MQTT

Канал управления MQTT

Управление устройством выполняется путем отправки ему команды через один из доступных каналов - UDP или MQTT.
Не имеет значения по какому каналу устройство получило команду - обработка выполняется одинаково.

Полный перечень команд управления устройством приведен в статье API управления устройством
Настройка Канала управления MQTT описана в статье Настройка подключения к MQTT серверу

Сообщения в MQTT канал, отправляемые по инициативе устройства

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

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

• Включение и запуск устройства
• Изменение значения параметра
• Событие получение времени с сервера NTP
• Событие получения информации о текущей погоде
• Событие, запрограммированое для одного из режимов по времени
• Срабатывание и отключение будильника
• Ошибки обработки запросов и команд, выполнения операций

Один из параметров настройки MQTT канала - "Пакетный режим" (чекбокс "Пакеты" в приложении на странице настройки соединений).
В зависимости текущего состояния чекбокса, сообщения об измененим значений параметров будут приходить в разных форматах:

• Чекбокс отмечен: сообщения поступают в виде пакета в формате JSON, содержащие пары "Ключ-Значение".
• Чекбокс снят: сообщения об актуальном значении параметра поступают в виде отдельного сообщения в топик, содержащие только актуальное значение параметра.

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

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

Топики сообщений

Используемые устройством топики и их назначение приведены в таблице

Топик	Назначение
cmd	получение команды управления от клиента
dta	отправка запрошенных данных клиенту, в ответ на полученную команду, например '$6 7
err	уведомления об ошибке клиенту
sta	уведомление о старте прошивки (перезапуск микроконтроллера)
alm	сообщения о событиях будильника
amd	сообщения о наступлении событий авторежимов по времени
wtr	сообщения о получении актуальной погоды
tme	сообщения о синхронизации времени
pwr	сообщения о включении/выключении устройства
sdc	сообщения о событиях SD-карты (загрузка файла эффекта)
txt	сообщения о событиях бегущей строки - запуск, окончание
stt	сообщения о текущем статусе параметров устройства - пакетный режим
stt/xx	сообщения о текущем статусе параметров устройства - индивидуальный режим, где XX - имя (ключ) параметра

Параметры и их значения

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

Константные параметры (не изменяются в процессе работы)

Ключ	Тип	Значение
W	byte	ширина матрицы
H	byte	высота матрицы
LE	String	список эффектов, разделенный запятыми
TM	bool	в системе присутствует индикатор TM1637, - false / true
QZ	bool	сборка поддерживает MQTT - false / true
S1	String	список звуков будильника, разделенный запятыми
S2	String	список звуков рассвета, разделенный запятыми
S3	String	список звуков для макроса {A} бегущей строки, разделенный запятыми
WZ	bool	Прошивка поддерживает погоду - false / true

Параметры состояния устройства

Ключ	Тип	Значение
AD	byte	продолжительность рассвета, мин
AE	byte	эффект, использующийся для будильника
AO	bool	включен будильник: false / true
AL	bool	сработал будильник: false / true
AM1T	String	час 00..23 и минуты 00..59 включения режима 1, разделенные пробелом: HH MM
AM1A	int8_t	номер эффекта режима 1: -3 - не используется; -2 - выключить матрицу; -1 - ночные часы; 0 - включить случайный с автосменой; 1 - номер режима из списка EFFECT_LIST
AM2T	String	час 00..23 и минуты 00..59 включения режима 2, разделенные пробелом: HH MM
AM2A	int8_t	номер эффекта режима 1: -3 - не используется; -2 - выключить матрицу; -1 - ночные часы; 0 - включить случайный с автосменой; 1 - номер режима из списка EFFECT_LIST
AM3T	String	час 00..23 и минуты 00..59 включения режима 3, разделенные пробелом: HH MM
AM3A	int8_t	номер эффекта режима 1: -3 - не используется; -2 - выключить матрицу; -1 - ночные часы; 0 - включить случайный с автосменой; 1 - номер режима из списка EFFECT_LIST
AM4T	String	час 00..23 и минуты 00..59 включения режима 4, разделенные пробелом: HH MM
AM4A	int8_t	номер эффекта режима 1: -3 - не используется; -2 - выключить матрицу; -1 - ночные часы; 0 - включить случайный с автосменой; 1 - номер режима из списка EFFECT_LIST
AN	String	имя точки доступа
AT	String	часы-минуты времени будильника для дня недели 1..7 -> например "1 9 15
AU	bool	создавать точку доступа false / true
AW	byte	битовая маска дней недели будильника b6..b0: b0 - пн .. b7 - вс -> '5' биты 00000101 -> пн,ср
BE	String	контрастность эффекта: "X", если не используется или число 0..255
BR	byte	яркость
C1	String	цвет режима "монохром" часов оверлея; цвет: "192,96,96" - R,G,B
C2	String	цвет режима "монохром" бегущей строки; цвет: "192,96,96" - R,G,B
CС	byte	режим цвета часов оверлея: 0 - монохром, 1 - по цифрам, 2 - часы-точки-минуты
CE	String	оверлей часов вкл/выкл, где "Х" - N/A, false - выкл; true - вкл -> "использовать часы в эффектах"
CK	byte	размер горизонтальных часов, где Х = 0 - авто; 1 - малые 3x5; 2 - большие 5x7
CL	String	цвет рисования в формате: "192,96,96" - R,G,B
CO	String	ориентация часов: X - N/A, 0 - горизонтально, 1 - вертикально
CT	byte	режим цвета текстовой строки: 0 - монохром, 1 - радуга, 2 - цвет по буквам
DC	bool	показывать дату вместе с часами: false / true
DD	byte	время показа даты при отображении часов (в секундах)
DI	byte	интервал показа даты при отображении часов (в секундах)
DM	bool	демо режим, где Х = false - ручное управление; true - авторежим
DW	bool	показывать температуру вместе с часами: false / true
EF	int8_t	текущий эффект - ID
EN	String	текущий эффект - название
IP	String	Текущий IP адрес WiFi соединения в сети - xx.xx.xx.xx
IT	byte	время бездействия в секундах
LF	String	список файлов эффектов считанных с SD-карты, разделенный запятыми
LT	String	список текстовых строк, разделенный '~'
MA	byte	номер файла звука будильника из SD:/01
MB	byte	номер файла звука рассвета из SD:/02
MD	byte	сколько минут звучит будильник, если его не отключили
MP	String	номер папки и файла звука который проигрывается, номер папки и звука разделены '': "папкафайл"
MU	bool	использовать звук в будильнике false / true
MV	byte	максимальная громкость будильника
MX	bool	MP3 плеер доступен для использования false / true
NB	byte	яркость цвета ночных часов 1..255
NC	byte	цвет ночных часов; 0 - R; 1 - G; 2 - B; 3 - C; 4 - M; 5 - Y; 6 - W;
NP	bool	использовать NTP false / true
NS	String	сервер NTP (30 символов)
NT	byte	период синхронизации NTP в минутах
NW	String	SSID сети подключения (24 символа)
NZ	int8_t	часовой пояс -12..+12
OF	bool	выключать часы на индикаторе TM1637 вместе с лампой false / true
OM	uint16_t	сколько ячеек памяти осталось свободно для хранения строк
PD	byte	продолжительность режима в секундах
PS	bool	состояние программного вкл/выкл панели false - выключена; true - включена
PW	uint16_t	ограничение по току в миллиамперах
QA	bool	использовать MQTT false / true
QD	uint16_t	задержка отправки сообщения MQTT
QP	uint16_t	порт подключения к MQTT серверу
QR	String	префикс для формирования топика (30 cимволов)
QS	String	имя MQTT сервера (24 символа)
QU	String	имя пользователя MQTT соединения (14 символов)
RM	bool	смена режимов в случайном порядке false / true
SC	byte	скорость смещения часов оверлея
SD	bool	наличие и доступность SD карты false / true
SE	String	скорость эффектов: "X", если не используется или число 0..255
SS	String	параметр #1 эффекта "X", если не используется или число 0.255
SQ	String	параметр #2 эффекта; "X", если не используется или строка - "L>val>itrm1,item2,..itemN" - список, где val - текущее значение, далее список; "C>x>title" - чекбокс, где x=0 - выкл, x=1 - вкл; title - текст чекбокса
ST	byte	скорость смещения бегущей строки 0..255
TE	bool	оверлей текста бегущей строки false / true -> "использовать бегущую строку в эффектах"
TI	uint16_t	интервал отображения текста бегущей строки в секундах
TS	String	строка состояния кнопок выбора текста из массива строк: 36 символов 0..5, где - 0 - серый - пустая - 1 - черный - отключена - 2 - зеленый - активна - просто текст, без макросов - 3 - голубой - активна, содержит макросы кроме даты - 4 - синий - активная, содержит макрос даты - 5 - красный - для строки 0 - это управляющая строка
TY	String	текст для строки, с указанным индексом I 0..35, Z 0..9,A..Z; текст ответа в формате: 'I:Z > текст';
UC	String	использовать часы поверх эффекта X - N/A, false / true
UE	bool	использовать эффект в демо-режиме false / true
UI	uint16_t	интервал отправки uptime на сервер в секундах или 0, если отключено
UP	uint32_t	время работы системы с последнего перезапуска в секундах
UT	String	использовать бегущую строку поверх эффекта X - N/A, false / true
W1	String	текущая погода ('ясно','пасмурно','дождь'и т.д.)
W2	int8_t	текущая температура
WC	bool	Использовать цвет для отображения температуры в дневных часах false / true
WN	bool	Использовать цвет для отображения температуры в ночных часах false / true
WR	uint32_t	Регион погоды Yandex
WS	uint32_t	Регион погоды OpenWeatherMap
WT	byte	Период запроса сведений о погоде в минутах
WU	byte	Использовать получение погоды с сервера: 0 - выключено; 1 - Yandex; 2 - OpenWeatherMap

В пакетном режиме значения параметров отправляются втопик "stt" в виде json-строки, содержащей пары ключ-значение, например

{"W":48,"H":16,"DM":true,"PS":true,"PD":40,"IT":0,"AL":false,"RM":true,"PW":15000,"BR":6,
 "WU":1,"WT":15,"WR":62,"WS":1502026,"WC":true,"WN":true,"WZ":true,"EF":36,"EN":"Камин",
 "UE":true,"UT":true,"UC":true,"SE":"X","SS":"X","BE":176,"CE":true,"CC":0,"CO":0,"CK":0,
 "NC":0,"SC":119,"C1":"255,255,255","DC":true,"DD":3,"DI":240,"NP":true,"NT":60,"NZ":7,
 "NS":"ru.pool.ntp.org","DW":true,"OF":false,"TM":false,"AW":0,
 "AT":"1 0 0|2 0 0|3 0 0|4 0 0|5 0 0|6 0 0|7 0 0","AD":10,"AE":43,"MX":false,"AU":false,
 "AN":"PanelAP","NW":"AlvaNet","IP":"192.168.0.98","QZ":true,"QA":true,"QP":9124,
 "QS":"srv1.clusterfly.ru","QU":"user_eada9d0d","QD":100,"QR":"user_eada9d0d",
 "TE":true,"TI":90,"TS":"524133333222223344224444220000000041","CT":0,
 "C2":"255,255,254","OM":886,"ST":188,"AM1T":"23 35","AM1A":-1,"AM2T":"00 00","AM2A":-2,
 "AM3T":"09 30","AM3A":0,"AM4T":"00 00","AM4A":-3}

Параметры "LE" (список эффектов), "S1" (список звуков будильника), "S2" (список звуков рассвета), "LF" (список файлов на SD-карте), "LT" (список текстов бегущей строки) и "SQ" (варианты эффекта) могут содержать строки большой длины и во избежание переполнения буфера всегда передаются в виде отдельных топиков - stt/LE, stt/S1, stt/S2, stt/LF, stt/LT и stt/SQ соответственно.

Пример:

{"LE":"Часы,Лампа,Снегопад,Кубик,Радуга,Пейнтбол,Огонь,The Matrix,Шарики,Звездопад,Конфетти,Цветной шум,Облака,Лава,Плазма,
Радужные переливы,Полосатые переливы,Зебра,Шумящий лес,Морской прибой,Смена цвета,Светлячки,Водоворот,Циклон,Мерцание,
Северное сияние,Тени,Лабиринт,Змейка,Тетрис,Арканоид,Палитра,Спектрум,Синусы,Вышиванка,Дождь,Камин,Водопад,Стрелки,Анимация,
Погода,Жизнь,Узоры,Рассвет,SD-Карта"}

Если пакетный режим отключен - значение каждого параметра передается в отдельном топике, например

user_eada9d0d/WiFiPanel-0/stt/W	 >> 48
user_eada9d0d/WiFiPanel-0/stt/H	 >> 16
user_eada9d0d/WiFiPanel-0/stt/DM >> true
user_eada9d0d/WiFiPanel-0/stt/PS >> true
user_eada9d0d/WiFiPanel-0/stt/PD >> 40
user_eada9d0d/WiFiPanel-0/stt/IT >> 0
user_eada9d0d/WiFiPanel-0/stt/AL >> false
user_eada9d0d/WiFiPanel-0/stt/RM >> true
user_eada9d0d/WiFiPanel-0/stt/PW >> 15000
...
user_eada9d0d/WiFiPanel-0/stt/AT >> 1 0 0|2 0 0|3 0 0|4 0 0|5 0 0|6 0 0|7 0 0
user_eada9d0d/WiFiPanel-0/stt/AD >> 10
user_eada9d0d/WiFiPanel-0/stt/AE >> 43
user_eada9d0d/WiFiPanel-0/stt/MX >> false
user_eada9d0d/WiFiPanel-0/stt/AU >> false
user_eada9d0d/WiFiPanel-0/stt/EF >> 22
user_eada9d0d/WiFiPanel-0/stt/EN >> Водоворот
user_eada9d0d/WiFiPanel-0/stt/SQ >> C>1>Сегменты

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

Уведомления

Уведомления о событиях устройства отправляются в следующие топики MQTT канала:

Состояние питания устройства публикуются в топик "pwr" с флагом retain

После успешного подключения к MQTT-серверу отправляется сообщение - текстовая строка "online". После отключения питания / потери соединения с MQTT-сервером брокер автоматически отправляет всем подключенным клиентам сообщение "offline" - Last Will and Testament (LWT)

Запуск устройства после перезагрузки / подключения питания

После запуска устройства в топик "sta" отправляется сообщение - текстовая строка "START". Это позволяет (например по логам) отследить момент старта / перезапуска устройства

Нотификация о успешной / неуспешной синхронизации времени - топик "tme"

{"act":"TIME","server_name":"ru.pool.ntp.org","server_ip":"192.36.143.130","result":"REQUEST"}

{"act":"TIME","server_name":"ru.pool.ntp.org","server_ip":"192.36.143.130","result":"TIMEOUT"}

{"act":"TIME","server_name":"ru.pool.ntp.org","server_ip":"192.36.143.130","result":"OK","time":1601729577}

Нотификация о получении погоды с сервера погоды - топик "wtr"

{"act":"WEATHER","region":62,"result":"TIMEOUT"} - таймаут ожидания ответа сервера

{"act":"WEATHER","region":62,"result":"ERROR","status":"<http_code>"} - неожиданный ответ сервера в <http_code> (ожидается "OK 200")

{"act":"WEATHER","region":62,"result":"ERROR","status":"unexpected answer"} - получен ответ от сервера, который не содержит HTTP заголовков

{"act":"WEATHER","region":62,"result":"ERROR","status":"json error"} - полученный ответ - не информация о погоде в формате json

{"act":"WEATHER","region":62,"result":"ERROR","status":"no data"} - получен json-ответ, но в нем нет информации о погоде. Возможно в запросе указан неизвестный код региона погоды

{"act":"WEATHER","region":62,"result":"OK","status":"<условия>","temp":-2,"night":true,"icon":"ovc","town":"Krasnoyarsk","server":"Yandex","sky":"#00050f"} - погода получена с Yandex

{"act":"WEATHER","region":1502026,"result":"OK","status":"<условия>","temp":-3,"night":true,"icon":"01n","town":"Красноярск","server":"OpenWeatherMap","code":800} - погода получена с OpenWeatherMap

При удачном получении информации о погоде, в ответе содержатся следующие поля:

• region - код региона для которого выполен запрос информации
• status - текущие погодные условия - "ясно", "пасмурно", "дождь" и так далее
• temp - текущая температура
• night - true - темное время суток, false - светлое время суток
• icon - иконка погоды, соответствует текущим погодным условиям
• sky - цвет фона неба
• town - название населенного пункта, согласно переданному коду региона погоды

Для сведений, полученных с сервера Yandex

Код иконки	Значения
bkn-minus-ra-d	облачно с прояснениями, небольшой дождь (день)
bkn-minus-sn-d	облачно с прояснениями, небольшой снег (день)
bkn-minus-sn-n	облачно с прояснениями, небольшой снег (ночь)
bkn-d	переменная облачность (день)
bkn-n	переменная облачность (ночь)
bkn-ra-d	переменная облачность, дождь (день)
bkn-ra-n	переменная облачность, дождь (ночь)
bkn-sn-d	переменная облачность, снег (день)
bkn-sn-n	переменная облачность, снег (ночь)
bl	метель
fg-d	туман
ovc	пасмурно
ovc-minus-ra	пасмурно, временами дождь
ovc-minus-sn	пасмурно, временами снег
ovc-ra	пасмурно, дождь
ovc-sn	пасмурно, снег
ovc-ts-ra	пасмурно, дождь, гроза
skc-d	ясно (день)
skc-n	ясно (ночь)

Для сведений, полученных с сервера OpenWeatherMap

Код погоды	Значения
200	Гроза, небольшой дождь // thunderstorm with light rain
201	Дождь с грозой // thunderstorm with rain
202	Гроза, ливни // thunderstorm with heavy rain
210	Небольшая гроза // light thunderstorm
211	Гроза // thunderstorm
212	Сильная гроза // heavy thunderstorm
221	Прерывистые грозы // ragged thunderstorm
230	Гроза, небольшой дождь // thunderstorm with light drizzle
231	Гроза с дождем // thunderstorm with drizzle
232	Гроза с проливным дождем // thunderstorm with heavy drizzle
300	Мелкий дождь // light intensity drizzle
301	Моросящий дождь // drizzle
302	Сильный дождь // heavy intensity drizzle
310	Небольшой дождь // light intensity drizzle rain
311	Моросящий дождь // drizzle rain
312	Сильный дождь // heavy intensity drizzle rain
313	Ливень, дождь и морось // shower rain and drizzle
314	Сильный ливень, дождь и морось // heavy shower rain and drizzle
321	Моросящий дождь // shower drizzle
500	Небольшой дождь // light rain
501	Умеренный дождь // moderate rain
502	Ливень // heavy intensity rain
503	Проливной дождь // very heavy rain
504	Проливной дождь // extreme rain
511	Град // freezing rain
520	Небольшой дождь // light intensity shower rain
521	Моросящий дождь // shower rain
522	Сильный дождь // heavy intensity shower rain
531	Временами дождь // ragged shower rain
600	Небольшой снег // light snow
601	Снег // Snow
602	Снегопад // Heavy snow
611	Слякоть // Sleet
612	Легкий снег // Light shower sleet
613	Ливень, снег // Shower sleet
615	Мокрый снег // Light rain and snow
616	Дождь со снегом // Rain and snow
620	Небольшой снегопад // Light shower snow
621	Снегопад, метель // Shower snow
622	Сильный снегопад // Heavy shower snow
701	Туман // mist
711	Дымка // Smoke
721	Легкий туман // Haze
731	Пыльные вихри // sand/ dust whirls
741	Туман // fog
751	Песчаные вихри // sand
761	Пыльные вихри // dust
762	Вулканический пепел // volcanic ash
771	Шквалистый ветер // squalls
781	Торнадо // tornado
800	Ясно // clear sky
801	Небольшая облачность // few clouds: 11-25%
802	Переменная облачность // scattered clouds: 25-50%
803	Облачно с прояснениями // broken clouds: 51-84%
804	Пасмурно // overcast clouds: 85-100%

Нотификация о срабатывании / отключении работающего будильника - топик "alm"

{"act":"ALARM","state":"on","type":"dawn"} - будильник - состояние "рассвет, без звука"

{"act":"ALARM","state":"on","type":"alarm"} - будильник - состояние "звук"

{"act":"ALARM","state":"off","type":"auto"} - будильник - состояние "выкл. автоматически после истечения времени"

{"act":"ALARM","state":"off","type":"stop"} - будильник - состояние "выкл. кнопкой или командой из приложения"

Нотификация о срабатывании авторежима 1..4 - топик "alm"

{"act":"AUTO","mode":X,"text":"<text>"}

• mode - код режима (эффекта) который включен
• text - информационное сообщение в виде текста о наступившем событии

Нотификация о начале и окончании показа текста бегущей строки - топик "txt"

{"act":"TEXT","run":true,"text":"<text>"}

{"act":"TEXT","run":false}

• run - true - начало отображения бегущей строки; false - окончание отображения текста бегущей строки
• text - отображаемый текст

Нотификация о загрузке и воспроизведении файла эффекта с SD-карты - "sdc"

{"act":"SDCARD","result":"OK","file":"<file>"}

{"act":"SDCARD","result":"ERROR"}

• result - true - эффект загружен и воспроизводится; false - ошибка загрузки файла эффекта
• file - имя файла , загруженного с SD-карты

Сообщения об ошибках - топик "err"

Сообщение отправляется устройством в топик "err" в ответ на нераспознанную команду или некорректные параметры команды

{"message":"unknown page","text":"нет страницы с номером X"} - ответ на команду $18 X;, где X- неизвестная страница

{"message":"unknown command","text":"неизвестная команда '<команда>'"} - ответ на несуществующую или нераспознанную команду '<команда>'