Greminn/ha-spatial-context

Home Assistant knows your devices by name and area, but not where anything actually is: how far the hallway sensor is from the router, which walls sit between a Zigbee bulb and its parent, what's on the other side of the garage door. Spatial Context lets you trace your floor plans over the top of your house plans, place your real devices on them, and hand the result to an AI assistant, an automation or a script as real-world, measured data.

An AI assistant answering questions about the home from its floor plan, beside the Top Floor with the Zigbee mesh layer on. The conversations are illustrations of what the map makes possible.

• A floor-plan editor that looks like part of Home Assistant. One tab per HA floor. Trace rooms and walls over your plans, add doors and windows, calibrate to real metres, and place your actual devices.
• Data an AI can reason about. Rooms, walls (with material, thickness and estimated signal loss), doors and windows, and every device's position in real units, from one action or an export.
• A live Connectivity Map. Zigbee, Wi-Fi, Matter/Thread and Bluetooth links drawn on your plan and coloured by signal quality, so weak spots are visible where they physically are.
• A whole-property view. Place each building on a site photo or a live street or aerial map, along with devices that live outdoors.
• Works on a phone, and in English and German, following your Home Assistant profile.

The full guide is at https://greminn.github.io/ha-spatial-context/:

• What is Spatial Context? and your first floor plan
• Using the panel, placing devices and wall materials
• Connectivity Map (what each layer needs), the Property tab and Settings
• Using the map with AI, the map data and automations and actions
• Reporting a problem

Needs Home Assistant 2024.10 or newer, with your floors set up in Settings → Areas → Floors. Spatial Context isn't in the HACS default repository yet, so it's added as a custom repository. A submission to HACS is planned.

1. Click the button above, or in HACS choose ⋮ → Custom repositories, paste https://github.com/Greminn/ha-spatial-context and set Type to Integration.
2. Install Spatial Context.
3. Restart Home Assistant, then Settings → Devices & Services → Add Integration → Spatial Context.

Prefer to copy files by hand? Put custom_components/spatial_context/ into your /config/custom_components/. The install guide has the details.

1. Open Spatial Context from the sidebar and pick a floor tab.
2. Add a background image, then Set Scale by clicking two points a known distance apart.
3. Trace Room and Trace Wall, then Place Device to drop your devices on the plan.
4. Repeat for each floor, use Align Floors for floors that stack, and place buildings on the Property tab.

Changes save automatically. The first floor plan walkthrough covers each step.

spatial_context.get_map returns the whole layout (floors, rooms, walls with material and signal loss, doors, windows and every placed device in real units) as the action's response. It's the same data as ⋮ → Export JSON.

actions:
  - action: spatial_context.get_map
    response_variable: home_map

An assistant can work out which room a device is in, how far apart two devices are, and which walls sit between a Zigbee router and a flaky sensor, without knowing anything about the editor. See the map data for the full shape.

Spatial Context is a personal project, free and shared as is. If it's useful to you and you'd like to say thanks, you can buy me an espresso. It's never expected, and bug reports and ideas are just as welcome.

Found a bug, or have an idea? Please open an issue. Problems and feature ideas are equally welcome, not just polished bug reports.

Home Desk: a place for everything that needs your attention in your smart home. Coming soon.

Building, testing and deploying are covered in docs/development.md. The panel is built from frontend/ (Lit and TypeScript) and the output is committed, so HACS and a manual copy need no build step.

MIT