Sensores de calidad del agua (pH, ORP) + indicadores configurables con umbrales de color

Desarrollo
1

Hola a todos :waving_hand:

Quería compartir 2 PRs que acabo de abrir, relacionados con un caso concreto: integrar mi sonda iopool Eco (monitoreo de la calidad del agua de la piscina) en Gladys a través de MQTT.

He subido la sonda en Node-RED, que publica en el broker MQTT, lo que me permite crear un dispositivo virtual MQTT en Gladys con las siguientes funcionalidades: temperatura, pH, ORP (capacidad de desinfección), modo, duración de filtrado recomendada, fecha de la última medición.

El problema: para el pH y el ORP, ninguna categoría de sensor coincidía. Tuve que poner « Desconocido » para el pH y « Índice de calidad del aire » para el ORP (porque airquality-sensor era lo que más se parecía). No es ideal.

Por lo tanto, he hecho 2 PRs (pila):

PR 1 — Categorías de sensores para la calidad del agua

:link: Add water quality sensor categories (pH, ORP) by Terdious · Pull Request #2530 · GladysAssistant/Gladys · GitHub

Añadí 2 categorías genéricas, reutilizables por cualquier integración (MQTT, Z2M, Matter, servicios personalizados):

  • ph-sensor — pH del agua, rango 0–14, nueva unidad sin dimensión ph
  • orp-sensor — Potencial de oxidación-reducción (Redox / « Capacidad de desinfección »), en milivolt (unidad existente)

Cubre las sondas de piscina (iopool, Ondilo, BWT), acuarios, estaciones de medición de agua de lluvia, etc.

Convención de nomenclatura: términos científicos estándar (no capacite-desinfection-sensor). Pero el texto en FR mantiene « ORP / Capacidad de desinfección » para ser accesible al público en general.

¿Por qué no hay coloración automática en el widget « Dispositivo »?

Pregunta legítima: la calidad del aire (CO2, PM2.5, VOC…) muestra una etiqueta de color automáticamente en el widget Dispositivo según el valor. ¿Por qué no hacer lo mismo para el pH y el ORP?

Porque solo funciona para mediciones con umbrales universales. El CO2 a 1200 ppm es malo en todas partes, sin importar el contexto — es una norma sanitaria mundial.

El pH y el ORP, en cambio, son escalas absolutas cuyo rango « correcto » depende completamente del uso:

Uso pH ideal ORP ideal
Piscina 7.0 – 7.4 650 – 750 mV
Acuario de agua dulce 6.5 – 7.5 250 – 400 mV
Acuario de arrecife 8.1 – 8.4 350 – 450 mV
Agua potable 6.5 – 8.5 —
Hidroponía 5.5 – 6.5 —

Si codificáramos umbrales de piscina en el widget Dispositivo, un usuario de acuario vería su valor en rojo aunque su agua esté perfecta. Engañoso.

A esto se suma un detalle técnico: la coloración de la calidad del aire es monótona (« cuanto más bajo, mejor »). El pH es una banda: malo abajo y arriba, bueno en el medio. La lógica existente simplemente no se aplica.

Por eso la coloración por umbrales pasa por la PR2 (medidor configurable): cada uno define sus propios umbrales según su uso. Neutral, correcto para todos, y reutilizable mucho más allá de la calidad del agua (batería, nivel de tanque, etc.).

PR 2 — Medidor configurable con umbrales de color

:link: Gauge dashboard widget: add configurable color thresholds by Terdious · Pull Request #2531 · GladysAssistant/Gladys · GitHub

Retoma la lógica de umbral + color ya presente en los widgets « Temperatura de la habitación » y « Humedad de la habitación », pero de manera genérica en el widget Medidor:

  • Casilla de verificación « Configurar umbrales personalizados » en el editor
  • Doble control deslizante para definir los 2 umbrales (los límites del control deslizante provienen del min/max de la característica, por lo que coherente con pH 0-12, ORP 500-1100, batería 0-100, etc.)
  • 3 selectores de color (zona baja / dentro del rango / zona alta) con la paleta del widget chart
  • Leyenda debajo del medidor con los 3 colores y los límites formateados con la unidad
  • Sin umbrales personalizados → se conserva el degradado ApexCharts original (cero regresión)

image
image871×356 15.4 KB

image
image954×490 17.8 KB

¿Por qué estas elecciones de diseño?

  • Categorías separadas en lugar de una categoría paraguas water-quality-sensor con varios tipos: alineado con el patrón existente (co2-sensor, pm25-sensor, voc-sensor, etc. — 1 categoría = 1 medida física)
  • Medidor configurable en lugar de un widget dedicado a piscinas: genérico = útil para muchos más casos de uso (batería de vehículo eléctrico, humedad del suelo, dB, nivel de tanque, etc.)
  • Sin coloración inteligente codificada por categoría (como « pH entre 7.0-7.4 = verde »): dejado al criterio del usuario a través del editor, para mantenerse neutral sobre las convenciones comerciales (piscina ≠ acuario ≠ spa)

¡Feedback bienvenido :folded_hands: — especialmente sobre:

  1. La nomenclatura de las categorías (ph-sensor / orp-sensor vs alternativas?)
  2. El texto en FR para ORP — ¿« Capacidad de desinfección » es lo suficientemente claro para quienes no conocen la química del agua?
  3. ¿Alguien más tiene casos de uso (acuarios, agua de lluvia, hidroponía…) que se beneficiarían de estas categorías o que requerirían otras (TDS, conductividad, salinidad)?
  4. El medidor configurable — ¿ven otros widgets que merecerían el mismo tratamiento de umbrales/colores?

Gracias por su lectura :slightly_smiling_face:

2

Llevo mucho tiempo buscando una sonda para mi piscina. Siempre he tenido miedo de lanzarme por miedo a que la calibración fuera totalmente mala / se modificara demasiado con el tiempo.

¿Puedes decirme cómo te va por tu lado? :wink:

3

Hola @guim31,

Sí, por supuesto, tengo este sensor desde 2022, compré uno para un compañero en 2023 (Sel), y otro para mi padre en 2024 (Sel también).

Por mi parte, uso Oxígeno Activo durante el verano, tuve un problema de valor erróneo en 2024, compré el kit de recalibración y luego todo volvió a la normalidad.
Lo reemplacé por completo al reiniciar en 2025 porque ya no tenía batería (dada por 2 años, duró 3 veranos). Desafortunadamente, era la primera versión y no era desmontable para reemplazar solo la batería, por lo que tuve que comprar la nueva versión completa.
Las nuevas pueden abrirse con tornillos en la cabeza y, por lo tanto, se puede reemplazar el sensor o la batería de forma independiente.

Mi compañero tiene la nueva versión, aún no ha tenido ningún problema, quizás al reiniciar este año para la batería. En cuanto al sensor, es metrólogo y su opinión es que funciona muy bien. Las derivas son normales en este tipo de uso con hibernación en invierno, pero la calibración no tiene problemas. En cuanto al sensor, como metrólogo, da una vida útil de 5 a 10 años, es totalmente normal. Para un uso de oxígeno activo o cloro, los sensores son más baratos.

Mi padre vive en el sur, no lo hiberna, y hasta ahora no ha tenido ningún problema, ni siquiera una recalibración.

Para la supervisión de la desviación para recalibración, se pueden hacer pruebas de tira directamente con la aplicación para detectar las desviaciones. También me he equipado con un sensor electrónico de pH y ORP para mayor fiabilidad.

4

Yo personalmente no conocía ORP, pero Redox sí me suena mucho más, porque cuando tengo que comprobar, es el Redox lo que verifico (yo también estoy en sal).
De hecho, para las piscinas, se habla más de Redox que de ORP (o entonces necesito encontrar una piscina más grande :joy:).
Yo estaría más a favor de tener redox-sensor que orp-sensor, ¿qué opinas?

Y genial para el desarrollo, gracias por todo lo que haces :wink:

5

¡Parece genial! ¡Excelente desarrollo! :slight_smile:

Te aviso en cuanto pueda echarle un vistazo.

¿No tendría sentido que tu sonda tuviera un plugin Matterbridge?

No dudes en probar la fábrica, para eso está hecha :wink: (aunque, para ti que ya usas Claude Code, no te va a impresionar tanto).

6

¡Muchas gracias por tu respuesta! ¡Voy a mirarlo más de cerca gracias a ti!!!

7

Hola mutmut,

Tienes razón sobre el contexto de las piscinas en Francia: Redox es efectivamente el término dominante (Zodiac, Hayward, CCEI… todos etiquetan sus reguladores como « Redox »). Un pequeño matiz, sin embargo: « para las piscinas, se habla más de Redox que de ORP » → es cierto en Francia, pero a nivel internacional (y en inglés en general), ORP sigue siendo el estándar según mis breves investigaciones. Y en otros ámbitos que podrían utilizar esta categoría — acuariofilia, hidroponía, tratamiento de agua potable — ORP también domina, especialmente porque casi todas las sondas vendidas en línea están etiquetadas como « ORP probe ».
Técnicamente, ambos designan exactamente lo mismo (potencial de oxidación-reducción en mV), es solo una cuestión de uso regional/sectorial.

Por lo tanto, propondría un compromiso: mantener orp-sensor en el código (coherencia internacional, más universal para el SEO y la búsqueda de material), pero mostrar « Redox / ORP » en la interfaz de usuario en francés.
Así se habla a todo el mundo, desde los piscinistas franceses hasta los acuariófilos, sin excluir a nadie.

¿Qué opinas?

8

¡Gracias, Pierre-Gilles! :grinning_face_with_smiling_eyes:

¿Por qué no para el plugin Matterbridge! La conexión a la API de iopool es bastante sencilla, y ya existe una integración de ejemplo en Home Assistant de la que podemos inspirarnos.
De mi parte, puedo compartir mi flujo de Node-RED que ya hace el trabajo, debería dar una buena base para el desarrollo.

Pero será más para la comunidad que para mí: realmente no soy fan de Matter por el momento :sweat_smile:

Voy a probar la fábrica con gusto, un poco curioso de ver qué sale.

9

Me parece un buen compromiso :+1:

10

¡Hecho!

Problema creado por la IA => para la IA :sweat_smile: :

Con un punto planteado por Claude Opus 4.7 :

« La única reserva honesta que hay que tener en mente: pH y ORP no tienen un clúster Matter estándar, por lo que la representación en Gladys probablemente será impecable para la temperatura y « best-effort » para pH/ORP — es precisamente el tipo de retroalimentación que Pierre-Gilles espera de esta prueba. »

EDIT :

Hemos investigado el tema en Matter: verificación directa
en el SDK oficial (project-chip/connectedhomeip) la lista de clústeres de
medición. Veredicto — Matter no tiene ningún clúster pH ni ORP/Redox. Los únicos
clústeres « de sustancia » son los 10 Concentration Measurement (CO, CO2, NO2,
ozono, PM1/2.5/10, formaldehído, COV, radón) : 100 % calidad del aire.

Búsqueda de pH Measurement, pH Measurement, redox, water quality en todo el SDK → 0 resultados.

En cuanto a la calidad del agua, es un tema mixto :

  • El espacio de IDs de Matter reserva clústeres para muchos parámetros
    de agua (cloro, flúor, turbidez, oxígeno disuelto…), heredados de Zigbee — pero
    no están implementados : solo existen 10 clústeres Concentration Measurement
    y son los 10 de calidad del aire.
  • Sobre todo : pH y ORP están ausentes incluso del espacio reservado. Y es lógico
    — no son concentraciones (el pH es una escala log, el ORP un potencial en mV), por lo que ningún modelo de clúster Matter actual puede representarlos.

Conclusión :

  • Temperatura → un plugin Matterbridge tiene todo el sentido (clúster estándar,
    ya mapeado por Gladys).
  • pH / ORP → Matter no puede representarlos estructuralmente hoy en día.
    La ruta MQTT de la PR1 (ph-sensor / orp-sensor) sigue siendo la única
    funcional — los dos enfoques son complementarios.

Aún así : el SDK ha ganado recientemente un clúster soil-measurement
(humedad del suelo), por lo que la CSA añade nuevos clústeres de nicho con el tiempo. Un clúster « water quality » algún día no es imposible — pero es a largo plazo, por parte de la CSA.

Voy a probar la fábrica para la parte de temperatura, te haré un
retorno ! :slightly_smiling_face:

EDIT 2 :
Por si acaso, hemos creado un problema en el único lugar posible del proyecto Matter :

11

He probado el plugin generado por la fábrica en mi instancia de Matterbridge (3.7.9). Primer balance :backhand_index_pointing_down:

:white_check_mark: Lo que funciona bien

  • El plugin se instala y funciona (estado Running), se conecta a la API de iopool, descubre mi piscina y la nombra correctamente (« Piscina DUBLEM », el nombre definido en iopool).
  • La temperatura del agua es perfecta: se remonta en un cluster real de Matter TemperatureMeasurement → 11.15 °C, utilizable nativamente. Para esta parte, el plugin hace exactamente el trabajo.

:warning: La trampa pH / ORP — exactamente lo que habíamos anticipado

Matter no tiene ningún cluster pH ni ORP, por lo que la IA ha hecho lo mejor: expone el pH y el ORP… en clusters TemperatureMeasurement también. Resultado:

  • 3 « sensores de temperatura » para una sola piscina (agua + pH + ORP).
  • pH: el número correcto (6.69) pero mostrado en °C.
  • ORP: directamente incorrecto — mostrado 5.73 en lugar de 573 mV. El cluster de temperatura está en centígrados (÷100 del lado del controlador), y el ORP no cabe en esta escala → valor dividido por 100.

:cross_mark: Otro error detectado: el estado « En línea »

El dispositivo está marcado como « En línea » permanentemente (reachable = true fijo). Esto solo refleja el éxito de la llamada a la API en la nube, no el estado real de la sonda — mi sonda está actualmente fuera del agua y el plugin la muestra como « En línea » con los últimos valores en caché. La API de iopool proporciona isValid + measuredAt para manejar esto correctamente.

:magnifying_glass_tilted_left: Conclusión

La fábrica ha producido un muy buen primer borrador: conexión, descubrimiento, temperatura → perfecto. Pero esto confirma de manera inequívoca el problema fundamental: Matter no puede estructuralmente soportar el pH y el ORP. La « solución de temperatura » es la única posible hoy, pero da datos falsos/engañosos en cualquier controlador.

:person_raising_hand: Decisión a tomar — @pierre-gilles

He preparado un informe detallado para el problema #15 (lista de verificación + errores + causa raíz). Antes de publicarlo, tu opinión sobre el pH/ORP del lado del plugin Matterbridge:

  1. Los mantenemos en el plugin, documentando claramente las trampas (pH = leer el valor sin la unidad, ORP = ×100 mentalmente) ?
  2. Los eliminamos del plugin Matter y asumimos « solo temperatura » como entrega de Matter, dejando el pH/ORP en el canal MQTT (categorías ph-sensor/orp-sensor de mi PR) hasta que Matter tenga los clusters ?

El error reachable/« En línea » y un productUrl cosmético son corregibles con un --fix de la fábrica, sin importar lo que pase.

(En paralelo, he creado una solicitud de función en project-chip/connectedhomeip para clusters pH/ORP reales — tema a largo plazo 6-24 meses, si se tiene en cuenta.)

12

En este caso, la gran ventaja de los plugins Matterbridge es que no necesitas mi ayuda, haz lo que mejor te parezca :wink:

Mi objetivo es no ser un cuello de botella en estos temas, libertad total :wind_face:

¡Genial!

13

Perfecto, me tomo la libertad de decidir :slightly_smiling_face:

Por lo tanto, voy a cerrar la solicitud sobre la fábrica de plugins (issue #15) — un plugin de Matterbridge no tiene sentido para este tipo de dispositivo:

  • Matter no tiene ningún clúster de pH ni ORP.
  • Consecuencia, el plugin generado solo puede exponer correctamente la temperatura — es decir, ~10 % del interés de una sonda de ~250 €, mientras que un simple sensor de temperatura de agua cuesta ~20 €.
  • El pH y el ORP, en cambio, quedan inutilizables.

A destacar: la fábrica ha funcionado muy bien — instalación, conexión API, descubrimiento de la piscina y temperatura: todo perfecto desde el primer intento. El problema es la especificación Matter. He dejado un informe de prueba detallado en la issue antes de cerrarla.

En su lugar, voy a redactar un tutorial en el foro para el manejo de estas sondas a través de Node-RED. Esta vía recupera 100 % de los datos (temperatura, pH, ORP, modo, consejo de filtración, alerta de consejo de tratamiento), ya funciona muy bien en mi casa desde hace 3 años, y se basará en las nuevas categorías ph-sensor / orp-sensor de mi PR.

Y a largo plazo, he abierto una feature request en project-chip/connectedhomeip para clústeres reales de pH/ORP en Matter — el día que se concrete, la ruta Matter volverá a ser relevante para estos sensores.

14

La primera PR se ha fusionado y está disponible en Gladys Assistant 4.75: Release v4.75.0 · GladysAssistant/Gladys · GitHub

15

He avanzado en esta PR, está listo para mí, está fusionado y saldrá en la próxima versión de Gladys :slight_smile:

16

Disponible en Gladys Assistant 4.77: