Интеграция умного дома часто сталкивается с проблемой визуализации. Стандартные инструменты платформы Home Assistant предоставляют базовый контроль над устройствами, но для роботизированных пылесосов Xiaomi и Roborock этого недостаточно. Вы получаете статус заряда или возможность запустить уборку, но не видите, где именно находится устройство в реальном времени. Решением этой проблемы становится Xiaomi Vacuum Map Card — специализированное дополнение, превращающее интерфейс в интерактивную карту квартиры.
Этот инструмент позволяет не просто наблюдать за движением робота, но и полноценно управлять им через графический интерфейс. Вы можете создавать виртуальные зоны, делить карту на комнаты и назначать сценарии уборки для каждого помещения отдельно. В отличие от стандартного виджета, который часто отображает лишь статичную картинку, Map Card реагирует на действия пользователя, отправляя команды непосредственно на устройство через интеграцию Xiaomi Miio.
Установка данной карты требует определенных знаний в области конфигурации YAML и понимания структуры пакетов Home Assistant. Однако результат стоит затраченных усилий: вы получаете профессиональную панель управления, сопоставимую с официальными приложениями производителей, но полностью интегрированную в вашу локальную экосистему умного дома. Далее мы рассмотрим процесс установки, тонкости конфигурации и способы решения типичных проблем.
Подготовка среды и установка компонента
Перед тем как начать работу с интерфейсом, необходимо убедиться, что у вас установлен пакетный менеджер HACS (Home Assistant Community Store). Без него установка сторонних карт значительно усложняется, так как требует ручного копирования файлов в системные директории. Если HACS уже настроен, перейдите в раздел Frontend и найдите в поиске Xiaomi Vacuum Map Card. Нажмите кнопку загрузки и обязательно перезагрузите браузер, очистив кэш, чтобы новые скрипты корректно подгрузились.
После перезагрузки интерфейса новая карта еще не появится автоматически. Вам нужно вручную добавить её в конфигурацию вашего дашборда. Для этого откройте редактор карточек в режиме конфигурации и выберите тип custom:xiaomi-vacuum-map-card. На этом этапе критически важно правильно указать entity_id вашего пылесоса. Обычно он имеет вид vacuum.xiaomi_vacuum_cleaner, но может отличаться в зависимости от способа добавления устройства в систему.
☑️ Проверка перед установкой
⚠️ Внимание: Если вы используете старую версию интеграции
vacuum.xiaomi_miio, убедитесь, что она поддерживает получение карт в реальном времени. В некоторых случаях требуется переключение на альтернативные интеграции, такие как Xiaomi Miot Auto, для корректной работы токенов и протоколов связи.
Важно понимать разницу между базовой установкой и продвинутой конфигурацией. По умолчанию карта может отображать только текущее положение робота без возможности редактирования. Для полноценного использования функционала зон и комнат потребуется создать отдельный файл конфигурации или прописать параметры непосредственно в YAML-коде дашборда. Это дает гибкость в настройке отступов, размеров и поведения элементов управления.
Базовая конфигурация YAML и параметры сущности
Основная магия настройки происходит в блоке конфигурации YAML. Здесь вы определяете, как именно карта будет взаимодействовать с вашим устройством. Ключевым параметром является entity, который связывает визуальный компонент с физическим пылесосом. Также необходимо указать путь к изображению карты, если автоматическое получение не сработало, хотя современные интеграции часто подтягивают карту автоматически через сервис xiaomi_vacuum_map_card.
Для настройки поведения карты используются параметры calibration_points. Они отвечают за привязку координат пикселей изображения к реальным координатам робота. Если карта отображается со смещением или робот "ездит" за пределами стен, проблема кроется именно здесь. Вы можете получить эти точки через сервис получения карты или использовать стандартные значения для популярных моделей Roborock S50, S6 и других.
type: custom:xiaomi-vacuum-map-card
entity: vacuum.roborock_s6
map_source:
camera: camera.xiaomi_cloud_map_extractor
calibration_source:
camera: true
vacuum_platform: default
Параметр vacuum_platform играет важную роль при использовании различных прошивок или сторонних интеграций. Значение default подходит для стандартной интеграции Home Assistant, но если вы используете Home Assistant Vacuum от сторонних разработчиков, возможно, потребуется указать miio или mqtt. Неправильный выбор платформы приведет к тому, что кнопки на карте станут неактивными, хотя сама карта будет отображаться корректно.
Настройка зон, комнат и интерактивных элементов
Одной из главных преимуществ карты является возможность создания интерактивных зон. Вы можете разделить квартиру на логические блоки: кухня, гостиная, спальня. Для этого в конфигурации используется секция predefined_zones. Каждый элемент зоны содержит координаты прямоугольника x, y, width, height и имя, которое будет отображаться при наведении или в логах.
Создание комнат требует более точной настройки, так как часто подразумевает не просто прямоугольник, а сложную геометрическую фигуру. Однако базовая карта работает с прямоугольными зонами, которые можно комбинировать. Для каждой зоны можно назначить свои параметры уборки, например, количество проходов или мощность всасывания. Это реализуется через передачу параметров в сервис запуска уборки при нажатии на соответствующую область карты.
- 🏠 Гостиная: зона с координатами [25000, 25000, 5000, 4000], режим "Тихий".
- 🍳 Кухня: зона с координатами [20000, 30000, 3000, 3000], режим "Максимальный", 2 прохода.
- 🛌 Спальня: зона с координатами [15000, 15000, 4000, 4000], запрет на работу в ночное время.
Помимо зон, вы можете добавлять кастомные кнопки прямо на карту. Это могут быть команды "Вернуться на базу", "Найти робота" или запуск конкретного сценария Home Assistant. Кнопки настраиваются в секции map_buttons и позиционируются абсолютно относительно изображения карты. Это позволяет создать уникальный интерфейс, где все необходимые действия находятся под рукой в один клик.
Интеграция с камерами и получение карты
Для работы карты необходим источник изображения. Чаще всего используется интеграция Xiaomi Cloud Map Extractor, которая создает камеру, транслирующую карту в реальном времени. Эта камера затем передается в параметр map_source конфигурации карты. Без работающей камеры карта будет пустой или будет показывать статичное изображение, не обновляющее положение робота.
Настройка экстрактора карты требует указания учетных данных Mi Cloud и выбора модели устройства. После настройки в системе появляется новая сущность типа camera, которую и нужно прописать в конфигурации Vacuum Map Card. Важно обеспечить стабильное соединение с облаком Xiaomi или использовать локальные методы получения карты, если ваша модель пылесоса это поддерживает, чтобы избежать задержек обновления.
| Параметр | Описание | Пример значения |
|---|---|---|
camera |
Сущность камеры с картой | camera.xiaomi_cloud_map |
calibration |
Источник калибровки | camera или sensor |
rotate |
Угол поворота карты | 0, 90, 180 |
crop |
Обрезка изображения | [x, y, width, height] |
Если карта отображается перевернутой или повернутой на 90 градусов, используйте параметр rotate в конфигурации. Также доступна функция crop, позволяющая обрезать лишние поля изображения, оставляя только полезную площадь квартиры. Это особенно полезно, если камера транслирует изображение с большим количеством пустого пространства вокруг помещения.
⚠️ Внимание: Интерфейсы облачных сервисов и протоколы связи могут меняться разработчиком. Если карта перестала обновляться, проверьте логи компонента Xiaomi Cloud Map Extractor на предмет ошибок авторизации или изменений в API.
Тонкая настройка интерфейса и стилизация
Визуальная составляющая не менее важна, чем функциональная. Вы можете изменять размер маркера робота, цвет контуров зон и прозрачность элементов. Для этого используются параметры icon и style внутри конфигурации карты. Например, можно заменить стандартный значок пылесоса на кастомную иконку из набора Material Design Icons, чтобы она лучше сочеталась с темой вашего дашборда.
Для продвинутых пользователей доступна возможность внедрения собственного CSS. Это позволяет менять шрифты, добавлять тени или анимацию при наведении на зоны. Однако стоит быть осторожным: излишняя стилизация может усложнить поддержку конфигурации при обновлении компонента. Рекомендуется использовать стандартные параметры темы Home Assistant, которые автоматически адаптируются под светлую или темную тему оформления.
Секретная настройка отладки
Добавьте параметр debug: true в корень конфигурации карты, чтобы видеть координаты курсора мыши при наведении на карту. Это незаменимо для точного выставления зон.
Также можно настроить поведение карты при изменении размера окна браузера. Параметр scale позволяет фиксировать масштаб или разрешать адаптивное изменение размера. Если у вас сложный дашборд с множеством виджетов, фиксированный масштаб поможет избежать "прыжков" интерфейса и сохранит читаемость элементов управления на мобильных устройствах.
Решение распространенных проблем и ошибок
Наиболее частая проблема — рассинхронизация положения робота на карте и в реальности. Обычно это решается повторной калибровкой через сервисы интеграции. Иногда помогает простая перезагрузка сервера Home Assistant, если данные в кэше устарели. Проверьте, не изменился ли IP-адрес пылесоса в локальной сети, так как это может разорвать соединение с компонентом.
Если кнопки зон не реагируют на нажатия, проверьте права доступа сущности vacuum. Убедитесь, что в конфигурации не заблокированы вызовы сервисов для данной карты. Также стоит проверить логи браузера (F12 -> Console) на наличие JavaScript ошибок, которые могут указывать на конфликт версий компонента и ядра системы.
- ❌ Карта не грузится: Проверьте работоспособность сущности камеры и наличие токенов доступа.
- ❌ Зоны не сохраняются: Убедитесь, что вы редактируете правильный файл YAML и перезагрузили конфиг.
- ❌ Робот не едет в зону: Проверьте координаты — они могут выходить за пределы допустимой области карты.
В случаях, когда обновляется прошивка пылесоса, структура данных карты может измениться. Производители иногда меняют формат передачи данных, что требует обновления компонента Xiaomi Vacuum Map Card. Следите за релизами в репозитории HACS и своевременно устанавливайте новые версии, чтобы избежать потери функциональности после автоматических обновлений робота.
Часто задаваемые вопросы (FAQ)
Можно ли использовать эту карту с пылесосами не от Xiaomi?
Официально карта заточена под экосистему Xiaomi и Roborock. Однако, если сторонний пылесос интегрирован через платформу vacuum и поддерживает сервисы получения карты и калибровки, теоретически его можно подключить, но это потребует глубокой ручной настройки координат и эмуляции ответов сервера.
Почему карта обновляется с задержкой в несколько минут?
Задержка обычно связана с методом получения данных. Если используется облачный экстрактор, задержка зависит от скорости ответа серверов Xiaomi. Для минимизации задержек рекомендуется использовать локальные интеграции, если модель вашего робота поддерживает прямой обмен данными внутри локальной сети без обращения к облаку.
Как добавить несколько пылесосов на один дашборд?
Вам нужно создать несколько отдельных карточек типа custom:xiaomi-vacuum-map-card, каждая со своим параметром entity, указывающим на конкретного робота. Объединить их в одну карту с переключением между устройствами стандартными средствами компонента нельзя, но можно использовать контейнеры дашборда для группировки.
Безопасно ли передавать логины от Mi Cloud в конфигурацию?
Данные для входа в Mi Cloud хранятся в файле конфигурации на вашем локальном сервере. Это безопаснее, чем использование облачных приложений, так как данные не передаются третьим лицам, кроме серверов Xiaomi для авторизации. Рекомендуется использовать отдельный аккаунт с ограниченными правами, если такая возможность предусмотрена производителем.