Valetudo is a production-grade, self-contained control web interface for robot vacuums. It replaces vendor cloud services by running directly on the vacuum's embedded Linux hardware and communicating with the robot over reverse-engineered local protocols (MiIO/MIoT for Dreame and Roborock, MSmart for Midea, and 3irobotix for Viomi). The backend is a Node.js/Express application that exposes a REST API with OpenAPI schemas, server-sent events for live state/map/log updates, MQTT integration for Home Assistant and Homie discovery, an updater for over-the-air firmware-style binary updates, timers, consumables, and map management. The frontend is a React/TypeScript SPA with a canvas-based interactive map renderer, manual control, provisioning, timers, updater UI, and configuration pages.
This repository implements a custom Lovelace card for Home Assistant that displays an interactive map of a robot vacuum's environment. It allows users to select zones, rooms, points, or paths for cleaning and sends corresponding service calls to the vacuum. The card supports multiple vacuum platforms (Xiaomi Miio, Roborock, Valetudo, Neato, Dreame, Roomba, etc.) via platform-specific templates that define map modes, tiles, and icons. It includes a visual editor, localization in 28 languages, pinch-zoom functionality, and a configurable tile/icon system. The architecture is a single-page web component built with LitElement, with modular internal components for map objects, map modes, generators, and UI elements. It relies on Home Assistant frontend internals and custom-card-helpers. The codebase is well-structured with reusable patterns like dependency injection (Context), coordinate transformation (CoordinatesConverter), and template-based service call generation (ServiceCallSchema). However, it has some technical drift due to deprecated rollup plugins, polyfills for legacy browsers, and tight coupling to HA APIs that may break with updates.