Integración domótica AirNow, gratuita y de código abierto
Calidad del aire de AirNow (EPA, EE. UU.): AQI actual, previsión y alertas.
Publicado por William-De71
- Dispositivos
- Versión 0.1.0
- Requiere Gladys >=5.2.0
- ★ 0
Presentación
AirNow es el programa de calidad del aire de la Agencia de Protección Ambiental de EE. UU. (EPA) y de más de 150 agencias estatales, locales y tribales. Publica el índice de calidad del aire (AQI) medido cada hora por más de 2.500 estaciones, y las previsiones de más de 500 ciudades, en Estados Unidos, Canadá y México.
Esta integración lo lleva a Gladys para hasta tres lugares, cada uno una casa de Gladys o un código ZIP: el AQI actual con PM2,5, ozono y PM10, la previsión de los próximos días, disparadores de escena cuando cambia la calidad del aire o se anuncia una alerta, y dos widgets de panel.
El AQI va de 0 a 500 (más con el humo de incendios forestales): Buena (0-50), Moderada (51-100), Dañina para grupos sensibles (101-150), Dañina (151-200), Muy dañina (201-300), Peligrosa (301 o más). Los datos de AirNow son provisionales: no están totalmente verificados y pueden cambiar.
Requisitos
- Gladys Assistant 5.2.0 o posterior (el selector de casa de la configuración). Las instancias más antiguas no pueden instalar la integración.
- Una clave de API de AirNow gratuita (más abajo).
- Un lugar cubierto por AirNow: Estados Unidos, y Canadá o México mediante una casa (los códigos ZIP son solo de EE. UU.). AirNow responde con la zona de medición más cercana y sus estaciones, en un radio de unos 80 km.
Obtener una clave de API
- Abra Request an AirNow API account y rellene el formulario (un nombre y una dirección de correo).
- Confirme el correo y inicie sesión.
- Abra Web Services: su clave de API está arriba a la derecha de la página. Cópiela.
Una clave permite 500 solicitudes por hora; la integración hace menos de dos por lugar y por hora, y nunca más de 200 por hora.
Configuración
| Campo | Qué introducir |
|---|---|
| Clave de API | La clave de su cuenta de AirNow. Guardada como secreto, nunca se vuelve a mostrar ni se registra. |
| Casa (lugar 1, 2, 3) | Una casa de Gladys: su ubicación (Ajustes → Casas) sitúa el lugar. La integración pide este acceso. |
| O un código ZIP | Un código postal de EE. UU. (ZIP), cinco dígitos: 90210. Prevalece sobre la casa del mismo lugar. |
| Idioma de los textos | Nombres de los dispositivos y textos pasados a las escenas. Automático: el idioma del último widget mostrado. |
Dos botones completan la pantalla: Leer ahora (comprueba la clave, sitúa los lugares y los lee enseguida) y Diagnóstico (el estado de la integración en sus registros, sin la clave).
Uso
Dispositivos
Abra la pestaña Descubrir de la integración y cree un dispositivo por lugar, con el nombre de su zona de medición («AirNow NW Coastal LA»):
- Índice de calidad del aire: el AQI actual, el más alto de los contaminantes medidos;
- PM2,5 (AQI), Ozono (AQI), PM10 (AQI): el AQI de cada contaminante (NowCast, el índice horario de AirNow);
- Calidad del aire: la categoría, en texto;
- AQI previsto hoy y AQI previsto mañana: cuando la agencia da un número (algunas solo dan una categoría);
- Previsión: «Mañana: Moderada (Ozono)», y la alerta si la hay.
Gladys colorea las funcionalidades AQI con esta misma escala. Un contaminante que una estación no envió conserva su último valor: no se inventa ningún 0. Las mediciones se leen en el minuto 35 de cada hora, una vez publicadas por AirNow, y las previsiones cada 3 horas.
Widgets del panel
- Calidad del aire AirNow: el AQI actual con el color de su categoría, PM2,5, ozono y PM10, el consejo de salud de la categoría, la hora de la medición y la agencia que la realizó.
- Previsión AirNow: una tarjeta por día con su categoría y su contaminante principal; un toque muestra el consejo de salud y el comentario del pronosticador. Una alerta de calidad del aire se anuncia abajo.
Ambos tienen un ajuste Lugar (el primer lugar por defecto) y un botón Actualizar, que solo vuelve a leer si AirNow puede tener algo nuevo.
Escenas
Disparadores:
- AirNow: cambio de calidad del aire: la categoría actual cambia. Filtros: lugar, nueva categoría (una o varias), sentido (empeora, mejora). Variables:
aqi,category,category_name,previous_category,direction,pollutant_name,area. - AirNow: previsión actualizada: la categoría prevista de un día aparece o cambia. Filtros: lugar, día (hoy, mañana, más adelante), categoría.
- AirNow: alerta de calidad del aire: una previsión anuncia un Air Quality Action Day, una alerta de la agencia local. Filtros: lugar, día. Variables:
date,aqi,category_name,pollutant_name,discussion.
Acción: AirNow: leer la calidad del aire de un lugar: el AQI, la categoría, la previsión de hoy y mañana, si se anuncia una alerta, y una frase summary lista.
Ejemplos:
- Cuando la calidad del aire pasa a Dañina para grupos sensibles o peor → cerrar las ventanas y encender el purificador de aire.
- Cuando se anuncia una alerta de calidad del aire para mañana → enviar
{{triggerEvent.data.category_name}} prevista mañana ({{triggerEvent.data.pollutant_name}})a su teléfono. - Cada mañana a las 7:00 → leer la calidad del aire y anunciar el
summaryantes de salir a correr.
Transporte
Nube ("transports": ["cloud"]): la integración contacta www.airnowapi.org por HTTPS con su clave y, por lugar, el código ZIP o las coordenadas de la casa (redondeadas a unos 10 m). Nada más sale de su red. Las lecturas se guardan en el volumen /data de la integración: un reinicio no vuelve a leer nada que siga actualizado.
Solución de problemas
- AirNow rechazó la clave de API: cópiela de nuevo desde la página Web Services (sin espacios) y guarde la configuración: las lecturas se reanudan enseguida.
- No hay datos cerca de un lugar: el lugar está demasiado lejos de una zona de medición o de una estación (centro de Nevada, fuera de Norteamérica). Pruebe el código ZIP de la ciudad más cercana.
- La casa no tiene ubicación: indíquela en Ajustes → Casas y haga clic en Leer ahora.
- No hay previsión: algunas agencias solo prevén parte del año o algunos días; el widget lo indica.
- Valores que difieren de AirNow.gov en unos puntos: ambos muestran el NowCast de la misma hora, pero la zona de medición y las estaciones elegidas pueden diferir ligeramente.
- Si el problema persiste: haga clic en Diagnóstico y abra una incidencia en GitHub con las versiones de Gladys y de la integración, el lugar, y las líneas «AirNow diagnostic» de los registros (añada
DEBUG=gladys-integration-sdken modo desarrollador).
Datos: U.S. EPA AirNow y sus agencias asociadas, datos provisionales, mostrados tal como se reciben.
Parámetros de configuración
Estos son los parámetros que AirNow te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Clave de API de AirNow | section | No | AirNow es el programa de calidad del aire de la EPA de EE. UU. y de sus socios: mediciones y previsiones del índice AQI para Estados Unidos, Canadá y México. Su API necesita una clave gratuita: solicite una cuenta y copie la clave que aparece arriba a la derecha de su página Web Services. |
| Clave de API | secret | Sí | |
| Lugar 1 | section | No | Hasta tres lugares, cada uno una casa de Gladys o un código ZIP. AirNow responde con la zona de medición más cercana y sus estaciones (en un radio de unos 80 km). |
| Casa | select | No | Su ubicación en Gladys sitúa el lugar (Estados Unidos, Canadá, México). |
| O un código ZIP | string | No | Un código postal estadounidense (ZIP), cinco dígitos. Prevalece sobre la casa. |
| Lugar 2 | section | No | Opcional. |
| Casa | select | No | Su ubicación en Gladys sitúa el lugar (Estados Unidos, Canadá, México). |
| O un código ZIP | string | No | Un código postal estadounidense (ZIP), cinco dígitos. Prevalece sobre la casa. |
| Lugar 3 | section | No | Opcional. |
| Casa | select | No | Su ubicación en Gladys sitúa el lugar (Estados Unidos, Canadá, México). |
| O un código ZIP | string | No | Un código postal estadounidense (ZIP), cinco dígitos. Prevalece sobre la casa. |
| Opciones | section | No | AirNow actualiza las mediciones una vez por hora y las previsiones una o dos veces al día: la integración las lee en el minuto 35 de cada hora. |
| Idioma de los textos | select | No | Nombres de los dispositivos y textos pasados a las escenas. Automático: el idioma del último widget mostrado. |
Cómo instalar AirNow en Gladys
- En Gladys, abre Integraciones: AirNow aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/william-de71/gladys-airnow:0.1.0), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/William-De71/gladys-airnow.
AirNow requiere Gladys >=5.2.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
AirNow 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 William-De71, 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