diff --git a/README.md b/README.md index d6d04a1..a641cf5 100755 --- a/README.md +++ b/README.md @@ -1,75 +1,153 @@ -# House Plan Card — интерактивный план дома для Home Assistant +# 🏠 House Plan — интерактивный план дома для Home Assistant -Нативная Lovelace-карточка «План дома» (дача, Кирилловское) + интеграция для серверного -хранения раскладки иконок. Замена прототипа `/local/houseplan/` (iframe + токен + localStorage). +**Живая карта вашего дома прямо в Home Assistant: этажи, комнаты и устройства на настоящем плане — с реальными состояниями, температурой и уровнем сигнала. Всё настраивается мышкой, без единой строчки YAML.** -- Работает **без токена** — использует объект `hass` фронтенда (сессия пользователя). -- План этажей (подложки РЕМПЛАННЕР 1489×1053, 1 ед. = 1 px) + двор, комнаты-зоны кликабельны. -- Устройства строятся **из реестров HA** (devices/entities/areas) с курированием и - группировкой ламп — те же правила, что в прототипе. Новое устройство с area появляется само. -- **Живые состояния**: температура у датчиков, подсветка вкл/выкл (свет/розетки/медиа), - открыто/закрыто (шторы/ворота/замки/датчики), приглушение при `unavailable`. Всё реактивно. -- Клик по иконке → штатное окно **more-info** (группа ламп → меню: вся группа / отдельные). -- Клик по комнате → страница зоны (`/config/areas/area/…`) без перезагрузки. -- **Правка**: кнопка ✥ — drag иконок + ввод X/Y; позиции сохраняются **на сервере** - (WS-команды интеграции `houseplan`) — раскладка одна на все устройства и браузеры. - Без интеграции карточка откатывается на localStorage. +![Интерактивный план дома с устройствами](docs/images/01-plan.png) -## Установка (HACS) +--- -1. HACS → меню (⋮) → **Custom repositories** → URL этого репозитория, категория **Integration**. -2. Установить «House Plan», перезапустить HA. -3. Настройки → Устройства и службы → **Добавить интеграцию → House Plan** (одна запись; опция - «правка только администраторами»). Интеграция сама раздаёт и подключает JS карточки — - ресурс Lovelace добавлять не нужно. -4. В дашборд добавить карточку: +## Что это и зачем + +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, вкл/выкл, открыто/закрыто — всё обновляется в реальном времени. +- **Чёткий зум.** Приближение не «мылит» картинку: план, подписи и иконки остаются векторно-чёткими на любом масштабе. + +--- + +## Установка + +### Через HACS (рекомендуется) + +1. Откройте **HACS → меню (⋮) → Custom repositories**. +2. Вставьте URL этого репозитория, категория — **Integration**, и нажмите **Add**. +3. Найдите в списке **House Plan**, установите и **перезапустите Home Assistant**. +4. Перейдите в **Настройки → Устройства и службы → Добавить интеграцию** и выберите **House Plan**. + +Карточка подключается автоматически — добавлять ресурс Lovelace вручную не нужно. + +### Вручную + +1. Скопируйте папку `custom_components/houseplan` в каталог `config/custom_components` вашего Home Assistant. +2. Перезапустите Home Assistant. +3. Добавьте интеграцию: **Настройки → Устройства и службы → Добавить интеграцию → House Plan**. + +### Добавление экрана с планом + +Создайте новую вкладку дашборда (удобнее всего — в режиме «Панель»/Panel) и добавьте карточку: ```yaml type: custom:houseplan-card -title: План дома · Кирилловское -default_floor: f1 # f1 | f2 | yard -icon_size: 22 # px -show_temperature: true -live_states: true +title: План дома ``` -Только карточка (без серверного хранения): категория **Dashboard/Lovelace**, ресурс -`/hacsfiles/houseplan-card/houseplan-card.js` — позиции будут в localStorage браузера. +Больше ничего указывать не нужно — всё остальное настраивается прямо на экране. -## WS-API интеграции +--- -| Команда | Параметры | Действие | -|---|---|---| -| `houseplan/layout/get` | — | вернуть раскладку `{device_id: {x, y}}` | -| `houseplan/layout/set` | `layout` | заменить целиком | -| `houseplan/layout/update` | `device_id`, `pos` | обновить одну позицию | +## Как пользоваться -Хранилище: `.storage/houseplan.layout` (helpers.storage.Store). +### Шаг 1. Добавьте пространство (этаж) -## Почему не ha-floorplan +При первом открытии план ещё пуст — House Plan сразу предложит создать первое пространство. -Оценивали `ExperienceLovelace/ha-floorplan` (установлен в этом HA): он закрывает SVG-план, -привязку сущностей и стили по состоянию, но привязки статичны (entity → элемент SVG прописывается -руками в YAML/SVG), нет автопоявления новых устройств из реестра, нет курирования/группировки -ламп и главное — нет drag-раскладки с серверным сохранением. Перенос этих требований в -ha-floorplan потребовал бы генератор SVG+конфига и всё равно не дал бы редактирование из UI. -Своя карточка (~1 файл) оказалась дешевле и полностью повторяет прототип. Решение: **свой card**. +![Пустой план — предложение добавить пространство](docs/images/02-onboarding-empty.png) -## Документация +В диалоге задайте **название** (например, «1 этаж») и **загрузите подложку** — картинку плана этажа в формате SVG, PNG или JPG. Оба поля обязательны: без плана кнопка «Сохранить» неактивна. -- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — устройство карточки и интеграции, координаты, WS API -- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — сборка, деплой, грабли окружения (обязательно к прочтению) -- [docs/CHANGELOG.md](docs/CHANGELOG.md) — история версий -- [docs/ROADMAP.md](docs/ROADMAP.md) — план до публикации в HACS (универсализация, редактор разметки, виртуальные устройства) +![Диалог создания пространства](docs/images/03-space-dialog.png) -## Разработка +> 💡 Подложку можно нарисовать в любом планировщике (например, РЕМПЛАННЕР) или сфотографировать бумажный план. Лучше всего SVG — он остаётся чётким при увеличении. -```bash -npm install -npm run build # dist/houseplan-card.js (+ скопировать в custom_components/houseplan/frontend/) -``` +Позже можно добавить сколько угодно пространств (этажи, двор, гараж) кнопкой **＋** рядом со вкладками. -Геометрия комнат/viewBox — `src/data/house.ts`; подложки — `src/data/backgrounds.ts` -(генерируются из data.js прототипа); правила иконок/курирования — `src/rules.ts`. +### Шаг 2. Обведите комнаты -Релиз: тег `vX.Y.Z` → GitHub Release; workflow соберёт и приложит `houseplan-card.js`. +После добавления первого пространства карточка сама переходит в режим разметки. Кликайте по точкам сетки, соединяя их линиями, и замкните контур комнаты кликом по первой точке. + +Как только контур замкнётся, появится окно сохранения комнаты. Здесь нужно **привязать комнату к зоне Home Assistant** — именно это включает автоматику. Для служебных помещений без устройств (холл, сауна) есть кнопка **«Без зоны»**. + +![Разметка комнаты и её сохранение](docs/images/05-room-dialog.png) + +### Шаг 3. Устройства появляются сами + +Как только вы сохранили комнату с привязкой к зоне, **устройства этой зоны автоматически расставляются внутри контура**. Берутся те же устройства, что показаны на странице **Настройки → Устройства → (фильтр по нужной комнате)** — только осмысленные, без служебных записей, мостов и дубликатов. + +Дальше можно просто пользоваться планом: клик по иконке открывает карточку устройства с моделью, ссылкой и кнопкой перехода в Home Assistant. + +![Карточка устройства по клику](docs/images/08-info.png) + +### Шаг 4. Масштаб + +Колесо мыши или кнопки **－ / ⊹ / ＋** приближают и отдаляют план; на сенсорном экране работает «щипок» двумя пальцами. При отдалении виден весь план целиком, при приближении — детали, и всё остаётся чётким. Масштаб запоминается отдельно для каждого пространства. + +![Приближённый план — всё остаётся чётким](docs/images/09-zoom.png) + +### Шаг 5. Правка расположения + +Кнопка **✥ (режим правки)** позволяет перетаскивать иконки мышью, ставя их точно по местам. Позиции сохраняются на сервере и одинаковы во всех браузерах. + +![Режим правки — перетаскивание иконок](docs/images/06-edit.png) + +### Шаг 6. Добавление своих устройств вручную + +Не всё нужно оставлять на автоматику. Кнопкой **＋ (добавить устройство)** в режиме правки можно поставить на план любое устройство, группу или **виртуальную точку** (например, «Вентиль на вводе», которого нет как устройства). Задайте имя, иконку, модель, ссылку, описание и при желании приложите **PDF-инструкцию**. + +![Добавление устройства вручную](docs/images/07-marker-dialog.png) + +--- + +## Удаление + +1. Уберите карточку (или вкладку с планом) из дашборда. +2. **Настройки → Устройства и службы → House Plan → Удалить** запись интеграции. +3. Удалите интеграцию из **HACS** (или папку `custom_components/houseplan` при ручной установке) и перезапустите Home Assistant. +4. При желании удалите сохранённые данные плана: файлы `config/houseplan/` (подложки и вложения) и записи `houseplan.config` / `houseplan.layout` в каталоге `config/.storage`. + +--- + +## Часто задаваемые вопросы + +**Нужно ли что-то писать в YAML?** Нет. Единственная строчка — это добавление карточки на дашборд; всё остальное делается мышкой. + +**Мои устройства не появились на плане.** Устройство появляется, только если его зона в Home Assistant привязана к нарисованной комнате. Проверьте, что у устройства задана комната (Настройки → Устройства), а комната обведена и привязана к этой зоне. + +**Можно ли скрыть лишнее устройство или переименовать его?** Да — в режиме правки откройте устройство и отредактируйте имя, иконку или скройте его. + +**Данные хранятся в облаке?** Нет. Всё хранится локально в вашем Home Assistant. + +--- + +

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

diff --git a/docs/images/01-plan.png b/docs/images/01-plan.png new file mode 100644 index 0000000..6f89f8e Binary files /dev/null and b/docs/images/01-plan.png differ diff --git a/docs/images/02-onboarding-empty.png b/docs/images/02-onboarding-empty.png new file mode 100644 index 0000000..a2ca48a Binary files /dev/null and b/docs/images/02-onboarding-empty.png differ diff --git a/docs/images/03-space-dialog.png b/docs/images/03-space-dialog.png new file mode 100644 index 0000000..7c85614 Binary files /dev/null and b/docs/images/03-space-dialog.png differ diff --git a/docs/images/04-markup.png b/docs/images/04-markup.png new file mode 100644 index 0000000..3de7425 Binary files /dev/null and b/docs/images/04-markup.png differ diff --git a/docs/images/05-room-dialog.png b/docs/images/05-room-dialog.png new file mode 100644 index 0000000..3dc4194 Binary files /dev/null and b/docs/images/05-room-dialog.png differ diff --git a/docs/images/06-edit.png b/docs/images/06-edit.png new file mode 100644 index 0000000..88e95c4 Binary files /dev/null and b/docs/images/06-edit.png differ diff --git a/docs/images/07-marker-dialog.png b/docs/images/07-marker-dialog.png new file mode 100644 index 0000000..b72cad0 Binary files /dev/null and b/docs/images/07-marker-dialog.png differ diff --git a/docs/images/08-info.png b/docs/images/08-info.png new file mode 100644 index 0000000..6a92f7a Binary files /dev/null and b/docs/images/08-info.png differ diff --git a/docs/images/09-zoom.png b/docs/images/09-zoom.png new file mode 100644 index 0000000..2ba3aea Binary files /dev/null and b/docs/images/09-zoom.png differ