houseplan-card/README.ru.md

🏠 House Plan — интерактивный поэтажный план дома для Home Assistant

Превратите Home Assistant в живую интерактивную карту дома. Загрузите или нарисуйте план этажа, обведите комнаты мышкой — и умные устройства появятся на своих местах: живые состояния, свет по клику, температура и влажность по комнатам, карта Zigbee-сигнала, светящиеся пятна ламп и полноэкранный киоск-режим для настенного планшета. Без YAML, без Inkscape и внешних редакторов — весь план настраивается прямо на дашборде.

🇬🇧 Documentation in English · 💬 Чат в Telegram: @ha_houseplan

Главное

• 🖱 Редакторы прямо в карточке — комнаты, двери и окна, комнаты-острова, виртуальные стены и декор-слой рисуются кликами; помощник выравнивания и линейка в реальных метрах.
• 💡 Свет переключается кликом из коробки; значок выключателя может управлять группой ламп (в т.ч. «тупые» выключатели и кнопки-пульты).
• 🌒 Заливка «Свет по источникам» — тёмный дом, где каждая горящая лампа даёт пятно своего цвета, проникающее через дверные проёмы и открытые зоны.
• 🌡 Карточки комнат: температура, влажность, Zigbee-сигнал, свет «1 из 3»; температурная заливка по комфортным границам.
• 🚪 Двери, окна и замки с датчиками — отпирание только явной кнопкой, никогда случайным тапом.
• 📺 Киоск-режим для настенных планшетов и ТВ: полноэкранно, свайп между этажами, автокарусель, свои размеры на каждом экране.
• 🔔 Новые устройства сами появляются на плане с красной точкой; раскладка хранится на сервере HA — один план для всех экранов, живая синхронизация.

---

Что это и зачем

House Plan показывает ваш умный дом так, как он выглядит на самом деле — на плане этажей. Вместо длинных списков сущностей вы видите комнаты и устройства на своих местах: где протечка, какая температура в детской, включён ли свет в прихожей, открыты ли ворота.

Это удобно, когда:

• устройств много, и списками пользоваться неудобно;
• нужно быстро понять состояние дома «одним взглядом»;
• хочется отдать доступ близким — по картинке разберётся любой;
• вы хотите красивый обзорный экран для настенного планшета.

Интеграция состоит из двух частей, которые ставятся вместе:

• карточка Lovelace houseplan-card — сам интерактивный план;
• серверный компонент — хранит разметку комнат и позиции иконок в Home Assistant, поэтому план одинаков во всех браузерах и на всех устройствах.

---

Чем отличается от аналогов

Обычно план дома в Home Assistant делают через picture-elements, ha-floorplan и подобные решения. Там приходится вручную писать YAML, вычислять координаты каждой иконки и заново править конфиг при каждом изменении. House Plan устроен иначе:

	House Plan	Обычные решения (picture-elements / ha-floorplan)
Настройка	Полностью через интерфейс, мышкой	Ручной YAML и правка кода
Добавление устройств	Автоматически по комнатам	Каждую сущность вписываете руками
Координаты иконок	Перетаскиваете мышью	Считаете пиксели и пишете в конфиг
Разметка комнат	Встроенный редактор контуров	Рисуете в стороннем редакторе SVG
Хранение	На сервере HA (общее для всех устройств)	В YAML дашборда
Масштаб	Плавный зум, всё остаётся чётким (вектор)	Обычно фиксированная картинка

Ключевые преимущества коротко:

• Никакого кода. Всё — пространства, комнаты, устройства — настраивается кликами.
• Автоматическое добавление устройств. Обвели комнату и привязали её к зоне Home Assistant — устройства этой зоны сами появляются на плане.
• Ручное добавление своих. Любое устройство, группу или даже «виртуальную» точку можно поставить на план вручную, задать имя, иконку, модель, ссылку и приложить PDF-инструкцию.
• Живые состояния. Температура, уровень сигнала Zigbee, вкл/выкл, открыто/закрыто — всё обновляется в реальном времени. Цвета значков подчиняются одному принципу — жёлтый значит «устройство прямо сейчас выполняет свою основную работу»: лампа светит, розетка подаёт, вентилятор крутится, медиа играет, пылесос убирает, термоголовка реально греет (а не просто включена). Оранжевый = открыто / не заперто. Пульсирующее красное кольцо = авария (протечка, дым, газ). Цвет RGB-лампы живёт в её пятне света (режим glow), где само пятно — индикатор включения, а подложка значка остаётся стандартной. Полупрозрачный значок = недоступно. Тёмный = покой.
• Чёткий зум. Приближение не «мылит» картинку: план, подписи и иконки остаются векторно-чёткими на любом масштабе.

---

Настенный планшет / ТВ (киоск-режим)

Отдельный дашборд с view типа «панель», у карточки — kiosk: true (или галочка «Режим настенного устройства» в редакторе карточки):

type: custom:houseplan-card
kiosk: true
cycle: 0   # автосмена пространств каждые N секунд, 0 = выкл (удобно для ТВ)

Без шапки и редакторов — только живой план. Свайп листает этажи (при 1:1), пинч — зум, двойной тап — сброс. Долгое нажатие (3 с) по пустому месту — настройка размеров значков и текста для ЭТОГО экрана (хранится на устройстве). Шапку самого Home Assistant скрывают настройки companion-app или плагин kiosk-mode.

Установка

В один клик, если у вас уже есть HACS:

Через HACS (рекомендуется)

1. Откройте HACS → меню (⋮) → Custom repositories.
2. Вставьте URL этого репозитория, категория — Integration, и нажмите Add.
3. Найдите в списке House Plan, установите и перезапустите Home Assistant.
4. Перейдите в Настройки → Устройства и службы → Добавить интеграцию и выберите House Plan.

Карточка подключается автоматически — добавлять ресурс Lovelace вручную не нужно.

Карточка не грузится (Custom element doesn't exist: houseplan-card) или вы ведёте ресурсы Lovelace в YAML? Добавьте ресурс вручную, указав URL, который раздаёт сама интеграция:

resources:
  - url: /houseplan_files/houseplan-card.js
    type: module

Не используйте /custom_components/houseplan/frontend/houseplan-card.js — это путь к файлу на диске, который Home Assistant не отдаёт по HTTP (получите ошибку MIME text/plain, и элемент не зарегистрируется). Правильный URL, который раздаёт интеграция, — /houseplan_files/houseplan-card.js. Обе карточки (houseplan-card и houseplan-space-card) лежат в этом одном файле — отдельный ресурс не нужен.

Вручную

1. Скопируйте папку custom_components/houseplan в каталог config/custom_components вашего Home Assistant.
2. Перезапустите Home Assistant.
3. Добавьте интеграцию: Настройки → Устройства и службы → Добавить интеграцию → House Plan.

Добавление экрана с планом

Создайте новую вкладку дашборда (удобнее всего — в режиме «Панель»/Panel) и добавьте карточку:

type: custom:houseplan-card
title: План дома

Больше ничего указывать не нужно — всё остальное настраивается прямо на экране.

---

Как пользоваться

Шаг 1. Добавьте пространство (этаж)

При первом открытии план ещё пуст — House Plan сразу предложит создать первое пространство.

Если в вашем Home Assistant уже настроены этажи, мастер предложит создать пространство для каждого: названия подставятся сами, план попросит по очереди, любой этаж можно пропустить.

В диалоге задайте название (например, «1 этаж») и выберите подложку: загрузите картинку плана (SVG, PNG, JPG, WebP), возьмите уже загруженную на сервер ранее или отметьте «без подложки, нарисую комнаты сам». Холст всегда квадратный; картинка сохраняет свои пропорции и центрируется внутри него.

💡 Подложку можно нарисовать в любом планировщике (например, РЕМПЛАННЕР) или сфотографировать бумажный план. Лучше всего SVG — он остаётся чётким при увеличении.

Позже можно добавить сколько угодно пространств (этажи, двор, гараж) кнопкой ＋ рядом со вкладками.

Шаг 2. Обведите комнаты

После добавления первого пространства карточка сама переходит в режим разметки. Кликайте по точкам сетки, соединяя их линиями, и замкните контур комнаты кликом по первой точке.

Как только контур замкнётся, появится окно сохранения комнаты. Здесь нужно привязать комнату к зоне Home Assistant — именно это включает автоматику. Для служебных помещений без устройств (холл, сауна) есть кнопка «Без зоны».

Во время рисования у курсора показывается линейка с реальной длиной текущего отрезка (метры или футы+дюймы на имперской системе HA). Масштаб задаётся для каждого пространства — поле «Масштаб (размер ячейки сетки)» в диалоге пространства: сколько сантиметров в одной ячейке (по умолчанию 5 см).

Комнаты не могут пересекаться: клик строго внутри существующей комнаты или контур, охватывающий её, отклоняются. Ещё два инструмента помогают перекроить план позже:

• Объединить — кликните комнату, затем соседнюю с общей стеной; они сольются в одну. Диалог выбирает, чьё имя и зона останутся.
• Разделить — кликните комнату, затем две точки на её стенах; хорда разрежет её надвое. Бо́льшая часть остаётся прежней комнатой (имя, зона, устройства), меньшая просит новое имя и зону.

Двери, окна и замки

В режиме разметки инструмент «Проём» ставит двери и окна: кликните рядом со стеной — проём примагнитится к ней. Выберите тип, длину в реальных сантиметрах (по умолчанию дверь 90 см, окно 120 см), датчик открытия и — для двери — замок.

С привязанным датчиком план оживает: створка двери поворачивается на петле, и дуга распахивания дорисовывается по мере открытия настоящей двери; окно раскрывает две створки. Пока открыто, подвижные части подсвечены акцентным цветом. У двери с замком рядом отображается замочек — зелёный, когда заперто, оранжевый, когда нет. Ради безопасности замок с плана нельзя переключить — клик по проёму показывает карточку с обоими статусами.

Проёмы легко поправить позже: при наведении проём подсвечивается, его можно перетащить вдоль стен (в том числе за угол), а двойной клик открывает свойства.

Шаг 3. Устройства появляются сами

Как только вы сохранили комнату с привязкой к зоне, устройства этой зоны автоматически расставляются внутри контура. Берутся те же устройства, что показаны на странице Настройки → Устройства → (фильтр по нужной комнате) — только осмысленные, без служебных записей, мостов и дубликатов.

По умолчанию на план попадают только осмысленные устройства: нефизические (служебные записи, мосты, сцены, лампы, свёрнутые в световую группу) приходят с уже установленной галкой «Скрыть устройство с плана». Дальше галка принадлежит вам — она есть в диалоге каждого устройства, включая виртуальные. Чтобы увидеть и вернуть скрытые, откройте редактор устройств и нажмите «Показать скрытые»: скрытые отобразятся полупрозрачными синими призраками, клик открывает диалог. Скрытые устройства учитываются в Zigbee-сигнале комнаты, но света не дают.

Дальше можно просто пользоваться планом: клик по иконке открывает карточку устройства с моделью, ссылкой и кнопкой перехода в Home Assistant.

Шаг 4. Масштаб

Колесо мыши или кнопки － / ⊹ / ＋ приближают и отдаляют план; на сенсорном экране работает «щипок» двумя пальцами. При отдалении виден весь план целиком, при приближении — детали, и всё остаётся чётким. Масштаб запоминается отдельно для каждого пространства.

Шаг 5. Расставьте значки по местам

Расставлять значки нужно на вкладке «Устройства»: там они перетаскиваются мышью, а клик открывает редактор. В режиме «Просмотр» ничего сдвинуть нельзя — панорамирование карты больше не сдвигает датчики (главная просьба пользователей). Позиции сохраняются на сервере и одинаковы во всех браузерах и устройствах. Кнопка ↺ возвращает автоматическую раскладку.

Управление с плана (tap actions)

По умолчанию тап по значку открывает инфо-карточку. В настройках карточки можно переключить «Тап по устройству» на Переключить — тогда тап включает/выключает свет, розетки, вентиляторы и увлажнители прямо с плана (режим настенного планшета). Для безопасности общий toggle не действует на замки, сигнализации, шторы/ворота и клапаны; для конкретного устройства toggle можно включить осознанно в его диалоге (кроме замков и сигнализаций — они с плана не переключаются никогда). Долгое нажатие всегда открывает инфо-карточку.

Правила иконок

Какая MDI-иконка достанется устройству, решают правила иконок — редактируются прямо в карточке (кнопка ⬡ в шапке): упорядоченный список «шаблон имени → иконка» с живым тест-полем, двуязычные умолчания (EN/RU) и сброс одной кнопкой. Если ни одно правило не подошло — решает device class сущности (термометр для датчиков температуры и т.п.).

Шаг 6. Добавление своих устройств вручную

Можно поставить и отдельную сущность (не только устройство целиком): начните печатать в поиске привязки — рядом с устройствами появятся отдельные сущности. Удобно, когда одно устройство отдаёт несколько значений (например, температуру и влажность), а вы хотите каждое своей иконкой.

Не всё нужно оставлять на автоматику. Кнопкой ＋ в шапке можно поставить на план любое устройство, группу или виртуальную точку (например, «Вентиль на вводе», которого нет как устройства). Задайте имя, иконку, модель, ссылку, описание и при желании приложите PDF-инструкцию.

В этом же диалоге настраивается вид устройства на плане. Отображение переключает значок, анимированную пульсацию присутствия (расходящиеся кольца, пока сущность активна, и тусклая точка в покое — идеально для датчиков движения) или то и другое сразу, с цветом и размером колец на устройство. Размер значка (×0,5–3) и поворот — тоже индивидуальные: вентиль на стене может быть маленьким и повёрнутым так, как он установлен.

---

Удаление

1. Уберите карточку (или вкладку с планом) из дашборда.
2. Настройки → Устройства и службы → House Plan → Удалить запись интеграции.
3. Удалите интеграцию из HACS (или папку custom_components/houseplan при ручной установке) и перезапустите Home Assistant.
4. При желании удалите сохранённые данные плана: файлы config/houseplan/ (подложки и вложения) и записи houseplan.config / houseplan.layout в каталоге config/.storage.

---

Помощь и обмен опытом

• 💬 Чат в Telegram — @ha_houseplan — вопросы, помощь с настройкой, идеи и скриншоты ваших планов. Самый быстрый способ связаться с автором и другими пользователями.
• 🐞 Issues на GitHub — баги и запросы фич (пожалуйста, указывайте версию House Plan).
• 💡 Discussions — для развёрнутых обсуждений.
• 📜 История изменений — что менялось в каждой версии.

Версия видна в консоли браузера при загрузке (HOUSEPLAN-CARD vX.Y.Z) и в Настройки → Устройства и службы → House Plan — с ней разбираться сильно быстрее.

---

Часто задаваемые вопросы

Нужно ли что-то писать в YAML? Нет. Единственная строчка — это добавление карточки на дашборд; всё остальное делается мышкой.

Мои устройства не появились на плане. Устройство появляется, только если его зона в Home Assistant привязана к нарисованной комнате. Проверьте, что у устройства задана комната (Настройки → Устройства), а комната обведена и привязана к этой зоне. Если устройство есть, но скрыто (галка «Скрыть устройство с плана» — для мостов, сцен и прочих нефизических записей она ставится автоматически) — откройте редактор устройств, нажмите «Показать скрытые» и снимите галку в его диалоге.

Можно ли скрыть лишнее устройство или переименовать его? Да — кликните по устройству на плане и в его карточке нажмите «Редактировать»: там можно сменить имя, иконку, модель или скрыть значок.

Данные хранятся в облаке? Нет. Всё хранится локально в вашем Home Assistant.

---

_{Скриншоты сделаны на реальной конфигурации Home Assistant.}