Integración domótica Google Air Quality, gratuita y de código abierto
Calidad del aire de Google: índices universal y local, PM2,5, NO₂, O₃, previsión, escenas.
Publicado por William-De71
- Dispositivos
- Versión 0.1.0
- Requiere Gladys >=5.1.0
- ★ 0
Presentación
Esta integración lleva la calidad del aire de Google Maps Platform a Gladys: para sus casas y para los lugares que añada (trabajo, colegio, casa de vacaciones), da el índice universal de calidad del aire, el índice de su país, las concentraciones de los principales contaminantes y una previsión a 48 horas, y puede lanzar sus escenas cuando el aire empeora.
- Cada lugar se convierte en un dispositivo: índice universal (UAQI, 0-100, cuanto más alto, mejor), índice local (su valor cuando es un número), PM2,5, PM10, NO₂, O₃, SO₂ en µg/m³, categoría de calidad del aire, categoría del índice local, contaminante principal.
- Los lugares se miden cada hora por defecto (Google actualiza sus datos una vez por hora), y su previsión cada 6 horas, dentro de un presupuesto mensual por debajo del uso gratuito de Google.
- Disparadores de escena: la categoría de calidad del aire cambia, el presupuesto del mes está casi gastado, Google rechaza la clave de API. Acciones de escena: leer la calidad del aire de un lugar, leer la peor hora de la previsión.
- Tres widgets: la calidad del aire de un lugar con los consejos de salud de Google, su previsión a 48 horas, las solicitudes del mes.
La imagen de arriba es una ilustración generada, no una captura de pantalla. Sin relación con Google; aún no probada con una clave de API real. El polen queda fuera del alcance (la API Pollen de Google la cubren otras integraciones).
Requisitos
- Gladys Assistant 5.1.0 o posterior.
- Una clave de API de Google Maps Platform con la Air Quality API activada:
- En la consola de Google Cloud, cree un proyecto (o tome el de su clave de Google Weather o Google Maps Travel Time) con una cuenta de facturación: Google la pide incluso si se queda en el uso gratuito.
- Active la Air Quality API (API y servicios → Biblioteca → «Air Quality API», o este enlace).
- Cree una clave de API (Google Maps Platform → Claves y credenciales), o reutilice la del proyecto. En sus restricciones de API, permita la Air Quality API (junto a Weather API o Routes API si la clave también las usa). Una restricción por IP solo funciona si la dirección IP pública de su Gladys es fija.
- La ubicación de su casa indicada en Gladys (Ajustes → Casas), o lugares añadidos con Añadir un lugar. Al instalar, Gladys le pide permitir que la integración lea la ubicación de las casas.
Coste. Google factura cada solicitud correcta más allá de 10 000 solicitudes gratuitas al mes (SKU «Air Quality Usage»), luego 5 USD por 1000. Una medida de las condiciones actuales es una solicitud, una previsión a 48 horas una solicitud (una página). Con los valores por defecto, un lugar cuesta unas 870 solicitudes al mes: diez lugares caben en el presupuesto por defecto, el 90 % del uso gratuito. Más allá, la integración mide con menos frecuencia antes que superarlo. El uso gratuito pertenece a la cuenta de facturación: Google Weather, Travel Time y cualquier otro uso de la cuenta cuentan también.
Configuración
| Campo | Por defecto | Significado |
|---|---|---|
| Clave de API de Google Maps Platform | — | Obligatoria. Secreta: nunca aparece en los registros. |
| Seguir las casas de Gladys | sí | Un lugar por cada casa con ubicación. |
| Medida cada (minutos) | 60 | 30 a 360. Una solicitud por lugar cada vez. |
| Previsión cada (horas) | 6 | 0 a 24. 0: sin previsión (ni widget ni acción de previsión). |
| Índice local | vacío | Vacío: el índice por defecto del país (MITECO en España). Si no, su código de Google: eaqi (índice europeo), usa_epa, deu_uba, gbr_defra… (lista: página «Air Quality Index» de la documentación de Google). |
| Presupuesto mensual (%) | 90 | Parte de las 10 000 solicitudes gratuitas que la integración puede gastar. Por encima de 100, Google factura las solicitudes adicionales. |
| Idioma de los textos | automático | Nombres de las funciones, categorías y consejos de salud de Google, resúmenes de escenas, mensajes de los botones. |
Botones al final de la página:
- Añadir un lugar: un nombre y «latitud, longitud» (clic derecho en el lugar en Google Maps y clic en las coordenadas para copiarlas, por ejemplo
45.7640, 4.8357). - Eliminar un lugar: por su nombre o su número (
#2). Su dispositivo permanece en Gladys hasta que lo elimine. - Listar los lugares: los intervalos, las solicitudes del mes, la última medida y el último error de cada lugar.
- Probar la clave de API: lee la calidad del aire en París (una solicitud).
Uso
Lugares
Cada casa de Gladys con ubicación es un lugar, con el nombre de la casa. Los lugares añadidos se suman (20 como máximo). La primera medida de un lugar nuevo llega en menos de un minuto.
Dispositivos
Abra Integraciones → Google Air Quality → Descubrir y añada los lugares que quiera. Cada dispositivo tiene:
| Función | Categoría / tipo | Unidad |
|---|---|---|
| Índice universal (UAQI) | airquality-sensor / aqi | 0-100, cuanto más alto, mejor |
| Índice local (cuando es un número: MITECO, US EPA, DAQI…) | airquality-sensor / aqi | la escala del índice |
| PM2,5, PM10 | pm25-sensor, pm10-sensor / decimal | µg/m³ |
| NO₂, O₃, SO₂ | no2-sensor, o3-sensor, so2-sensor / decimal | µg/m³ (convertido desde ppb a 25 °C) |
| Calidad del aire, categoría del índice local, contaminante principal | text | — |
ATMO (Francia) y EAQI (Europa) tienen categorías, no números: su categoría está en el texto «categoría del índice local». Un contaminante que Google no mide en un lugar queda sin valor. El CO no tiene categoría de concentración en Gladys: lo encontrará en las salidas de la acción «Leer la calidad del aire».
Widgets
- Calidad del aire: un lugar (elegido entre los dispositivos): indicador del índice universal, índice local, PM2,5, PM10, NO₂, O₃, categorías, contaminante principal y el consejo de salud de Google para la población general.
- Previsión calidad del aire: el índice universal de las próximas 48 horas, la peor hora de las próximas 24 marcada.
- Solicitudes calidad aire: las solicitudes del mes frente al presupuesto, lo previsto, el estado de la clave.
Escenas
Disparadores:
- La categoría de calidad del aire cambia (filtros: lugar, índice universal o local, nuevo nivel universal). Variables:
name,index,category,previous_category,level,previous_level,aqi,dominant_pollutant,summary. Solo en las medidas programadas, nunca en la primera. - El presupuesto del mes está casi gastado (80 %, luego 100 %, una vez cada uno al mes).
- Google rechaza la clave de API (una vez, hasta que una solicitud vuelva a funcionar).
Acciones:
- Leer la calidad del aire: la última medida de un lugar (una nueva solicitud con «Leerla ahora», ninguna si se midió hace menos de un minuto). Salidas:
uaqi,level,category,local_index,local_aqi,local_category,dominant_pollutant,pm25,pm10,no2,o3,so2,co,health_recommendation,summary. - Leer la previsión de calidad del aire: la peor hora de las próximas 1 a 48 horas. Salidas:
worst_uaqi,worst_level,worst_category,worst_time,worst_local_category,summary.
Ejemplos:
- Cuando el índice universal de «Casa» pasa a «baja» → bajar las persianas y enviar el resumen.
- Cada mañana a las 7:00 → leer la previsión de «Casa» a 12 horas → si
worst_uaqiestá por debajo de 40, enviar «No es buen día para correr». - Cuando las PM2,5 de «Casa» superan 25 µg/m³ (disparador de dispositivo) → encender el purificador de aire.
Transporte
La integración usa los servidores de Google (nube): las coordenadas de sus lugares se envían a Google en cada medida, con su clave de API. Los lugares añadidos se guardan en la configuración de Gladys; las últimas medidas, las previsiones y el contador de solicitudes se guardan en el volumen /data de la integración.
Solución de problemas
- «Google rechaza la clave de API»: el mensaje da el motivo de Google.
API_KEY_INVALID: copie de nuevo la clave.SERVICE_DISABLED: active la Air Quality API en el proyecto de la clave.BILLING_DISABLED: vincule una cuenta de facturación.API_KEY_SERVICE_BLOCKED: añada la Air Quality API a las API permitidas de la clave. Una restricción por IP rechaza a Gladys si su dirección pública cambió. La integración reintenta cada hora, y enseguida tras Probar la clave de API o una clave nueva. - Ningún lugar: indique la ubicación de la casa en Ajustes → Casas (luego pulse Listar los lugares), o añada un lugar.
- «No hay datos de calidad del aire para este lugar»: Google no cubre todos los países (vea la página de cobertura de la Air Quality API).
- Sin valor de índice local: el índice de su país es una categoría (ATMO, EAQI); mire la categoría del índice local, o elija un índice numérico en la configuración.
- Medidas más espaciadas que el intervalo: «Para no superar el presupuesto» en el estado significa que los lugares prevén más que el presupuesto; siga menos lugares, mida con menos frecuencia o aumente el presupuesto.
- «Se han usado las solicitudes del mes»: el presupuesto se ha alcanzado; las medidas se reanudan el mes que viene (UTC). La cuenta de Google (consola de Cloud → Google Maps Platform → Métricas) es la referencia.
- 429: Google limita las solicitudes de la clave; la integración espera 15 minutos.
- Para informar de un problema, indique las versiones de Gladys y de la integración, el texto de Listar los lugares y los registros de la integración (Ajustes → Supervisión). No pegue nunca su clave de API.
Parámetros de configuración
Estos son los parámetros que Google Air Quality te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Google Air Quality | section | No | Cómo funciona: 1. En la consola de Google Cloud, en un proyecto con una cuenta de facturación, active la «Air Quality API» y cree una clave de API (la clave de Google Weather o de Google Maps Travel Time también sirve una vez activada la API en su proyecto). Péguela abajo. 2. Cada casa de Gladys con ubicación se convierte en un lugar; añada otros con «Añadir un lugar». 3. Abra la pestaña Descubrir y añada los lugares: cada uno se convierte en un dispositivo con el índice universal (UAQI), el índice local, PM2,5, PM10, NO₂, O₃ y SO₂. 4. Añada los widgets a un panel y use las escenas. Coste: cada medida es una solicitud, facturada por Google más allá de 10 000 solicitudes gratuitas al mes (luego 5 USD por 1000). Con los valores por defecto, un lugar cuesta unas 870 solicitudes al mes; la integración se queda bajo el 90 % del uso gratuito y espacia las medidas antes que superarlo. Las coordenadas de los lugares se envían a Google. |
| Clave de API de Google Maps Platform | secret | Sí | Una clave de un proyecto de Google Cloud con la Air Quality API activada. Restrínjala a las API que usa (y a la dirección IP pública de su Gladys si es fija). |
| Seguir las casas de Gladys | boolean | No | Un lugar por cada casa con ubicación en Gladys (Ajustes → Casas). |
| Medida cada (minutos) | number | No | Google actualiza la calidad del aire una vez por hora: 60 basta (30 a 360). Una solicitud por lugar cada vez. |
| Previsión cada (horas) | number | No | La previsión a 48 horas de cada lugar, para el widget y la acción de escena de previsión (una solicitud por lugar cada vez). 0: sin previsión. |
| Índice local (opcional) | string | No | Vacío: el índice por defecto del país (MITECO en España, EAQI en Bélgica…). Si no, su código de Google, como eaqi, usa_epa o deu_uba. |
| Presupuesto mensual (% del uso gratuito) | number | No | Parte de las 10 000 solicitudes mensuales gratuitas que la integración puede gastar: 90 deja un margen (Google cuenta también los otros usos de la cuenta de facturación). Por encima de 100, Google factura las solicitudes adicionales. |
| Idioma de los textos | select | No | Nombres de las funciones, categorías, consejos de salud, resúmenes de escenas y mensajes de los botones. Automático: el idioma de su panel en cuanto se haya mostrado un widget, deducido de la zona horaria de Gladys antes de eso. |
Cómo instalar Google Air Quality en Gladys
- En Gladys, abre Integraciones: Google Air Quality 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-google-air-quality: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-google-air-quality.
Google Air Quality 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
Google Air Quality 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