Ukraine Alarm (alerts.in.ua) smart home integration, free and open source

Unofficial connector: Ukrainian air raid alerts by oblast, raion or hromada (alerts.in.ua).

• Published by LM1LC3N7
• Devices
• Version 0.1.1
• Requires Gladys >=5.1.0
• ★ 0

View on GitHubAll integrations

Ukrainian air raid alerts in Gladys, by oblast, raion, hromada or city, read from the official API of alerts.in.ua.

Unofficial connector, not affiliated with alerts.in.ua. Never tested with a real token: written from the official API documentation; please report what you see.

This is NOT a safety system. The data comes with delays (technical or human) and the integration reads it every 30 s by default. Rely on the official channels: sirens, the Air Alert app, the local authorities.

What you get

• One device per location you watch, with one feature, Alert level:
  • 0 no alert;
  • 1 alert in part of the location (some of its raions or hromadas, not the whole of it);
  • 2 alert of yellow level;
  • 3 alert of red level.
• Two scene triggers:
  • Air raid alert started: an alert of yellow or red level started on the whole location, or a yellow alert turned red. Filters: the location (empty: any) and the level (empty: any). Information passed to the scene: the location name, its UID, the level (yellow or red), whether a yellow alert turned red, and whether the change was seen late (see below).
  • Air raid alert ended: the alert of yellow or red level on the whole location ended (level 0 or 1). Information: the location name, its UID, the duration in minutes (empty when the start was not seen) and "seen late".
• The level is also a normal device state: a scene can test it (for example "Alert level of Kyiv is 2 or more").

A level 1 (alert in part of the location) fires no trigger: watch the smallest location that holds your home (its hromada or its raion) to know whether the alert concerns it.

Step 1: get a token

Request a free personal token with the form of alerts.in.ua: https://alerts.in.ua/api-request. They send it by e-mail. The token is yours: alerts.in.ua links every request made with it to you.

Step 2: configure

In Gladys, Integrations > Ukraine Alarm > Configuration:

1. alerts.in.ua API token: paste the token. Kept by Gladys in its database, never shown again, sent only to alerts.in.ua (in the Authorization header of each request, over HTTPS).
2. Locations to watch (UIDs): the UIDs of the locations, separated by commas, 20 at most. Examples: 31 Kyiv city, 14 Kyiv Oblast, 1293 Kharkiv city, 564 Zaporizhzhia city.
   • The button Find a location gives the UID of an oblast, a raion or a city from part of its name, in Ukrainian or Latin letters (Kharkiv, Львів). It sends no request.
   • A hromada: take its UID from the full list of the locations linked by the API documentation. Its device is named "Alerts: Location <UID>": rename it in Gladys.
3. Read interval: 30 s by default, 20 s to 600 s. One request reads every location at once.
4. Save, then Test the connection: it reads alerts.in.ua and shows the level of each location.
5. In the Discover tab, add the devices you want. Nothing is read before a device is added.

How it reads

• One GET request per interval, whatever the number of locations, with If-Modified-Since (alerts.in.ua answers "not modified" when nothing changed). One request at a time.
• alerts.in.ua allows 8 to 10 requests a minute per Internet address (12 is the hard limit, then the address and the token are blocked). Other applications behind the same address count too: this is why 20 s is the fastest interval.
• The pace survives a restart: the time of each attempt is written to the integration folder before the request, and the next read waits for the end of the interval.
• The Test the connection button sends no new request less than 20 s after the last one: it then shows the last answer.

When something goes wrong

What happens	What the integration does
The token is refused (HTTP 401)	No automatic read any more. Saving a new token, or the test button reading with success, starts the reads again. The status says so.
HTTP 403 (your address is blocked, or the API is not served in your country)	Not a refusal of the token: reads paused 30 min, then 1 h, 2 h... up to 6 h.
Too many requests (HTTP 429)	Reads paused for the time alerts.in.ua asks (Retry-After), else 1 min doubling; between 1 min and 6 h.
Server error, timeout, network, an answer cut or unreadable	Not a refusal: retried after one interval, then the wait doubles each time, up to 15 min (30 s, 1 min, 2, 4, 8, then 15 min with the default interval).
No good read for 10 min	The status says the levels shown are not recent.
A UID without data	The status names it; its device gets no level.

The pauses and the refusal are kept in the integration folder (/data) and survive a restart. Of a refused token, only 8 bits of a salted hash are kept, never the token. Two tokens share the same 8 bits once in 256: if a new token saved after a restart happens to match the refused one, click Test the connection once to start the reads.

Scene events after a restart or an outage

The last level of each location is kept for 2 hours. After a restart or an outage, the first read is compared with it: an alert that started (or ended) meanwhile fires its trigger with "seen late" set. A level older than 2 hours is not compared: no trigger for a change that may be hours old. The new levels are written to the integration folder before the triggers fire; if that folder cannot be written, a trigger may fire a second time after a restart (at least once; not lost, unless the integration stops or the token changes at that very moment).

Limits

• The level comes from the compact "IoT" status of alerts.in.ua (v2, with the red and yellow levels). An active alert given without a level (A) counts as red.
• Whether the status of a hromada also shows an alert declared for its whole oblast is up to alerts.in.ua (not checked without a real token).
• Only air raid alerts: the other threats of alerts.in.ua (artillery, urban fights, chemical, nuclear) and the details of each threat are not read in this version.
• The names of the raions are in Ukrainian only.

Privacy

The integration sends nothing but the token and its own User-Agent (gladys-ukraine-alarm/<version>) to api.alerts.in.ua. It never follows a redirect. The token is never written to the logs, the status, nor the integration folder.

Source

Data: alerts.in.ua, volunteer project; API: https://devs.alerts.in.ua. Source code: Apache-2.0, https://github.com/LM1LC3N7/gladys-ukraine-alarm.

Configuration settings

These are the settings Ukraine Alarm (alerts.in.ua) asks for in its configuration screen in Gladys.

Setting	Type	Required	Description
Ukrainian air raid alerts in Gladys	section	No	Unofficial connector, not affiliated with alerts.in.ua. It reads the official API of alerts.in.ua with your own free token (request it with the form linked below) and gives one device per location you watch (oblast, raion, hromada or city, by its UID) with its alert level: 0 no alert, 1 alert in part of it, 2 yellow level, 3 red level. The scene triggers "Alert started" and "Alert ended" fire on each change. One request reads every location, every 30 s by default. This is NOT a safety system: delays happen, rely on the official channels (sirens, the Air Alert app). Never tested with a real token.
alerts.in.ua API token	secret	Yes	The free personal token alerts.in.ua sends you by e-mail. Kept by Gladys in its database, never shown again, sent only to alerts.in.ua.
Locations to watch (UIDs)	string	Yes	The UIDs of the locations, separated by commas (20 at most). Kyiv city is 31, Kyiv Oblast 14, Kharkiv city 1293. The button "Find a location" below gives the UID of an oblast, a raion or a city; a hromada: see the full list linked above.
Read interval (seconds)	number	No	One request per interval reads every location. alerts.in.ua allows 8 to 10 requests a minute per Internet address, other applications included: 20 s at the fastest.

How to install Ukraine Alarm (alerts.in.ua) in Gladys

1. In Gladys, open Integrations: Ukraine Alarm (alerts.in.ua) appears in the catalog, next to the native integrations, with a community badge.
2. Click Install. Gladys pulls the Docker image (ghcr.io/lm1lc3n7/gladys-ukraine-alarm:0.1.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
3. Open the Configuration screen of the integration, fill in the settings, and save.
4. You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-ukraine-alarm.

Ukraine Alarm (alerts.in.ua) requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations

Ukraine Alarm (alerts.in.ua) is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by LM1LC3N7, not by the Gladys core team.

• Browse all integrations, native and community
• Build and publish your own external integration
• Source code on GitHub — source of this documentation

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂