MQTT / HTTP API

Зміст

• Огляд
• Отримання статусу
• LiveView
• Керування живленням
• Відтворення звуку
• Фонове підсвічування
• Кольорові індикатори
• Користувацькі застосунки та сповіщення
  • Взаємодія
  • Властивості JSON
    • Приклад
  • Інструкції малювання
  • Приклад
  • Відображення тексту кольоровими фрагментами
  • Надсилання кількох користувацьких сторінок одночасно
  • Видалення користувацького застосунку
  • Закриття сповіщення
  • Перемикання застосунків
  • Перехід до конкретного застосунку
• Зміна налаштувань
  • Властивості JSON
• Оновлення
  • Перезавантаження Svitrix
  • Очищення Svitrix
  • Скидання налаштувань

Огляд

Ця документація API охоплює різноманітні функції, такі як отримання статистики пристрою, дзеркалювання екрану, сповіщення, користувацькі застосунки, відтворення звуку та фонове підсвічування. Ви можете взаємодіяти з цими функціями через протоколи MQTT та HTTP.

Отримання статусу

Доступ до різноманітної статистики пристрою, такої як батарея, RAM тощо:

MQTT-топік	HTTP URL	Опис
[PREFIX]/stats	http://[IP]/api/stats	Загальна статистика пристрою (батарея, RAM)
[PREFIX]/stats/effects	http://[IP]/api/effects	Список усіх ефектів
[PREFIX]/stats/transitions	http://[IP]/api/transitions	Список усіх ефектів переходу
[PREFIX]/stats/loop	http://[IP]/api/loop	Список усіх застосунків у циклі

Примітка: MQTT також транслює інші дані, наприклад натискання кнопок та поточний застосунок.

LiveView

Отримання поточного зображення матриці у вигляді масиву 24-бітних кольорів:

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
[PREFIX]/sendscreen	http://[IP]/api/screen	-	GET

При виклику MQTT API, SVITRIX надсилає масив до [PREFIX]/screen.

Додатково:

• Переглядайте екран наживо у вашому браузері: http://[IP]/screen.
• Можливість завантажити скріншот або згенерувати GIF із поточного вмісту дисплея.
• http://[IP]/fullscreen надає повноекранний перегляд. Тут ви можете додатково встановити параметр fps (стандартно 30).

Керування живленням

Увімкнення або вимкнення матриці:

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
[PREFIX]/power	http://[IP]/api/power	{"power": true} або {"power": false}	POST

Переведення плати в режим глибокого сну (також вимикає матрицю), корисно для збереження заряду батареї:

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
[PREFIX]/sleep	http://[IP]/api/sleep	{"sleep": X} де X — кількість секунд	POST

SVITRIX прокинеться лише після завершення часу або натискання середньої кнопки. Немає можливості розбудити пристрій через API.

Відтворення звуку

Відтворення RTTTL-звуку з папки MELODIES.

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
[PREFIX]/sound	http://[IP]/api/sound	{"sound":"alarm"}	POST

Відтворення RTTTL-звуку з заданого RTTTL-рядка:

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
[PREFIX]/rtttl	http://[IP]/api/rtttl	rttl string	POST

Фонове підсвічування

Встановлення кольору або температури для всієї матриці:

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
[PREFIX]/moodlight	http://[IP]/api/moodlight	Див. нижче	POST

⚠️ Увага: Використання цієї функції призводить до підвищеного споживання струму та нагрівання, особливо коли всі пікселі увімкнені. Переконайтеся, що ви відповідально керуєте значеннями яскравості.

Щоб вимкнути фонове підсвічування, надішліть порожнє тіло запиту.

Приклад:

{
  "brightness": 170,
  "kelvin": 2300
}

Можливі варіанти фонового підсвічування:

{"brightness":170,"kelvin":2300}
or
{"brightness":170,"color":[155,38,182]}
or
{"brightness":170,"color":"#FF00FF"}

Кольорові індикатори

Кольорові індикатори — це невеликі знаки сповіщень, що відображаються у певних областях екрану:

• Верхній правий кут: Індикатор 1
• Правий бік: Індикатор 2
• Нижній правий кут: Індикатор 3

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
[PREFIX]/indicator1	http://[IP]/api/indicator1	{"color":[255,0,0]}	POST
[PREFIX]/indicator2	http://[IP]/api/indicator2	{"color":[0,255,0]}	POST
[PREFIX]/indicator3	http://[IP]/api/indicator3	{"color":[0,255,0]}	POST

Варіанти кольору:

• Використовуйте RGB-масив, наприклад, {"color":[255,0,0]}
• Використовуйте HEX-рядки кольорів, наприклад, {"color":"#32a852"}

Приховання індикаторів:

• Щоб приховати індикатори, надішліть чорний колір ({"color":[0,0,0]}) або використовуйте скорочення {"color":"0"}. Також можна надіслати порожнє тіло запиту.

Додаткові ефекти:

• Блимання: Щоб індикатор блимав, додайте ключ "blink" зі значенням, що вказує інтервал блимання у мілісекундах.
• Згасання: Щоб індикатор плавно згасав і з'являвся, додайте ключ "fade" зі значенням, що вказує інтервал згасання у мілісекундах.

Користувацькі застосунки та сповіщення

З SVITRIX ви можете створювати користувацькі застосунки або сповіщення для відображення власного тексту та іконок.

Взаємодія

• MQTT: Надішліть JSON-об'єкт до [PREFIX]/custom/[app], де [app] — назва вашого застосунку (без пробілів).
• HTTP API: Додайте назву застосунку у параметр запиту (name=[appname]).
• Оновлення: Щоб оновити користувацьку сторінку, надішліть змінений JSON-об'єкт на той самий endpoint. Дисплей оновиться миттєво.
• Одноразове сповіщення: Використовуйте той самий формат JSON. Направте ваш JSON-об'єкт до [PREFIX]/notify або http://[IP]/api/notify.

MQTT-топік	HTTP URL	Тіло запиту	Параметри запиту	HTTP-метод
[PREFIX]/custom/[appname]	http://[IP]/api/custom	JSON	name=[appname]	POST
[PREFIX]/notify	http://[IP]/api/notify	JSON	-	POST

Властивості JSON

Нижче наведено властивості, які ви можете використовувати в JSON-об'єкті. Усі ключі необов'язкові; додавайте лише ті властивості, які вам потрібні.

Ключ	Тип	Опис	За замовч.	Застосунок	Сповіщення
text	string	Текст для відображення. Зверніть увагу, що шрифт не має фіксованого розміру, і I займає менше місця, ніж W. Це впливає на те, коли текст почне прокручуватися.	N/A	X	X
textCase	integer	Змінює налаштування великих літер. 0 = глобальне налаштування, 1 = примусово великі літери; 2 = відображати як надіслано.	0	X	X
topText	boolean	Малювати текст зверху.	false	X	X
textOffset	integer	Встановлює зміщення позиції x для початку тексту.	0	X	X
center	boolean	Центрує короткий текст, що не прокручується.	true	X	X
color	string або array of integers	Колір тексту, стовпчикової діаграми або лінії.	N/A	X	X
gradient	Array of string або integers	Розфарбовує текст градієнтом із двох заданих кольорів.	N/A	X	X
blinkText	Integer	Блимання тексту із заданим інтервалом у мс, несумісне з градієнтом або веселкою.	N/A	X	X
fadeText	Integer	Плавне згасання тексту із заданим інтервалом, несумісне з градієнтом або веселкою.	N/A	X	X
background	string або array of integers	Встановлює колір фону.	N/A	X	X
rainbow	boolean	Кожна літера тексту плавно переливається різними кольорами RGB-спектру.	false	X	X
icon	string	ID іконки або ім'я файлу (без розширення) для відображення у застосунку. Також можна надіслати 8x8 jpg як Base64-рядок.	N/A	X	X
pushIcon	integer	0 = Іконка не рухається. 1 = Іконка рухається з текстом і більше не з'являється. 2 = Іконка рухається з текстом, але з'являється знову, коли текст починає прокручуватися знову.	0	X	X
repeat	integer	Встановлює, скільки разів текст має прокрутитися через матрицю перед завершенням застосунку.	-1	X	X
duration	integer	Встановлює тривалість відображення застосунку або сповіщення.	5	X	X
hold	boolean	Встановіть true, щоб утримувати сповіщення зверху, доки ви не натиснете середню кнопку або не закриєте його через HomeAssistant. Цей ключ стосується лише сповіщень.	false		X
sound	string	Ім'я файлу RTTTL-мелодії з папки MELODIES (без розширення).	N/A		X
rtttl	string	Дозволяє надсилати RTTTL-рядок звуку разом з JSON.	N/A		X
loopSound	boolean	Зациклює звук або RTTTL на час відображення сповіщення.	false		X
bar	array of integers	Малює стовпчикову діаграму. Без іконки максимум 16 значень, з іконкою 11 значень.	N/A	X	X
line	array of integers	Малює лінійний графік. Без іконки максимум 16 значень, з іконкою 11 значень.	N/A	X	X
autoscale	boolean	Вмикає або вимикає автомасштабування для стовпчикової діаграми та лінійного графіка.	true	X	X
barBC	string або array of integers	Колір фону стовпчиків.	0	X	X
progress	integer	Показує індикатор прогресу. Значення може бути 0–100.	-1	X	X
progressC	string або array of integers	Колір індикатора прогресу.	-1	X	X
progressBC	string або array of integers	Колір фону індикатора прогресу.	-1	X	X
pos	integer	Визначає позицію вашої користувацької сторінки у циклі, починаючи з 0 для першої позиції. Застосовується лише при першому надсиланні. Ця функція експериментальна.	N/A	X
draw	array of objects	Масив інструкцій малювання. Кожен об'єкт представляє команду малювання. Див. інструкції малювання нижче.		X	X
lifetime	integer	Видаляє користувацький застосунок, якщо не було оновлення протягом заданого часу в секундах.	0	X
lifetimeMode	integer	0 = видаляє застосунок, 1 = позначає його як застарілий червоною рамкою навколо застосунку.	0	X
stack	boolean	Визначає, чи буде сповіщення додано в чергу. false негайно замінить поточне сповіщення.	true		X
wakeup	boolean	Якщо матриця вимкнена, сповіщення увімкне її на час відображення сповіщення.	false		X
noScroll	boolean	Вимикає прокручування тексту.	false	X	X
clients	array of strings	Дозволяє пересилати сповіщення на інші пристрої SVITRIX. Використовуйте MQTT-префікс для MQTT та IP-адреси для HTTP.			X
scrollSpeed	integer	Змінює швидкість прокручування. Введіть відсоткове значення від початкової швидкості прокручування.	100	X	X
effect	string	Показує ефект як фон. Ефект можна видалити, надіславши порожній рядок для effect.		X	X
effectSettings	json map	Змінює колір та швидкість ефекту.		X	X
save	boolean	Зберігає ваш користувацький застосунок у флеш-пам'ять та завантажує його після перезапуску. Уникайте цього для застосунків з високою частотою оновлення, оскільки флеш-пам'ять ESP має обмежену кількість циклів запису.		X
overlay	string	Встановлює накладення ефекту (не може використовуватися з глобальними накладеннями).		X	X

Колір: Приймає HEX-рядок або R,G,B масив: "#FFFFFF" або [255,255,0].

Ефекти накладення:

• "clear"
• "snow"
• "rain"
• "drizzle"
• "storm"
• "thunder"
• "frost"

Приклад

Ось приклад JSON для відображення тексту "Hello, SVITRIX!" у веселкових кольорах протягом 10 секунд:

{
  "text": "Hello, SVITRIX!",
  "rainbow": true,
  "duration": 10
}

MQTT Placeholder

Ця функція особливо корисна для користувачів без повноцінної системи розумного дому. Вона усуває необхідність у зовнішній системі для відображення даних, наприклад від інвертора, який може надсилати свої дані через MQTT. Ви можете просто створити файл [AppName].json у папці CUSTOMAPP з вашими ключами JSON для користувацького застосунку. Цей JSON-файл буде завантажено при запуску, тому вам не потрібно надсилати його із зовнішнього джерела. Також ви можете використовувати його у вашому HTTP або MQTT API запиті.

Заповнювачі всередині значення text, укладені у , будуть замінені на payload вказаного MQTT-топіку. Наразі немає доступних варіантів форматування payload.

{"text": "Solar: {{inverter/total/P_AC}} W"}

Інструкції малювання

WARNING

Зверніть увагу: Залежно від кількості об'єктів, використання RAM може бути дуже високим. Це може спричинити зависання або перезавантаження.

Важливо враховувати кількість об'єктів та складність інструкцій малювання, щоб уникнути проблем з продуктивністю.

Кожна інструкція малювання — це об'єкт з обов'язковим ключем команди та масивом значень залежно від команди:

Команда	Значення масиву	Опис
dp	[x, y, cl]	Малює піксель у позиції (x, y) кольором cl
dl	[x0, y0, x1, y1, cl]	Малює лінію від (x0, y0) до (x1, y1) кольором cl
dr	[x, y, w, h, cl]	Малює прямокутник з верхнім лівим кутом у (x, y), шириною w, висотою h та кольором cl
df	[x, y, w, h, cl]	Малює зафарбований прямокутник з верхнім лівим кутом у (x, y), шириною w, висотою h та кольором cl
dc	[x, y, r, cl]	Малює коло з центром у (x, y), радіусом r та кольором cl
dfc	[x, y, r, cl]	Малює зафарбоване коло з центром у (x, y), радіусом r та кольором cl
dt	[x, y, t, cl]	Малює текст t з верхнім лівим кутом у (x, y) та кольором cl
db	[x, y, w, h, [bmp]]	Малює RGB888 растровий масив [bmp] з верхнім лівим кутом у (x, y) та розміром (w, h)

Приклад

Ось приклад JSON-об'єкта для малювання червоного кола, синього прямокутника та тексту "Hello" зеленим кольором:

{"draw":[
 {"dc": [28, 4, 3, "#FF0000"]},
 {"dr": [20, 4, 4, 4, "#0000FF"]},
 {"dt": [0, 0, "Hello", "#00FF00"]}
]}

Відображення тексту кольоровими фрагментами

SVITRIX дозволяє відображати текст, де окремі фрагменти можуть мати різні кольори. Використовуйте масив фрагментів, де "t" представляє текстовий фрагмент, а "c" — HEX-значення кольору.

{
  "text": [
    {
      "t": "Hello, ",
      "c": "FF0000"
    },
    {
      "t": "world!",
      "c": "00FF00"
    }
  ],
  "repeat": 2
}

Надсилання кількох користувацьких застосунків одночасно

SVITRIX дозволяє відправляти кілька користувацьких застосунків однією дією. Замість надсилання одного об'єкта користувацького застосунку, ви можете відправити масив об'єктів.

Наприклад, MQTT-топік: /custom/test

[
  {"text":"1"},
  {"text":"2"}
]

Обробка кількох користувацьких застосунків:

• Присвоєння суфікса: Внутрішньо назва застосунку отримує суфікс, перетворюючись у формат на кшталт test0, test1 тощо.
• Оновлення: Ви можете оновлювати кожен застосунок окремо або всі разом.
• Видалення:
  • При видаленні застосунків SVITRIX не шукає точну назву. Натомість він знаходить застосунки, що починаються із зазначеної назви.
  • Щоб видалити всі пов'язані застосунки, надішліть порожнє тіло запиту до /custom/test. Ця дія видалить test0, test1 тощо.
  • Щоб видалити окремий застосунок, направте команду, наприклад, до /custom/test1.
  • Увага: Видалення лише одного застосунку може порушити порядок решти застосунків у циклі, оскільки немає механізму збереження позицій.

Видалення користувацького застосунку

Щоб видалити користувацький застосунок, надішліть порожнє тіло запиту на відповідний топік або URL.

Закриття сповіщення

Легко закрийте сповіщення, яке було налаштовано з "hold": true.

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
[PREFIX]/notify/dismiss	http://[IP]/api/notify/dismiss	Порожнє тіло	POST

Перемикання застосунків

Перехід до наступного або попереднього застосунку.

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
[PREFIX]/nextapp	http://[IP]/api/nextapp	Порожнє тіло	POST
[PREFIX]/previousapp	http://[IP]/api/previousapp	Порожнє тіло	POST

Перехід до конкретного застосунку

Безпосередній перехід до потрібного застосунку за його назвою.

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
[PREFIX]/switch	http://[IP]/api/switch	{"name":"Time"}	POST

Вбудовані назви застосунків:

• Time
• Date
• Temperature
• Humidity
• Battery

Для користувацьких застосунків використовуйте назву, яку ви вказали у топіку або HTTP-параметрі. У MQTT, якщо [PREFIX]/custom/test — ваш топік, то test буде назвою застосунку.

Зміна налаштувань

Налаштування різноманітних параметрів відображення застосунків.

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
[PREFIX]/settings	http://[IP]/api/settings	JSON	GET/POST

Властивості JSON

Ви можете налаштувати кожну властивість у JSON-об'єкті відповідно до ваших уподобань. Додавання властивості є необов'язковим.

Ключ	Тип	Опис	Діапазон значень	За замовч.
ATIME	number	Тривалість відображення застосунку у секундах.	Додатне ціле число	7
TEFF	number	Вибір ефекту переходу між застосунками.	0–10	1
TSPEED	number	Час переходу до наступного застосунку у мілісекундах.	Додатне ціле число	500
TCOL	string/array of ints	Глобальний колір тексту.	RGB-масив або HEX-колір	N/A
TMODE	integer	Змінює стиль застосунку часу.	0–6	1
CHCOL	string/array of ints	Колір заголовка календаря у застосунку часу.	RGB-масив або HEX-колір	#FF0000
CBCOL	string/array of ints	Колір тіла календаря у застосунку часу.	RGB-масив або HEX-колір	#FFFFFF
CTCOL	string/array of ints	Колір тексту календаря у застосунку часу.	RGB-масив або HEX-колір	#000000
WD	boolean	Увімкнути або вимкнути відображення дня тижня.	true/false	true
WDCA	string/array of ints	Колір активного дня тижня.	RGB-масив або HEX-колір	N/A
WDCI	string/array of ints	Колір неактивного дня тижня.	RGB-масив або HEX-колір	N/A
BRI	number	Яскравість матриці.	0–255	N/A
ABRI	boolean	Автоматичне керування яскравістю.	true/false	N/A
ATRANS	boolean	Автоматичне перемикання на наступний застосунок.	true/false	N/A
CCORRECTION	array of ints	Корекція кольору для матриці.	RGB-масив	N/A
CTEMP	array of ints	Колірна температура для матриці.	RGB-масив	N/A
TFORMAT	string	Формат часу для застосунку часу.	Різні (див. нижче)	N/A
DFORMAT	string	Формат дати для застосунку дати.	Різні (див. нижче)	N/A
SOM	boolean	Починати тиждень з понеділка.	true/false	true
CEL	boolean	Показувати температуру у Цельсіях (Фаренгейт, якщо false).	true/false	true
BLOCKN	boolean	Блокувати фізичні навігаційні кнопки (введення все одно надсилається до MQTT).	true/false	false
UPPERCASE	boolean	Відображати текст великими літерами.	true/false	true
TIME_COL	string/array of ints	Колір тексту застосунку часу. Використовуйте 0 для глобального кольору тексту.	RGB-масив або HEX-колір	N/A
DATE_COL	string/array of ints	Колір тексту застосунку дати. Використовуйте 0 для глобального кольору тексту.	RGB-масив або HEX-колір	N/A
TEMP_COL	string/array of ints	Колір тексту застосунку температури. Використовуйте 0 для глобального кольору тексту.	RGB-масив або HEX-колір	N/A
HUM_COL	string/array of ints	Колір тексту застосунку вологості. Використовуйте 0 для глобального кольору тексту.	RGB-масив або HEX-колір	N/A
BAT_COL	string/array of ints	Колір тексту застосунку батареї. Використовуйте 0 для глобального кольору тексту.	RGB-масив або HEX-колір	N/A
SSPEED	integer	Зміна швидкості прокручування.	Відсоток від початкової швидкості прокручування	100
TIM	boolean	Увімкнути або вимкнути вбудований застосунок часу (потребує перезавантаження).	true/false	true
DAT	boolean	Увімкнути або вимкнути вбудований застосунок дати (потребує перезавантаження).	true/false	true
HUM	boolean	Увімкнути або вимкнути вбудований застосунок вологості (потребує перезавантаження).	true/false	true
TEMP	boolean	Увімкнути або вимкнути вбудований застосунок температури (потребує перезавантаження).	true/false	true
BAT	boolean	Увімкнути або вимкнути вбудований застосунок батареї (потребує перезавантаження).	true/false	true
MATP	boolean	Увімкнути або вимкнути матрицю. Аналогічно endpoint power, але без анімації.	true/false	true
VOL	integer	Дозволяє встановити гучність зумера.	0–30	25
OVERLAY	string	Встановлює глобальне накладення ефекту (не може використовуватися з накладеннями окремих застосунків).	Різні (див. нижче)	N/A

Значення кольору: Може бути RGB-масивом (наприклад, [255,0,0]) або 6-значним HEX-кольором (наприклад, "#FF0000" для червоного).

Ефекти накладення:

• "clear"
• "snow"
• "rain"
• "drizzle"
• "storm"
• "thunder"
• "frost"

Доступні формати часу:

Формат	Приклад	Опис
%H:%M:%S	13:30:45	24-годинний формат із секундами
%l:%M:%S	1:30:45	12-годинний формат із секундами
%H:%M	13:30	24-годинний формат
%H %M	13.30	24-годинний формат із блимаючою двокрапкою
%l:%M	1:30	12-годинний формат
%l %M	1:30	12-годинний формат із блимаючою двокрапкою
%l:%M %p	1:30 PM	12-годинний формат з індикатором AM/PM
%l %M %p	1:30 PM	12-годинний з блимаючою двокрапкою та AM/PM

Доступні формати дати:

Формат	Приклад	Опис
%d.%m.%y	16.04.22	День.Місяць.Рік (скор.)
%d.%m	16.04	День.Місяць
%y-%m-%d	22-04-16	Рік-Місяць-День
%m-%d	04-16	Місяць-День
%m/%d/%y	04/16/22	Місяць/День/Рік
%m/%d	04/16	Місяць/День
%d/%m/%y	16/04/22	День/Місяць/Рік
%d/%m	16/04	День/Місяць
%m-%d-%y	04-16-22	Місяць-День-Рік

Доступні ефекти переходу:

Код	Ефект
0	Random
1	Slide
2	Dim
3	Zoom
4	Rotate
5	Pixelate
6	Curtain
7	Ripple
8	Blink
9	Reload
10	Fade

Оновлення

Ви можете ініціювати оновлення прошивки через кнопку оновлення в HA або за допомогою наступного:

MQTT-топік	HTTP URL	Тіло запиту	HTTP-заголовок	HTTP-метод
[PREFIX]/doupdate	http://[IP]/api/doupdate	JSON	порожнє тіло	POST

Перезавантаження Svitrix

Якщо вам потрібно перезавантажити Svitrix:

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
[PREFIX]/reboot	http://[IP]/api/reboot	-	POST

Очищення Svitrix

УВАГА: Ця дія відформатує флеш-пам'ять та EEPROM, але не змінить налаштування WiFi. По суті, це скидання до заводських налаштувань.

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
N/A	http://[IP]/api/erase	-	POST

Скидання налаштувань

УВАГА: Ця дія скине всі налаштування з API налаштувань. Вона не скидає файли флеш-пам'яті та налаштування WiFi.

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
N/A	http://[IP]/api/resetSettings	-	POST