mirror of
https://github.com/Matysh/houseplan-card
synced 2026-09-29 03:09:36 +00:00
Sergey Matyunin
d03a68b88a
Прямые и винтовые лестницы получили отдельную модель, инструменты редактора, безопасную межэтажную навигацию, вычитание из чистой площади и плоское отображение в 2.5D. Issue: #663 User-Visible: yes
210 lines
8.8 KiB
Markdown
Executable File
210 lines
8.8 KiB
Markdown
Executable File
# 🏠 House Plan — a live home map for Home Assistant
|
||
|
||
[](https://github.com/hacs/integration)
|
||
[](https://github.com/Matysh/houseplan-card/releases)
|
||
[](https://github.com/Matysh/houseplan-card/actions)
|
||
[](https://demo.houseplan.tech)
|
||
[](https://t.me/ha_houseplan)
|
||
|
||
📘 **[Full user guide](docs/USER-GUIDE.md)** · 🇷🇺 **[Русский](README.ru.md)** · 🗂 **[Project issues](https://github.com/Matysh/houseplan-card/issues)**
|
||
|
||
<!-- docs-section: overview -->
|
||
|
||
## Your whole home at a glance
|
||
|
||
House Plan turns Home Assistant into a live map of your home. Open the dedicated
|
||
**House Plan** item in the Home Assistant sidebar, upload a plan or draw rooms,
|
||
bind them to Home Assistant areas, and
|
||
the area's devices appear automatically. You can immediately see where a light
|
||
is on, a door is open, a room is too cold, Zigbee signal is weak, or a leak
|
||
sensor has fired.
|
||
|
||
|
||
|
||
Setup is entirely graphical: no floor-plan YAML, Inkscape, or external editor.
|
||
Plan data and device positions live on the Home Assistant server and stay in
|
||
sync across screens.
|
||
|
||
> **Edit on a desktop computer.** View and kiosk are fully supported on phones
|
||
> and tablets. The editors are designed primarily for a mouse and keyboard;
|
||
> individual touch editing operations may be awkward or unavailable. See the
|
||
> exact [touch support contract](docs/TOUCH-SUPPORT.md).
|
||
|
||
<!-- docs-section: features -->
|
||
|
||
## What House Plan provides
|
||
|
||
- **Live state and safe actions.** Lights and other safe devices can toggle from
|
||
the plan; a lock cannot be opened by an accidental plan tap.
|
||
- **Three built-in editors.** Plan creates rooms, walls and openings; Device
|
||
places and configures markers; Background adds lines, labels and furniture.
|
||
- **Area-aware rooms.** New devices appear automatically, while room cards can
|
||
show temperature, humidity, light state and average LQI.
|
||
- **Light and environment.** Room fills, lamp Glow, wall shadows, a day-cycle
|
||
backdrop and sunlight through windows.
|
||
- **Flat or 2.5D.** One switch in General settings › Display shows the plan
|
||
with depth everywhere: raised device tiles with soft floor shadows and a soft
|
||
wash of sunlight; decor and wall colours stay as you set them.
|
||
- **Doors, windows, gates and vacuums.** Openings follow real contacts and locks;
|
||
a robot can show its position, dock and travelled path.
|
||
- **Several floors and screens.** Space tabs, swipe navigation, local viewport,
|
||
and a separate initial floor for each card.
|
||
- **Wall-display kiosk.** A plan-only view with fullscreen navigation and icon
|
||
sizes saved for that display.
|
||
|
||
|
||
|
||
<!-- docs-section: first-run -->
|
||
|
||
## Your first working room
|
||
|
||
1. Install the integration and open **House Plan** in the Home Assistant sidebar.
|
||
2. Create the first **space**: upload SVG/PNG/JPG/WebP, reuse an uploaded image,
|
||
or choose no image and draw the plan by hand.
|
||
3. In Plan, select **Room outline**, place vertices, and click the first point to
|
||
close the outline.
|
||
4. Name the room and bind it to a Home Assistant area. Use “No area” for a room
|
||
that has no devices.
|
||
5. Open Device: devices from the bound area are already placed; drag their
|
||
markers to the correct positions.
|
||
6. Optionally use Background for lines, text and furniture.
|
||
7. Return to View. The plan now displays live state and accepts safe actions.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Every workflow and edge case is in the [full user guide](docs/USER-GUIDE.md).
|
||
The [Background editor contract](docs/DECOR-EDITOR.md) and
|
||
[vacuum guide](docs/VACUUM.md) are the authorities for those subsystems.
|
||
|
||
<!-- docs-section: installation -->
|
||
|
||
## Installation
|
||
|
||
### HACS
|
||
|
||
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=Matysh&repository=houseplan-card&category=integration)
|
||
|
||
House Plan is in the HACS default catalog — no custom repository needed.
|
||
|
||
1. In HACS search for **House Plan** and install it.
|
||
2. Restart Home Assistant.
|
||
3. Open **Settings → Devices & services → Add integration → House Plan**.
|
||
|
||
The sidebar page and optional dashboard cards are registered automatically.
|
||
After installing or updating House Plan,
|
||
restart Home Assistant and fully reload the page: `Ctrl+F5` on Windows/Linux or
|
||
`Cmd+Shift+R` on macOS.
|
||
|
||
#### Storage mode (Home Assistant default)
|
||
|
||
No YAML is normally needed. If automatic registration did not make the card
|
||
available, open **Settings → Dashboards → menu ⋮ → Resources → Add
|
||
resource**, enter `/houseplan_files/houseplan-card.js`, and select **JavaScript
|
||
module**.
|
||
|
||
#### YAML resources mode (Home Assistant 2026.2+)
|
||
|
||
To manage resources in `configuration.yaml` independently of the dashboard
|
||
mode, use:
|
||
|
||
```yaml
|
||
lovelace:
|
||
resource_mode: yaml
|
||
resources:
|
||
- url: /houseplan_files/houseplan-card.js
|
||
type: module
|
||
```
|
||
|
||
#### Legacy Home Assistant 2024.6–2026.1
|
||
|
||
Only for a full-YAML dashboard that is already managed in YAML, use:
|
||
|
||
```yaml
|
||
lovelace:
|
||
mode: yaml
|
||
resources:
|
||
- url: /houseplan_files/houseplan-card.js
|
||
type: module
|
||
```
|
||
|
||
`mode: yaml` changes the dashboard itself to YAML mode. Do not switch a storage
|
||
dashboard to legacy YAML just for House Plan; use the Storage mode instructions
|
||
above instead. Do not use the on-disk path inside `custom_components`; Home
|
||
Assistant does not serve that path as a JavaScript module.
|
||
|
||
### Manual installation
|
||
|
||
Copy the complete `custom_components/houseplan` release folder to
|
||
`config/custom_components`, restart Home Assistant, and add the House Plan
|
||
integration. Do not copy only `houseplan-card.js`: the card also uses an
|
||
internal manifest and content-hashed modules from the same release.
|
||
|
||
### Open House Plan
|
||
|
||
After the integration is added, open **House Plan** in the Home Assistant
|
||
sidebar. This full-page view is the primary entry point and needs no dashboard
|
||
or YAML setup. It remembers the last space but always returns from another HA
|
||
page in View rather than reopening an editor. Users without editing permission
|
||
see the same live plan without editor controls.
|
||
|
||
If the sidebar entry cannot be registered, the integration and existing
|
||
dashboard cards continue to work; check **Settings → System → Repairs → System
|
||
information → House Plan** after restarting and hard-refreshing HA.
|
||
|
||
### Optional dashboard card
|
||
|
||
Add the card only when House Plan must be embedded in a dashboard. In a Sections
|
||
view it requests full width by default, while a manual size chosen in HA remains
|
||
authoritative. Add it in the UI or as:
|
||
|
||
```yaml
|
||
type: custom:houseplan-card
|
||
title: House plan
|
||
```
|
||
|
||
Different screens may start on different spaces:
|
||
|
||
```yaml
|
||
type: custom:houseplan-card
|
||
default_floor: ground
|
||
```
|
||
|
||
All cards share server-side rooms and coordinates. Current mode, viewport and
|
||
selected space remain local to the screen. Revision checks and live sync cover
|
||
concurrent clients, but avoid editing the same object in two browsers at once.
|
||
|
||
## Detailed documentation
|
||
|
||
- [Full user guide](docs/USER-GUIDE.md)
|
||
- [Mouse/touch/keyboard matrix](docs/USER-GUIDE.md#6-navigation-zoom-and-input)
|
||
- [Plan tools](docs/USER-GUIDE.md#plan-tools-at-a-glance)
|
||
- [Stairs and floor links](docs/STAIRS.md)
|
||
- [Background editor](docs/DECOR-EDITOR.md)
|
||
- [Robot vacuums](docs/VACUUM.md)
|
||
- [Touch support](docs/TOUCH-SUPPORT.md)
|
||
|
||
<!-- docs-section: support -->
|
||
|
||
## Support and feedback
|
||
|
||
- Questions and plan examples: [Telegram @ha_houseplan](https://t.me/ha_houseplan).
|
||
- Bugs and proposals: [GitHub Issues](https://github.com/Matysh/houseplan-card/issues).
|
||
- Before reporting, update House Plan, restart HA and hard-refresh the page.
|
||
Include the version, browser, logs and reproduction steps; private entity IDs
|
||
may be replaced with fictional ones.
|
||
|
||
Documentation screenshots are produced by the reproducible
|
||
`npm run build && node demo/docs/capture.mjs` command using synthetic data only. Scenario version,
|
||
source fingerprint and every image hash are recorded in the
|
||
[screenshot index](docs/images/screenshots.json).
|
||
|
||
License: [MIT](LICENSE).
|