💥 Aerial Danger для Home Assistant

Українською | English

Note

Інтеграція Home Assistant для виявлення повітряних загроз, що стосуються вибраних регіонів і місцевостей України.

Про інтеграцію

Aerial Danger аналізує повідомлення про повітряні загрози та визначає, чи стосуються вони вибраних регіонів або місцевостей.

Інтеграція виявляє БРСД¹, РСЗВ², КАБ³, балістичні й крилаті ракети, дрони та невстановлені повітряні загрози.

Aerial Danger не завантажує повідомлення самостійно. Інтеграція аналізує текстовий стан вибраних сутностей Home Assistant. Наприклад, такі сутності можна створити з публічних Telegram-каналів за допомогою інтеграції Scrape.

Caution

Інтеграція може помилятися, пропускати повідомлення або виявляти їх із запізненням.

Не використовуйте її як єдине чи офіційне джерело сповіщень.

Завжди стежте за офіційними сповіщеннями та виконуйте їхні вказівки. Під час повітряної тривоги негайно прямуйте до найближчого укриття та залишайтеся там до офіційного відбою.

Інтеграція надається «як є». Автор не гарантує точність, повноту чи своєчасність даних і не несе відповідальності за безпеку користувачів, ухвалені рішення чи наслідки використання інтеграції.

Підтримати проєкт

Ваша підтримка допомагає розвивати цей та інші українські проєкти для Home Assistant.

• 💖 GitHub Sponsors
• ☕️ Buy Me A Coffee
• Bitcoin: bc1q7lfx6de8jrqt8mcds974l6nrsguhd6u30c6sg8
• Ethereum: 0x6aF39C917359897ae6969Ad682C14110afe1a0a1

Встановлення

Найпростіший спосіб встановити інтеграцію — через HACS:

Якщо кнопка не працює, додайте репозиторій вручну

1. Відкрийте HACS → Інтеграції.
2. Відкрийте меню ⋮ → Користувацькі репозиторії.
3. Вставте https://github.com/denysdovhan/ha-aerial-danger.
4. Виберіть категорію Integration і натисніть Add.
5. Знайдіть Aerial Danger, встановіть інтеграцію та перезапустіть Home Assistant.

Налаштування джерел повідомлень

Для роботи Aerial Danger потрібне щонайменше одне джерело повідомлень з актуальним текстом повідомлення про загрозу.

Інтеграція підтримує сутності доменів sensor, text та input_text. Вона аналізує лише стан сутності, тому він має містити текст самого повідомлення.

Warning

Користувачі самостійно обирають джерела повідомлень. Інтеграція не перевіряє достовірність або повноту даних і не гарантує своєчасність сповіщень.

Як джерела повідомлень можна використовувати публічні моніторингові Telegram-канали, наприклад:

Канал	Адреса
Повітряні Сили ЗСУ	https://telegram.me/s/kpszsu
War Monitor	https://telegram.me/s/war_monitor
Aeris Rimor	https://telegram.me/s/AerisRimor
Оперативний інформ	https://telegram.me/s/operinform
Kyiv Air Defence (лише Київ)	https://telegram.me/s/kyiv_airdef

Читати повідомлення з Telegram-каналів можна за допомогою інтеграції Scrape.

Створіть Scrape-сенсор для Telegram-каналу

Створіть окремий запис інтеграції Scrape для кожного потрібного каналу:

Якщо кнопка не працює, налаштуйте запис вручну

1. Відкрийте Налаштування → Пристрої та служби → Додати інтеграцію.
2. Виберіть Scrape.
3. Вкажіть URL каналу у форматі https://telegram.me/s/CHANNEL.

Для каналу Повітряних сил ЗСУ заповніть основні параметри так:

Параметр	Значення
Ресурс	https://telegram.me/s/kpszsu
Метод	GET

На наступному кроці додайте сенсор:

Параметр	Значення
Назва	Повітряні Сили ЗСУ Telegram
CSS-селектор	.js-widget_message_wrap:last-child .js-message_text
Додаткові налаштування → Шаблон значення	{{ value | trim | truncate(255, end='', leeway=0) }}

Шаблон прибирає зайві пробіли та обмежує стан сенсора до 255 символів — максимальної довжини стану сутності Home Assistant.

Повторіть ці кроки для кожного потрібного каналу.

Оновлюйте дані створених сенсорів частіше

Scrape за замовчуванням опитує ресурс кожні 600 секунд (10 хвилин). Для сповіщень про повітряні загрози цей інтервал може бути надто довгим.

Імпортуйте готовий шаблон автоматизації, а потім виберіть створені Scrape-сенсори та інтервал оновлення — 5 або 10 секунд:

Якщо кнопка не працює, створіть автоматизацію вручну

alias: Оновлення Telegram-сенсорів кожні 5 секунд
description: Примусово оновлює джерела повідомлень для Aerial Danger
triggers:
  - trigger: time_pattern
    seconds: "/5"
conditions: []
actions:
  - action: homeassistant.update_entity
    target:
      entity_id:
        - sensor.telegram_kpszsu
mode: single
max_exceeded: silent

[!IMPORTANT] Замініть sensor.telegram_kpszsu на фактичний ідентифікатор свого сенсора. Для кількох каналів додайте всі сутності до списку entity_id.

[!TIP] Щоб зменшити кількість запитів, оновлюйте сенсори лише під час активної повітряної тривоги. У готовому шаблоні для цього можна вибрати сенсори безпеки Повітряна тривога з інтеграції Ukraine Alarm. Якщо створюєте автоматизацію вручну, додайте відповідну перевірку до блоку conditions.

Налаштування Aerial Danger

Додайте запис інтеграції Aerial Danger (Повітряна загроза):

Якщо кнопка не працює, налаштуйте інтеграцію вручну

1. Відкрийте Налаштування → Пристрої та служби → Додати інтеграцію.
2. Знайдіть і виберіть Aerial Danger.

1. Задайте назву запису. За замовчуванням використовується назва вашого дому.
2. Оберіть одне або кілька джерел повідомлень про загрози.
3. Оберіть готові регіони й місцевості або додайте власні регулярні вирази.

Налаштування регіонів та місцевостей

Регіони використовуються для виявлення балістичних і крилатих ракет та інших швидких загроз.

Місцевості потрібні для виявлення РСЗВ², КАБ³ і дронів. Вони також використовуються для всіх інших типів загроз.

Готові регіони та місцевості можна поєднувати з власними регулярними виразами Python у форматі списку YAML:

- (до|на) нас
- наш(у|ої) област(ь|і)?

Important

Оберіть щонайменше одне джерело повідомлень та щонайменше один регіон або одну місцевість.

Tip

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

Створіть кілька незалежних записів інтеграції, якщо для різних територій потрібні різні джерела або правила виявлення.

Створені сутності

Кожен запис інтеграції створює такі сутності:

Сенсори небезпек	Діагностичні сенсори

Як працюють ці сутності:

Тип	Сутності	Призначення
Сенсори небезпеки	БРСД1, РСЗВ2, КАБ3, балістика, крилаті ракети, дрони, невстановлена небезпека	Показують активну загрозу відповідного типу
Загальний сенсор	Небезпека	Увімкнений, доки активний хоча б один тип загрози
Діагностичні сенсори	Виявлене повідомлення, територія, тип загрози та джерело повідомлень	Показують дані останнього активного виявлення
Сутність подій	Виявлена небезпека	Реєструє кожне нове виявлення для автоматизацій

Усі бінарні сенсори мають стабільні атрибути:

Атрибут	Значення
matched_message	Повний текст повідомлення, у якому виявлено загрозу
matched_area	Частина повідомлення, що збіглася з вибраним регіоном або місцевістю
matched_danger	Частина повідомлення, що вказує на тип загрози
source_entity_id	Ідентифікатор сутності, з якої надійшло повідомлення

Для загрози БРСД¹ сенсор території показує Вся країна, оскільки такі повідомлення вважаються загальнонаціональними.

Автоматизації та сповіщення

Основне призначення інтеграції — запускати автоматизації та критичні сповіщення після виявлення загрози.

Критичні сповіщення

Імпортуйте готовий шаблон і створіть із нього автоматизацію критичних сповіщень:

Під час створення автоматизації:

1. Оберіть пристрій Повітряної загрози.
2. Оберіть мобільний пристрій із застосунком Home Assistant.
3. Задайте затримку між повторними сповіщеннями.

Шаблон надсилає критичні сповіщення на iOS та сповіщення з високим пріоритетом на Android. Текст містить виявлену територію та повне повідомлення про загрозу.

Вбудовані тригери

Щоб створити власну автоматизацію, додайте тригер, оберіть пристрій Aerial Danger, а потім потрібний тип виявлення:

• Виявлено будь-яку небезпеку
• Виявлено небезпеку БРСД
• Виявлено небезпеку РСЗВ
• Виявлено небезпеку КАБ
• Виявлено балістичну небезпеку
• Виявлено небезпеку крилатих ракет
• Виявлено небезпеку дронів
• Виявлено невстановлену небезпеку

Important

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

Як працює виявлення

1. Інтеграція реагує на зміну текстового стану кожної вибраної сутності та не опитує зовнішні джерела самостійно.
2. У кожному повідомленні інтеграція шукає ключові слова загроз і згадки вибраних регіонів або місцевостей.
3. Для кожного джерела зберігається перший знайдений тип небезпеки.
   1. БРСД¹ не потребує згадки місцевості чи регіону.
   2. РСЗВ², КАБ³ і дрони потребують назви місцевості.
   3. Решта типів загроз — або регіону, або місцевості.
4. Стан залишається активним, доки з того самого джерела не надійде нове повідомлення без загрози.
5. Джерела обробляються незалежно: повідомлення без загрози очищає стан лише свого джерела.
6. Кожне нове виявлення, зокрема повторне повідомлення того самого типу, оновлює сутність подій і діагностичні сенсори.

Часті питання

Чому інтеграція не отримує повідомлення самостійно?

Джерела для різних регіонів і місцевостей відрізняються. Ви самі обираєте потрібні джерела, а Aerial Danger лише аналізує текст їхніх станів.

Чому для аналізу не використовується штучний інтелект?

ШІ-моделі можуть пропустити небезпеку, помилково відреагувати на безпечне повідомлення або затримати результат. Регулярні вирази та ключові слова простіші, але працюють передбачувано й майже миттєво.

Як додати відсутній регіон або місцевість?

1. Створіть регулярний вираз, який враховує різні форми назви. Наприклад: київ, києва, києві, києвом.
2. Перевірте вираз у пісочниці для регулярних виразів.
3. Додайте вираз до налаштувань інтеграції.
4. Щоб поділитися ним з іншими користувачами, додайте його до переліку місцевостей і надішліть пул-реквест.

Вирішення проблем

• Джерело порожнє або має стан unavailable. Перевірте URL, CSS-селектор і доступність публічного каналу без авторизації.
• Загроза не виявляється. Переконайтеся, що вибрана сутність містить текст повідомлення, а повідомлення згадує налаштований регіон або місцевість. Для БРСД згадка території не потрібна.
• Оновлення каналів створює надто багато запитів. Виберіть у шаблоні інтервал 10 секунд, залиште лише потрібні канали або обмежте оновлення часом активної тривоги через Ukraine Alarm.
• Потрібно змінити джерела або території. Відкрийте Налаштування → Пристрої та служби → Aerial Danger → Налаштувати.

Видалення

Щоб видалити запис Aerial Danger:

1. Відкрийте Налаштування → Пристрої та служби → Aerial Danger.
2. Відкрийте меню ⋮ біля потрібного запису та виберіть Видалити.

Запис інтеграції видаляється разом зі своїми сутностями. Scrape-сенсори, автоматизації та файли інтеграції в HACS потрібно видалити окремо, якщо вони більше не потрібні.

Розробка

Хочете допомогти проєкту? Дякуємо! Перегляньте настанови для учасників.

Інші інтеграції

• ☁️ Check Weather — створює бінарний сенсор на основі прогнозу погоди на кілька наступних годин.
• 💨 ЛУН Місто Air — надає дані про якість повітря та довкілля зі станцій моніторингу ЛУН Місто.
• 🌦️ Український гідрометеорологічний центр — надає погодні, радіаційні й гідрологічні дані з meteo.gov.ua.
• ⚡️ Yasno Outages — надає графіки планових відключень електроенергії, сенсори та календарі від Yasno.

Ліцензія

Ліцензія MIT © Денис Довгань.

Footnotes

1. БРСД — балістична ракета середньої дальності (англ. IRBM — intermediate-range ballistic missile) ↩ ↩² ↩³ ↩⁴

2. РСЗВ — реактивна система залпового вогню (англ. MLRS — multiple launch rocket system) ↩ ↩² ↩³ ↩⁴

3. КАБ — керована авіаційна бомба (англ. GAB — guided aerial bomb) ↩ ↩² ↩³ ↩⁴