Display real-time vacuum cleaner maps in Home Assistant for vacuums running Valetudo Hypfer, Valetudo RE (rand256) or Congaduto firmware. Simple installation via HACS with guided GUI configuration.
❗ Note: This is an unofficial project and is not affiliated with valetudo.cloud
- Easy Setup: Install and configure in minutes through Home Assistant's UI
- Real-time Maps: Automatically decode and render vacuum maps from MQTT
- Full Control: Pair with lovelace-xiaomi-vacuum-map-card for complete vacuum control
Deliver an out-of-the-box solution for integrating MQTT-based vacuums into Home Assistant, including:
- Real-time map extraction and rendering
- Sensor data (when not provided by the vacuum)
- Control services for seamless operation
- Full vacuum control beyond basic map rendering
- Continuous improvements and regular updates
- Valetudo Map Parser - Python library for map extraction
- MVC Renderer - High-performance C library for map rendering
Click to expand full feature list
- ✅ Universal Support - All Valetudo-equipped vacuums (Hypfer & Rand256)
- 🌍 Multi-language - 14 languages supported (English, Arabic, Chinese, Czech, Dutch, French, German, Italian, Japanese, Polish, Norwegian, Russian, Spanish, Swedish)
- 🤖 Multiple Vacuums - Render maps for multiple vacuums simultaneously (e.g.,
vacuum.robot1→camera.robot1_camera) - 🔄 ON/OFF Control - Suspend and resume camera stream as needed
- 📸 Snapshots - Save maps using Home Assistant's camera.snapshot service
service: camera.snapshot target: entity_id: camera.valetudo_your_vacuum_camera data: filename: /config/www/vacuum_map.png
- 🔄 Image Rotation - 0°, 90°, 180°, 270°
- ✂️ Auto-Trim - Automatically resize large maps (5210×5210+) with customizable margins
- 🔍 Auto-Zoom - Automatically zoom to the room being cleaned
- 🎨 Customizable Colors - Configure colors for robot, charger, walls, background, zones, and rooms
- 🌈 Transparency Control - Adjust transparency for all elements and rooms
- 📊 Status Display - Show vacuum status, current room, battery level, and dock operations on the map
- 🧹 Mop Mode - Visualize mop path with customizable width, color, and transparency (Hypfer vacuums)
- 🗺️ Auto-Generated Calibration - Automatic calibration points for lovelace-xiaomi-vacuum-map-card
- 🏠 Auto-Generated Rooms - Automatic room configuration when supported by vacuum
- 🚫 Zone Visualization - Display No-Go zones, virtual walls, zone clean areas, and active segments
- 🚧 Obstacle Detection - View obstacles and obstacle images with customizable link settings
- 🏗️ Floor Materials - Detect and render different floor types (wood, tiles, carpets)
- 🏢 Multi-Floor Management - Manage multiple floors with individual trim settings for each level
- 📡 Rand256 Sensors - Pre-configured sensors for complete Home Assistant integration
- 🎮 Control Actions - Control vacuums without formatting MQTT messages manually
- 📹 MJPEG Streaming - Stream maps to go2rtc/ffmpeg for HomeKit and other video consumers
For detailed installation instructions, including manual setup and configuration of the lovelace-xiaomi-vacuum-map-card, see our Installation Guide.
Click to view compatibility information
- ✅ All 64-bit systems (Raspberry Pi 4+, ProxMox VE, Docker, etc.)
- ❌ 32-bit systems - Not supported since version 2025.10.0
| Hardware | Single Vacuum | Multiple Vacuums |
|---|---|---|
| Raspberry Pi 3 (4GB) | ✅ Works | ❌ Not recommended |
| Raspberry Pi 4 (4GB) | ✅ Works well | |
| Raspberry Pi 4 (8GB) | ✅ Excellent | ✅ Recommended |
| ProxMox VE / Docker | ✅ Excellent | ✅ Recommended |
- ✅ All vacuums running Valetudo Hypfer firmware
- ✅ All vacuums running Valetudo RE (rand256) firmware
- 💬 Other MQTT-connected vacuums? Let us know!
- Extensively tested on Raspberry Pi 4 (8GB) with Home Assistant OS
- Also tested on ProxMox and Docker Supervised environments
- For unsupported platforms, consider ValetudoPNG as an alternative
- Please read our NOTICE for additional information
Your feedback is invaluable! Please report any issues you encounter on different platforms.
We welcome contributions! Whether you can help with code, testing, or documentation, your support is appreciated. Check the Wiki for details on how the camera works and how you can contribute.
If you find this integration useful, consider supporting its development:
Thank you to everyone using this integration and providing feedback, bug reports, and feature suggestions. Your support, understanding, and contributions make this project possible!
- Developed and tested on Raspberry Pi 4 with Home Assistant OS (latest version)
- Also tested on ProxMox VE and Docker Supervised production environments
- Maintained as a solo project with community support
See NOTICE.txt for license information and disclaimers.