Integración domótica AirGradient, gratuita y de código abierto
Sensores de calidad del aire AirGradient en la red local: CO₂, PM2,5, COV, temperatura, humedad.
Publicado por guim31
- Dispositivos
- Versión 1.0.1
- Requiere Gladys >=5.1.0
- ★ 0
Esta integración lleva a Gladys los sensores de calidad del aire AirGradient: el AirGradient ONE (interior), el Open Air (exterior), los kits DIY y el AirGradient Go. Los lee en su red local, a través de la API local de su firmware: sin cuenta, sin nube, sin clave de API.
Desarrollada sin el hardware: sus comentarios son bienvenidos. La integración se ha escrito a partir del código fuente del firmware de AirGradient, de la documentación de su API local y de las respuestas reales publicadas con la biblioteca Python
airgradienty la integración de Home Assistant. Aún no se ha probado con un sensor real: cuéntenos en el foro de Gladys qué funciona y qué no.
Esta integración no está afiliada a AirGradient.
Lo que obtiene
- Un dispositivo por sensor, encontrado automáticamente en su red (mDNS) o añadido por su dirección IP.
- Sus mediciones, actualizadas cada minuto: PM1, PM2,5, PM10, CO₂, temperatura, humedad, índice de COV, índice de NOx, recuento de partículas de 0,3 µm, señal Wi-Fi (y la batería del Go). Solo lo que mide su modelo: un Open Air sin sensor de CO₂ no tiene función de CO₂.
- Los valores corregidos cuando el firmware los proporciona (PM2,5 con la corrección EPA, temperatura y humedad del Open Air): son los que muestra el sensor.
- Como opción, los ajustes del sensor desde Gladys: brillo de la pantalla, brillo de la barra LED, modo de la barra LED y unidad de temperatura de la pantalla (AirGradient ONE, kits DIY).
- Un widget «Calidad del aire» para el panel: las mediciones en directo y la calidad del aire en color.
- Un disparador de escena cuando un sensor deja de responder, y una acción de escena para calibrar el sensor de CO₂ (desactivada por defecto).
Requisitos
- Gladys Assistant 5.1.0 o posterior.
- Un sensor AirGradient con firmware 3.1 o posterior (3.0.10 para la API local, 3.1.4 para el PM2,5 corregido), conectado a la misma red que Gladys o a una red que Gladys pueda alcanzar.
- Nada más: la API local no necesita contraseña.
Para encontrar la dirección IP de un sensor: la lista de dispositivos conectados de su router (el
sensor se llama airgradient_<número de serie>), o el panel de AirGradient, en los detalles del
sensor.
Configuración
Instale la integración desde Integraciones → Instalar desde la tienda (o Instalar desde GitHub) y abra su pestaña Configuración.
Ajustes
| Ajuste | Por defecto | Qué hace |
|---|---|---|
| Direcciones IP de los sensores | vacío | Opcional. Las direcciones que el descubrimiento automático no encuentra, separadas por comas (192.168.1.50). |
| Intervalo de lectura | 1 minuto | Frecuencia de lectura de cada sensor: 30 segundos, 1, 2 o 5 minutos. |
| Ajustes de los sensores desde Gladys | No | Añade a los dispositivos los ajustes de la pantalla y de la barra LED (vea más abajo). |
| Calibración del CO₂ desde escenas | No permitida | Permite la acción de escena «Calibrar el sensor de CO₂». |
| Idioma de los nombres de las funciones | Francés | Nombres dados a las funciones de los nuevos dispositivos. |
Encontrar los sensores
Los sensores se anuncian en la red (mDNS, servicio _airgradient._tcp). La integración funciona en
un contenedor que no oye esos anuncios: Gladys los escucha por ella y se los transmite. Abra la
pestaña Descubrir y añada los sensores que desee.
Si falta un sensor (otra red, una VLAN, mDNS filtrado por el router), introduzca su dirección IP en Direcciones IP de los sensores. El botón Buscar sensores vuelve a buscarlos e indica lo que ha encontrado. Un sensor que cambia de dirección (DHCP) se sigue por su número de serie: su dispositivo sigue siendo el mismo. Darle una dirección fija en su router sigue siendo lo más fiable.
Ajustes de los sensores desde Gladys
Con Ajustes de los sensores desde Gladys en Sí, los dispositivos del AirGradient ONE y de los kits DIY reciben funciones adicionales:
- Brillo de la pantalla y Brillo de la barra LED (de 0 a 100 %, la barra LED solo en el ONE);
- Modo de la barra LED: apagada, CO₂ o PM2,5 (solo ONE);
- Unidad de temperatura de la pantalla: °C o °F, solo para la pantalla del sensor — Gladys recibe siempre la temperatura en °C y la muestra en su unidad.
Después de cambiar este ajuste, pulse Actualizar en el sensor, en la pestaña Descubrir.
Un sensor configurado en el panel de AirGradient puede tomar sus ajustes solo de la nube. Gladys no puede cambiarlos entonces: ejecute Ajustes locales en la pestaña Configuración y elija el sensor. A partir de ese momento, el sensor solo toma sus ajustes de la red local, y los del panel de AirGradient dejan de aplicarse.
Dispositivos
Cada sensor es un dispositivo con el nombre de su modelo y el final de su número de serie (por ejemplo «AirGradient ONE 12f5»): cámbielo como quiera.
| Función | Unidad | Notas |
|---|---|---|
| PM1 | µg/m³ | Gladys no tiene categoría PM1: se muestra con el icono del PM2,5. |
| PM2,5 | µg/m³ | Valor corregido cuando el firmware lo proporciona. |
| PM10 | µg/m³ | |
| CO₂ | ppm | ONE, Open Air con sensor de CO₂, Go, la mayoría de los kits DIY. |
| Temperatura | °C | Valor corregido en el Open Air. |
| Humedad | % | Valor corregido en el Open Air. |
| Índice de COV | de 1 a 500 | Índice Sensirion: 100 es la media del último día, más es peor. |
| Índice de NOx | de 1 a 500 | Índice Sensirion: 1 es el nivel normal, más indica óxidos de nitrógeno. |
| Partículas de 0,3 µm | por decilitro | Recuento bruto del sensor de partículas. |
| Batería | % | Solo AirGradient Go. |
| Señal Wi-Fi | dBm | -30 es excelente, -80 es débil. |
Los valores se redondean (temperatura a 0,1 °C, humedad a 1 %, partículas a 0,1 µg/m³) y solo se envían a Gladys cuando cambian; un valor estable se vuelve a enviar cada 12 horas. El dispositivo muestra una insignia «local», o «inaccesible» cuando el sensor no responde.
Widget del panel
Añada el widget Calidad del aire (AirGradient) a un panel y elija un sensor en sus ajustes. Muestra el CO₂, el PM2,5, la temperatura y la humedad en directo, y un estado en color:
| Nivel | CO₂ (ppm) | PM2,5 (µg/m³) |
|---|---|---|
| Buena | hasta 800 | hasta 9 |
| Moderada | hasta 1000 | hasta 35 |
| Mala | hasta 1500 | hasta 55 |
| Muy mala | más de 1500 | más de 55 |
Son los colores de la barra LED de AirGradient (para el PM2,5, los umbrales de la EPA de Estados Unidos; el valor guía de la OMS para 24 horas, 15 µg/m³, está en la franja «moderada»). La calidad del aire global es la peor de las dos.
Disparador de escena
Sensor AirGradient sin respuesta: un sensor ha dejado de responder (tres lecturas seguidas, tres minutos con el intervalo por defecto). Filtre por un sensor o déjelo vacío para cualquiera. Variables: el nombre del sensor y su dirección IP. Se dispara una vez, cuando se pierde el sensor; sus últimos valores permanecen en Gladys.
No hay disparador «CO₂ por encima de 1000»: utilice el disparador de dispositivo habitual de Gladys sobre la función CO₂, con su propio umbral.
Acción de escena
Calibrar el sensor de CO₂ AirGradient: el sensor toma su medición actual como 400 ppm, el nivel del aire exterior fresco. Se rechaza mientras Calibración del CO₂ desde escenas no esté en Permitida. Ejecútela solo con el sensor fuera (o junto a una ventana abierta de par en par) desde hace varios minutos: en interior, todas las mediciones posteriores serían demasiado bajas. El sensor de CO₂ también se recalibra solo en unos días (calibración automática de la línea base): la mayoría de los usuarios nunca necesita esta acción.
Ejemplos de escenas
- Ventilar el dormitorio: cuando el CO₂ del dormitorio supere 1200 ppm, enviar el mensaje «Abra la ventana» — y cuando vuelva a bajar de 800 ppm, «Puede cerrarla».
- Humo o contaminación: cuando el PM2,5 del Open Air supere 35 µg/m³, cerrar las persianas y encender el purificador de aire.
- Sensor perdido: con el disparador «Sensor AirGradient sin respuesta», enviar un mensaje con
{{triggerEvent.data.name}}y su dirección. - Modo noche (con los ajustes): a las 22 h, poner a 0 el brillo de la pantalla y de la barra LED del ONE; a las 7 h, volver a ponerlos a 80.
Solución de problemas
- Ningún sensor en la pestaña Descubrir: compruebe que el sensor está conectado al Wi-Fi (su pantalla muestra las mediciones, no un mensaje de configuración), introduzca su dirección IP en Direcciones IP de los sensores y pulse Buscar sensores. El informe indica si el descubrimiento automático está disponible.
- «no responde»: el sensor está apagado, fuera del alcance del Wi-Fi o tiene una nueva
dirección. Abra
http://<dirección IP>/measures/currenten un navegador de la misma red: deben aparecer las mediciones en JSON. Un firmware anterior a 3.0.10 no tiene API local: actualícelo desde el sensor. - Se rechaza un ajuste, «solo acepta ajustes de la nube de AirGradient»: ejecute Ajustes locales.
- Falta un valor justo después de reiniciar el sensor: los sensores necesitan hasta un minuto antes de su primera medición; el valor llega en la siguiente actualización.
- Registros: la página Supervisión de Gladys muestra los registros de la integración. Son
discretos a propósito: una línea cuando se encuentra, se pierde o vuelve un sensor, y una por
acción. Defina la variable
LOG_LEVEL=debugpara ver cada lectura.
Límites
- La integración solo lee la API local. La API en la nube de AirGradient (con token) no está soportada: el sensor debe ser accesible desde Gladys en la red.
- La API local no tiene contraseña: cualquiera en su red puede leer un sensor y cambiar sus ajustes si acepta ajustes locales. Así funciona el firmware.
- No se ofrecen los ajustes del AirGradient Go (API más reciente) ni del Open Air (sin pantalla); sus mediciones sí.
- Los índices de COV y NOx se muestran con la categoría «Índice COV Sensirion»: Gladys no tiene categoría NOx. El PM1 usa la categoría PM2,5.
- Las mediciones son medias calculadas por el sensor; leer más a menudo que cada 30 segundos solo las repetiría. La API local no tiene cuota, pero el sensor es un dispositivo pequeño: una lectura por minuto es también lo que hace Home Assistant.
- Gladys no ve los ajustes cambiados desde el panel de AirGradient hasta la siguiente lectura.
Parámetros de configuración
Estos son los parámetros que AirGradient te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Encontrar sus sensores | section | No | Los sensores AirGradient (ONE, Open Air, kits DIY, firmware 3.1 o posterior) de la misma red que Gladys se encuentran automáticamente (mDNS): abra la pestaña Descubrir. Si falta alguno, introduzca su dirección IP a continuación. |
| Direcciones IP de los sensores | string | No | Opcional, separadas por comas. Solo para los sensores que el descubrimiento automático no encuentra. |
| Intervalo de lectura | select | No | Frecuencia de lectura de cada sensor. Los sensores promedian sus mediciones durante un minuto aproximadamente. |
| Ajustes de los sensores desde Gladys | select | No | Añade a los dispositivos el brillo de la pantalla y de la barra LED, el modo de la barra LED y la unidad de temperatura de la pantalla (ONE y kits DIY). Después, pulse Actualizar en la pestaña Descubrir. |
| Calibración del CO₂ desde escenas | select | No | La calibración toma la medición actual como 400 ppm: ejecútela solo con el sensor al aire libre, o todas las mediciones posteriores serán erróneas. |
| Idioma de los nombres de las funciones | select | No | Nombres dados a las funciones de los nuevos dispositivos (CO₂, Temperatura, Humedad…). |
Cómo instalar AirGradient en Gladys
- En Gladys, abre Integraciones: AirGradient 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-airgradient: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-airgradient.
AirGradient 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
AirGradient 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