MQTT / HTTP API

Зміст

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

Огляд

Ця документація 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	Список усіх застосунків у циклі
N/A	http://[IP]/api/apps	Список застосунків з даними іконок

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

Примітка: GET /api/apps повертає застосунки з їхніми іконками. POST /api/apps (тіло JSON) оновлює вектор застосунків; також доступно через MQTT на [PREFIX]/apps.

LiveView

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

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

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

Додатково:

• Переглядайте екран наживо у браузері за адресою http://[IP] (головна сторінка SPA).
• Сторінка Screen відображає матрицю в реальному часі на canvas-елементі з можливістю завантаження PNG.

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

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

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

Відтворення звуків у стилі R2-D2, згенерованих із рядка опису звуку:

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод
[PREFIX]/r2d2	http://[IP]/api/r2d2	рядок R2D2	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	Текст для відображення (UTF-8). Підтримуються ASCII, кирилиця (великі/малі), українські та латинські розширені символи. Шрифт має змінну ширину — 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
layout	string	Визначає позицію іконки: "left" (за замовчуванням), "right" або "none". При значенні "right" іконка відображається праворуч. При "none" іконка прихована, а текст займає всі 32 пікселі.	"left"	X	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 буде назвою застосунку.

Збирач даних

Збирач даних дозволяє SVITRIX періодично отримувати дані із зовнішніх HTTP/HTTPS API та відображати результати як користувацькі застосунки — без системи розумного дому.

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

HTTP URL	Тіло запиту	HTTP-метод	Опис
http://[IP]/api/datafetcher	-	GET	Список усіх налаштованих джерел
http://[IP]/api/datafetcher	JSON	POST	Додати або оновити джерело
http://[IP]/api/datafetcher?name=X	-	DELETE	Видалити джерело
http://[IP]/api/datafetcher/fetch?name=X	-	POST	Примусово отримати дані

Примітка: Збирач даних працює лише через HTTP, MQTT-топіки відсутні.

JSON конфігурації джерела

Ключ	Тип	Обов'язковий	Опис	За замовч.
name	string	Так	Унікальний ID джерела, стає назвою застосунку	-
url	string	Так	Повний HTTP/HTTPS URL	-
jsonPath	string	Так	Шлях до значення у JSON через крапку (напр., "bitcoin.usd", "data.0.price")	-
displayFormat	string	Ні	Рядок формату printf з одним перетворенням (напр., "$%.0f", "%.1f°C"). Дозволені: %d %i %u %o %x %X %f %g %e %E %s з модифікаторами ширини та точності; %% для літерального %. Інші формати відхиляються з HTTP 400.	сире значення
icon	string	Ні	Назва іконки з папки ICONS (без розширення)	немає
color	string	Ні	Колір тексту hex "#RRGGBB"	глобальний колір
interval	integer	Ні	Інтервал опитування у секундах (мінімум 60)	900 (15 хв)

Приклад

Додати трекер ціни Bitcoin:

{
  "name": "btc",
  "url": "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd",
  "jsonPath": "bitcoin.usd",
  "displayFormat": "$%.0f",
  "icon": "btc",
  "color": "#F7931A",
  "interval": 300
}

Обмеження

• Максимум 8 джерел одночасно
• Максимальний розмір відповіді: 4 КБ — більші відповіді API будуть відхилені
• HTTPS: підтримується, але без перевірки сертифіката (для довільних сторонніх API)
• Циклічне опитування: одне джерело перевіряється за цикл, щоб уникнути блокування
• Джерела зберігаються у флеш-пам'яті та відновлюються при завантаженні
• Також можна налаштувати через веб-інтерфейс за адресою http://[IP]/datafetcher

Ротація (Застосунки + Ефекти)

Єдина конфігурація ротації: порядок застосунків і ефектів разом із тривалістю та кольором кожного елемента. Замінює старі endpoint'и /api/reorder та /api/playlist.

HTTP URL	Тіло запиту	HTTP-метод	Опис
http://[IP]/api/rotation	-	GET	Отримати поточну конфігурацію ротації
http://[IP]/api/rotation	JSON	POST	Зберегти конфігурацію ротації

Примітка: Лише HTTP, без MQTT-топіків.

Тіло та відповідь використовують ключ items з масивом елементів ротації (застосунки та ефекти, кожен із необов'язковими тривалістю та кольором).

Приклад:

{
  "items": [
    {"type": "app", "name": "Time", "duration": 7},
    {"type": "effect", "name": "Plasma", "duration": 10, "color": "#FF00FF"}
  ]
}

Будильники та нагадування

Керування будильниками та нагадуваннями. Працює без WiFi завдяки RTC.

MQTT-топік	HTTP URL	Тіло запиту	HTTP-метод	Опис
N/A	http://[IP]/api/alarms	-	GET	Список усіх будильників і стан спрацювання
[PREFIX]/alarm/add	http://[IP]/api/alarms	JSON	POST	Додати новий будильник (або дію snooze/dismiss)
N/A	http://[IP]/api/alarms	JSON	PUT	Оновити наявний будильник (за id)
N/A	http://[IP]/api/alarms?id=X	-	DELETE	Видалити будильник із заданим id
[PREFIX]/alarm/snooze	http://[IP]/api/alarms	{"action":"snooze","minutes":N}	POST	Відкласти будильник, що дзвонить
[PREFIX]/alarm/dismiss	http://[IP]/api/alarms	{"action":"dismiss"}	POST	Вимкнути будильник, що дзвонить

Властивості JSON будильника

Ключ	Тип	Опис	За замовчуванням
id	integer	Ідентифікатор будильника (лише для PUT).	0
hour	integer	Година (0–23).	0
minute	integer	Хвилина (0–59).	0
days	integer	Бітова маска активних днів тижня. 0x7F = щодня.	0x7F (127)
enabled	boolean	Чи будильник активний.	true
oneTime	boolean	Одноразовий будильник (вимикається після спрацювання).	false
snoozeMinutes	integer	Хвилини відкладання (snooze).	5
label	string	Необов'язкова текстова мітка.	""
melody	string	Звук для відтворення: ім'я файлу RTTTL з папки MELODIES або повний RTTTL-рядок.	""

Примітка: Для snooze через MQTT на [PREFIX]/alarm/snooze можна надіслати {"minutes":N}; якщо пропущено, використовується snoozeMinutes будильника. Відповідь GET також містить поле ringing (boolean), яке вказує, чи зараз дзвонить будильник.

Приклад будильника:

{
  "hour": 7,
  "minute": 30,
  "days": 127,
  "enabled": true,
  "oneTime": false,
  "snoozeMinutes": 9,
  "label": "Прокидатися",
  "melody": "alarm"
}

Погода

Налаштування та отримання даних зовнішньої погоди. Джерелом може бути WeatherAPI.com (через apiKey) АБО ваш власний сервер (через serverUrl). Якщо serverUrl не порожній, годинник опитує цей URL замість WeatherAPI, і він має повертати формат current.json від WeatherAPI (наприклад, https://clima.xe1e.net/api/svitrix) з необов'язковими додатковими полями solar_radiation, precip_event_mm, rain_rate_mm. Погодні застосунки (зовнішня температура, вологість, тиск, якість повітря, UV, вітер, радіація, опади) додаються та впорядковуються на вкладці «Застосунки» (ротація).

HTTP URL	Тіло запиту	HTTP-метод	Опис
http://[IP]/api/weather	-	GET	Отримати конфігурацію погоди
http://[IP]/api/weather	JSON	POST	Оновити конфігурацію погоди
http://[IP]/api/weather/fetch	-	POST	Примусово оновити дані негайно
http://[IP]/api/weather/data	-	GET	Отримати поточні дані погоди

Примітка: Лише HTTP, без MQTT-топіків.

JSON конфігурації погоди

Ключ	Тип	Опис
apiKey	string	API-ключ постачальника погоди.
serverUrl	string	Власний сервер. Якщо не порожній, годинник опитує цей URL замість WeatherAPI. Має повертати формат current.json від WeatherAPI (+ необов'язкові додаткові поля solar_radiation, precip_event_mm, rain_rate_mm). Порожній = використовувати WeatherAPI.com.
locationType	integer	Тип локації (0 = місто, 1 = координати, 2 = ID станції).
city	string	Назва міста.
latitude	float	Широта.
longitude	float	Довгота.
stationId	string	ID метеостанції.
updateInterval	integer	Інтервал оновлення у хвилинах (1–120; варіанти в UI 1/2/5/10/15/30/60). З власним сервером тримайте його низьким (1–2), щоб відстежувати швидкозмінні значення.
showOutdoorTemp	boolean	Показувати застосунок зовнішньої температури.
showOutdoorHumidity	boolean	Показувати застосунок зовнішньої вологості.
showPressure	boolean	Показувати застосунок тиску.
showAirQuality	boolean	Показувати застосунок якості повітря (AQI).
showIndoorTemp	boolean	Показувати застосунок внутрішньої температури.
showIndoorHumidity	boolean	Показувати застосунок внутрішньої вологості.
showUV	boolean	Показувати застосунок UV-індексу.
outdoorTempColor	integer	Колір зовнішньої температури (ціле RGB).
outdoorHumColor	integer	Колір зовнішньої вологості (ціле RGB).
pressureColor	integer	Колір тиску (ціле RGB).
aqiColor	integer	Колір AQI (ціле RGB).
uvColor	integer	Колір UV-індексу (ціле RGB).
aqiAutoColor	boolean	Автоматичний колір AQI за рівнем.
aqiShowComponents	boolean	Після ICA:N по черзі показувати забруднювачі (PM2.5, O3, NO2…), що перевищують рівень 4, кожен у кольорі свого рівня. Увімкнено за замовчуванням.
aqiComponentSecs	integer	Скільки секунд показується кожен забруднювач у ротації (2–10, за замовчуванням 3).
uvAutoColor	boolean	Автоматичний колір UV-індексу за рівнем.
outdoorTempDuration	integer	Тривалість застосунку зовнішньої температури (секунди).
outdoorHumDuration	integer	Тривалість застосунку зовнішньої вологості (секунди).
pressureDuration	integer	Тривалість застосунку тиску (секунди).
aqiDuration	integer	Тривалість застосунку AQI (секунди).
uvDuration	integer	Тривалість застосунку UV-індексу (секунди).
showWind	boolean	Показувати застосунок вітру.
windColor	integer	Колір вітру (ціле RGB).
windDuration	integer	Тривалість застосунку вітру (секунди).
windShowGust	boolean	Додавати порив R<n> до рядка вітру, напр. W 5 R4.
showRadiation	boolean	Показувати застосунок сонячної радіації (Вт/м²).
radColor	integer	Колір радіації (ціле RGB).
radAutoColor	boolean	Автоматичний колір радіації за інтенсивністю (як UV).
radDuration	integer	Тривалість застосунку радіації (секунди).
showPrecip	boolean	Показувати застосунок опадів.
precipColor	integer	Колір опадів (ціле RGB).
precipDuration	integer	Тривалість застосунку опадів (секунди).
precipShowRate	boolean	Додавати інтенсивність дощу <n>/h до рядка, напр. 0.0mm 0.0/h.

GET /api/weather/data повертає поточні дані: valid, outdoorTemp, outdoorHumidity, pressure, aqi, uv, condition, conditionCode, windSpeed (км/год), windDeg, windGust (км/год), windDir, solarRadiation (Вт/м²), precipToday (мм), precipEvent (мм поточної події), rainRate (мм/год), lastUpdate (мілісекунди), failStreak (кількість послідовних невдалих мережевих запитів; 0 = останній успішний).

Самовідновлення: якщо запит застрягає, годинник спершу повторно під'єднується до WiFi (м'яке відновлення, після кількох поспіль невдач) і лише якщо все одно провів max(15 хв, 5× інтервал) без успішного запиту, з підключеним WiFi, він перезавантажується як останній засіб (скидає мережевий стек/пам'ять). Він тримає WiFi без енергозбереження (годинник живиться від USB), щоб з'єднання не «застаріло». У звичайній роботі він ніколи не перезавантажується; failStreak та /api/nvs дозволяють стежити за його станом.

Нічний режим: поки активний нічний режим, годинник призупиняє всі запити (погода + власні джерела) — показується лише годинник — і заморожує таймер самовідновлення (він не перезавантажується вночі). Коли нічне вікно завершується, він повторно під'єднується до WiFi і одразу виконує запит, тож застосунки погоди знову з'являються зі свіжими даними.

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

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

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

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

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

Ключ	Тип	Опис	Діапазон значень	За замовч.
ATIME	number	Тривалість відображення застосунку у секундах.	Додатне ціле число	7
TEFF	number	Вибір ефекту переходу між застосунками (повний список у /api/transitions).	0–13	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
NILAYOUT	string	Розташування іконки для вбудованих застосунків (Температура, Вологість, Батарея).	"left", "right", "none"	"left"
NMODE	boolean	Увімкнути нічний режим — затемнення за розкладом з перевизначенням кольору.	true/false	false
NSTART	integer	Час початку нічного режиму в хвилинах від опівночі (напр. 1260 = 21:00).	0–1439	1260
NEND	integer	Час закінчення нічного режиму в хвилинах від опівночі (напр. 360 = 06:00).	0–1439	360
NBRI	integer	Яскравість під час нічного режиму.	0–255	5
NCOL	integer	Колір тексту під час нічного режиму (hex як число, напр. 16711680 = червоний).	RGB число	16711680
NBTRANS	boolean	Блокувати автоперехід під час нічного режиму (тільки ручна навігація).	true/false	true
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
BEFF	integer	Індекс фонового ефекту — відтворюється за кожним застосунком і сповіщенням. Використовуйте -1, щоб вимкнути.	-1 або дійсний індекс ефекту (див. /api/effects)	-1
GAMMA	number	Гамма-корекція дисплея. 1.9 = нейтрально; вище = більше контрасту / темніші середні тони; нижче = пласкіше.	Додатне число з рухомою комою	1.9

Значення кольору: Може бути 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

Налаштування WiFi

Перегляд або зміна мереж WiFi (до 3) через API. eraseWifi очищує лише облікові дані WiFi і перезавантажує (вужче, ніж erase).

HTTP URL	Тіло запиту	HTTP-метод
http://[IP]/api/wifi	-	GET
http://[IP]/api/wifi	{"networks":[{"ssid":"МояМережа","password":"..."}]}	POST
http://[IP]/api/eraseWifi	-	POST

Резервне копіювання та відновлення налаштувань

Експортуйте всі налаштування як JSON або відновіть їх із резервної копії. Див. також Резервне копіювання та відновлення.

HTTP URL	Тіло запиту	HTTP-метод
http://[IP]/api/settings/export	-	GET
http://[IP]/api/settings/import	JSON (попередня копія)	POST

Система та файли

Системні endpoint'и та прямий доступ до файлової системи LittleFS (іконки, мелодії, користувацькі застосунки, резервні копії).

Версія прошивки

HTTP URL	Тіло запиту	HTTP-метод
http://[IP]/version	-	GET

Діагностика NVS (розділ налаштувань)

Використання розділу NVS (20 КБ), де зберігаються всі налаштування. Якщо він заповнюється, NVS псується і налаштування втрачаються (годинник переходить у режим точки доступу AP). Стежте, щоб usedPct залишався нижче ~85%.

HTTP URL	Тіло запиту	HTTP-метод	Опис
http://[IP]/api/nvs	-	GET	{used, free, total, namespaces, usedPct} (записи по 32 байти)

Застосування конфігурації мережі/брокера

Застосовує файл /DoNotTouch.json (статичний IP, MQTT-брокер, Home Assistant, NTP, авторизація) до системи "на льоту", без перезавантаження. Використовується SPA після зміни розширених налаштувань.

HTTP URL	Тіло запиту	HTTP-метод
http://[IP]/save	form-data	POST

Файловий менеджер (LittleFS)

Перегляд, завантаження, вивантаження та видалення файлів у сховищі (/ICONS/, /MELODIES/, /CUSTOMAPPS/, /PALETTES/). Це те, що використовує сторінка «Файли» в SPA.

HTTP URL	Тіло запиту	HTTP-метод	Опис
http://[IP]/list?dir=/ICONS	-	GET	Список каталогу (JSON: ім'я, тип, розмір)
http://[IP]/<шлях>	-	GET	Завантажити файл (напр. /ICONS/962.jpg)
http://[IP]/edit?filename=/<шлях>	multipart (поле data)	POST	Вивантажити або створити файл
http://[IP]/edit	path=/<шлях>	PUT	Створити каталог
http://[IP]/edit	path=/<шлях>	DELETE	Видалити файл

Примітка: відповіді з файлами можуть бути стиснені gzip (Content-Encoding: gzip); використовуйте клієнт, який розпаковує автоматично.