Skip to content

readme.uk.md

Latest commit

 

History

History
116 lines (83 loc) · 7.67 KB

readme.uk.md

File metadata and controls

116 lines (83 loc) · 7.67 KB

🟡 Svitlo.live

Інтеграція для Home Assistant, що показує наявність електропостачання у вашій області та черзі за даними сервісу svitlo.live.

Це нова версія (v2), що повністю перейшла на API наданий розробниками svitlo.live сайту замість парсингу HTML сайту svitlo.live.
Інтеграція оновлена з нуля: швидша, безпечніша та з мінімальним навантаженням на сервер.

⚙️ Основні можливості

  • ✅ Показує поточний статус світла (Є / Немає),
  • ✅ Визначає наступне вмикання та відключення електроенергії,
  • ✅ Показує час останнього оновлення розкладу,
  • ✅ Має вбудовану локалізацію (UA / EN),
  • ✅ Підтримує усі області України і типи черг / груп (1.1–6.2, 1–6, 1–12),
  • ✅ Може мати довільну кількість entry (областей/черг) в одному Home Assistant,
  • ✅ Усі entry оновлюються через один спільний запит до API, щоб зменшити навантаження,
  • ✅ Сенсори та бінарні сенсори зручні для автоматизацій та дашбордів.

🔄 Принцип роботи

🧩 Архітектура інтеграції

Інтеграція складається з двох шарів:

  1. SvitloApiHub (api_hub.py)
    Один спільний хаб для всіх entry.

    • Робить один HTTP-запит до проксісервера (Cloudflare Worker) з ключем API.
    • Зберігає отримані дані в кеш на 15 хв.
    • Гарантовано не викликає дублюючих запитів навіть при перезапуску Home Assistant.

  2. SvitloCoordinator (coordinator.py)
    Окремий координатор для кожного доданого регіону/черги.

    • Отримує розклад з хаба (api_hub), без повторного запиту в мережу.
    • Розумний вибір проксі: Автоматично перемикається між стандартним API (для більшості областей) та спеціалізованим ДТЕК-проксі (для Києва, Одеси та Дніпра) для забезпечення максимальної надійності.
    • Аналізує півгодинні слоти, формує стани (on/off).
    • Планує точне перемикання ентиті в момент відключення/включення без додаткових звернень до API.

🕒 Таймзона

  • API повертає розклад у локальному українському часі (Europe/Kyiv).
  • Інтеграція повністю коректно конвертує цей час у UTC для Home Assistant,
    тому незалежно від вашої часової зони все відображається точно.

🔐 Як захищено ключ API

Інтеграція не містить ключ API відкрито.

Для доступу до https://svitlo.live/api/asistant.php створено проміжний Cloudflare Worker, який:

  • зберігає ключ x-api-key у приватному середовищі Worker’а,
  • приймає безпечний запит без авторизації з інтеграції,
  • пересилає запит до svitlo.live і повертає JSON-відповідь.

Для регіонів ДТЕК (Київ, Одеса, Дніпро):

Інтеграція використовує окремий проксі сервер як джерело даних (dtek-api), який агрегуються безпосередньо з офіційних сайтів ДТЕК, гарантуючи актуальність графіків, навіть коли АРІ svitlo.live відстає від оновлень графіків.

🧠 Як часто оновлюються дані

  • Кожні 15 хвилин Home Assistant отримує нові дані з API.
  • Кеш API зберігається 15 хвилин.
  • Проміж оновлень інтеграція самостійно перемикає стани точно за розкладом (півгодинні інтервали).
    Наприклад, якщо відключення о 17:30, сенсор “Electricity” зміниться рівно о 17:30, навіть без запиту до API.

🧩 Створювані entity

Тип Назва Опис
🟢 Binary Sensor Electricity status Увімкнено / Вимкнено світло
📘 Sensor Electricity Текстовий статус: “Grid ON / OFF”
⏰ Sensor Next grid connection Час наступного вмикання (якщо зараз вимкнено)
⚠️ Sensor Next outage Час наступного відключення (якщо зараз увімкнено)
🔄 Sensor Schedule updated Час останнього опитування API
📅 Calendar calendar.svitlo_<region>_<queue> “💡 Electricity available”
⏳ Sensor Minutes to grid connection Показує кількість хвилин до наступного відновлення світла. Оновлюється кожні 30 секунд. Активний лише коли світло вимкнене.
⏱ Sensor Minutes to outage Показує кількість хвилин до наступного відключення. Оновлюється кожні 30 секунд. Активний лише коли світло увімкнене.

🌍 Підтримувані області

Усі області України (неокупованої частини), крім тимчасово недоступних (наразі Херсонська).
Для Чернівецької та Донецької — “Група N”, інші — “Черга N.M”.

🧰 Встановлення через HACS

  1. Відкрий HACS → Integrations → Custom repositories.
  2. Додай репозиторій: 
    https://github.com/chaichuk/svitlo_live
    тип — Integration.
  3. Встанови Svitlo.live і перезапусти Home Assistant.
  4. Додай інтеграцію через Settings → Devices & Services → + Add Integration → Svitlo.live.

Разом з інтеграцією автоматично встановлюється blueprint для щоденних сповіщень про графік електропостачання.

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

  1. Перейдіть в Налаштування → Автоматизації та сцени
  2. Натисніть Створити автоматизацію → Почати з blueprint
  3. Виберіть "Svitlo Live: ....."
  4. Заповність поля.

💡 Автор

  • github: @chaichuk
  • TG: @serhii_chaichuk