Valetudo smart home integration, free and open source
Robot vacuums freed from the cloud by Valetudo: control, rooms, live map, consumables.
Published by William-De71
- Devices
- Version 0.1.0
- Requires Gladys >=5.3.0
- ★ 0
Overview
This integration drives robot vacuums running Valetudo (valetudo.cloud), the open firmware that replaces the manufacturer cloud, through its official local REST API: no account, nothing leaves your network. Each robot becomes a Gladys device with the native robot vacuum features (state, cleaning, dock, battery), its suction and water presets and the remaining life of its consumables. Scene actions clean rooms by name and control the robot; scene triggers tell when a cleaning starts or ends, when the robot is in error or needs you. Three dashboard widgets show the robot, its live map and its maintenance.
Not affiliated with the Valetudo project. Not tested on a real robot yet: the requests follow the official API of Valetudo 2026.10; feedback is welcome.
Prerequisites
- Gladys Assistant 5.3.0 or later.
- A robot vacuum running Valetudo, on the same network as Gladys, whose Valetudo page opens in a browser.
- Ideally, a fixed IP address for the robot in your router. Cleaning rooms needs a robot with room segmentation and a saved map.
Configuration
- Install the integration from the store, then open its configuration.
- Leave Find the robots automatically (mDNS) on. For a robot on another network, type its address (IP or name, with
:portif needed) in Robot addresses. - If HTTP authentication is on in Valetudo (Settings → Connectivity → Auth settings), type the same user name and password.
- Choose the language of the device texts and click Search and test the robots: the message lists every robot found, with its address and battery.
- Open the Discover tab and add your robots.
Usage
Every robot gets these features, depending on what Valetudo offers for it:
| Feature | Type | What it does |
|---|---|---|
| State | robot vacuum, sensor | Stopped, cleaning, paused, error, returning, charging, docked |
| Cleaning | robot vacuum, list | Stop, Clean (starts or resumes), Map (a mapping pass, when supported) |
| Dock | robot vacuum, button | Sends the robot back to its dock |
| Battery | battery, % | Charge level |
| Suction | list | The suction presets of the robot |
| Water | list | The water presets (mopping robots) |
| Mode | list | Vacuum, mop, vacuum and mop… (robots that offer it) |
| Consumable | maintenance, % | Remaining life of each brush, filter, mop pad… that reports it |
Changes are pushed by Valetudo as they happen; consumables and statistics are read every few minutes.
Dashboard widgets
- Robot vacuum: state, battery, area and duration of the current run, suction and water, the error message; buttons Start / Pause / Resume, Dock, Locate and Clean a room (choose the room and the passes).
- Robot map: the live map drawn by the integration (rooms in colors, walls, path, robot in blue, dock in green, virtual walls and no-go areas in red), the room being cleaned in amber.
- Robot maintenance: lifetime area, time and runs, every consumable from the most worn (badge Replace under 10 %, Soon under 25 %), and Reset after you replaced one.
Scenes
Actions: Clean rooms with a robot vacuum (room names as set in Valetudo, accents and case ignored, or room numbers, separated by commas; passes; optional suction and water set first; returns the rooms sent) and Control a robot vacuum (start or resume, pause, stop, back to the dock, locate, empty the bin at the dock, wash or dry the mop at the dock).
Triggers: cleaning started, cleaning finished (with the area in m² and the duration in minutes), error (with the message of the robot), needs attention (dust bin full, consumable worn out, mop pad reminder, something missing, map change to accept; filter by reason), not answering and answering again. The robot name is always a variable.
Examples:
- When everybody leaves home → clean "Kitchen, Living room" twice.
- When the cleaning is finished → send "{{triggerEvent.data.area_m2}} m² cleaned" to your phone.
- When the robot needs attention because the dust bin is full → flash the hall light.
Troubleshooting
- No robot found: check that its Valetudo page opens at its address from another device, then type that address in the configuration and use Search and test the robots. mDNS does not cross VLANs or guest networks.
- "refuses the user name or password": the credentials do not match the HTTP authentication of Valetudo.
- "cannot do this": Valetudo has no such capability for this robot (a dock function, rooms, mapping); the message names it.
- No map in the widget: the robot has no saved map yet; let it finish a first full cleaning.
- For a bug report, give the versions of Gladys, of the integration and of Valetudo, the robot model, the message of the test button and the logs (add
DEBUG=gladys-integration-sdkin developer mode): open an issue.
Configuration settings
These are the settings Valetudo asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Before you start | section | No | For robot vacuums running Valetudo (valetudo.cloud), the open firmware that replaces the manufacturer cloud. Gladys talks to the robot through its official local REST API: no account, nothing leaves your network. Install Valetudo on the robot first, then open the Discover tab. |
| Find the robots automatically (mDNS) | boolean | No | Valetudo announces itself on the local network; Gladys listens for it. Turn it off to use the typed addresses only. |
| Robot addresses (optional) | string | No | For a robot the automatic search does not reach (another network, mDNS off in Valetudo). IP address or name, with :port if needed; separate them with commas. Give the robot a fixed address in your router. |
| Valetudo password (if set) | section | No | Only when HTTP authentication is on in Valetudo (Settings → Connectivity → Auth settings). The same user name and password are used for every robot. |
| User name | string | No | |
| Password | secret | No | |
| Language of the device texts | select | No | Feature and option names in the Discover tab, messages of the scene triggers and errors of the scene actions. Gladys does not send your language with them. |
| A robot is not found? | section | No | Check that the robot is on its dock and on the same network as Gladys, that the Valetudo page opens in a browser at its address, then type that address in the field above and use “Search and test the robots”. |
How to install Valetudo in Gladys
- In Gladys, open Integrations: Valetudo appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/william-de71/gladys-valetudo:0.1.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/William-De71/gladys-valetudo.
Valetudo requires Gladys >=5.3.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Valetudo is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by William-De71, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation