Integración domótica Qingping, gratuita y de código abierto
Monitores de aire y termómetros Qingping vía la nube Qingping: CO₂, partículas, COV, temperatura.
Publicado por guim31
- Dispositivos
- Versión 1.0.1
- Requiere Gladys >=5.1.0
- ★ 0
Presentación
Esta integración trae sus monitores de aire y termómetros Qingping a Gladys, mediante la API oficial de la nube Qingping — la nube que usa la aplicación Qingping+. Cada dispositivo de su cuenta Qingping se convierte en un dispositivo de Gladys con lo que mide: temperatura, humedad, CO₂, PM2,5, PM10, COV, ruido, presión, batería y la antigüedad de la última medida.
Además de los valores, ofrece un nivel de calidad del aire legible (Buena, Moderada, Mala, Muy mala) con el contaminante responsable, un widget del panel, disparadores de escena cuando cambia la calidad del aire o un dispositivo deja de enviar datos, y una acción de escena que da la calidad del aire en palabras.
Modelos previstos: Qingping Air Monitor Lite, Air Monitor 2, CO₂ Temp & RH Monitor, los termohigrómetros Wi-Fi (con o sin sonda), el higrómetro Lee Guitars y los sensores Bluetooth sincronizados mediante una pasarela Qingping o la aplicación. Se admite cualquier dispositivo que devuelva la API: las funciones siguen las medidas que envía.
Developed without the hardware: feedback welcome — desarrollada sin el hardware: sus comentarios son bienvenidos. La integración se escribió a partir de la documentación de la API de Qingping y de los clientes de código abierto de la comunidad, y se probó contra una nube simulada. Si algo no funciona con su dispositivo, abra una incidencia en github.com/guim31/gladys-qingping/issues.
Esta integración no está afiliada a Qingping (Qingping Technology / ClearGrass). Qingping es su marca.
Requisitos
- Gladys Assistant 5.1.0 o posterior.
- Sus dispositivos añadidos en la aplicación Qingping+, en modo Qingping (un dispositivo emparejado en modo HomeKit no envía nada a la nube de Qingping).
- Un acceso de desarrollador gratuito en developer.qingping.co, con la misma cuenta que la aplicación.
- Gladys debe tener acceso a Internet (
oauth.cleargrass.comyapis.cleargrass.com, HTTPS).
Configuración
Obtener la App Key y el App Secret
- Añada sus dispositivos en la aplicación Qingping+ y compruebe que muestran valores.
- Inicie sesión en developer.qingping.co con la cuenta de la aplicación (misma región).
- Abra Access Management (enlace directo) y copie la App Key y el App Secret. Es gratuito.
Ajustes
- App Key y App Secret: copiados de Access Management. Gladys guarda el secreto y nunca aparece en los registros.
- Lectura de la nube: Automático (recomendado) lee la nube justo después de cada envío previsto de los dispositivos, según su intervalo de envío. Puede elegir en su lugar un intervalo fijo (de 5 minutos a una hora).
- Idioma de las funciones: los nombres que reciben las funciones al añadir un dispositivo (fijos después) y el idioma de los textos enviados a las escenas. Francés por defecto.
Pulse Probar la conexión: el resultado enumera sus dispositivos y la antigüedad de su última medida. Abra después la pestaña Descubrimiento y añada los dispositivos que desee.
Con qué frecuencia cambian los valores. La nube solo conoce lo que los dispositivos han enviado. Un monitor de aire con batería envía cada 15 minutos por defecto (el intervalo de envío de la aplicación Qingping+); enchufado, puede enviar cada minuto. Un termómetro Bluetooth envía cuando la aplicación o una pasarela lo sincroniza. Leer la nube más a menudo no aporta valores más recientes: en modo automático, la integración la lee una vez por envío previsto — nunca más de una vez cada 2 minutos, nunca menos de una vez por hora. Una sola solicitud lee todos los dispositivos de la cuenta.
Cuotas. Qingping no publica ninguna cuota de solicitudes para su API abierta. La integración pide un token aproximadamente cada 2 horas (se guarda en /data: un reinicio no pide uno nuevo) y hace una solicitud por lectura — unas cien al día con un intervalo de envío de 15 minutos. Cuando la nube responde «demasiadas solicitudes», espera al menos 15 minutos, o más si la nube lo pide.
Dispositivos
Un dispositivo de Gladys por cada dispositivo de su cuenta Qingping, con el nombre de la aplicación Qingping+. Su identidad es su dirección MAC: cambiarle el nombre en la aplicación lo conserva en Gladys.
Funciones
Cada dispositivo recibe las funciones de las medidas que envía, todas de solo lectura:
| Función | Unidad | Modelos |
|---|---|---|
| Temperatura | °C | todos |
| Temperatura de la sonda | °C | termómetros con sonda externa |
| Humedad | % | todos |
| CO₂ | ppm | monitores de aire, monitor de CO₂ |
| PM2,5 | µg/m³ | monitores de aire |
| PM10 | µg/m³ | monitores de aire |
| COV | ppb | Air Monitor (primera generación) |
| Índice COV | 1–500 | Air Monitor 2 (100 = el aire habitual de la sala) |
| Ruido | dB | Air Monitor 2 |
| Presión | kPa | termómetros con barómetro |
| Batería | % | dispositivos con batería |
| Antigüedad de la medida | min | todos: minutos desde el último envío |
La Antigüedad de la medida distingue un valor estable de uno congelado: si supera el doble del intervalo de envío, el dispositivo ya no envía (batería, Wi-Fi, fuera de alcance). La insignia del dispositivo pasa entonces a «inaccesible».
Una medida que un dispositivo empieza a enviar más tarde (un sensor que se calienta tras un reinicio) añade su función: Gladys ofrece entonces Actualizar en la pestaña Descubrimiento. Un sensor que se declara averiado o en precalentamiento no publica nada, en lugar de un valor erróneo.
Nivel de calidad del aire
Cada monitor recibe un nivel de calidad del aire, el peor de sus contaminantes:
| Nivel | CO₂ (ppm) | PM2,5 (µg/m³) | PM10 (µg/m³) | COV (ppb) | Índice COV |
|---|---|---|---|---|---|
| Buena | menos de 800 | menos de 15 | menos de 45 | menos de 220 | menos de 150 |
| Moderada | 800–999 | 15–34 | 45–99 | 220–659 | 150–249 |
| Mala | 1000–1999 | 35–54 | 100–199 | 660–2199 | 250–399 |
| Muy mala | 2000 o más | 55 o más | 200 o más | 2200 o más | 400 o más |
Los umbrales siguen los valores guía del aire interior de la Agencia Federal de Medio Ambiente alemana (CO₂, COV), las directrices 2021 de la OMS y los umbrales de la US EPA (partículas). Para evitar oscilaciones, un nivel solo baja cuando el valor queda un 5 % por debajo del umbral superado. La temperatura, la humedad y el ruido no cuentan: son confort, no calidad del aire. Un termómetro no tiene nivel de calidad del aire.
Widget del panel
Calidad del aire Qingping: añádalo a un panel y elija un dispositivo, o deje el dispositivo vacío para verlos todos.
- Un dispositivo: su nombre, hasta seis mosaicos (CO₂, PM2,5, temperatura, humedad, PM10, COV…) coloreados según el nivel, y después la calidad del aire en palabras con su causa (por ejemplo Mala · CO₂), la antigüedad de la última medida y la batería.
- Todos los dispositivos: una línea por dispositivo con su calidad del aire, o su temperatura y humedad para un termómetro.
Un dispositivo que ya no envía muestra Sin medida reciente en lugar de un nivel congelado. El widget funciona incluso antes de añadir los dispositivos a Gladys.
Disparadores de escena
- Calidad del aire cambiada: el nivel de un monitor ha cambiado. Filtros: el monitor, el nuevo nivel, el sentido (Empeora o Mejora). Variables: nombre del monitor, nivel, nivel anterior, contaminante principal, sentido, CO₂ y PM2,5.
- Dispositivo sin datos: ninguna medida nueva en dos intervalos de envío (30 minutos como mínimo), o la nube de Qingping indica que el dispositivo está sin conexión. Variables: nombre del dispositivo, minutos desde la última medida, sin conexión para Qingping.
- Dispositivo de vuelta: un dispositivo que había dejado de enviar datos ha enviado una nueva medida. Variable: minutos sin medida.
Para reaccionar a un valor que supera un umbral (CO₂ por encima de 1200 ppm, temperatura por debajo de 5 °C), utilice el disparador habitual de Gladys sobre la función del dispositivo: ya compara valores.
Acción de escena
Obtener la calidad del aire: lee la calidad del aire de un monitor a partir de su última medida (sin solicitud a la nube) y la entrega a las acciones siguientes de la escena: el nivel (código, número de 1 Buena a 4 Muy mala, y etiqueta), el contaminante principal, el CO₂, las PM2,5, los minutos desde la medida y si la medida es reciente. Úsela en un mensaje («Aire del dormitorio: {nivel}») o en una condición «continuar solo si».
Acciones de configuración
- Probar la conexión: lee la nube de inmediato y enumera los dispositivos con la antigüedad de su medida.
- Ajustar el intervalo de envío: cambia la frecuencia de envío de un monitor de aire (de 1 minuto a 1 hora). El dispositivo lo aplica en su próximo envío y la integración sigue el nuevo ritmo. Un intervalo corto agota la batería mucho más rápido: mantenga 15 minutos con batería. Los demás dispositivos (termómetros) se ajustan en la aplicación Qingping+.
Ejemplos de escenas
- Ventilar el dormitorio: disparador Calidad del aire cambiada, monitor Dormitorio, nuevo nivel Mala y Muy mala, sentido Empeora → enviar «Abra la ventana del dormitorio: {contaminante principal} elevado», o encender la ventilación.
- El aire vuelve a ser bueno: disparador Calidad del aire cambiada, nuevo nivel Buena, sentido Mejora → apagar la ventilación.
- Revisar el monitor: disparador Dispositivo sin datos → enviar «{nombre del dispositivo} no envía datos desde hace {minutos} min: ¿batería o Wi-Fi?».
- Informe matinal: cada día a las 7:00 → Obtener la calidad del aire del dormitorio → enviar «Aire del dormitorio: {nivel}, CO₂ {co2} ppm».
Solución de problemas
- «Qingping ha rechazado la App Key o el App Secret»: vuelva a copiar ambos desde Access Management, sin espacios, y guarde. Compruebe que inició sesión en developer.qingping.co con la cuenta de la aplicación.
- Conectado, pero sin dispositivos: los dispositivos deben estar en la aplicación Qingping+ de la misma cuenta, en modo Qingping (no HomeKit). Un dispositivo emparejado solo en HomeKit no llega a la nube de Qingping.
- Los valores no cambian: mire la Antigüedad de la medida. Si aumenta, el dispositivo no envía (batería, Wi-Fi, pasarela). Si se mantiene baja, los valores simplemente son estables.
- Falta una función: espere una medida en la que el sensor la envíe (un sensor de CO₂ se calienta unos minutos tras un reinicio) y pulse Actualizar en el dispositivo en la pestaña Descubrimiento.
- Más detalles: ajuste
LOG_LEVEL=debugen la integración para ver cada lectura en sus registros. El App Secret y el token nunca aparecen.
Limitaciones
- Solo nube: la integración lee la nube de Qingping, nunca los dispositivos de su red. Sin Internet, los valores se detienen (los dispositivos conservan su historial en la nube).
- Los valores son tan recientes como los envíos de los dispositivos: 15 minutos por defecto con batería.
- Solo lectura: el único ajuste que modifica la integración es el intervalo de envío de los monitores de aire, a petición.
- Un hueco en el historial mientras Gladys estaba apagado no se recupera: solo se lee la última medida.
- Los dispositivos que la nube de Qingping no expone (modo HomeKit, algunos sensores solo Bluetooth sin pasarela) no pueden aparecer.
- Desarrollada sin el hardware ni una cuenta: las respuestas de la API se reconstruyeron a partir de la documentación de Qingping y de clientes de la comunidad. Informe de cualquier anomalía en github.com/guim31/gladys-qingping/issues.
Parámetros de configuración
Estos son los parámetros que Qingping te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Su cuenta Qingping | section | No | Gratuito. Inicie sesión en developer.qingping.co con la cuenta de la aplicación Qingping+, abra Access Management y copie la App Key y el App Secret. Los dispositivos deben estar en la aplicación Qingping+ (modo Qingping, no HomeKit). |
| App Key | string | Sí | La App Key que aparece en Access Management en developer.qingping.co. |
| App Secret | secret | Sí | El App Secret, junto a la App Key. Gladys lo guarda y nunca aparece en los registros. |
| Lectura de la nube | select | No | Automático: justo después de cada envío previsto de los dispositivos (su intervalo de envío, ajustado en la aplicación Qingping+). Leer más a menudo no aporta valores más recientes. |
| Idioma de las funciones | select | No | Nombres de las funciones al añadir un dispositivo e idioma de los textos de escenas. |
Cómo instalar Qingping en Gladys
- En Gladys, abre Integraciones: Qingping 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-qingping: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-qingping.
Qingping 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
Qingping 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