Integración domótica Airthings, gratuita y de código abierto
Radón, CO₂, COV, partículas, temperatura y humedad de sus sensores Airthings.
Publicado por guim31
- Dispositivos
- Versión 1.0.1
- Requiere Gladys >=5.1.0
- ★ 0
Lleva sus monitores de calidad del aire Airthings a Gladys: radón, CO₂, COV, partículas, temperatura, humedad, presión, batería y antigüedad de la última medición, leídos a través de la API en la nube oficial de Airthings. Un widget del panel muestra el aire de cada estancia de un vistazo, con un código de colores claro para el radón.
El radón es un gas radiactivo natural, la segunda causa de cáncer de pulmón después del tabaco, y una verdadera preocupación en las regiones graníticas (Galicia, Extremadura, la sierra de Guadarrama, Bretaña…). En España y en Francia, el nivel de referencia es de 300 Bq/m³ (media anual).
Desarrollada sin el hardware: sus comentarios son bienvenidos. Esta integración se escribió a partir de la especificación oficial de la API y de respuestas publicadas, sin sensor ni cuenta de Airthings. Si algo le parece incorrecto, abra una incidencia: https://github.com/guim31/gladys-airthings/issues
Esta integración no está afiliada a Airthings. Airthings, Wave, View y Space son marcas de Airthings ASA.
Requisitos
- Gladys Assistant 5.1.0 o posterior.
- Uno o varios sensores Airthings (Wave, Wave Plus, Wave Mini, Wave Radon, Wave Enhance, View Plus, View Radon, View Pollution, Space…) registrados en la aplicación Airthings. Los Wave envían sus medidas a través de un Airthings Hub, un View Plus o la aplicación del teléfono por Bluetooth: un Wave que solo se sincroniza con el teléfono solo se actualiza cuando la aplicación está abierta cerca.
- Un cliente de API de Airthings (gratuito): su ID y su secreto. Un cliente por cuenta de Airthings.
- Acceso a Internet para Gladys: los datos vienen de la nube de Airthings, no directamente de los sensores.
Configuración
- Abra el panel de la API de Airthings (https://consumer-api-doc.airthings.com/dashboard) e inicie sesión con su cuenta de Airthings.
- Cree un cliente de API y copie su ID de cliente (client id) y su secreto de cliente (client secret).
- En Gladys, abra Integraciones, instale Airthings (Integraciones → Instalar desde GitHub, o desde la tienda) y rellene su configuración:
- ID de cliente y Secreto de cliente;
- Intervalo de lectura: se recomiendan 5 minutos (de 2 a 60 minutos);
- Nivel de referencia del radón: a partir de este nivel, el widget muestra el radón en rojo (300 Bq/m³ en España, Francia y la UE; 148 Bq/m³ es el nivel de acción de la EPA de EE. UU.; 100 Bq/m³ la recomendación de la OMS);
- Idioma de los nombres de funciones: el de los nombres dados a las nuevas funciones (francés por defecto).
- Pulse Probar la conexión: el mensaje enumera los sensores encontrados y las solicitudes de API usadas en esta hora.
- Abra la pestaña Descubrimiento de la integración y añada a Gladys los sensores que desee.
Dispositivos y funciones
Un dispositivo de Gladys por sensor Airthings (el hub, que no mide nada, se deja de lado). Cada dispositivo solo tiene las funciones que su sensor envía realmente:
| Función (nombres en español) | Unidad | Sensores |
|---|---|---|
| Radón (corto plazo) | Bq/m³ | Wave, Wave Plus, Wave Radon, View Plus, View Radon, Corentium Home 2 |
| Radón (largo plazo) | Bq/m³ | cuando la API lo envía |
| CO₂ | ppm | Wave Plus, Wave Enhance, View Plus, View CO2, Space |
| COV | ppb | Wave Plus, Wave Mini, Wave Enhance, View Plus |
| PM1 | µg/m³ | View Plus, View Pollution |
| PM2.5 | µg/m³ | View Plus, View Pollution |
| PM10 | µg/m³ | cuando la API lo envía |
| Temperatura | °C | la mayoría de los sensores |
| Humedad | % | la mayoría de los sensores |
| Presión | hPa | Wave Plus, Wave Enhance, View Plus |
| Luminosidad | lux | Wave Enhance, cuando la API la envía |
| Ruido | dBA | Wave Enhance, cuando la API lo envía |
| Batería | % | sensores con pilas |
| Antigüedad de la medición | minutos | todos los sensores: la antigüedad de su última medición |
El radón a corto plazo es la media de las últimas 24 horas. Gladys no tiene categoría de radón: las funciones de radón se publican como contadores en Bq/m³ y el widget da el código de colores. Gladys tampoco tiene categoría PM1: PM1 se publica como una función PM2.5 llamada «PM1».
Todas las funciones son de solo lectura: no se puede controlar nada.
Widget
Calidad del aire (panel → Editar → añadir un widget → Airthings):
- Todas las estancias (ajuste vacío): una fila por sensor, su punto del color del peor de sus valores, las estancias que requieren atención primero; además, el radón y el CO₂ más altos de la casa.
- Un sensor (elegido en el ajuste): cinco mosaicos (radón, CO₂, PM2.5, temperatura y humedad primero), la curva de radón de la última semana una vez añadido el dispositivo a Gladys, la valoración del radón, los demás valores, la batería y la antigüedad de la medición.
Colores: radón verde por debajo de 100 Bq/m³ (OMS), naranja hasta el nivel de referencia de la configuración, rojo a partir de él. CO₂ 800 / 1000 ppm, COV 250 / 2000 ppb, partículas 10 / 25 µg/m³, humedad buena de 30 a 60 %: los umbrales de las aplicaciones Airthings.
Disparadores y acciones
La integración no declara disparadores ni acciones de escena propios: los estados de los dispositivos ya cubren todos los usos con los disparadores de Gladys («el valor de un dispositivo supera un umbral»). La única acción es el botón Probar la conexión de la pantalla de configuración.
Ejemplos de escenas
- Radón por encima de la referencia: disparador «Radón (corto plazo) de Sótano por encima de 300», acción: enviar un mensaje «Ventile el sótano: radón por encima de 300 Bq/m³» y encender la ventilación (un enchufe inteligente).
- Ventilar el dormitorio: disparador «CO₂ de Dormitorio por encima de 1000», condición: alguien en casa, acción: una notificación «Abra la ventana del dormitorio».
- Sensor mudo: disparador «Antigüedad de la medición de Salón por encima de 180» (tres horas sin envío), acción: un mensaje «Compruebe el hub Airthings o las pilas».
- Pilas: disparador «Batería de Dormitorio por debajo de 15», acción: un mensaje para comprar pilas.
Lectura y cuota de la API
La API Airthings Consumer admite 120 solicitudes por hora y por cliente de API. Una lectura de toda la cuenta cuesta una solicitud (50 sensores por página), más la lista de dispositivos una vez por hora y un nuevo token cada pocas horas: a 5 minutos, la integración usa unas 13 solicitudes por hora. Por sí misma nunca supera 100 por hora, y se detiene hasta la hora indicada por la API cuando esta responde «demasiadas solicitudes».
Los sensores envían sus medidas cada 2,5 minutos (gama View) a 5 minutos o más (gama Wave, a través de un hub o del teléfono): leer más a menudo solo volvería a leer los mismos valores. La integración lee la nube con su propio temporizador y solo publica un valor en Gladys cuando cambia (y al menos cada 6 horas). Un sensor añadido en Gladys recibe sus valores en el acto, desde la última lectura.
Guardados en el contenedor: el token de acceso, el ID de la cuenta de Airthings y las funciones vistas por sensor (en /data). El secreto de cliente permanece en la configuración de Gladys.
Solución de problemas
- «ID o secreto rechazado»: vuelva a copiarlos desde el panel de la API de Airthings (sin espacios); un cliente de API eliminado debe crearse de nuevo. La integración lo vuelve a intentar cada 30 minutos, o inmediatamente después de guardar la configuración.
- «cuota de solicitudes de la API de Airthings alcanzada»: otra herramienta usa el mismo cliente de API, o el intervalo es corto. La lectura se reanuda sola; elija un intervalo más largo.
- Un sensor no tiene valor reciente: mire su Antigüedad de la medición. Un Wave necesita un hub, un View Plus o la aplicación del teléfono cerca para enviar sus medidas; puede que las pilas estén agotadas.
- Falta un sensor: debe estar registrado en la aplicación Airthings con la misma cuenta que el cliente de API; pulse Buscar en la pestaña Descubrimiento.
- Más detalles: reinicie el contenedor con
LOG_LEVEL=debug. Los registros nunca contienen el ID de cliente, el secreto ni el token.
Limitaciones
- Solo nube: no hay lectura local de los sensores por Bluetooth (el contenedor de Gladys no tiene Bluetooth).
- Los valores son los del último envío del sensor: hasta 5 minutos o más de retraso para un Wave.
- No se leen los índices de riesgo de moho y de virus de algunos sensores (Gladys no tiene función para ellos), ni los mandos del purificador Renew.
- Los nombres de las funciones se fijan cuando el dispositivo se añade en Gladys.
- Desarrollada sin el hardware: sus comentarios son bienvenidos en https://github.com/guim31/gladys-airthings/issues
Parámetros de configuración
Estos son los parámetros que Airthings te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Cliente de API de Airthings | section | No | Abra el panel de la API de Airthings (enlace abajo), inicie sesión con su cuenta de Airthings, cree un cliente de API y copie aquí su ID y su secreto. Gratuito, un cliente por cuenta. Sin relación con Airthings. |
| ID de cliente (client id) | string | Sí | |
| Secreto de cliente (client secret) | secret | Sí | |
| Intervalo de lectura | select | No | Los sensores envían sus medidas cada 2,5 a 5 minutos o más, y la API admite 120 solicitudes por hora: 5 minutos bastan. |
| Nivel de referencia del radón | select | No | A partir de este nivel, el widget muestra el radón en rojo; a partir de 100 Bq/m³ (OMS), en naranja. |
| Idioma de los nombres de funciones | select | No | Gladys no comunica su idioma a las integraciones: elija el de los nombres de las nuevas funciones. |
Cómo instalar Airthings en Gladys
- En Gladys, abre Integraciones: Airthings 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/guim31/gladys-airthings:1.0.1), 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/guim31/gladys-airthings.
Airthings 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
Airthings 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 guim31, 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