How pkozul/ha-floorplan works
Project Type and Purpose
• This is a Home Assistant UI extension plugin that embeds a custom SVG‐based floorplan into the Home Assistant frontend, exposing Home Assistant entities (binary sensors, lights, cameras, etc.) in a visual layout.
• It hooks into Home Assistant either as a custom state card or a custom panel, using a combination of JavaScript, SVG, CSS, and YAML configuration.
File Structure
• Top‐level YAMLs (configuration.yaml, binary_sensors.yaml, customize.yaml, floorplan.yaml, panel_custom.yaml) define Home Assistant’s core configuration, virtual sensors, custom panel/state‐card registration, and Floorplan‐specific settings.
• www/custom_ui/floorplan holds static frontend assets:
• ha-floorplan.html – main floorplan widget
• floorplan.css – styling for SVG and entity states
• floorplan.svg – the user’s custom vector floorplan
• lib/ – JavaScript dependencies (jquery, moment, svg-pan-zoom)
• www/custom_ui/state-card-floorplan.html registers the floorplan as a custom state card.
• panels/floorplan.html registers the floorplan as a panel_custom when you want a full‐window view.
README Insights
• Shows two integration modes (state‐card vs. panel_custom).
• Describes loading order, YAML includes, available configuration options (pan/zoom, hide toolbar, last‐motion tracking, CSS‐based styling, actions on click).
• Explains the plugin’s runtime behavior: loading the SVG, mapping SVG element IDs to entity IDs, listening to real‐time state changes over Home Assistant’s WebSocket API, and dispatching service calls for clicks.
Main Components and Their Interactions
a. Home Assistant Backend
• Loads configuration.yaml, includes virtual binary_sensor (for state‐card), panel_custom entries, and the floorplan.yaml config.
• Exposes a WebSocket/REST API for state changes and service calls.
b. Static Asset Server
• Serves ha-floorplan.html, state-card-floorplan.html, floorplan.css, floorplan.svg, and JS libraries from /local/custom_ui/....
c. Browser Frontend
• Fetches the appropriate HTML (panel or state‐card), CSS, JS, and SVG.
• Initializes the Floorplan JS widget, connects to the Home Assistant WebSocket, queries initial entity states.
d. SVG Floorplan
• Defines <path>, <rect>, <text>, etc., each with id="entity_id" linking to Home Assistant entity states.
• Acts as the view layer that gets updated dynamically.
e. JavaScript Libraries & Floorplan Code
• jquery/moment/svg-pan-zoom handle DOM manipulation, timestamps, and interactive pan/zoom.
• The plugin’s main script reads floorplan.yaml (via config: include), applies CSS classes based on entity states, handles click events, and issues service calls back to the backend.
f. Home Assistant State Machine & Integrations
• Underlying integrations (e.g., MQTT, template sensors) supply entity states that feed the floorplan.
Architectural Patterns & Design Principles
• Plugin Architecture: The project is a drop‐in extension that follows Home Assistant’s custom_ui and panel_custom interfaces.
• Model–View Binding: Entities (model) drive SVG element classes/attributes (view) via real‐time WebSocket updates.
• Configuration‐Driven Behavior: All runtime behavior (styles, actions, panning) is driven by floorplan.yaml.
• Separation of Concerns:
• Backend persists states & runs integrations
• Frontend only renders and dispatches service calls
• SVG/CSS handle visuals
• YAML handles configuration
Detail to Capture
• YAML config inclusion (!include floorplan.yaml) and registration entries in configuration.yaml and panel_custom.yaml.
• How SVG element IDs map 1:1 to Home Assistant entity IDs.
• JS library responsibilities.
• Real‐time update cycle: Backend → WebSocket → JS → SVG/CSS.
• Click action cycle: SVG → JS → WebSocket → Backend service call → Entity state change.