Home Assistant Integration

Zircon3D integrates with Home Assistant through a lightweight service called Zircon3D HA Proxy
(Home Assistant add-on or Docker container).

This integration allows Zircon3D to:

• Read devices and entities from Home Assistant
• Receive real-time updates for sensors and devices
• Store short-term history for dashboards and heatmap replay
• Send basic control commands (e.g., switches, lights) back through Home Assistant

All monitoring data stays local on your Home Assistant machine. Zircon3D Cloud is only used for account & license management.

Installation & Activation

The installation steps are covered in the Getting Started section:

• 2. Install Zircon HA Proxy
• 3. Activate Your Add-on

Please follow those pages to:

1. Install the Zircon3D HA Proxy add-on (or Docker container)
2. Generate an Access Token from your zircon3d.com account
3. Paste the token into the add-on / Zircon3D Settings → Access Token

Once these steps are complete, the integration is active and this page becomes your reference for how it works.

How the Integration Works

After activation, the Zircon3D HA Proxy:

• Connects to Home Assistant’s HTTP API and WebSocket API
• Periodically synchronizes the device & entity list
• Subscribes to state changes for your entities
• Stores a local history used by Zircon3D for heatmaps and dashboards

Zircon3D (the UI) talks only to the proxy service.
The proxy is the only component that communicates with Home Assistant.

What Zircon3D Imports from Home Assistant

Devices

Devices are logical groupings of entities (for example, a multi-sensor device).

Zircon3D uses devices to:

• Organize items in the Monitored → Devices list
• Mount sensors as “monitored devices” in the 3D scene

Entities

Zircon3D imports all entities that Home Assistant exposes, including:

• Standard sensors, lights, switches
• Template sensors (with unique_id)
• Orphan / standalone sensors
• Entities from third-party integrations

These appear under Monitored → Properties and can be:

• Mounted directly into the floorplan
• Mapped into Heatmap Layers
• Used as data sources for Dashboards and View Profiles

Real-Time Updates

Through the HA WebSocket, Zircon3D receives:

• New sensor readings
• On/off state changes
• Changes to attributes (e.g., brightness, battery level)
• Entity additions/removals

The 3D view, dashboards, and heatmaps update automatically as values change.

History Data

The proxy stores short-term history locally to support:

• Heatmap Replay over a selected time range
• Historical charts in Dashboards
• Time-based analysis in future features

History is stored on the same machine where the proxy / add-on runs.

Device Control from Zircon3D

Some entities can be controlled directly from Zircon3D:

• Switches — toggle on/off
• Lights — toggle and adjust brightness (where supported)

All commands are sent through Home Assistant, not directly to devices.
If Home Assistant can control it, Zircon3D can safely control it through the proxy.

Security & Privacy

Zircon3D is designed so that your Home Assistant data stays under your control:

• The HA Proxy runs inside your Home Assistant environment
• Sensor data, device states, and history are stored locally, not in Zircon3D Cloud
• Zircon3D Cloud only handles:
  • User account
  • Subscription / license validation
• The Access Token used by the proxy is stored inside the add-on / container
• Embedded views in Home Assistant dashboards still load data from your local proxy, not from the internet

If you disable or uninstall the add-on / container, all communication between Zircon3D and Home Assistant stops immediately.

Troubleshooting

Entities not showing in Zircon3D

Check:

• The proxy / add-on is running
• Refresh the Zircon3D UI
• Entity has a unique_id (especially template sensors)
• For new entities, give Home Assistant a moment and then click Reload in Zircon3D (if available)

Heatmap does not update

Verify:

• The sensor is mounted into the floorplan
• It is linked to the correct Heatmap Layer (Data Layer Mapping)
• The heatmap layer is enabled in Display Settings
• The sensor is actually changing value in Home Assistant

Access Token or authorization errors

Try:

1. Generate a new Access Token from your zircon3d.com profile
2. Update it in Zircon3D → Settings → Access Token
3. Confirm your Home Assistant system time is correct (large clock drift can cause auth issues)

For installation details, screenshots, and first-time setup walkthrough,
see the Getting Started pages:

• 2. Install Zircon HA Proxy
• 3. Activate Your Add-on