Integración domótica Valetudo, gratuita y de código abierto
Robots aspiradores sin nube gracias a Valetudo: control, habitaciones, mapa, consumibles.
Publicado por William-De71
- Dispositivos
- Versión 0.1.0
- Requiere Gladys >=5.3.0
- ★ 0
Presentación
Esta integración controla los robots aspiradores que funcionan con Valetudo (valetudo.cloud), el firmware libre que sustituye a la nube del fabricante, mediante su API REST local oficial: sin cuenta, nada sale de su red. Cada robot se convierte en un dispositivo de Gladys con las funciones nativas de robot aspirador (estado, limpieza, vuelta a la base, batería), sus niveles de aspiración y de agua y la vida restante de sus consumibles. Las acciones de escena limpian habitaciones por su nombre y controlan el robot; los desencadenantes de escena avisan cuando empieza o termina una limpieza, cuando el robot está en error o le necesita. Tres widgets del panel muestran el robot, su mapa en directo y su mantenimiento.
Sin relación con el proyecto Valetudo. Todavía no probada con un robot real: las peticiones siguen la API oficial de Valetudo 2026.10; sus comentarios son bienvenidos.
Requisitos previos
- Gladys Assistant 5.3.0 o posterior.
- Un robot aspirador con Valetudo, en la misma red que Gladys, cuya página de Valetudo se abra en un navegador.
- Idealmente, una dirección IP fija para el robot en su router. Limpiar habitaciones requiere un robot con segmentación por habitaciones y un mapa guardado.
Configuración
- Instale la integración desde la tienda y abra su configuración.
- Deje activado Encontrar los robots automáticamente (mDNS). Para un robot en otra red, escriba su dirección (IP o nombre, con
:puertosi hace falta) en Direcciones de los robots (opcional). - Si la autenticación HTTP está activada en Valetudo (Settings → Connectivity → Auth settings), escriba el mismo Usuario y la misma Contraseña.
- Elija el Idioma de los textos de los dispositivos y pulse Buscar y probar los robots: el mensaje lista cada robot encontrado, con su dirección y su batería.
- Abra la pestaña Descubrir y añada sus robots.
Uso
Cada robot tiene estas funciones, según lo que Valetudo ofrezca para él:
| Función | Tipo | Qué hace |
|---|---|---|
| Estado | robot aspirador, sensor | Detenido, limpiando, en pausa, error, volviendo, cargando, en la base |
| Limpieza | robot aspirador, lista | Detener, Limpiar (inicia o reanuda), Cartografiar (una pasada de cartografía, si puede) |
| Volver a la base | robot aspirador, botón | Envía el robot a su base |
| Batería | batería, % | Nivel de carga |
| Aspiración | lista | Los niveles de aspiración del robot |
| Agua | lista | Los niveles de agua (robots que friegan) |
| Modo | lista | Aspirar, fregar, aspirar y fregar… (robots que lo ofrecen) |
| Consumible | mantenimiento, % | Vida restante de cada cepillo, filtro, mopa… que la indique |
Valetudo envía los cambios en cuanto se producen; los consumibles y las estadísticas se leen cada pocos minutos.
Widgets del panel
- Robot aspirador: estado, batería, superficie y duración de la limpieza en curso, aspiración y agua, el mensaje de error; botones Iniciar / Pausa / Reanudar, A la base, Localizar y Limpiar habitación (elija la habitación y las pasadas).
- Mapa del robot: el mapa en directo dibujado por la integración (habitaciones en colores, paredes, trayecto, robot en azul, base en verde, paredes virtuales y zonas prohibidas en rojo), con la habitación en limpieza en ámbar.
- Mantenimiento del robot: superficie, tiempo y número de limpiezas totales, cada consumible del más gastado al menos (insignia Cambiar por debajo del 10 %, Pronto por debajo del 25 %), y Reiniciar después de cambiar uno.
Escenas
Acciones: Limpiar habitaciones con un robot aspirador (nombres de las habitaciones tal como están en Valetudo, sin tener en cuenta tildes ni mayúsculas, o números de habitación, separados por comas; pasadas; aspiración y agua opcionales ajustadas antes; devuelve las habitaciones enviadas) y Controlar un robot aspirador (iniciar o reanudar, pausar, detener, volver a la base, localizar, vaciar el depósito en la base, lavar o secar la mopa en la base).
Desencadenantes: limpieza iniciada, limpieza terminada (con la superficie en m² y la duración en minutos), error (con el mensaje del robot), requiere atención (depósito de polvo lleno, consumible gastado, recordatorio de la mopa, algo que falta, cambio de mapa por aceptar; filtrable por motivo), deja de responder y vuelve a responder. El nombre del robot siempre está disponible como variable.
Ejemplos:
- Cuando todos salen de casa → limpiar «Cocina, Salón» dos veces.
- Cuando termina la limpieza → enviar «{{triggerEvent.data.area_m2}} m² limpiados» a su teléfono.
- Cuando el robot requiere atención porque el depósito de polvo está lleno → hacer parpadear la luz del recibidor.
Solución de problemas
- No se encuentra ningún robot: compruebe que su página de Valetudo se abre en su dirección desde otro aparato, luego escriba esa dirección en la configuración y use Buscar y probar los robots. El mDNS no atraviesa las VLAN ni las redes de invitados.
- «rechaza el usuario o la contraseña»: las credenciales no coinciden con la autenticación HTTP de Valetudo.
- «no puede hacer esto»: Valetudo no ofrece esa capacidad para este robot (una función de la base, las habitaciones, la cartografía); el mensaje la nombra.
- No hay mapa en el widget: el robot todavía no tiene un mapa guardado; deje que termine una primera limpieza completa.
- Para informar de un problema, indique las versiones de Gladys, de la integración y de Valetudo, el modelo del robot, el mensaje del botón de prueba y los registros (añada
DEBUG=gladys-integration-sdken modo desarrollador): abrir una issue.
Parámetros de configuración
Estos son los parámetros que Valetudo te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Antes de empezar | section | No | Para robots aspiradores con Valetudo (valetudo.cloud), el firmware libre que sustituye la nube del fabricante. Gladys habla con el robot mediante su API REST local oficial: sin cuenta, nada sale de su red. Instale primero Valetudo en el robot y después abra la pestaña Descubrir. |
| Encontrar los robots automáticamente (mDNS) | boolean | No | Valetudo se anuncia en la red local; Gladys lo escucha. Desactívelo para usar solo las direcciones escritas. |
| Direcciones de los robots (opcional) | string | No | Para un robot que la búsqueda automática no alcanza (otra red, mDNS desactivado en Valetudo). Dirección IP o nombre, con :puerto si hace falta; sepárelas con comas. Asigne al robot una dirección fija en su router. |
| Contraseña de Valetudo (si la hay) | section | No | Solo si la autenticación HTTP está activada en Valetudo (Ajustes → Conectividad → Auth settings). Se usan el mismo usuario y la misma contraseña para todos los robots. |
| Usuario | string | No | |
| Contraseña | secret | No | |
| Idioma de los textos de los dispositivos | select | No | Nombres de las funciones y opciones en la pestaña Descubrir, mensajes de los disparadores y errores de las acciones de escena. Gladys no envía su idioma con ellos. |
| ¿No se encuentra un robot? | section | No | Compruebe que el robot está en su base y en la misma red que Gladys, y que la página de Valetudo se abre en un navegador en su dirección; luego escriba esa dirección en el campo de arriba y use «Buscar y probar los robots». |
Cómo instalar Valetudo en Gladys
- En Gladys, abre Integraciones: Valetudo 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/william-de71/gladys-valetudo:0.1.0), 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/William-De71/gladys-valetudo.
Valetudo requiere Gladys >=5.3.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
Valetudo 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 William-De71, 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