Integración domótica Philips Air, gratuita y de código abierto
Purificadores y humidificadores Philips en la red local: calidad del aire, modos, filtros.
Publicado por guim31
- Dispositivos
- Versión 1.0.1
- Requiere Gladys >=5.1.0
- ★ 0
Controle sus purificadores y humidificadores de aire Philips conectados desde Gladys, en su red local, sin la nube de Philips: calidad del aire (PM2.5, índice de alérgenos, humedad), modos y velocidad del ventilador, humedad objetivo, bloqueo infantil, iluminación de la pantalla y horas restantes de cada filtro. Los cambios hechos en el purificador o en la aplicación de Philips llegan a Gladys en pocos segundos.
Desarrollada sin el hardware: sus comentarios son bienvenidos («Developed without the hardware: feedback welcome»). Esta integración se escribió a partir del protocolo documentado por la comunidad de código abierto y se probó con un purificador simulado. Si su modelo se comporta de otra forma, abra una incidencia en https://github.com/guim31/gladys-philips-air/issues con la salida del script de sondeo (vea Solución de problemas).
Sin relación con Philips ni Versuni. Philips es una marca de Koninklijke Philips N.V.
Requisitos
- Gladys Assistant 5.1 o posterior.
- Un purificador o humidificador Philips con Wi-Fi que hable el protocolo local CoAP (puerto UDP 5683): la serie AC (AC2889, AC2729, AC3829, AC3858, AC4236, Series 2000i y 3000i…), los recientes AC0850, AC0950, AC2220, AC3220, AC3420, AC4220, y los humidificadores HU (HU1509, HU4209, HU5710…). La lista completa está en «Modelos compatibles».
- El purificador configurado una vez en la aplicación Philips Air+ (allí se une a su Wi-Fi), en la misma red local que Gladys.
- Su dirección IP. Su router la muestra (el aparato suele aparecer como
MXCHIP…). Asígnele una dirección fija (reserva DHCP) en su router: la integración busca el purificador en la dirección introducida.
Configuración
En Gladys, abra Integraciones → Philips Air → Configuración:
| Campo | Para qué sirve |
|---|---|
| Direcciones IP de los purificadores | Una o varias direcciones IPv4, separadas por comas. |
| Intervalo de actualización | Frecuencia de lectura de cada purificador (de 10 s a 2 min, 30 s por defecto). El purificador suele enviar los cambios al instante; esta lectura es la red de seguridad. |
| Aviso de cambio de filtros | Cuándo se activa el disparador de mantenimiento para un filtro por cambiar: cuando el purificador lo pide (por defecto), o 1 día, 3 días, 1 semana antes. El prefiltro se avisa siempre cuando el purificador lo pide. |
| Idioma de los nombres | Idioma de los nombres de los nuevos dispositivos, sus funciones, la lista de modos y los mensajes del disparador. Francés por defecto. |
Guarde y abra la pestaña Descubrimiento: un dispositivo por purificador, con el nombre que tiene en la
aplicación de Philips y su modelo, por ejemplo Dormitorio (AC2729/10). Añádalo a Gladys.
El botón Comprobar los purificadores (pantalla de configuración) lee todas las direcciones a la vez e indica qué purificadores responden y qué modelo no está en la lista de la integración.
El dispositivo
Cada purificador recibe solo las funciones de su modelo:
| Función | En Gladys |
|---|---|
| Encendido | Interruptor. |
| Modo | Lista de los modos del modelo (vea más abajo). |
| Velocidad del ventilador | Velocidad manual, de 1 a 2, 3 o 5 según el modelo. Ajustarla selecciona «Manual». |
| PM2.5 | Partículas finas, en µg/m³. |
| Índice de alérgenos | Índice de alérgenos interiores de Philips, de 1 (bueno) a 12 (muy malo). |
| Humedad | Humedad relativa, en % (modelos con sensor de humedad). |
| Temperatura | En °C (modelos con sensor de temperatura). |
| Humedad objetivo | Lista de valores que acepta el humidificador (de 40 a 70 % o de 30 a 70 %). |
| Humidificación | Enciende o apaga la parte humidificadora de un purificador 2 en 1. |
| Depósito de agua | «Bajo» cuando el depósito está vacío o retirado, «Normal» si no. |
| Bloqueo infantil | Bloquea los botones del purificador. |
| Iluminación de la pantalla | Brillo de la pantalla y del anillo de calidad del aire. |
| Prefiltro (horas restantes) | Horas hasta la próxima limpieza del prefiltro. |
| Filtro HEPA (horas restantes) | Horas hasta el cambio del filtro HEPA (o NanoProtect). |
| Filtro de carbón (horas restantes) | Horas hasta el cambio del filtro de carbón activo. |
| Mecha (horas restantes) | Horas hasta el cambio de la mecha del humidificador. |
Modos
Según el modelo: Automático, Alérgenos, Bacterias y virus, Contaminación, Suave, Medio, Alto, Sueño, Sueño alergias, Turbo y Manual (una velocidad fija). Elegir un modo también enciende el purificador. Un modelo que no está en la lista de la integración conserva sus sensores, su interruptor y sus filtros, pero no tiene lista de modos.
Widget del panel
El widget Purificador Philips muestra, para el purificador elegido en su configuración:
- PM2.5 y humedad, en directo;
- el modo, el índice de alérgenos en la escala de Philips (Bueno, Regular, Malo, Muy malo), el impulso en curso y su hora de fin, y lo que pide el purificador (o el filtro más cercano a su fin);
- botones: dos modos habituales (Automático o Contaminación, Sueño), Impulso de 15, 30 o 60 minutos (ajuste del widget), y encendido/apagado.
Disparador de escena
Mantenimiento del purificador necesario se activa una vez cuando un purificador empieza a pedir mantenimiento, y de nuevo solo después de hacerlo (filtro cambiado, depósito lleno):
- Prefiltro por limpiar (cuando el purificador lo pide);
- Filtro HEPA por cambiar, Filtro de carbón por cambiar, Mecha por cambiar (cuando el purificador lo pide, o antes: vea el ajuste «Aviso de cambio de filtros»);
- Depósito de agua vacío (mientras humidifica).
Filtros: el purificador y los elementos que le interesan. Variables: item, hours_left y message, un
texto listo como «Dormitorio (AC2729/10): Filtro HEPA por cambiar (quedan 70 h)», en el idioma de la
configuración.
Acción de escena
Impulsar el purificador pone el purificador en Turbo (o a su velocidad más alta) de 5 a 240 minutos y
luego lo devuelve al modo que tenía, o lo apaga si estaba apagado. Si alguien cambia el purificador durante el
impulso, este termina sin tocarlo. La acción devuelve until, el fin del impulso.
Ejemplos de escenas
- Después de cocinar: cuando la PM2.5 de la cocina supera 35 µg/m³, Impulsar el purificador 20 minutos.
- Recordatorio de filtros: con Mantenimiento del purificador necesario, enviar
{{triggerEvent.data.message}}a su teléfono. - Noche: a las 22:30, modo Sueño e iluminación de la pantalla apagada para el purificador del dormitorio; a las 7:00, de vuelta a Automático.
- Ausencia: cuando la casa está vacía, purificadores en Automático; al volver la primera persona, Impulsar el purificador 15 minutos.
Solución de problemas
- «Ningún purificador Philips responde»: compruebe la dirección IP (puede haber cambiado: fíjela), que el purificador está enchufado y conectado al Wi-Fi, y que responde en la aplicación de Philips. Un cortafuegos estricto en el equipo de Gladys (ufw…) puede bloquear el tráfico UDP entre el contenedor de la integración y su red.
- Funcionaba y dejó de responder: el firmware de estos purificadores deja de responder en local al cabo de un tiempo (también visto con Home Assistant). Desenchufe el purificador 10 segundos; la integración se reconecta sola.
- Un modelo sin lista de modos: su modelo aún no está en la lista. Ejecute el script de sondeo desde un
equipo de la misma red,
node scripts/probe.mjs <dirección IP>(en un clon del repositorio, Node.js 22+): solo lee y oculta los identificadores. Pegue su salida en una incidencia. - Más detalles: los registros de la integración (Gladys → Integraciones → Philips Air → Registros) solo
muestran la vida de los purificadores en el nivel normal;
LOG_LEVEL=debugen el contenedor muestra cada lectura.
Límites
- Solo control local (CoAP sobre UDP 5683). Los modelos antiguos que solo hablan HTTP y los firmwares recientes que cerraron el acceso local no son compatibles.
- Sin descubrimiento automático: los purificadores no se anuncian de forma que el contenedor de Gladys pueda verlo. Introduzca su dirección IP.
- Las listas de modos proceden de lo que ha observado la comunidad de código abierto: un modelo puede aceptar un modo que falta en su lista, o al revés. El temporizador, el pitido, la luz ambiental y el «índice preferido» de algunos modelos no se ofrecen.
- Los cambios enviados por el purificador atraviesan la red Docker de Gladys; si no pasan, la siguiente lectura (30 s por defecto) los trae.
- Un impulso en curso sobrevive a un reinicio de la integración, pero termina en la siguiente respuesta si el purificador no estaba disponible a la hora prevista.
Modelos compatibles
- Serie AC, firmware clásico: AC2729, AC2889, AC2936, AC2939, AC2958, AC2959, AC3021, AC3033, AC3036, AC3039, AC3055, AC3059, AC3259, AC3829, AC3854/50, AC3854/51, AC3858/50, AC3858/51, AC3858/83, AC3858/86, AC4231, AC4236, AC5659, AC5660.
- AC1715 y AC0850 (firmware «AWS_Philips_AIR»).
- Nueva generación: AC0850 (firmware «AWS_Philips_AIR_Combo»), AC0950, AC0951, AC2210, AC2220, AC2221, AC3210, AC3220, AC3221, AC3420, AC3421, AC4220, AC4221.
- Humidificadores: HU1509, HU1510, HU4209, HU4210, HU5710.
Los demás modelos de estas generaciones reciben sus sensores, su interruptor y sus filtros.
Soporte y agradecimientos
Incidencias y comentarios: https://github.com/guim31/gladys-philips-air/issues
El protocolo fue descifrado por Radoslav Gerganov (py-air-control) e implementado por betaboon y kongo09 (aioairctrl, philips-airpurifier-coap para Home Assistant); esta integración se lo debe todo. Sin relación con Philips ni Versuni.
Parámetros de configuración
Estos son los parámetros que Philips Air te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Conectar sus purificadores | section | No | Gladys se comunica con los purificadores Philips en su red local, sin la nube de Philips. Configure primero el purificador en la aplicación Philips Air+ y después introduzca su dirección IP abajo (mejor una dirección fija en su router). Sin relación con Philips ni Versuni. |
| Direcciones IP de los purificadores | string | No | Separadas por comas. Su router las muestra (el aparato suele llamarse «MXCHIP»). |
| Intervalo de actualización | select | No | Frecuencia de lectura de cada purificador. Los cambios suelen llegar al instante; esta lectura es la red de seguridad. |
| Aviso de cambio de filtros | select | No | Cuándo se activa el disparador «Mantenimiento necesario» para un filtro por cambiar (HEPA, carbón, mecha). El prefiltro se avisa cuando el purificador lo pide. |
| Idioma de los nombres | select | No | Nombres de los nuevos dispositivos, sus funciones, la lista de modos y los mensajes del disparador. |
Cómo instalar Philips Air en Gladys
- En Gladys, abre Integraciones: Philips Air 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-philips-air: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-philips-air.
Philips Air 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
Philips Air 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