mirror of
https://github.com/Matysh/houseplan-card
synced 2026-09-29 03:09:36 +00:00
161 lines
6.8 KiB
Markdown
Executable File
161 lines
6.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. Upload a plan or
|
|
draw rooms directly on the dashboard, 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.
|
|
- **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 add the card to a dashboard.
|
|
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 card is registered automatically. If you manage Lovelace resources
|
|
manually, use the URL served by the integration:
|
|
|
|
```yaml
|
|
resources:
|
|
- url: /houseplan_files/houseplan-card.js
|
|
type: module
|
|
```
|
|
|
|
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.
|
|
|
|
### Add the card
|
|
|
|
Create a dashboard view (Panel works best) and add the card 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)
|
|
- [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).
|