mirror of
https://github.com/Matysh/houseplan-card
synced 2026-07-31 16:38:31 +00:00
76 lines
5.5 KiB
Markdown
Executable File
76 lines
5.5 KiB
Markdown
Executable File
# House Plan Card — интерактивный план дома для Home Assistant
|
||
|
||
Нативная Lovelace-карточка «План дома» (дача, Кирилловское) + интеграция для серверного
|
||
хранения раскладки иконок. Замена прототипа `/local/houseplan/` (iframe + токен + localStorage).
|
||
|
||
- Работает **без токена** — использует объект `hass` фронтенда (сессия пользователя).
|
||
- План этажей (подложки РЕМПЛАННЕР 1489×1053, 1 ед. = 1 px) + двор, комнаты-зоны кликабельны.
|
||
- Устройства строятся **из реестров HA** (devices/entities/areas) с курированием и
|
||
группировкой ламп — те же правила, что в прототипе. Новое устройство с area появляется само.
|
||
- **Живые состояния**: температура у датчиков, подсветка вкл/выкл (свет/розетки/медиа),
|
||
открыто/закрыто (шторы/ворота/замки/датчики), приглушение при `unavailable`. Всё реактивно.
|
||
- Клик по иконке → штатное окно **more-info** (группа ламп → меню: вся группа / отдельные).
|
||
- Клик по комнате → страница зоны (`/config/areas/area/…`) без перезагрузки.
|
||
- **Правка**: кнопка ✥ — drag иконок + ввод X/Y; позиции сохраняются **на сервере**
|
||
(WS-команды интеграции `houseplan`) — раскладка одна на все устройства и браузеры.
|
||
Без интеграции карточка откатывается на localStorage.
|
||
|
||
## Установка (HACS)
|
||
|
||
1. HACS → меню (⋮) → **Custom repositories** → URL этого репозитория, категория **Integration**.
|
||
2. Установить «House Plan», перезапустить HA.
|
||
3. Настройки → Устройства и службы → **Добавить интеграцию → House Plan** (одна запись; опция
|
||
«правка только администраторами»). Интеграция сама раздаёт и подключает JS карточки —
|
||
ресурс Lovelace добавлять не нужно.
|
||
4. В дашборд добавить карточку:
|
||
|
||
```yaml
|
||
type: custom:houseplan-card
|
||
title: План дома · Кирилловское
|
||
default_floor: f1 # f1 | f2 | yard
|
||
icon_size: 22 # px
|
||
show_temperature: true
|
||
live_states: true
|
||
```
|
||
|
||
Только карточка (без серверного хранения): категория **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).
|
||
|
||
## Почему не ha-floorplan
|
||
|
||
Оценивали `ExperienceLovelace/ha-floorplan` (установлен в этом HA): он закрывает SVG-план,
|
||
привязку сущностей и стили по состоянию, но привязки статичны (entity → элемент SVG прописывается
|
||
руками в YAML/SVG), нет автопоявления новых устройств из реестра, нет курирования/группировки
|
||
ламп и главное — нет drag-раскладки с серверным сохранением. Перенос этих требований в
|
||
ha-floorplan потребовал бы генератор SVG+конфига и всё равно не дал бы редактирование из UI.
|
||
Своя карточка (~1 файл) оказалась дешевле и полностью повторяет прототип. Решение: **свой card**.
|
||
|
||
## Документация
|
||
|
||
- [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 (универсализация, редактор разметки, виртуальные устройства)
|
||
|
||
## Разработка
|
||
|
||
```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`.
|
||
|
||
Релиз: тег `vX.Y.Z` → GitHub Release; workflow соберёт и приложит `houseplan-card.js`.
|