Device Floorplan
Put your Home Assistant devices on your own floorplan image and watch your
home live: lights glowing in their real colour and staying in their room, the
plan darkening at night, AC air flow, people in their rooms, an interactive Zigbee map (ZHA) and
much more. Things that usually take custom cards, templates and lots of YAML,
done with clicks: upload your picture (or start from a sample plan), drag your
rooms onto it, press Auto-place and fine-tune by dragging.
📖 Full guide: https://johnkotrolos.github.io/ha-device-floorplan/
🎮 Live demo: https://johnkotrolos.github.io/ha-device-floorplan/demo/
Beta
Device Floorplan is in beta. It runs every day in a real home with ~90
devices, but your setup is different from mine, and that's exactly where
your feedback helps. Please
open an issue
for anything that breaks, confuses you or is missing. Screenshots help a lot.
Known limits today:
- The interactive Zigbee map (roles, links, link quality) needs ZHA.
- Room shapes are optional: without one, a room is a name pin and its light glow
isn't stopped by walls.
- Best on PC (Editor) and tablets / wall panels (card); phones work but aren't
optimised yet.
- People need a room sensor per person (Bermuda, ESPresense, a template…).
No floorplan yet? See
Turn your sketch into a floorplan in 10 minutes.
Features
- Welcome intro on the first visit (reopen it from ⋮ → Show intro).
- Create a plan first, then choose which kinds of devices belong on it
(the rest is skipped: nothing changes in HA).
- Floorplan image: drop a file, pick an image that is already in Home
Assistant (
config/www, stays linked, a backup copy is kept), or start from
one of seven bundled sample plans.
- Three guided steps:
- Measure (optional): one horizontal and one vertical measurement give
the plan a real scale. Drag the ends to adjust, click a label to change
the length or delete it.
- Mark rooms: drag your HA areas onto the plan. Rooms that are not on
this plan can be hidden: their devices leave the list. Optionally give a
room a shape (four corners, + for more): light then stays inside it.
Overlapping shapes are one open space, a gap between them is a wall.
- Place devices: Auto-place, click-to-place (with "then next" queue) or
drag. Auto-placed devices are approximate (dashed) until you drag or
confirm them.
- Layers: the current step is shown in full, the others faded (and not
clickable). The Layers button on the plan switches them off completely.
- The plan always fits the screen: zoom, scale and layers sit on the plan,
the legend below always stays visible.
- Floors: each plan is an HA floor (or a level, or a free "view"). The ⋮ on
a floor tab has settings, rename, replace image, export, move and delete.
- “I'm ready” appears as soon as the first device is placed: see what was
created in HA, preview the live view and add it to a dashboard in one click.
- Dashboard card
custom:device-floorplan-card with live overlays, several floors,
a night look with glowing lights, people in their rooms, and a companion
chip card for your top bar.
- Export a plan as CSV, JSON backup (re-importable, also on another HA) or
PNG picture.
- Search finds everything: names, rooms, models, entity names and ids, also
skipped devices and helpers without a device (which can be placed on their own).
- One marker per device per overlay, and you choose what it shows: the leading
value, extra readings (with their own icons), a badge, the icon and the tap. Press
the ✎ Edit markers pen on the card while editing the dashboard and click a marker.
- Live shows what is happening at home right now: things that are off stay
hidden, lights that are on glow in their real colour.
Install
From the Marketplace (Home Assistant 2026.11 and later, recommended)
- Settings → Marketplace → add a custom repository by its link:
https://github.com/JohnKotrolos/ha-device-floorplan (the first time,
Home Assistant asks you to sign in to GitHub, read-only).
- Find Device Floorplan → install, accept the community notice.
- Restart Home Assistant.
An install made with HACS moves to the Marketplace by itself.
With HACS (Home Assistant before 2026.11): HACS → ⋮ → Custom repositories
→ the link above, type Integration → find Device Floorplan → Download
→ restart Home Assistant.
Manually: copy custom_components/device_floorplan from the
latest release
into your config/custom_components/ folder and restart Home Assistant.
Then:
-
or Settings → Devices & services → Add integration → Device Floorplan.
- Open Floorplan Editor in the sidebar.
Options (Settings → Devices & services → Device Floorplan → Configure):
new-device notification and automatic placement, both on by default.
What you get in Home Assistant
Each plan is a device (“Ground floor plan”) under Settings → Devices with:
image.device_floorplan_<plan>: the plan picture, usable in any card.sensor.device_floorplan_<plan>: state = number of devices on the plan;
attributes (kept out of the history database): plan_id, image_url,
image_fallback_url, image_width, image_height, kind, floor_id,
level, image_type, metres_per_px_x/y, real_width_m, real_height_m,
approx_count, devices
({device_id: {name, x, y, px, py, approx, z?, ieee?, mac?, via?, main_entity, entities, roles, conns, group, box?, light?, parts?}},
x/y in % of the image; all entities of a device share its position),
entities (helpers / entities without a device placed on their own), bonds, phantoms,
zigbee_devices (the format of the Zigbee Floorplan Card) and areas (room pins).
sensor.device_floorplan_new_devices: devices added since setup that are not
placed or skipped yet.
Action:
action: device_floorplan.get_positions
data:
plan: ground_floor
response_variable: plan
Privacy
A floorplan with device positions is a map of your home, so plan images are
only served to logged-in users (/api/device_floorplan/image/…, the
frontend uses signed URLs). They are stored in config/device_floorplan/.
Images you link from config/www stay public at /local/…, as everything in
that folder. Planner data lives in .storage/device_floorplan.
Dashboard card
The easiest way: press I'm ready → Add to dashboard in the Floorplan Editor. The card shows
your plan and its overlay buttons: Plan · Live · Lights · Comfort · Security · Network · Health,
People, plus your own. Tap a light to switch it, a cover for its controls, a reading for its
last 24 hours; hold for the details. Several floors get a floor rail next to the plan. At night
the plan darkens and the lights that are on glow (follows the sun by default).
Everything else (floors, which overlays, where the buttons are, what each overlay shows, light
scenes, rooms, people, day & night, tap behaviour, look, per-device settings) is set in the card
editor. Other cards can switch the overlay with the action device_floorplan.show_overlay, or use
the chip card that glows for the active overlay. See the card reference.
type: custom:device-floorplan-card
plans: [ground_floor, first_floor]
Keyboard
| Key | Action |
|---|
| Esc | Stop placing / measuring, cancel a drag, close menus and panels |
| Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z (or Ctrl+Y) | Undo, redo |
| Delete / Backspace | Remove the selected device (or the selected measurement) |
| Arrow keys (Shift = bigger steps) | Nudge the selected device |
| Shift while measuring | Don't snap the line straight |
Shortcuts don't fire while you type in a field.
Related projects
Roadmap
Next: polishing from your feedback, people on several floors, light pools in more overlays. Later: motion zones that fade, doors and covers drawn, a coverage map,
Zigbee2MQTT topology. Ideas welcome as issues with the label idea. Full list:
roadmap.
Changelog
- 0.8.0 – Comfort heatmap; room thermometer beats an AC's built-in sensor; appliances (washer, dryer, dishwasher) with "Done · tap to unload"; info card on tap for bonds, phantoms and appliances; one tooltip with hold-and-slide on touch screens; AC air flow from the real unit; TV glow; layers per viewer; Edit markers live preview; trackpad and keyboard zoom in the Editor.
- 0.7.3 – Room pulse for motion; move whole room shapes and bars; shutter + contact combined into one bar with an alert; Wi-Fi / LAN map from your router (FRITZ!Box and others); Network layers show only what applies; option to hide the "N new" button; edge-aware marker labels.
- 0.7.2 – Daylight spreads through the home from windows and shutters; twin bars for window + shutter on one opening.
- 0.7.1 – Softer shutter shading, fading smoothly into open-plan rooms.
- 0.7.0 – Doors, windows and shutters as bars on the plan; night look only inside the home; fixes (AC main entity, chip phantom value, Browser Mod devices, card-mod).
- 0.6.0 – First public release (beta). See the changelog.
