Bring your plan
into Home Assistant.

01 · KEEP YOUR EDITABLE SOURCE

Export your drawing

1. Open Home studio. Draw your rooms and walls, add openings, and check each floor in Preview 3D.
2. Choose Build & install and review any validation message. You can export an unfinished draft, but the compiler needs a valid project.
3. Choose Export project.json. Move the downloaded file to a private folder you can find again.

Keep this JSON file when you build or install. It is the editable source for future geometry changes. Entity IDs can stay blank until you link devices inside Home Assistant.

02 · A COMPLETE LOCAL TOOLKIT

Download and open the toolkit

1. Open the latest stable release. Under Assets, download home-studio-VERSION.zip, where VERSION is the release number. Choose this packaged toolkit, not GitHub's Source code ZIP. Extract it and open the resulting home-studio folder.
2. Open a terminal in that folder. You should see scripts, planner, and custom_components alongside README.md.
3. Run python3 --version. If needed, install Python 3.10 or newer from python.org. The compiler and installer use the standard library; no pip install step is needed.

On Windows, your command may be py -3; use that wherever this guide says python3. Replace example paths with real paths on your computer, and put quotes around a path containing spaces. A downloaded website page by itself is not the complete toolkit.

The release includes a matching .sha256 file for checking the download. Beta and release-candidate packages are previews; the link above selects the stable release.

03 · MAKE YOUR VIEWER AND PACKAGE

Build, then take a look

From the toolkit folder, run this command with the path to your exported project:

python3 scripts/build-planner-project.py --project /path/to/project.json --output dist/my-home --ha-package

The compiler writes your viewer and floor exports to dist/my-home, including home-floorplan.tar.gz for Home Assistant. Use an empty output folder or one created by an earlier build. Keep the editable project outside that output folder.

Preview the result with a local web server:

python3 -m http.server 8099 --bind 127.0.0.1 --directory dist/my-home

Open http://127.0.0.1:8099/, choose a floor, and check its layout. Keep the terminal open while viewing; press Ctrl+C when finished. This preview does not control devices.

04 · CHOOSE YOUR FILE ACCESS

Install into the right config folder

If Python runs on a host with direct access to Home Assistant's config directory, use the local installer below. This is the directory containing configuration.yaml; for a container it is the host directory mounted as /config.

If you use Home Assistant OS and only access HA through a browser or file share, follow the Samba copy route instead. The installer expects a local filesystem path, not an HA address or token.

First, validate without changing files

python3 scripts/install-home-assistant.py dist/my-home/home-floorplan.tar.gz --config /path/to/ha/config --dry-run

Check the printed destination and site name. The config directory must already exist, and its path must not pass through a symlink. A successful dry run creates or changes no files.

Then install

python3 scripts/install-home-assistant.py dist/my-home/home-floorplan.tar.gz --config /path/to/ha/config

The installer places the complete component under custom_components/home_floorplan. It does not edit YAML, restart HA, or change saved placements. Continue to enable the panel.

Home Assistant OS: validate locally, copy over Samba

1. Build on your computer using the steps above. Create an empty folder named ha-transfer inside the toolkit folder.
2. Validate and unpack through the installer into that local folder:

   python3 scripts/install-home-assistant.py dist/my-home/home-floorplan.tar.gz --config ha-transfer --dry-run
   python3 scripts/install-home-assistant.py dist/my-home/home-floorplan.tar.gz --config ha-transfer

   This prepares files for transfer; it has not installed anything on your HA machine.

3. Use the official Samba share instructions to open HA's config share in your computer's file manager. Use your own share credentials there.
4. Before replacing an existing component, back up HA and stop Core through a console or management connection that can start it again. On the HAOS command line, use ha core stop. Keep that connection available.
5. If config/custom_components/home_floorplan exists, move that entire old folder into a dated folder under config/.home-studio-backups. Keep the backup outside custom_components.
6. Copy the complete ha-transfer/custom_components/home_floorplan folder to config/custom_components/home_floorplan on the share. Create custom_components if needed. Do not merge new files into the old component; wait for the entire copy to finish.

Leave .storage and unrelated components alone. If a copy fails, remove the incomplete new component and put the retained old folder back before starting Core. File-manager transfers do not have the local installer's automatic rollback.

05 · ONE YAML ENTRY

Enable 3D Home

Open your HA configuration.yaml. Add this entry at the top level, with no spaces before its name:

home_floorplan: {}

If home_floorplan: already exists, keep that entry and merge any changes there; do not add a second key. Check the configuration before starting or restarting Core. HAOS provides ha core check; a running HA also has a YAML configuration check in its tools. See the official configuration-check instructions.

After a successful check, start Core if you stopped it, or restart it if it is running. On the HAOS command line use ha core start or ha core restart, respectively. Other installations use their normal host or container controls.

Sign in to Home Assistant with an administrator account, refresh the browser, and open 3D Home in the sidebar. The panel uses your existing HA login.

06 · CONNECT YOUR OWN ENTITIES

Make the plan respond to your home

1. In 3D Home, choose Edit layout, then Plan & placement.
2. Select or place an item and set its Home Assistant entity_id to an actual entity from your HA installation. Use the suggested entities where available.
3. Wait for Saved in Home Assistant before leaving the panel. These saved placements belong to HA, separately from the hosted editor's browser draft.
4. Return to Home view. Check a known light or switch with an intentional click and confirm its state in HA.

Entity IDs entered in the browser editor become initial mappings; the editor itself never controls those devices. Missing or unavailable entities remain disabled. The generic panel supports its documented entity controls; placing a TV or sensor does not activate specialized TV capture, camera, or RF sensing adapters.