[Custom Integration] Air Threat Monitor — air alerts, nearby threats and radar for Ukraine

[serg-ill]

English

Hi everyone!

I’d like to share Air Threat Monitor , a custom Home Assistant integration created for users in Ukraine.

Honestly, this integration would never have existed if Ukraine had a normal neighbour instead of Russia. Unfortunately, air alerts, drones and missiles have become part of our daily reality. I wanted to make the most important information visible directly in Home Assistant, so my family could understand the situation quickly and react without opening several different applications.

Air Threat Monitor displays:

• Local air-alert status for the selected district or oblast.
• Alert start time and live duration.
• Nearby reported aerial threats.
• Distance, bearing, heading and approach direction.
• Threat categories such as UAVs, FPV drones, reconnaissance drones, missiles and guided aerial bombs.
• An animated radar with north-up or optional device-compass orientation.
• Total and per-category target statistics.
• Dynamic positioning using the current device GPS or a Home Assistant person /device_tracker .
• Automatic location labels for dynamic positions.
• Red/green signal styling and an alternative style that follows the Home Assistant light or dark theme.
• A graphical card editor with safe and alert demonstration modes.
  
  

The integration is configured entirely through the Home Assistant interface. The radar card appears in the standard card picker, so no manual YAML is required for normal use.

Exact configured coordinates remain inside Home Assistant and are not sent to the data provider.

Installation

The integration is currently available as a custom HACS repository:

1. Open HACS .
2. Open the three-dot menu and select Custom repositories .
3. Add https://github.com/serg-ill/air-threat-monitor .
4. Select Integration as the category.
5. Install Air Threat Monitor and restart Home Assistant.
6. Open Settings → Devices & services → Add integration .
7. Search for Air Threat Monitor .

GitHub repository:

GitHub - serg-ill/air-threat-monitor: Air threat and air alert monitoring integration for Home Assistant · GitHub

A submission to the default HACS catalog is planned. Feedback, testing and bug reports are very welcome.

Threat and alert data is provided by NEPTUN. This is an independent community project and is not affiliated with or endorsed by NEPTUN.

Important: This integration is for informational use only. It is not an official warning system and must never be the only source of safety information. Always follow official air-alert signals and instructions from Ukrainian authorities.

---

Українська

Привіт усім!

Хочу поділитися Air Threat Monitor — користувацькою інтеграцією Home Assistant для користувачів в Україні.

Відверто кажучи, ця інтеграція ніколи б не з’явилася, якби Україна мала нормального сусіда замість Росії. На жаль, повітряні тривоги, дрони та ракети стали частиною нашої щоденної реальності. Мені хотілося бачити найважливішу інформацію безпосередньо в Home Assistant, щоб моя сім’я могла швидко оцінити ситуацію та відреагувати без відкривання кількох різних застосунків.

Air Threat Monitor показує:

• Стан повітряної тривоги для вибраного району або області.
• Час початку та поточну тривалість тривоги.
• Найближчі зафіксовані повітряні цілі.
• Відстань, напрямок, курс і характер руху цілі.
• Категорії цілей: БпЛА, FPV-дрони, розвідники, ракети та КАБ.
• Анімований радар із північчю вгорі або орієнтацією за компасом пристрою.
• Загальну кількість цілей і статистику за категоріями.
• Динамічну позицію через GPS поточного пристрою або сутність person /device_tracker .
• Автоматичне визначення назви поточного населеного пункту.
• Червоно-зелене сигнальне оформлення та нейтральний стиль відповідно до теми Home Assistant.
• Графічний редактор картки з безпечним демонстраційним режимом.

Інтеграція повністю налаштовується через інтерфейс Home Assistant. Картка автоматично з’являється у стандартному каталозі карток, тому для звичайного використання вручну писати YAML не потрібно.

Точні координати залишаються всередині Home Assistant і не передаються постачальнику даних.

Інтеграцію вже можна встановити через HACS як користувацький репозиторій: посилання наведені вище

Надалі планується подання до загального каталогу HACS. Буду вдячний за тестування, відгуки та повідомлення про помилки.

Дані про загрози та повітряні тривоги надає [NEPTUN]. Air Threat Monitor - це незалежний спільнотний проєкт, який не є офіційним продуктом NEPTUN і не підтримується ним.

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

[IOT7712]

…Putin dowloaded a copy and changed the geofence so it could run in their territory too…

Is it geofenced to keep the enemy away, for security?

Is it polling based, tying up valuable internet traffic bandwidth, for what are (deliberately) random events at unpredictable times? Does your radar display update continuously, or just during alert status times?

Is there garnularity in the data, where you give up sending (interceptible) location data as a trade-off from having to download the entire set of national/regional warnings?

Is the Neptun warning data freely available for all and sundry? Do you have to give out any identifying information to access it?

What if it drops out? Does your app catch up when connectivity returns or just drop out-of-date warnings?

Regardless of my or anybodies political views, I strongly feel for you, on high alert, nerves frayed, trying to stay on top of living a life as close to normal as possible while war rages around you. You do whatever you can do to survive - we all do. Keeping yourself, your families, loved ones, and friends updated doesn’t take away the risk, just removes fear of the unknown, which can make an enormous difference.

Does existence of this app reflect that NEPTUN is not adequate in the role expected and added resources could/should be directed there?

Could this be adapted for other war ravaged countries such as currently in the Middle East? Was your app written in mind that it could be translated and adapted easily?

[serg-ill]

Regarding Putin downloading a copy: open-source code cannot be protected by any meaningful geofence. But this integration would be of little use to him anyway, because it was built to help Ukrainians protect themselves from the threats his regime sends into our country.

Thank you for such thoughtful questions and for your words of support. I will try to answer everything point by point.

1. Is the integration limited to Ukraine?

Yes. The current version was created exclusively for Ukraine. It uses Ukrainian oblasts and districts, Ukrainian threat categories, and data provided by NEPTUN.

However, this is not a security geofence intended to keep the enemy out. The code is open source, so any geographic restriction could be changed in a fork. At the same time, the integration contains no classified or original military intelligence. It only visualizes information that NEPTUN already makes publicly available.

2. How often does it contact the service, and how much traffic does it use?

The integration currently uses polling and retrieves the latest threat and alert snapshots every 10 seconds. These are compact JSON responses without maps, video, or image downloads.

The radar animation is rendered locally in the browser and creates no additional network traffic. Data is updated continuously, even when there is no alert in the selected district, because a target may be reported before a local air alert is officially activated.

3. Are the user’s coordinates transmitted anywhere?

They are not sent to NEPTUN.

The integration downloads the current nationwide threat and alert dataset, then performs the following operations locally inside Home Assistant:

• identifies the relevant oblast and district;
• calculates the distance to each target;
• determines bearing, heading, and whether the target is approaching;
• selects which targets should appear on the card.

Dynamic coordinates from a phone, person , or device_tracker entity are also processed inside Home Assistant. NEPTUN only receives a normal HTTP request from the Home Assistant server, including its IP address and User-Agent, as any web service would.

4. Does NEPTUN require registration?

No. The integration uses documented public API endpoints. It does not require an account, phone number, email address, API key, or other identifying information.

We also received explicit permission from the NEPTUN team to use their API. The data source is credited on the card, in the documentation, and in the repository.

5. What happens if the connection drops?

If NEPTUN or the internet connection is temporarily unavailable, the card explicitly reports that current data is unavailable instead of presenting old information as current.

Once connectivity returns, the integration downloads the complete current snapshot during the next polling cycle. It cannot reconstruct every event that happened while the connection was unavailable, but it immediately catches up with the present situation.

6. Is this an actual radar?

No. It is a visual representation of publicly reported information. It does not detect targets itself, does not see them in real time, and must never be used as the only source of safety information.

The data may be incomplete, approximate, or delayed. Official air alert signals and instructions from Ukrainian authorities always take priority.

7. Does the existence of this integration suggest that NEPTUN is inadequate?

No, quite the opposite. Without NEPTUN’s work, this integration would not exist at all.

NEPTUN collects and publishes the data. My integration brings that information into Home Assistant and adds local calculations, entities, a dashboard card, and the ability to use the information in home automations. It complements NEPTUN rather than replacing or criticizing it.

8. Could it be adapted for other countries?

Technically, yes, but it would require much more than changing the translation or coordinates. The current version works only for Ukraine and depends on the NEPTUN API structure, Ukraine’s administrative geography, and the threat categories used here.

Another country would require a reliable and legally usable data source, its own regional boundary data, a new provider adapter, and appropriate local terminology. The technical foundation could be reused, but it would effectively become a separate integration.

Finally, thank you for the kind words. Reducing uncertainty was one of the main reasons I created this card. It cannot remove the danger, but it can help people understand the situation faster and make a decision. Unfortunately, this has become part of everyday life for us.

Thank you for such thoughtful questions and for your words of support. I will try to answer everything point by point.

[IOT7712]

Thank you for your deep and detailed reply. It indicates you have carefully considered issues that could affect security and operation.

Geofence was a bit of a distraction, it being used to ask if your app was only able to be run within the country, then I realised that family displaced elsewhere may benefit considerably from it, even if trapped behind enemy lines, to keep up with what was happening back home. Conversely, your enemy knowing how much you know about their attacks, with what precision and warning, can modify their strategy as well. i’m sure the military on both sides have far greater detail in their monitoring than you have access to with NEPTUN.

While this is specifically HomeAssistant related, do versions that similary access the critically important NEPTUN data and aggregate ancillary data exist for IOS and Android too? This would reach a greater portion of the population that may not have HomeAssistant. If not, an opportunity to contribute further awaits you!

My concern with your 10 second polling loop may cause excessive load on the NEPTUN server needs to be balanced by how frequently the outgoing data is updated, and that each second counts if you need to take shelter from incoming threats. If there are decentralised servers, then that could distribute the session load, and your code could be easily altered to accommodate. Alternate forms of push data transmission such as shortwave, or FM Radio sidebands commonly used for road traffic updates (TMC/RDS) could be used where the internet access is sporadic.

Like many other advances in technology used in novel ways, I’m sure the rest of the world is keenly watching the developments and rapid advancement by Ukraine, and that it will help improve our lives in ways not even envisaged twelve years ago. Having an effective civilian warning system is one of these. I wish you the best in your endeavours and a peaceful night.

[serg-ill]

Thank you for continuing the discussion and for raising these thoughtful points.

Home Assistant and its user do not have to be physically located in Ukraine. The integration can run from anywhere in the world while monitoring a selected location inside Ukraine. It can therefore be useful to people who have been displaced but still want to follow what is happening back home. The geographic limitation applies only to the territory for which NEPTUN provides threat data and district and oblast boundaries.

Regarding the possibility of this information being used by the enemy, the integration does not expose anything beyond what NEPTUN already publishes publicly. It only calculates distance and direction from the location selected by the user. I do not have access to any additional military information. I think you are correct that the military systems used by both sides are vastly more detailed than the public information available to civilians.

I do not currently plan to create a separate mobile application. NEPTUN and Fluger already provide Android and iOS applications that display aerial threats, their types, movement directions, and other useful information. My goal was not to create another similar application, but to bring these capabilities into Home Assistant so the data could be used on home dashboards, in automations, voice announcements, and personalized notifications.

Polling every 10 seconds is not considered excessive in this case. The integration retrieves two small JSON datasets without downloading maps, images, or video. The radar animation runs entirely locally and generates no additional requests.

Before publishing the integration, I contacted the NEPTUN team and received permission to use their public API. The current polling interval does not conflict with their usage terms or the permission I received.

That said, I agree that server load should be monitored if the number of users grows significantly. If the NEPTUN team asks me to change the interval or switch to a streaming method, I will certainly do so.

Transmitting warnings through radio, RDS, or other channels that do not depend on internet connectivity is a very interesting and important idea. However, my integration does not generate its own data. It depends on NEPTUN and an internet connection. Such backup communication channels would be better implemented by the data provider or as part of an official warning system, while Home Assistant could then receive and display them.

Thank you again for the thoughtful feedback and your kind wishes. I hope that one day Ukraine will simply no longer need an integration like this. Until then, it helps reduce uncertainty and allows people to react to danger more quickly.