Integración domótica Aircraft overhead, gratuita y de código abierto

Unofficial connector: aircraft flying over your home, closest flight, altitude and heading.

• Publicado por LM1LC3N7
• Dispositivos
• Versión 0.1.1
• Requiere Gladys >=5.1.0
• ★ 0

Ver en GitHubTodas las integraciones

info

La documentación de esta integración la escribe su autor y, por ahora, solo está disponible en inglés.

Unofficial connector, not affiliated with adsb.lol, adsb.fi or the OpenSky Network. It shows in Gladys the aircraft flying over your house: their transponders broadcast their position (ADS-B), and networks of receivers run by volunteers collect it. You choose where the aircraft come from:

Source	What it is	Terms
adsb.lol (default)	A free, open community network. No account.	Open data under the ODbL 1.0. Data: adsb.lol (ODbL 1.0), https://adsb.lol
adsb.fi	Another community network. No account.	Personal, non-commercial use only. Data: adsb.fi, https://adsb.fi
Your own ADS-B receiver	A Raspberry Pi with readsb, dump1090-fa or tar1090 on your network. Nothing leaves your house.	Yours.
OpenSky Network (optional)	The research network. Only if OpenSky granted you its written agreement (see below).	Non-profit research and education. Data: The OpenSky Network, https://opensky-network.org

Never resell or republish the data.

What you get

Surface	Content
One device per located house	Aircraft over house: aircraft within the radius, distance of the closest one (km), its altitude (m), its flight (callsign)
Scene triggers	Aircraft overhead (within a distance, below an altitude, once per passage), aircraft emergency code (7500, 7600, 7700)
Scene action	Aircraft over a house: the count, the list, the closest flight with its registration, type, distance, altitude, speed, heading and where to look
Dashboard widget	Aircraft overhead: the count, the closest distance and altitude, the closest aircraft (flight and type, where to look, altitude, speed, heading arrow), or "clear sky"

Setup

1. Set the location of your house in Gladys (Settings → Houses), then install the integration and accept the location access.
2. Choose the source (adsb.lol by default: nothing else to do).
3. Open Discovery and add Aircraft over house. Nothing is read before a device exists.
4. Put the Aircraft overhead widget on a dashboard and pick the house.

Options: the radius (1 to 25 km, 10 by default), ignore the aircraft on the ground (on by default: an airport nearby is full of them), the altitude shown (geometric by default, or barometric), the language of the directions, the interval and the active hours.

Your own ADS-B receiver

Type the address of its map page or of its aircraft.json file:

• tar1090: http://192.168.1.30/tar1090/
• dump1090-fa / SkyAware: http://192.168.1.30:8080/ or http://192.168.1.30/skyaware/
• the file itself: http://192.168.1.30/tar1090/data/aircraft.json

When the address does not end with .json, /data/aircraft.json is added. A user name and password, when the page asks for one, go in the address (http://user:[email protected]/tar1090/). The file is read every 10 seconds for all your houses at once, and the distances are computed in Gladys. If the receiver keeps serving the same file for two minutes (its decoder stopped), the status says so.

OpenSky Network: only with its written agreement

OpenSky's terms of use reserve its API for non-profit research and education, and require a written agreement for any "operational" use in a live product, service or automated system, which a home automation box is. Choose this source only if OpenSky granted you that agreement. Anonymously, OpenSky grants 400 credits a day per internet address (a reading costs one); with an API client (on opensky-network.org, Account page, create an API client and copy its id and secret into the configuration), 4,000 a day.

Pace

Source	One reading	Minimum
adsb.lol, adsb.fi	every 30 s per house	15 s, two requests at least 1.1 s apart
Your receiver	every 10 s for all the houses	5 s
OpenSky, anonymous	every 7 min 15 s for one house	from the daily credits
OpenSky, account	every minute	a minute

A longer interval can be typed in the configuration (0 means automatic). Outside the active hours (the time of Gladys), nothing is read, and the values stay as they were. When adsb.lol or adsb.fi answers "too many requests" (429), the integration waits the time they announce (5 minutes otherwise). When they refuse a request (another 4xx answer, which their rules call a misuse), the readings stop until you save the configuration again. With OpenSky, the integration spends at most half of the anonymous credits (three quarters of an account's) on its readings, never more than 90 % of them in 24 hours, and waits when OpenSky says they are used up.

An airliner crosses a 10 km circle in about a minute. "Aircraft overhead" looks one minute ahead along each aircraft's track, so a reading every 30 seconds sees almost every passage.

Scenes

• Aircraft overhead: pick the house, the distance (1 to 25 km) and the altitude (500 m to 10,000 m, or any altitude). The scene runs once per aircraft and passage when an aircraft is, or will be within the minute, that close and that low; an aircraft seen again within 10 minutes is the same passage. {{triggerEvent.data.eta_seconds}} tells how many seconds before it is closest (0: now). Beyond the radius of the configuration, the radius applies. Variables: the flight {{triggerEvent.data.callsign}} (the transponder address when no callsign is received), {{triggerEvent.data.icao24}}, {{triggerEvent.data.registration}} and {{triggerEvent.data.aircraft_type}} (adsb.lol, adsb.fi, a receiver with its database), {{triggerEvent.data.country}} (OpenSky only), {{triggerEvent.data.distance}} (km), {{triggerEvent.data.altitude}} (m), {{triggerEvent.data.speed}} (km/h), {{triggerEvent.data.heading}}, {{triggerEvent.data.vertical_rate}}, where to look {{triggerEvent.data.direction}} and {{triggerEvent.data.bearing}}, {{triggerEvent.data.squawk}}.
• Aircraft emergency code: an aircraft within the radius transmits 7500 (unlawful interference), 7600 (radio failure) or 7700 (emergency); once per aircraft, code and passage. {{triggerEvent.data.emergency}} says what the code means.
• The first reading after a start announces nothing: it only records what is already in the sky. Changing the source does not announce the aircraft already seen again.

The action Aircraft over a house gives count, list (one line per aircraft) and the closest one: closest_callsign, closest_registration, closest_type, closest_distance, closest_altitude, closest_speed, closest_direction... The following actions of the scene find them in their variable list (written {{<step>.<action>.<key>}}, for instance {{0.0.count}} when this action is the first of the scene). A recent reading (within the interval, a minute at most) is reused; an action never fires a trigger.

Good to know

• The altitude is above sea level, not above your house. The barometric one can be off by a few hundred metres, and even negative near the ground.
• With a clear sky, the distance of the closest aircraft is the radius (a condition "closer than 2 km" stays false), and its altitude keeps the last value: combine a condition on the altitude with the count.
• Not every aircraft is visible: the coverage depends on the receivers near you, and some aircraft do not broadcast their position.

Troubleshooting

• No located house: set the location of the house in Gladys, then open Discovery again.
• adsb.lol (or adsb.fi) refused the request: look for an update of the integration (the API may have changed) or choose another source, then save the configuration.
• Your receiver is unreachable: open the address in a browser on the same network; it should show a JSON file with an aircraft list.
• OpenSky refused the API client: check the client id and secret, then save the configuration (nothing is sent until then).
• The Test the source button reads the sky over the first house now and shows the pace.

Privacy

With adsb.lol and adsb.fi, the integration sends only the position of the house rounded to 0.01 degree (about a kilometre) and a distance; with OpenSky, a box around the house rounded outward the same way. The exact position of the house never leaves Gladys, and it is never logged. With your receiver, nothing leaves your network. The OpenSky client secret only goes to OpenSky's sign-in server. Nothing is written on disk.

Parámetros de configuración

Estos son los parámetros que Aircraft overhead te pide en su pantalla de configuración en Gladys.

Parámetro	Tipo	Obligatorio	Descripción
Aircraft over your house	section	No	Unofficial connector, not affiliated with adsb.lol, adsb.fi or the OpenSky Network. One device per located house: the aircraft within the radius, the distance, altitude and flight of the closest one; an "aircraft overhead" scene trigger (within a distance, below an altitude, once per passage), an "emergency squawk" trigger, a scene action and a sky widget. The aircraft come from the source chosen below: adsb.lol by default (free, open data: Data: adsb.lol, ODbL 1.0), adsb.fi (personal, non-commercial use only: Data: adsb.fi, https://adsb.fi), your own ADS-B receiver on your network, or the OpenSky Network (only with OpenSky's written agreement). With adsb.lol and adsb.fi, only the position of the house rounded to about a kilometre leaves Gladys; with your receiver, nothing leaves your network.
Source of the aircraft	select	No	adsb.lol: free, no account, open data (ODbL 1.0), a reading every 30 s. adsb.fi: personal, non-commercial use only, a reading every 30 s. Your receiver: the aircraft.json of readsb, dump1090-fa or tar1090 on your network, a reading every 10 s. OpenSky: its terms require a written agreement for any use in an automated system such as Gladys; choose it only if OpenSky granted you one.
Radius around the house (km)	number	No	Only the aircraft closer than this count.
Ignore the aircraft on the ground	boolean	No	The aircraft taxiing or parked at a nearby airport, and its ground vehicles.
Altitude	select	No	Geometric (satellite positioning, closer to the real height above sea level) or barometric (the pressure altitude pilots fly by). The other one is used when the chosen one is missing.
Language of the directions	select	No	Where to look in the scenes and the scene action: N, NE, E... (English: W for west).
Your ADS-B receiver	section	No	Only with the source "My ADS-B receiver". The address of the map page of tar1090 or dump1090-fa (…/data/aircraft.json is added), or of the aircraft.json file itself. A private address is fine: the file is read on your network, and the distance to each house is computed in Gladys. A user name and password, when the page asks for one, go in the address: http://user:password@192.168.1.30/tar1090/.
Address of the receiver	string	No
OpenSky Network (with its written agreement only)	section	No	Only with the source "OpenSky Network", and only if OpenSky granted you a written agreement: its terms reserve the REST API for non-profit research and education and require one for any operational use in a live product or automated system, Gladys included. Anonymously, 400 credits a day per internet address (about one reading every 7 minutes for one house). With an API client (opensky-network.org, Account page: create an API client, copy its id and secret below), 4,000 a day, down to one reading a minute. The secret is only sent to OpenSky's sign-in server.
API client id	string	No
API client secret	secret	No
Pace and active hours	section	No	By default: a reading every 30 s per house with adsb.lol or adsb.fi (their requests at least 1.1 s apart), every 10 s with your receiver (one read for every house), and with OpenSky the interval its daily credits allow (a minute at least). A longer interval can be typed below. Outside the active hours (the time of Gladys) nothing is read.
Interval between two readings (s, 0 = automatic)	number	No	A shorter interval than the source allows is raised to its minimum: 15 s for adsb.lol and adsb.fi, 5 s for a receiver, the credits for OpenSky.
Active from (hour, 0-23)	number	No
Active until (hour, 1-24)	number	No	0 to 24: all day. Before the start hour (e.g. 22 to 6): through the night.

Cómo instalar Aircraft overhead en Gladys

1. En Gladys, abre Integraciones: Aircraft overhead aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
2. Haz clic en Instalar. Gladys descarga la imagen Docker (ghcr.io/lm1lc3n7/gladys-aircraft:0.1.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración).
3. Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
4. También puedes instalarla directamente desde la URL de su repositorio: https://github.com/LM1LC3N7/gladys-aircraft.

Aircraft overhead requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.

¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.

Sobre las integraciones externas

Aircraft overhead es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene LM1LC3N7, no el equipo principal de Gladys.

• Explorar todas las integraciones, nativas y de la comunidad
• Crear y publicar tu propia integración externa
• Código fuente en GitHub — fuente de esta documentación

Suscríbete a la newsletter de Gladys Assistant

Unos pocos correos al mes sobre nuevas versiones y novedades del proyecto. Enviados por Pierre-Gilles Leymarie, fundador del proyecto. Puedes darte de baja cuando quieras 🙂