DOCSEARCHbyAlgolia
Submit Docs

ha-floorplan

repository·master·Indexed 23 days ago

https://github.com/experiencelovelace/ha-floorplan

A Home Assistant integration for creating interactive, SVG-based floorplans and custom dashboards. It allows users to visualize entity states and trigger services through customizable visual elements. Key features include SVG-based floorplans, state visualization, and flexible deployment as a Lovelace card or full-page panel. Version 1.2.0.

Tokens
14.4K
Snippets
35
Records
86
Agent score
81%

What's inside ha-floorplan

  1. Overview of ha-floorplan features

    master

    ha-floorplan is a tool for Home Assistant that allows you to turn SVG files into interactive floorplans or custom interfaces. Key capabilities include:

    • SVG-based Floorplans: Create visual representations of your home using SVG files.
    • State Visualization: Trigger and visualize entity states (e.g., changing colors based on light status).
    • Service Calls: Trigger Home Assistant services directly from the floorplan elements.
    • Flexible Deployment: Use the floorplan as a standard Lovelace card or as a full-page panel.

  2. Overview of ha-floorplan

    master

    ha-floorplan is a tool for Home Assistant that allows you to bring your dashboard to life by mapping Home Assistant entities to SVG images. This enables you to visualize states, control devices, and call services through an interactive floorplan or custom interface.

    While typically used for home floorplans, it can be used for any interactive visualization, such as music boxes, doorbell interfaces, or remote controls. The power of the tool comes from combining YAML configuration, CSS for styling, and JavaScript for advanced logic.

  3. What is ha-floorplan?

    master
    ha-floorplan is a Lovelace card for Home Assistant that allows you to create interactive visual interfaces. The primary use case is creating floorplans by mapping Home Assistant entities to elements within an SVG file. Because you can import normal images into SVG files, the module is versatile enough to create various types of visual dashboards beyond just floorplans.

  4. Prepare SVG elements for Home Assistant interaction

    master

    To make your floorplan interactive, you must use a vector graphics tool like Inkscape.

    Key Requirement: You must add unique IDs to all SVG elements in Inkscape that you plan to interact with (e.g., to bind them to Home Assistant entities via YAML).

    Workflow Tip: If you use a tool like Floorplanner to generate a background image, export that image and then use Inkscape to draw your interactive SVG elements on top of it.

  5. Understand Floorplan Rules

    master

    Rules are the core mechanism in Floorplan used to describe how entities are displayed and how user interactions are handled. A rule consists of:

    1. Subjects: The entities or SVG elements being observed (for state changes or user interaction).
    2. Action Triggers: Events that trigger an action (e.g., a state change or a user tap).
    3. Actions: The resulting operation (e.g., calling a Home Assistant service).

    Rule Simplification

    Floorplan allows for concise rule definitions:

    • call-service is the default action.
    • If a service is called on an entity, Floorplan automatically includes that entity in the service_data.
    # Full version
- element: button.power
  entity: media_player.tv
  tap_action:
    action: call-service
    service: homeassistant.toggle
    service_data:
      entity_id: media_player.tv

# Simplified version
- element: button.power
  entity: media_player.tv
  tap_action:
    homeassistant.toggle

  6. Perform Actions and Services

    master

    When a trigger occurs, Floorplan can execute various actions:

    • call-service: Calls a Home Assistant service. Can be simplified by omitting action: call-service and providing the service name directly.
    • more-info: Opens the Home Assistant more-info dialog. By default, it opens for the rule's entity, but you can override this with entity_id in the action config.
    • toggle: A shorthand for toggling an entity.
    • navigate: Navigates to a specific Lovelace path.

    Haptic Feedback

    Any action can include a haptic field to trigger vibration on supported devices (Android/iOS).

    TypeDescription
    lightShort, subtle vibration (default for true)
    mediumMedium vibration
    heavyStrong vibration
    successSingle short pulse
    warningDouble pulse
    failureTriple pulse pattern
    selectionVery brief tick
    - entities:
    - light.living_room
  tap_action:
    action: toggle
    haptic: light
  hold_action:
    action: more-info
    haptic: success

  7. Execute Custom JavaScript with `floorplan.execute`

    master

    The floorplan.execute service allows you to run arbitrary JavaScript code. This is useful for complex logic, interacting with 3rd-party integrations like browser_mod, or triggering multiple actions sequentially.

    When writing JavaScript inside service_data, you have access to several helper objects:

    • config: Floorplan configuration
    • entity: State object for the current HA entity
    • entities (or states): State objects for all HA entities
    • hass: The Home Assistant hass object
    • element: The current SVG element
    • elements: The current SVG elements
    • svg: The root <svg> element
    • action: A function to make action-executions to ha-floorplan
    • util: Utility library
    • functions: Your own custom functions
    hold_action:
  - service: floorplan.execute
    service_data:
      my_custom_exec_calling_browser_mod: |
        >
        try{
          // Call browser_mod service
          browser_mod.service('popup',{
            title: "My custom function",
            content: { type: "vertical-stack", cards: [] }
          })
        }catch(e){
          console.log("Error", e);
        }

  9. Configure a minimal Floorplan instance

    master

    Floorplan requires its own configuration, which can be stored in a separate file (e.g., home.yaml) or embedded directly within a Lovelace card or Home Assistant custom panel. A minimal configuration requires an image path, a stylesheet path, and a rules list.

    image: /local/floorplan/examples/home/home.svg
stylesheet: /local/floorplan/examples/home/home.css

rules:
  - element: button.power
    entity: media_player.tv
    tap_action:
      action: call-service
      service: homeassistant.toggle

  11. Workflow overview for creating a floorplan

    master

    Creating a functional ha-floorplan involves several distinct stages:

    1. Graphic Creation: Draw your floorplan in a tool like Inkscape. If using a background image from a tool like Floorplanner, draw your interactive elements on top of it. Crucial: Assign IDs to elements you want to control.
    2. Asset Integration: Add your completed SVG file and any associated CSS files to your Home Assistant instance.
    3. Configuration: Create YAML configurations to map Home Assistant entities to the specific IDs you defined in your SVG file.
    4. Styling: Use CSS to enhance the visuals and state-based styling of your floorplan elements.

  12. Embed Home Assistant Cards using `card_set`

    master

    To embed a Home Assistant card inside your SVG, you must first add a <foreignObject> tag to your SVG markup:

    <foreignObject id="CardContainer" x="700" y="600" width="400" height="200"></foreignObject>

    Then, use the floorplan.card_set service to populate it. You can specify the container_id (the ID of the foreignObject) and the config for the card.

    To remove a card, call floorplan.card_set with the container_id but without a config.

    - entity:
    - binary_sensor.garage
  state_action:
    action: call-service
    service: floorplan.card_set
    service_data:
      container_id: CardContainer
      config:
        type: map
        entities:
          - zone.home
        aspect_ratio: "2"