houseplan-card/docs/USER-GUIDE.ru.md

House Plan — полное руководство пользователя

Актуально для v1.60.0. Руководство заново составлено по исходному коду и фактическому интерфейсу этой версии. Старые README и тематические спецификации использовались только для перепроверки сценариев.

House Plan — локальная интеграция и две Lovelace-карточки для Home Assistant:

• custom:houseplan-card — интерактивный план с редакторами, состояниями и управлением;
• custom:houseplan-space-card — статическая схема одного пространства со ссылкой на полный план.

Все планы, настройки и позиции хранятся внутри Home Assistant. Облачный сервис House Plan не используется.

Уровень поддержки устройств ввода. Просмотр и киоск должны полноценно и удобно работать на телефонах, планшетах и настенных touch-панелях. Создавать и редактировать планы рекомендуется на компьютере с мышью и клавиатурой. Редакторы на touch поддерживаются по остаточному принципу: отдельные жесты, точные операции или элементы интерфейса могут работать неудобно, ограниченно либо отсутствовать. Это не относится к безопасности данных и действий: touch-редактор не должен повреждать план или отправлять случайные команды.

Содержание

1. Модель данных и терминология
2. Установка и доступ
3. Добавление карточки
4. Быстрый старт
5. Режимы интерфейса
6. Навигация, масштаб и жесты
7. Пространства
8. Комнаты и стены
9. Двери, окна и замки
10. Устройства
11. Действия по нажатию
12. Визуальные состояния устройств
13. Заливки комнат и свет
14. Редактор подложки
15. Солнце и фон день/ночь
16. Роботы-пылесосы
17. Киоск-режим
18. Статическая карточка пространства
19. Обслуживание планов
20. Хранение, совместная работа и резервные копии
21. Ограничения текущей версии
22. Диагностика

1. Модель данных и терминология

Настройки образуют иерархию: общие значения задают базовый вид, пространство может их переопределить, затем отдельная комната, затем устройство.

Уровень	Что это	Что хранит
Карточка	Один экземпляр houseplan-card на дашборде	Стартовое пространство, язык, размер иконок, показ значений/LQI, живые состояния, киоск и автолистание
Общие настройки	Настройки всего House Plan	Палитры заливок, фон, радиус света, север, солнце, погода, правила иконок
Пространство	Этаж, двор, гараж, отдельное строение	Подложку, масштаб сетки, комнаты, стены, проёмы, декор и настройки отображения
Комната	Только замкнутый контур	Название, необязательную HA-зону, источники температуры/влажности и локальную заливку
Стена	Сторона контура комнаты	Необязательную толщину и виртуальные участки общей границы
Проём	Дверь, окно или ворота на стене	Размер, ориентацию, контактный датчик и, для двери/ворот, замок
Маркер	Значок устройства на плане	Привязку к HA, комнату, действие, внешний вид, свет, описание и файлы
Декор	Элемент подложки	Линию, фигуру, текст, мебель или положение изображения плана

Важное ограничение версии: стена пока не существует отдельно от комнаты. Она выводится из границы замкнутого контура. Незамкнутые и свободно стоящие стены пока не поддерживаются.

2. Установка и доступ

Требования

Компонент	Требование
Home Assistant	2024.6.0 или новее
Тип установки	Любой, где доступны пользовательские интеграции
Браузер	Современный браузер с Web Components, SVG и Pointer Events
Права	По умолчанию редактировать House Plan могут только администраторы

Установка через HACS

1. В HACS добавьте https://github.com/Matysh/houseplan-card как пользовательский репозиторий категории Integration.
2. Установите House Plan и перезапустите Home Assistant.
3. Откройте Настройки → Устройства и службы → Добавить интеграцию и выберите House Plan.
4. Оставьте включённой опцию «редактировать план только администраторам», если обычным пользователям нужен только просмотр и управление.

Интеграция сама регистрирует Lovelace-ресурс. При YAML-управлении ресурсами добавьте его вручную:

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

Не используйте файловый путь /custom_components/houseplan/frontend/houseplan-card.js: Home Assistant не раздаёт его как модуль. Обе карточки находятся в одном файле /houseplan_files/houseplan-card.js.

Ручная установка

1. Скопируйте папку custom_components/houseplan из релиза в config/custom_components/houseplan.
2. Перезапустите Home Assistant.
3. Добавьте интеграцию House Plan.
4. Если ресурсы Lovelace управляются YAML, добавьте ресурс из примера выше.

Права пользователей

Настройка интеграции	Просмотр	Управление устройствами	Редактирование планов и загрузка файлов
Только администраторы — включено (по умолчанию)	Все вошедшие пользователи	По обычным правам HA	Только администраторы
Только администраторы — выключено	Все вошедшие пользователи	По обычным правам HA	Все вошедшие пользователи

Оптимизация планов и отмена оптимизации всегда требуют администратора, независимо от этой опции.

3. Добавление карточки

Минимальная конфигурация основной карточки:

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

Параметры основной карточки доступны в визуальном редакторе Lovelace.

Поле	Значение по умолчанию	Поведение
title	пусто	Заголовок карточки
default_floor	первое/последнее открытое	Пространство при первом открытии этого экземпляра
language	язык HA	auto, ru или en
icon_size	2.5	Базовый размер маркеров, 1–6% ширины плана
show_temperature	true	Показывает компактные значения температуры и влажности у подходящих устройств
live_states	true	Включает рабочие/открытые/недоступные состояния, смену иконок и активность; аварии остаются видимыми всегда
show_signal	true	Базовый показ LQI; отдельное пространство может переопределить его
kiosk	false	Полноэкранный режим без шапки и редакторов
cycle	0	Интервал автолистания пространств в киоске, 0–3600 секунд; 0 выключает

Карточечный tap_action из старых конфигураций игнорируется. Действие задаётся отдельно для каждого устройства.

4. Быстрый старт

Рекомендуемый порядок настройки:

1. Создайте пространство кнопкой +. Можно импортировать этажи из реестра этажей HA.
2. Загрузите SVG/PNG/JPG/WebP или выберите вариант без изображения.
3. Укажите размер одной клетки сетки в сантиметрах. От него зависят размеры стен, проёмов, мебели и площадь.
4. В Редакторе плана обведите каждую комнату замкнутым контуром.
5. Свяжите комнату с одноимённой HA-зоной или оставьте без зоны.
6. Добавьте толщину стен и проёмы.
7. В Редакторе устройств расставьте автоматически найденные маркеры и настройте действия.
8. В Редакторе подложки подвиньте изображение, добавьте мебель, подписи и декоративные линии.
9. Выберите режим заливки пространства и настройте палитру в общих настройках.
10. При необходимости включите киоск, солнечные лучи и живую позицию пылесоса.

Шаги создания и редактирования плана выполняйте в desktop-браузере. Телефон, планшет и настенная панель являются полноценными целевыми устройствами для последующего просмотра и управления домом, но не гарантированной средой редактирования.

5. Режимы интерфейса

Обычный просмотр — не отдельная вкладка: это состояние, в которое возвращает крестик активного редактора. Редакторы переключаются напрямую. Новая панель инструментов коротко проявляется, а её фактическая высота плавно подстраивается даже при переносе кнопок на несколько строк; при системной настройке уменьшения движения переход отключается.

Режим	Основное назначение	Устройства	Комнаты/стены	Декор и проёмы
Просмотр	Контроль дома	Интерактивны; видны состояния, значения и подсказки	Комната подсвечивается при наведении; подсказка показывает название, чистую площадь, температуру и LQI	Видны, если не скрыты настройками пространства; проёмы не реагируют на клик, кроме значка замка
Редактор плана	Геометрия комнат, стен и проёмов	Скрыты	Интерактивны; видны кнопки настроек комнат, размеры и сетка	Проёмы всегда видны и редактируются; виртуальные стены рисуются полностью по оси
Редактор устройств	Позиции и параметры маркеров	Перетаскиваются; клик открывает настройки; доступны скрытые маркеры	Не редактируются	Служат фоном
Редактор подложки	Изображение, линии, фигуры, текст, мебель	Не редактируются и полупрозрачны	Комнаты, физические и виртуальные стены полупрозрачны	Декор интерактивен и непрозрачен; скрытый в просмотре декор всё равно виден здесь
Киоск	Настенный экран	Интерактивны как в просмотре	Только отображение	Только отображение; редакторы отсутствуют
Статическая карточка	Компактная схема пространства	Только рисунок	Только рисунок	Без состояний и интерактивности

В редакторах сетка продолжается по всему рабочему холсту. В режиме просмотра сетка не показывается.

Основная панель каждого редактора содержит только постоянные инструменты, а кнопка закрытия закреплена справа. Параметры активного инструмента, подсказки незавершённой операции и действия выбранного объекта появляются в полупрозрачной суб-панели поверх верхней части холста. Она не уменьшает рабочую область и не меняет масштаб плана. На узком экране действия прокручиваются горизонтально внутри самой суб-панели.

6. Навигация, масштаб и жесты

Холст практически бесконечен: элементы можно рисовать и размещать за пределами исходного квадрата плана. Команда Показать всё подбирает вид по фактическому содержимому.

Touch-жесты просмотра и киоска из таблицы ниже входят в гарантированный сценарий. Наличие редактора на сенсорном экране не означает полного соответствия desktop: для точного рисования, Resize, модификаторов клавиатуры и свойств по двойному клику используйте компьютер.

Действие	Мышь/клавиатура	Сенсорный экран
Масштаб	Колесо, кнопки −/+	Щипок двумя пальцами
Панорама	Перетаскивание пустого места	Перетаскивание
Показать всё	Центральная кнопка масштаба	Та же кнопка вне киоска
Привязка объектов	Выполняется автоматически и всегда	Выполняется автоматически и всегда
Сброс киоск-масштаба	—	Двойной тап
Следующее пространство в киоске	—	Горизонтальный свайп при масштабе 1:1
Локальный размер киоска	—	Удерживать пустое место 3 секунды

Особенности:

• панорамирование работает при любом масштабе;
• масштаб режима просмотра запоминается отдельно для каждого пространства на текущем клиенте;
• масштаб и панорама внутри редактора — рабочие и не заменяют сохранённый вид просмотра;
• если один или несколько объектов далеко от основного плана, появляется подсказка о дальних объектах;
• в киоске при увеличении выше 1:1 горизонтальный жест двигает план, а не листает этажи;
• любая ручная операция в киоске приостанавливает автолистание на 60 секунд;
• Shift не отключает позиционную сетку; при рисовании контура комнаты он фиксирует стену по ближайшему направлению с шагом 45°; в редакторе подложки делает прямоугольник квадратом/овал кругом при создании, разрешает непропорциональное масштабирование и свободный поворот; у компаса включает шаг 15°.

Клавиши отмены

Контекст	Esc	Ctrl+Z / Cmd+Z	Ctrl+Shift+Z / Ctrl+Y
Незавершённый Draw/Split	Убирает последнюю точку или выходит из инструмента	Сначала убирает незавершённую точку	—
Любой инструмент редактора плана	Отменяет текущий жест/выбор	Отменяет последнюю именованную геометрическую операцию	Повторяет отменённую операцию
Подложка	Отменяет незавершённое рисование или возвращает состояние до начала активного move/resize/rotate	Отменяет последнюю именованную операцию декора или картинки	Повторяет отменённую операцию
Текстовое поле	Закрывает верхний диалог	Обычная отмена текста браузером	Обычный повтор текста браузером

Общий стек геометрии хранит 50 операций и используется редакторами плана и подложки. В обе панели добавлены кнопки Отменить и Повторить; их подсказка показывает имя следующего шага. История живёт в текущей сессии карточки и безопасно сбрасывается, если с сервера приходит более новая внешняя ревизия плана.

Во всех диалогах Tab и Shift+Tab перемещают фокус только внутри открытого окна, Esc закрывает верхнее окно, а после закрытия фокус возвращается на кнопку или объект, которыми диалог был открыт. При открытии вложенного окна возврат сначала происходит в родительский диалог.

7. Пространства

Пространство подходит не только для этажа: это может быть двор, гараж, баня или отдельное строение.

Источник плана

Вариант	Когда использовать	Поведение
Изображение	Есть готовый чертёж или фото	SVG, PNG, JPG, WebP; пропорции изображения сохраняются, положение и масштаб можно менять позже
Уже загруженный файл	Один план используется повторно или файл уже лежит на сервере	Выбор из серверного списка; используемый пространством файл нельзя удалить
Без изображения	План рисуется непосредственно в House Plan	Бумага формируется по контурам комнат; границы и названия удобно включить сразу
Импорт этажей HA	В HA уже создан реестр этажей	Мастер создаёт пространства по очереди; любой этаж можно пропустить

Настройки пространства

Раздел	Настройка	Результат
Масштаб	Сантиметров на клетку	Переводит сетку в реальные размеры и площади; начальное значение 5 см
Отображение	Всегда показывать границы	Рисует контуры комнат в просмотре
Отображение	Показывать названия	Рисует карточки/названия комнат; их можно двигать в редакторе плана
Отображение	Показывать LQI	Переопределяет базовую настройку карточки для этого пространства
Отображение	Скрыть декоративный слой	Не рисует линии, фигуры, текст и мебель в просмотре; в редакторе подложки они остаются видимыми
Отображение	Скрыть проёмы	Скрывает только символы дверей, окон и ворот; свет, солнечные лучи и датчики проёмов продолжают работать
Карточка комнаты	Температура/влажность/LQI/свет	Добавляет выбранные показатели под названием комнаты
Карточка комнаты	Общий размер шрифта	Масштабирует все комнатные карточки пространства, 50–300%
Стиль	Цвет и прозрачность	Общий цвет границ и названий
Фон	Наследовать/статический/день-ночь	Управляет фоном вокруг плана
Солнце	Север и лучи	Локально переопределяет общие настройки
Заливка	Световые источники/нет/LQI/свет/температура	Выбирает модель заливки для комнат пространства

Удаление пространства удаляет его комнаты и разметку после подтверждения. Файл подложки при этом автоматически не удаляется: им можно управлять через список уже загруженных планов.

8. Комнаты и стены

Создание комнаты

1. Откройте Редактор плана.
2. Выберите Контур комнаты.
3. При необходимости укажите толщину новых стен в появившейся над холстом панели параметров. 0/пусто создаёт тонкую осевую границу.
4. Поставьте минимум три точки по сетке.
5. Замкните контур кликом по первой точке или Ctrl + кликом в любом месте. Быстрое замыкание доступно после двух нарисованных граней и не сработает, если замыкающая стена создаёт самопересечение.
6. В диалоге задайте название, выберите свободную HA-зону либо оставьте в списке «— без зоны —», затем нажмите «Сохранить».

Во время рисования показываются длина сегмента и угол. Углы, кратные 45°, выделяются. Удерживайте Shift, чтобы зафиксировать текущий отрезок по ближайшему такому направлению; предпросмотр и поставленная точка останутся на сетке. Новая комната не может частично перекрывать другую, но полностью вложенная «островная» комната поддерживается.

Каждый законченный отрезок незамкнутого контура сохраняется сразу. В той же сессии инструмент продолжит его автоматически; после перезагрузки выберите кликом один из концов. Замкнутый контур можно сохранить как комнату или выбрать в диалоге действие Оставить замкнутыми стенами.

Связь с HA-зоной

Одна HA-зона может быть назначена только одной комнате. Связь нужна для автоматического размещения устройств, LQI, света и средних климатических показателей. Комната без HA-зоны всё равно может иметь вручную назначенные устройства и отдельные источники температуры/влажности.

Инструменты плана

Инструмент	Что выбирать	Результат и ограничения
Контур комнаты	Точки контура	Создаёт комнату; незаконченный контур сохраняется и допускает разную толщину сегментов
Перегородка	Две точки	Создаёт одну независимую стену с текущей толщиной; комнату и HA-зону не делит
Колонна	Одну точку	Создаёт квадратную колонну с текущим размером; форму, размер и поворот можно изменить в свойствах
Объединить	Две соседние комнаты	Объединяет геометрию; в диалоге выбирается, чья идентичность/название/HA-зона сохранится
Split	Комнату, старт на стене, путь внутри, финиш на стене	Делит комнату; большая часть сохраняет исходную комнату, меньшая получает новое имя/HA-зону
Resize	Ручку стены или комнату	Двигает стену с общей геометрией; по клику на комнату даёт угловую рамку масштабирования
Opening	Точку на стене	Создаёт дверь, окно или ворота; клик существующего проёма открывает его настройки
Граница	Две точки общей стены или существующий пунктир	Два клика делают участок общей стены виртуальным; один клик по пунктиру целиком восстанавливает физическую стену
Толщина	Реальный участок стены	Задаёт толщину выбранному участку или всем стенам комнаты
Удалить комнату	Точку внутри комнаты	После подтверждения удаляет только эту комнату; стены не запускают другие скрытые действия

Merge

• Комнаты должны иметь общую границу.
• Пользователь выбирает, какая комната остаётся основной.
• Название, HA-зона и привязанные к ней устройства второй комнаты не переносятся автоматически. Устройства её HA-зоны исчезнут с этого плана, пока зона не будет назначена другой комнате.
• Вложенные и геометрически несовместимые варианты могут быть отклонены.

Split

• Первая и последняя точки разреза должны лежать на границе выбранной комнаты.
• Промежуточные точки должны идти внутри комнаты и не пересекать контур или сам разрез.
• Большая по площади часть сохраняет исходную комнату и устройства.
• Для меньшей части открывается диалог новой комнаты.

Resize

Сценарий	Что происходит
Движение внешней стены	Меняется только выбранная комната
Движение общей стены	Одновременно меняются обе соседние комнаты
На стене есть проём	Проём следует за стеной и остаётся на ней
На стене разная толщина/виртуальный участок	Интервалы толщины и виртуальности переносятся вместе со стеной
Клик по комнате	Появляется рамка для масштабирования всей комнаты
Размер стал слишком мал	Минимальный размер комнаты — 30 см

Resize показывает живые длины и чистую площадь по внутреннему контуру толстых стен. Завершённый drag становится одним именованным шагом общего 50-командного Undo/Redo.

Перегородки и колонны можно перетаскивать по сетке и редактировать двойным кликом. У перегородки задаётся толщина 1–100 см. У колонны задаются квадратная или круглая форма и внешний размер 1–150 см; у квадрата доступен поворот, у круга размер означает диаметр. Они вычитаются из чистой площади, перекрывают Glow и солнечные лучи, но при Resize комнаты остаются на месте. За пределами комнат эти объекты не создают пол или фон.

Толщина стены

Параметр	Поведение
Значение	1–100 см; пусто/0 в интерфейсе очищает толщину
Геометрия	Толщина растёт на половину значения в обе стороны от оси стены
Общая стена	Одна физическая стена между комнатами
Чистая площадь	Считается по внутренней грани стен
Углы	Соседние тела стен соединяются; на малом масштабе штриховка скрывается, тело остаётся
Соседние одинаковые участки	Нормализуются в один участок при редактировании/оптимизации
Виртуальный участок	Не имеет тела и толщины; реальные остатки сохраняют свою толщину

Виртуальные стены

Виртуальная стена — открытый участок общей границы двух комнат. Она нужна для зонирования одного физически открытого пространства.

Ситуация	Поведение
Создание	Два клика на одном общем ребре; участок ограничивается ближайшими углами
Закрытие	Тот же инструмент «Граница» восстанавливает весь канонический пунктир одним кликом
Несколько соседних участков	Объединяются в один канонический отрезок
Проёмы на открываемом участке	Удаляются, потому что в виртуальной стене проём не нужен
Толщина	На открытом участке удаляется; на реальных остатках сохраняется
Свет	Свет свободно распространяется по всей связанной открытой зоне
Просмотр	Пунктир проходит по оси, но скрывается под телом примыкающих толстых стен
Редакторы	Пунктир рисуется полностью от оси стены для точного редактирования
Внешняя стена	Сделать виртуальной нельзя
Ответвление из середины	Не поддерживается

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

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

Проём всегда привязан к стене. Дверь по умолчанию создаётся шириной 90 см, окно — 120 см, ворота — 300 см. Допустимый размер в интерфейсе: 20–600 см с шагом 5 см.

Ворота по данным и поведению равны двери: могут иметь датчик открытия и замок, вырезают стену и пропускают Glow. Отличается только символ: две половинные створки без большой дуги, приоткрытые наружу на 10°. С датчиком угол меняется от 0° до 10°; без датчика показаны статически открытыми на 10°. Выбор распашных/откатных и других типов пока не предусмотрен.

Настройки проёма

Поле	Дверь	Окно	Ворота
Размер	Да	Да	Да
Контактный датчик	Да	Да	Да
Инверсия датчика	Да	Да	Да
Петли с другой стороны	Да	Да	Нет: створки симметричны
Открывается в другую сторону	Да	Да	Да; по умолчанию — наружу
Замок lock.*	Да	Нет	Да

Контакт выбирается из подходящих binary_sensor и дверных cover. Состояние датчика анимирует створку/полотно. Инверсия нужна, если интеграция отдаёт противоположную логику.

Поведение в разных режимах

Режим	Клик по проёму	Перетаскивание
Просмотр	Сам проём инертен; значок замка открывает карточку проёма	Нет
Редактор плана	Открывает настройки	Да, вдоль стены
Остальные редакторы	Инертен	Нет

При перетаскивании проём всегда магнитится к центру стены либо к шагу сетки вдоль стены. Обхода этой привязки нет.

Замок

• locked показывается как закрытый замок;
• unlocked/open — как открытый, с оранжевым состоянием;
• неизвестное состояние получает нейтральное/неизвестное оформление;
• клик по значку открывает карточку проёма;
• закрытие выполняется без дополнительного подтверждения;
• открытие замка требует подтверждения;
• обычное действие маркера устройства никогда не переключает lock.* и не снимает охрану alarm_control_panel.*.

Толстые стены

Тело стены вырезается по ширине проёма, откосы идут через всю глубину стены. Створка/дуга двери и окна смещается к внутренней грани комнаты, а створки ворот — к наружной. Свет проходит через дверь или ворота по ширине внутреннего тоннеля и отсекается откосами. Солнечный луч начинается из внутренних углов оконного тоннеля.

Солнце проходит только через наружные окна. Внутренние окна солнечных лучей не создают.

10. Устройства

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

House Plan читает реестры устройств, сущностей и зон Home Assistant. Устройства HA-зоны появляются в комнате, связанной с этой зоной. Позиция назначается автоматически, затем её можно изменить.

Некоторые служебные и нефизические интеграции скрываются при первой материализации списка: например HACS, системные сущности, мосты, сцены и часть агрегатов. Лампочки, входящие в группу света, могут быть заменены одним групповым маркером.

После первичного заполнения новые устройства отмечаются красной точкой. Точка исчезает после первого открытия маркера в редакторе устройств.

Виды привязки

Вид	Что выбирается	Особенности
Устройство HA	Запись из реестра устройств	Использует все связанные сущности; основной домен выбирается автоматически
Сущность HA	Одна сущность	Доступно после включения «Показывать сущности»; удобно для helper/group/template
Виртуальное устройство	Ничего	Только подпись/иконка/описание; живого состояния HA нет

Одну и ту же привязку нельзя одновременно использовать в двух маркерах.

Редактор устройств

Действие	Результат
Перетащить маркер	Меняет его общую серверную позицию; центр всегда оказывается на узле сетки
Клик по маркеру	Открывает диалог настройки
Добавить	Создаёт виртуальный маркер или вручную выбирает HA-привязку
Скрытые и деактивированные	Показывает пользовательски скрытые и отключённые в HA устройства служебными маркерами только в этой вкладке
Правила иконок	Открывает приоритетный список регулярных выражений для «имя + модель»

Основные настройки маркера

Поле	Назначение
Имя	Подпись и заголовок карточки устройства
Привязка	Устройство, сущность или виртуальный маркер
Комната	Автоматическая HA-зона либо ручное назначение, включая комнату без зоны
Действие по нажатию	Карточка House Plan, HA more-info, toggle, запуск сценария или управление шторами
Управляет другими источниками света	Группа других light.*/switch.*, переключаемая вместе. Собственная entity и сущности привязанного устройства сюда не входят
Это источник света	Явно считает само реле/выключатель источником света и позволяет ему создавать световое пятно
Использовать температуру climate	Добавляет current_temperature термостата/кондиционера в маркер и среднее комнаты
Скрыть / Показать	Кнопка в левом нижнем углу диалога. После сохранения убирает или возвращает значок; LQI скрытого устройства всё ещё может участвовать в среднем комнаты
Удалить	Кнопка рядом со «Скрыть». После подтверждения сразу полностью убирает устройство с плана и позволяет позднее добавить его заново
Радиус свечения	Локально переопределяет общий радиус, 0.1–100 м в хранилище
Иконка	Ручная mdi:*; пусто — автоматический подбор. Автовариант показывается в поле как значок с именем mdi:*, но не сохраняется как ручная замена
Отображение	Иконка, иконка + активность или значение вместо иконки. Ниже сразу видны фактический результат, источник и интеграция
Размер/поворот	Масштаб маркера и угол
Модель, ссылка, описание	Информация во внутренней карточке
Файлы	PDF, PNG, JPG/JPEG, WebP, TXT; несколько вложений

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

Скрытые устройства

Скрытый маркер:

• не рисуется в просмотре;
• в редакторе виден только при включённом Скрытые и деактивированные;
• не показывает цвет состояния, число, температуру, влажность и LQI;
• не создаёт световое пятно и не считается источником для заливки «Свет»;
• может продолжать участвовать в среднем LQI комнаты, потому что оно считается по реестру устройств зоны.

Деактивированные в Home Assistant

Если устройство, привязанная сущность или все сущности устройства имеют disabled_by в HA, House Plan временно исключает привязку полностью: маркер не рисуется, не входит в LQI/температуру/влажность/свет/Glow, не питает текстовые переменные и проёмы, не выполняет действия; у пылесоса также нет puck и следа. Конфигурация, позиция, вложения и серверная история при этом не удаляются.

В редакторе Скрытые и деактивированные показывает серый marker с причиной. Его можно открыть, изменить описание, удалить с плана или перейти в настройки HA. «Показать» заблокировано до активации. После активации того же ID устройство возвращается со старыми настройками и позицией; ранее установленное пользователем «Скрыть» сохраняется.

Если аккаунту не разрешено читать полный реестр HA, House Plan не угадывает деактивацию по отсутствию записи. Подтверждённые живые привязки работают, а неподтверждённые безопасно не влияют на план до восстановления доступа.

11. Действия по нажатию

Жесты маркера

Жест	Режим просмотра	Редактор устройств
Короткий клик/тап	Выполняет выбранное действие	Открывает настройки маркера
Долгое нажатие, 600 мс	Открывает внутреннюю карточку House Plan	Не используется для управления
Правый клик	Открывает стандартный HA more-info основной сущности	Открывает контекст редактора/браузера по текущему поведению

Действия

Действие	Что происходит	Защита
Карточка устройства	Открывается House Plan-карточка с сущностями, моделью, описанием, ссылками и файлами	Состояние не меняется
HA more-info	Открывается штатный диалог основной сущности	Состояние не меняется
Toggle	Переключается основная сущность или группа controls	Никогда не переключает замок и охранную панель; можно включить подтверждение
Run	automation.trigger, script.turn_on или scene.turn_on	Цель выбирается явно; можно включить подтверждение
Open/close	Для подходящего cover.*: closed→open, open→close, opening/closing→stop, неизвестно→toggle	Только явный выбор; не предлагается для garage/door/gate; можно включить подтверждение

У устройства, чья основная функция — light.*, действие по умолчанию уже является Toggle. У остальных устройств по умолчанию открывается внутренняя карточка.

Если указаны несколько управляемых источников света:

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

12. Визуальные состояния устройств

В динамических режимах система состоит из трёх независимых слоёв:

1. подложка маркера сообщает устойчивый статус;
2. иконка/число сообщает тип или значение;
3. кольцо активности в режиме «Иконка + активность» сообщает событие, присутствие, движение или работу.

Приоритет статусов: авария → работа → открыто → нейтрально. Если все сущности, реально описывающие маркер, недоступны, маркер бледнеет. У медиаплеера off использует то же приглушённое отображение, что unknown и unavailable, без отдельного визуального состояния.

Подложка и постоянный статус

Вид	Что означает	Примеры
Красная авария	Критическое событие; показывается даже при выключенных живых состояниях	Дым, газ, CO, протечка, tamper/problem/safety, сирена on, охранная панель triggered
Жёлтая подложка	Устройство сейчас выполняет работу	Свет/реле/вентилятор/увлажнитель on; climate с распознанным action heating, cooling, preheating или defrosting; при отсутствии распознанного action — включённый HVAC-режим как лучшее доступное приближение; vacuum cleaning/returning; script on; техника washing/drying/etc.
Оранжевая подложка	Физически открыто/разблокировано	Датчик двери/окна/гаража on, замок unlocked/open, клапан open/opening/closing
Бледный маркер	Данные недоступны либо медиаплеер выключен	Все рабочие сущности маркера unknown, unavailable или отсутствуют; media_player.* = off
Нейтральный	Нет аварии, работы и открытого состояния	Выключено, закрыто, idle/standby/docked и т. п.

automation.* = on означает «автоматизация включена», а не «исполняется», поэтому жёлтая подложка не появляется. Для climate распознанный idle всегда нейтрален; неизвестные служебные значения action от сторонних интеграций игнорируются и не блокируют проверку HVAC-режима. cover.* специально не получает оранжевую подложку за открытое состояние: открытие показывается формой иконки.

Активность

Кольцо рисуется только при выбранном отображении Иконка + активность и включённых живых состояниях.

Тип активности	Длительность	Источники
Событие	Около 3.3 секунды	Motion/vibration/sound при срабатывании; открытие контакта; button/event при изменении; ручной запуск сценария из карточки
Присутствие	Пока состояние активно	Binary sensor с классом occupancy/presence
Переход	Пока идёт движение; при мгновенном переходе около 3.3 секунды	Cover opening/closing, lock locking/unlocking, valve opening/closing, moving sensor, vacuum returning
Работа	Пока устройство работает	Свет, switch, fan, humidifier, climate action (либо включённый HVAC-режим при отсутствии action), vacuum cleaning, script и известные рабочие состояния техники

Цвет и размер кольца можно изменить для конкретного маркера. Если цвет не задан, RGB-свет может передать кольцу свой текущий цвет.

Четыре варианта «Отображение»

Опция	Иконка	Подложка статуса	Активность	Значение
Значок + динамическая подложка	Да	Да	Нет	Отдельные компактные °/% и LQI возможны
Иконка + активность	Да	Да	Да	Отдельные компактные °/% и LQI возможны
Значение вместо иконки	Если значение получить нельзя или источник неоднозначен	Да	Нет	Температура/влажность либо числовое или текстовое состояние, отформатированное HA
Всегда статичный значок	Да	Всегда нейтральная тёмная	Нет	Нет

В режиме «Значение вместо иконки» поддерживаются и числа, и локализованные HA текстовые состояния. Если источник отсутствует, недоступен или неоднозначен, карточка возвращается к иконке; предпросмотр объясняет причину. Длинный текст сокращается многоточием, полный остаётся в подсказке и accessibility-описании. LQI остаётся отдельным бейджем.

«Всегда статичный значок» — осознанное исключение из общей матрицы состояний. Маркер не меняет подложку или иконку, не показывает тревогу, недоступность, RGB-цвет, значение, температуру, влажность и LQI. Для пылесоса также скрываются живой puck, след и подсветка убираемой комнаты, но сохранённая история не удаляется. Hover/focus остаются такими же, как у других маркеров; клик, controls, Glow и заливка «Свет» продолжают работать по фактическому состоянию и отдельным настройкам устройства. Для привязок, способных сообщать о тревоге, редактор показывает неблокирующее предупреждение перед сохранением этого режима.

Живой блок предпросмотра в настройках marker использует несохранённые поля формы и текущее состояние HA. Он отдельно показывает интеграцию привязки и фактическую сущность отображения. Для «Иконка + активность» можно безопасно запустить локальный пример кольца на 3,3 секунды: состояние HA, конфигурация и эффект marker на плане при этом не меняются.

Смена иконки по состоянию

При включённых живых состояниях автоматически меняются известные пары:

• дверь/окно/гараж — закрыто/открыто;
• шторы, жалюзи, ставни, ворота и другие cover — закрыто/открыто;
• замок — locked/unlocked;
• стандартная лампочка — off/on.

Ручная иконка обычно не меняется. Для cover.* известная пара может меняться даже при ручном выборе, чтобы открытое состояние не потерялось.

Матрица по типам устройств

Тип сущности/устройства	Устойчивый статус	Активность «Иконка + активность»	Смена иконки	Короткий клик по умолчанию
light.*	Жёлтый, пока on	Работа, пока on	Стандартная лампочка off/on	Toggle
switch.*, fan.*, humidifier.*	Жёлтый, пока on	Работа, пока on	Обычно нет	Внутренняя карточка, если Toggle не выбран явно
Составное switch-only устройство с отдельной сущностью Power	Нейтральное при Power=on; приглушённое при Power=off/unknown/unavailable	Нет: соседние переключатели режимов и функций не считаются работой всего устройства	Обычно нет	Внутренняя карточка
Motion/vibration/sound binary sensor	Нейтральный	Событие около 3.3 с при переходе off→on	Нет	Внутренняя карточка
Occupancy/presence binary sensor	Нейтральный	Пока присутствие активно	Нет	Внутренняя карточка
Door/window/garage contact	Оранжевый, пока on	Короткое событие при открытии	Закрыто/открыто для известных классов	Внутренняя карточка
cover.* штор/жалюзи	Нейтральный	Переход во время opening/closing либо короткий fallback	Закрыто/открыто	Внутренняя карточка; Open/close выбирается явно
cover.* garage/door/gate	Нейтральный	Переход во время движения	Закрыто/открыто	Только карточка; Open/close намеренно не предлагается
lock.*	Оранжевый при unlocked/open	Переход при locking/unlocking	Замкнут/открыт	Карточка; Toggle запрещён
valve.*	Оранжевый при open/opening/closing	Переход при opening/closing	Обычно нет	Карточка; Toggle можно выбрать явно
climate.*	Жёлтый при реальном heating/cooling/working; если интеграция не отдаёт action — пока включён HVAC-режим	Работа по hvac_action/аналогичному атрибуту, иначе по режиму из hvac_modes	Нет	Внутренняя карточка
media_player.*	Нейтральный при любом включённом/транспортном состоянии; приглушённый при off, как при unknown/unavailable	Нет: playing, вспомогательная подсветка и служебные переключатели не считаются работой	Нет	Внутренняя карточка
vacuum.*	Жёлтый при cleaning и returning	Работа при cleaning, переход при returning	Нет	Внутренняя карточка; движущийся puck открывает HA more-info
script.*	Жёлтый, пока on	Работа, пока выполняется	Нет	Внутренняя карточка или явный Run
automation.*	Нейтральный даже при on	Короткое событие после явного Run из плана	Нет	Внутренняя карточка или явный Run
button.* / event.*	Нейтральный	Короткое событие при изменении	Нет	Внутренняя карточка
Smoke/gas/CO/moisture/safety/tamper/problem, siren, triggered alarm	Красная авария	Кольцо не требуется: авария имеет высший приоритет	Зависит от базовой иконки	Карточка; опасный Toggle запрещён
Виртуальный маркер	Нейтральный	Нет без HA-источника	Нет	Внутренняя карточка или явный Run

13. Заливки комнат и свет

Режимы заливки пространства

Режим	Источник	Цвет/поведение	Нет данных
Световые источники	Включённые лампы и отмеченные реле	Дом затемняется, вокруг источников рисуются световые пятна	Остаётся базовая темнота
Нет	—	Прозрачная комната/только граница	—
Zigbee signal	Средний LQI устройств HA-зоны	Градиент от красного (≤40) до зелёного (≥180)	Без заливки
Свет	Единый набор видимых источников комнаты: внешние controls + собственный источник по флагу «Это источник света»; автоматические light.* — fallback	Цвет «включено», «всё выключено» или «нет источников»	Цвет «нет источников», если его прозрачность >0
Температура	Источник комнаты или среднее датчиков	Холодно ниже минимума, комфорт между границами, жарко выше максимума	Без заливки

Новая вручную созданная область по умолчанию предлагает «Световые источники». Старые планы без сохранённого режима остаются без заливки.

Наследование

Уровень	Что можно изменить
Общие настройки	Цвет и прозрачность всех состояний, радиус света, цвет стен
Пространство	Активный режим, температурные границы, показ LQI, фон
Комната	Наследовать или явно выбрать Нет/LQI/Свет/Температуру; отдельный Glow не выбирается
Устройство	Явно стать источником света, радиус свечения, цвет эффекта

Что считается светом

Источник	Заливка «Свет»	Световое пятно Glow	Жёлтая подложка устройства
Видимое light.* = on	Да	Да	Да
switch.* = on, обычный	Нет	Нет	Да
switch.* = on + «Это источник света»	Да	Да	Да
Управляемая группа controls	Да, по состояниям группы	Только у отдельных маркеров реальных источников; выключатель сам пятно не создаёт	Да, если работает любой источник
Скрытый маркер	Нет	Нет	Не рисуется

Для всех четырёх потребителей — Glow, заливки «Свет», строки света в карточке комнаты и группового toggle — набор вычисляется одинаково. Если заданы controls, они описывают управляемые источники и состояние группы, но не назначают координаты выключателя координатами лампы. Пятно Glow строится только от отдельного маркера реального light.* либо от маркера с явным флагом «Это источник света». Без явных настроек автоматически учитываются собственные light.* устройства. Одна сущность не считается дважды; при наличии и контроллера, и лампы физическая точка принадлежит лампе независимо от порядка реестра. Собственная switch.*-сущность внутри старого controls игнорируется, пока пользователь явно не включит флаг источника. Ручная привязка маркера к комнате (room_id) точнее HA-зоны и работает в том числе для комнаты без HA Area.

В режиме Glow свет ограничивается внутренним контуром комнаты, проходит в комнаты через двери и свободно объединяет комнаты через виртуальные границы. Наружная дверь не выпускает свет за пределы дома. У толстых стен сектор двери дополнительно обрезается внутренним тоннелем и откосами.

Цвет пятна выбирается по приоритету: RGB-состояние лампы → цветовая температура → общий цвет света. Яркость влияет на интенсивность, но имеет минимальный визуальный порог 15%.

14. Редактор подложки

Инструменты

Инструмент	Создание	Редактирование
Выбрать	Клик выбирает объект	Drag перемещает; общая рамка масштабирует пропорционально и поворачивает; Shift разрешает разные оси; двойной клик открывает свойства; Delete/Backspace удаляет
Подложка	Доступна, если есть изображение	Drag перемещает изображение, угловые ручки масштабируют, верхняя поворачивает; Shift разрешает разные оси/свободный угол; двойной клик открывает числовые размеры и угол
Линия	Drag между двумя точками	Цвет, толщина и стиль «Сплошная / Пунктирная»; показываются длина и угол. Стиль меняется только в свойствах по двойному клику
Прямоугольник	Drag по диагонали; Shift фиксирует квадрат	Контур и независимая заливка с прозрачностью; показываются ширина × высота и площадь
Овал	Drag по габаритам; Shift фиксирует круг	Контур и независимая заливка с прозрачностью; показывается R либо Rx × Ry
Текст	Клик открывает диалог	Многострочный текст, переменные HA, цвет/прозрачность, физический размер и угол; масштаб и поворот ручками
Мебель	Выбор символа и клик по центру	Символ, размер, цвет, толщина, поворот; магнитится к стене
Стереть	Клик по объекту	После подтверждения удаляет объект; действие можно отменить через Undo

Новые фигуры создаются не меньше половины клетки. После создания объект остаётся выбранным. Создание, движение и изменение размера всегда квантуются по сетке. При рисовании и перемещении действует лёгкий магнит к углам, серединам, центрам и рёбрам других объектов декора и комнат; устройства, проёмы и картинка-подложка не являются целями магнита.

Картинка подложки интерактивна только в своём инструменте. В остальных инструментах этого редактора она показана с непрозрачностью 0.5, а в просмотре и других редакторах — 1.0.

Цвет контура/текста/мебели и его прозрачность задаются общим компактным полем: нажмите на образец цвета, чтобы открыть выбор цвета и прозрачности. Толщина и размер текста хранятся физически и показываются в сантиметрах или дюймах. Для прямоугольника и овала заливка имеет собственные цвет и прозрачность. Большие размеры в свойствах показываются в метрах или футах.

Параметры нового объекта показываются в общей суб-панели над холстом только для применимого инструмента. При выборе готового объекта эта же панель показывает «Свойства» и «Удалить». Палитра мебели использует расширенный вариант той же поверхности и также не меняет высоту или масштаб рабочей области.

Редактор подложки использует тот же именованный Undo/Redo на 50 команд, что и геометрия плана. Esc отменяет только незавершённое рисование или текущий drag/resize/поворот; после отпускания указателя используйте Ctrl+Z/Cmd+Z. Повтор — Ctrl+Shift+Z либо Ctrl+Y.

Двойной клик в «Выбрать»

Объект	Что открывается
Текст	Полный диалог текста и HA-переменных
Линия	Длина, угол, цвет/прозрачность и физическая толщина; концы также двигаются отдельными ручками
Прямоугольник/овал	Ширина, высота, угол, контур и независимая заливка с прозрачностью
Мебель	Символ, ширина, глубина, угол, цвет/прозрачность и физическая толщина контура
Картинка-подложка	Ширина, высота и угол (двойной клик в инструменте «Подложка»)

Живой текст Home Assistant

Поле принимает обычный текст и любое количество ссылок в фигурных скобках до лимита 200 символов.

На улице {sensor.outdoor_temperature}, влажность {sensor.outdoor_humidity}%
Котёл: {climate.boiler:hvac_action}

Поддерживаемые формы:

Синтаксис	Значение
{sensor.room_temperature}	Состояние сущности, отформатированное Home Assistant
{climate.living_room:current_temperature}	Атрибут сущности
{climate.living_room.current_temperature}	Альтернативная форма атрибута

Выбор сущности и затем состояния/атрибута вставляет токен в позицию курсора либо заменяет выделение. Токены можно вводить вручную, смешивать с любым текстом и добавлять несколько раз.

Ситуация	Вывод
Сущность/атрибут отсутствует	—
Состояние unknown/unavailable	—
Массив	Элементы через запятую
Объект/dict	Не выводится
Некорректные скобки	Остаются обычным текстом
Очень длинное значение	Обрезается до 60 символов

Ctrl+Enter/Cmd+Enter сохраняет подпись. Переносы строк сохраняются, автоматического переноса по ширине нет.

Мебель

Библиотека содержит группы мебели, бытовой техники, сантехники и прочих символов. Размер можно задать в метрах или десятичных футах. При размещении рядом со стеной предмет:

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

15. Солнце и фон день/ночь

Для солнечных функций нужны sun.sun и направление севера на плане. Общие значения можно переопределить в конкретном пространстве.

Настройка

1. В общих настройках выберите фон Следует за солнцем при необходимости.
2. Укажите север числом 0–359° или поверните стрелку компаса.
3. Включите Солнечный свет через окна.
4. Для отдельного этажа задайте локальный север/режим/включение либо оставьте наследование.

Поведение

Условие	Результат
Редактор открыт	Лучи не рисуются
Солнце ниже 3°	Лучей нет
Переход через 3°	Слой плавно появляется/исчезает за 2 секунды
Окно внутреннее	Луча нет
Окно не смотрит на солнце	Луча нет
Толстая внешняя стена	Луч начинается из внутренних углов тоннеля окна
«Скрыть проёмы» включено	Символ окна скрыт, луч продолжает работать
Белый план	По бокам луча есть тонкая 1px тёмная кромка для читаемости
Любая погода, включая дождь и снег	Погода не влияет на лучи

Луч обрезается чистым контуром комнаты, имеет чёткие боковые границы и плавно растворяется по длине.

Фон день/ночь меняет оттенок вокруг плана по высоте солнца: нейтральный день, тёплый горизонт и тёмная ночь. Сам план ночью затемняется не более чем примерно на 10%. Обычные изменения плавные; после сна вкладки большой разрыв корректируется сразу.

Тени от других крыльев здания и внешних объектов не моделируются.

16. Роботы-пылесосы

Живая позиция доступна для маркера пылесоса, если источник отдаёт конечные координаты vacuum_position или robot_position. Поддерживаются Xiaomi Cloud Map Extractor, dreame-vacuum (Tasshack) и Valetudo-подобные камеры. Roomba со строковым атрибутом position в текущий этап не входит.

В настройках устройства блок «Живая позиция» показывает источник, интеграцию, статус, наличие позиции, число комнат, путь и ID карты. По умолчанию источник выбирается среди сущностей того же устройства независимо от порядка в реестре. Если XCME-камера не относится к устройству, откройте «Выбрать источник» → «Все камеры» и выберите её явно. Глобальные камеры никогда не выбираются автоматически.

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

Для Xiaomi Cloud Map Extractor включите атрибуты vacuum_position, rooms, path и map_name; точная YAML-подсказка показывается в самом диалоге.

Калибровка

Режим	Требования	Результат
Автоматическая	В карте робота и плане совпадают минимум три названия комнат	Вычисляется аффинное преобразование; при ошибке до 40 см оно сохраняется сразу
Ручная	Доступна карта/контуры робота	Полупрозрачную карту можно двигать, масштабировать, поворачивать на 90° и зеркалить

Для каждого map_id хранится собственная калибровка, поэтому многоэтажный робот может работать с несколькими пространствами. Если максимальное расхождение больше 40 см, настройки не меняются до выбора «Применить». Можно вместо этого открыть ручную подгонку или отменить операцию.

Позиция и путь

Настройка пути	Во время уборки	После уборки
Никогда	Нет пути	Нет пути
Во время уборки	Текущий путь	Не показывается
Всегда	Текущий путь	Последний завершённый путь

• Позиция показывается, когда пылесос cleaning/returning/on и данные валидны.
• Клик по движущемуся значку открывает HA more-info пылесоса.
• Стационарный маркер док-станции/устройства остаётся отдельным.
• Путь хранится на сервере, переживает перезагрузку карточки и виден другим клиентам.
• Хранятся текущая и предыдущая уборка; сервер ограничивает сырой путь 2000 точками с прореживанием, клиентский живой буфер — 600 точками.
• Позиция старше 60 секунд визуально считается устаревшей.
• Разрывы integration path сохраняются отдельными участками и не соединяются ложной линией. Хранятся максимум 64 рисуемых участка и 4000 точек.
• Для текущего пути приоритет таков: путь интеграции → серверный текущий run → локальный буфер. Пустой или одноточечный участок приоритет не перехватывает.

17. Киоск-режим

type: custom:houseplan-card
kiosk: true
cycle: 30

Возможность	Поведение
Шапка карточки	Скрыта
Редакторы	Недоступны
Высота	100dvh
Свайп	Листает пространства по кругу при масштабе 1:1
Щипок/панорама	Масштабирует и двигает план
Двойной тап	Сбрасывает масштаб к 1:1
Удержание пустого места 3 секунды	Открывает локальные размеры иконок и текста
cycle	Автоматически листает пространства; при взаимодействии пауза 60 секунд

Размеры киоска хранятся локально в браузере конкретного экрана. Это позволяет одному планшету использовать крупные значки, не меняя другие клиенты.

House Plan скрывает только собственную шапку. Шапка Home Assistant скрывается средствами companion app или отдельным kiosk-плагином.

18. Статическая карточка пространства

houseplan-space-card показывает один план как неинтерактивную живую схему. Маркеры используют те же состояния, значения, тревоги и эффекты, что полный план, но не открывают подсказки или more-info. Единственный интерактивный элемент — нижняя кнопка перехода.

type: custom:houseplan-space-card
space: ground_floor
title: Первый этаж
show_button: true
button_label: Открыть полный план
button_target: /lovelace/house
icon_size: 2.5
live_states: true
show_temperature: true
show_signal: true

Поле	По умолчанию	Назначение
space	обязательно	ID пространства
title	название пространства	Заголовок
show_button	true	Показывать нижнюю кнопку
button_label	локализованный текст	Подпись кнопки
button_target	/plan-doma	Путь к полному плану; карточка добавляет #space=<id>
icon_size	базовый	Размер статических маркеров
live_states	true	Рабочие/открытые/недоступные состояния, смена иконок и активность; тревоги видны всегда
show_temperature	true	Компактные температура и влажность у подходящих устройств
show_signal	true	LQI у маркеров, если он доступен

Устаревшее YAML-поле aspect_ratio в v1.59.1 фактически не используется и больше не предлагается визуальным редактором. Холст квадратный, а размер карточки определяется содержимым; старое поле можно безопасно удалить.

19. Обслуживание планов

Кнопка Общие настройки → Оптимизировать планы запускает явное обслуживание. Сначала показывается точный предпросмотр; данные не меняются до подтверждения.

Что делает оптимизация

Операция	Что меняется
Миграции модели	Старые, однозначно преобразуемые поля переводятся в текущий формат; для entity:switch.* собственный switch в старом controls становится флагом «Это источник света» (для device:* это делает сохранение настроек устройства, где доступен реестр HA)
Масштаб сетки	Некорректный старый cell_cm приводится к допустимому диапазону 0,1–1000 см
Комнаты	Вершины округляются к сетке
Декор и мебель	Положение и размеры округляются к сетке
Устройства и подписи комнат	Позиции округляются к сетке
Проёмы	Возвращаются на ближайшую стену, смещение вдоль стены округляется, угол исправляется
Стены	Одинаковые соседние участки толщины объединяются
Виртуальные стены	Соседние/перекрывающиеся участки объединяются и приводятся к общей границе

Перед записью диалог показывает количество затрагиваемых элементов, максимальный сдвиг в сантиметрах и пространство с этим сдвигом.

Что оптимизация сохраняет

• неизвестные поля новых версий;
• положение и масштаб изображения подложки;
• сохранённые виды/границы холста;
• неиспользуемые записи раскладки;
• файлы подложек и вложения.

Риск и отмена

Старые и импортированные объекты между узлами будут привязаны к сетке. Новые редакторы такие координаты не создают. После оптимизации доступна одна серверная отмена, но только до следующего изменения плана. Новый edit делает резервную копию оптимизации устаревшей.

20. Хранение, совместная работа и резервные копии

Где лежат данные

Данные	Хранение
Пространства, комнаты, стены, проёмы, декор и настройки маркеров	HA storage houseplan.config
Позиции маркеров и комнатных карточек	HA storage houseplan.layout
Планы	config/houseplan/plans
Вложения устройств	config/houseplan/files
Путь пылесоса	Отдельное серверное storage House Plan
Кэш, текущий вид, локальный киоск-масштаб	localStorage конкретного браузера

Обычная резервная копия Home Assistant, включающая каталог config, сохраняет конфигурацию и файлы House Plan. Перед крупной ручной переработкой плана всё равно разумно сделать свежую резервную копию HA.

Несколько клиентов

• Конфигурация и позиции общие для всех карточек и пользователей.
• Точечные обновления позиций не должны перетирать одновременные движения других устройств.
• Изменения транслируются через WebSocket и появляются без перезагрузки.
• Масштаб просмотра, последнее открытое пространство и киоск-размеры локальны браузеру.
• Если открыт несохранённый диалог и Lovelace быстро пересобирает карточку, текущая версия пытается восстановить черновик в течение короткого окна.

Файлы и квоты

Объект	Форматы	Лимит одного файла	Общий лимит
План	SVG, PNG, JPG, WebP	8 МБ	200 файлов / 256 МБ; в селекторе показываются 60 последних
Вложение устройства	PDF, PNG, JPG/JPEG, WebP, TXT	50 МБ	1000 файлов / 1 ГБ; до 50 ссылок на маркер

Запись также отклоняется, если на разделе HA остаётся меньше 512 МБ свободного места. Файлы не удаляются только из-за возраста. Подложка, отсоединённая от пространства, остаётся на сервере до явного удаления. Незавершённые временные загрузки очищаются автоматически.

21. Ограничения текущей версии

Ограничение	Практическое следствие
Только замкнутые комнаты	Нельзя оставить отдельную стену или незамкнутый контур
Незавершённый контур не сохраняется	Переключение режима/инструмента теряет текущие точки
Виртуальная стена только между комнатами	Нельзя открыть наружную стену или сделать ответвление из середины
Одна HA-зона на одну комнату	Нельзя автоматически разделить одну HA-зону на несколько комнат; используйте ручное назначение
Проёмы инертны в просмотре	Нельзя открыть их карточку кликом по полотну; только отдельный значок замка активен
Комнатные подсказки основаны на hover	На touch-экране без hover площадь доступна только косвенно/в редакторе Resize
Редакторы desktop-first	На touch-устройствах функции редактирования могут быть неудобны, ограничены или отсутствовать; для создания и обслуживания плана используйте компьютер
Солнце не знает внешнюю 3D-геометрию	Нет теней от соседних крыльев, навесов и деревьев
Иконки по регулярным выражениям	Правила мощные, но требуют знания regex; первая совпавшая строка побеждает

Технические пределы защиты хранилища: до 50 пространств, 400 комнат на пространство, 2000 маркеров, 500 проёмов, 1000 элементов декора, 500 записей стен и 500 виртуальных участков на пространство. Конфигурационный пакет ограничен 2 МБ.

22. Диагностика

Карточка не загрузилась

Симптом	Проверка
Custom element doesn't exist: houseplan-card	Интеграция добавлена и загружена; ресурс — /houseplan_files/houseplan-card.js, тип module; очистите кэш фронтенда
MIME text/plain	Использован неверный файловый URL /custom_components/...; замените на /houseplan_files/...
Интеграция не находится	Папка называется точно custom_components/houseplan; HA перезапущен; журнал не содержит ошибки импорта
После обновления старая версия	Перезапустите HA, перезагрузите ресурсы/браузер; URL ресурса содержит версионный query, который интеграция обновляет сама

Устройства или значения не появились

Симптом	Причина/действие
Устройство не на плане	Проверьте HA-зону комнаты; откройте Скрытые и деактивированные; если marker серый — активируйте устройство/сущность в HA; при необходимости добавьте маркер вручную
Устройство помечено деактивированным	Откройте его серый marker и нажмите «Открыть в HA». Если показано ограничение реестра, проверьте права текущего HA-пользователя или войдите администратором
Новая сущность не предлагается	В диалоге привязки включите Показывать сущности
Нет температуры climate	В маркере включите использование current_temperature
Нет значения в value-режиме	Основное состояние нечисловое; используйте иконку или живой текст подложки
Нет LQI	Сущности устройства не отдают известный атрибут качества; проверьте локальную настройку пространства
Реле не светит в Glow	Включите «Это источник света». controls управляет внешними лампами, но не переносит их Glow на координаты реле; реальные лампы должны иметь свои маркеры
Реле не влияет на заливку «Свет»	Включите «Это источник света», проверьте состояние основного switch.* и привязку маркера к нужной комнате

Геометрия выглядит неверно

Симптом	Действие
Дверь/окно слегка не на стене	Перетащите в редакторе плана или запустите оптимизацию после просмотра отчёта
Появились мелкие отрезки стен	Закройте соседние виртуальные участки; оптимизация объединит одинаковые реальные/виртуальные фрагменты
Площадь отличается от внешнего контура	Для толстых стен это ожидаемо: показывается чистая внутренняя площадь
После оптимизации сдвинулся старый декор	Объект был сохранён старой версией или импортирован вне сетки; отмените оптимизацию до следующего edit и скорректируйте его на сетке
Лучей нет	Нужны sun.sun, север, включённые лучи, наружное окно, высота солнца ≥3° и подходящее направление

Пылесос не движется

1. Проверьте наличие vacuum_position или robot_position у выбранной сущности.
2. Убедитесь, что включена живая позиция и выбрана правильная сущность-источник.
3. Проверьте калибровку текущего map_id.
4. Убедитесь, что пылесос находится в состоянии cleaning/returning/on.
5. Если координаты обновляются рывками реже минуты, бледнение позиции может быть ожидаемым.

Краткая памятка безопасности

• Не отключайте ограничение редактирования администраторами без необходимости: разрешение включает загрузку файлов и запись всего плана.
• Для потенциально опасных Toggle/Run/Cover включайте подтверждение.
• Замки открываются только через специальную карточку проёма с подтверждением; не обходите это ручной конфигурацией.
• Перед удалением пространства, массовым объединением комнат или оптимизацией сделайте резервную копию Home Assistant.
• Всегда читайте отчёт оптимизации: она исправляет все старые и импортированные координаты между узлами.