Usage

Configuration

Each instance of Floorplan requires its own configuration.

The configuration can be stored in a separate file (i.e. home.yaml) or it can be embedded directly within the configuration of a Lovelace card or HA custom panel.

The following example shows a minimal configuration of Floorplan.

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

The following sections describe the complete set of configuration items.

Image

Floorplan requires an SVG image, which can be configured using the image setting.

In the simplest case, image can be set to the file location of the image.

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

Alternatively, image can be set to an object that allows setting the caching option. By setting cache: true, Floorplan will use the Web browser’s cache, otherwise the image will be refetched every time the Floorplan is loaded.

image:
  location: /local/floorplan/examples/home/home.svg
  cache: true

For supporting multiple Floorplan images based on the current screen resolution, image can be set to an object that contains a list of image sizes.

In the example below, the first image will be used if the screen width is less than 1024 pixels, and the second image will be used if the screen widths is greater than that.

image:
  sizes:
    - min_width: 0
      location: /local/floorplan/examples/home/home.svg
      cache: true
    - min_width: 1024
      location: /local/floorplan/examples/home/home-wide.svg
      cache: true

Floorplan can display an alternate image for mobile devices. This can be configured using the image_mobile setting.

image_mobile: /local/floorplan/examples/home/home-mobile.svg

Just like the regular image setting, image_mobile can also be set to an object in order to configure caching, specify multiple image sizes, etc.

Stylesheet

Floorplan also requires a CSS file, which can be configured using the stylesheet setting.

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

Logging

Logging comes in handy when trying to debug any Floorplan issues. Floorplan can display its own logging panel which can be configured using the log_level setting.

log_level: info

By default, the logging panel is not displayed. Setting log_level to any of the following levels causes the logging panel to be displayed below the Floorplan image. The levels are listed in order of least to most verbose.

error
warn (or warning)
info
debug

Floorplan also allows logging to the Developer Console in the Web browser. This can be enabled using the console_log_level setting, in the same was as the reagular log_level setting.

console_log_level: info

Defaults

To avoid unnecessary repetition of actions within the configuration, Floorplan provides a defaults setting which can be used.

defaults:
  hover_action: hover-info
  hover_info_filter:
    - min_mireds
    - max_mireds
    - icon
    - order
    - color_mode
  tap_action: more-info

This is a powerful feature, as Floorplan ‘copies’ the default actions to all rules within the configuration.

To disable one of the defaults for a specific rule, the relevant action must be set to false within that rule.

- entity: switch.fan
  tap_action: false

Use hover_info_filter to filter unnecessary atrributes being displayed on hover. Note that this will impact hover-info on all entities.

More information about rules and actions can be found in the sections below.

Rules

At the heart of Floorplan is the concept of rules. Rules are used to describe how entities should be displayed on the floorplan, along with how user interactions should be handled.

Floorplan rules can be configured using the rules setting, which represents a list of rule objects.

Each rule object contains the following parts:

Subjects - entities / SVG elements to observe for changes, and to use in service calls
Action triggers (i.e. HA entity state change)
- Action (i.e. call a service)
- Service to call (i.e. toggle HA entity state)
- Service data (i.e. HA entity)

Below is an example of a simple rule.

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

The above rule can be described as follows:

Subjects:
- Observe the SVG button.power element for user interactions
- Observe the HA media_player.tv entity for state changes
Action triggers:
- When the SVG element (i.e. button.power) is tapped / clicked, call the homeassistant.toggle service for the HA media_player.tv entity

Rule Simplification

The above rule can be simplified as shown below, since Floorplan uses call-service as the default action. Also, Floorplan automatically includes the entity as part of the service data when calling the service.

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

Subjects

The following types of items can be used as subjects within a rule.

Subject	Description
`entity`	Single HA entity
`entities`	List of HA entities
`groups`	List of HA group entities
`element`	Single SVG element
`elements`	List of SVG elements

The special case entity: '*' represents all HA entities. It can be used in rules that need to run whenever the state of any HA entity changes.

Action Triggers

Floorplan supports the same action triggers used in Lovelace (tap_action, hold_action, double_tap_action). In addition to these, Floorplan adds two of its own action triggers.

Action Trigger	Triggered When
`state_action`	Home Assistant entity state is changed
`hover_action`	SVG element is hovered over

Actions

When an action trigger is executed, Floorplan can perform any of the available Lovelace actions (call-service, more-info, toggle, navigate, etc.). Floorplan expands on the call-service action, allowing it to run both Home Assistant and Floorplan services.

call-service

Example of a standard rule using call-service.

- entity: light.kitchen
  tap_action:
    action: call-service
    service: homeassistant.toggle
    service_data:
      entity_id: light.kitchen

Simplified version of the rule, where entity_id defaults to light.kitchen.

- entity: light.kitchen
  tap_action:
    action: call-service
    service: homeassistant.toggle

Even further simplified version of the rule, where action defaults to call-service.

- entity: light.kitchen
  tap_action: homeassistant.toggle

Services

Floorplan supports calling all services exposed by Home Assistant, as well services that are exposed by Flooorplan.

Below are the services that are specific to Floorplan.

Floorplan Service	Description	Service Data Properties
`floorplan.class_toggle`	Toggle a CSS class of the SVG element(s)	`class` (string)
`floorplan.class_set`	Set the CSS class of the SVG element(s)	`class` (string)
`floorplan.dataset_set`	Set a data attribute of the SVG element(s)	`key` (string) `value` (string)
`floorplan.style_set`	Set the CSS style of the of the SVG element(s)	`style` (string)
`floorplan.text_set`	Set the text of the SVG element(s)	`text` (string) `shift_y_axis: 2em`
`floorplan.image_set`	Set the image of the SVG element(s)	`image` (string) `image_refresh_interval` (number) `cache` (boolean)
`floorplan.execute`	Execute your own JS, defined in service_data	`<all>` (array)

Service data can be dynamically constructed using JavaScript code. Below is the full set of objects that are available when writing code.

Object	Description
`config`	Floorplan configuration
`util`	Utility library
`functions`	Custom functions
`entity`	State object for the HA current entity
`entities` (or `states`)	State objects for all HA entities
`hass`	Home Assistant hass object
`element`	current SVG element
`elements`	current SVG elements

Using `class_set` to define a entity-state related class

Below is an example of using JavaScript template literals to dynamically evaluate the CSS class to use.

- entities:
    - binary_sensor.kitchen
    - binary_sensor.laundry
  state_action:
    action: call-service
    service: floorplan.class_set
    service_data:
      class: '${(entity.state === "on") ? "motion-on" : "motion-off"}'

Using `text_set` to render mulitple tspans on linebreakes

If text_set spots a newline-character (\n), the text will be broken into multiple tspans. Find the related example here. By providing shift_y_axis: 2em as a key, you’ll be able to control the offset of each tspan. If a x or/an y offset are defined on the tspan, but not on the text-element, we’ll secure that the offset of the tspan, will be used on the text-element.

- entities:
    - binary_sensor.kitchen
    - binary_sensor.laundry
  state_action:
    action: call-service
    service: floorplan.text_set
    service_data:
      element: sample.multilinegroup_text
      shift_y_axis: 1.5em
      text: |
        > /* Note that this is a JavaScript block, where you normally can do cool stuff like console.log()*/
        return 'Multiline\nTSPAN-Print';

shift_y_axis: 2em

Using `hover_action` to set a class while mouse hovering a element

By moving your cursor over a element, you can also trigger over hover action. With the hover_action, it’s easy to toggle a hover class on a given elemen if needed. Here our element will get a hover-over class added, if the mouse hovers over the element related to the entity.

- entities:
    - binary_sensor.garage
  hover_action:
    - service: floorplan.class_set
      service_data: '${element.matches(":hover") ? "hover-over" : ""}'

Using `dataset_set` to add data-keys to the DOM-element

Following is an example of using dataset and JavaScript template literals to dynamically evaluate data attribute to use.

  - entities:
      - binary_sensor.kitchen
      - binary_sensor.laundry
    state_action:
      action: call-service
      service: floorplan.dataset_set
      service_data:
        key: motion
        value: ${entity.state}
      #or alternatively
      service_data: 'motion:${entity.state}'

Using `style_set` with a block of JavaScript code

The following example shows how the style is generated using a block of JavaScript code that spans multiple lines.

- entity: sensor.moisture_level
  state_action:
    action: call-service
    service: floorplan.style_set
    service_data:
      element: moisture-level-clip-path
      style: |
        >
        var height = Math.ceil(elements['sensor.moisture_level'].getBBox().height);
        return `transform: translate(0, ${height - Math.floor(entity.attributes.level / (100 / height))}px)`;

Using `execute` with browser_mod

The following example shows how to use the execute service, where we also use the 3rd-party solution called browser_mod (Can be found in HACS).

hold_action:
  - service: floorplan.execute
    service_data:
      my_custom_exec_calling_browser_mod: |
        > 
        try{
          // Remember that ha-floorplan exposes a lot of useful properties
          console.log(
            "this",this, "\nentitiy",entity, "\nelements", elements, "\nentities", entities,
            "\nconfig",config, "\nutil", util, "\nelement", element, "\nstates", states);

          // Call browser_mod service
          browser_mod.service('popup',{title: "My custom function with browser-mod call",
          content: 
            {
              // Create vertical stack card
              type: "vertical-stack",
              cards: [
                {
                  // Entities card
                  type: "entities",
                  entities: [
                    // Define each entity
                    { entity: "sensor.time", name: "Time" },
                    { entity: "sun.sun", name: "Sun" }
                  ]
                }
              ]
            }
          })
        }catch(e){
          console.log("Well.. That didn't go as planned",e);
        }

Service calls can be simplified. More information can be found in the section on rule simplification.

Advanced Topics

Custom Functions

Floorplan supports user-defined custom functions, which can be configured using the functions setting.

functions: |
  >
  return {
    someFunctionA: (entity, entities, hass) => {
      return 'foo'; 
    },

    someOtherFunctionB: (entity, entities, hass) => {
      return 'bar'; 
    },     
  };

These custom functions can be used within any of the rules within the configuration, and must be called using the functions. prefix. Below is an example of calling a custom function.

- entity: sensor.ring_salon_battery
  state_action:
    - service: floorplan.style_set
      service_data: ${functions.someFunctionA(entity)}

The Ring example shows how functions can be used.

Utility Library

Floorplan exposes a library of utility functions, which are available to JavaScript code within rules. The following functions are available. (Note: This list is expected to grow over time).

Function	Description	Parameters	Return Type
`util.color.miredToRGB`	Convert mired (light temperature) to RGB	`mired` (number)	`number[]`
`util.color.kelvinToRGB`	Convert kelvin (light temperature) to RGB	`kelvin` (number)	`number[]`
`util.date.strftime`	Format datetime (Python style) NPM package	`format` (string), `date` (Date)	`string`
`util.date.timeago`	Format datetime as ‘time ago’ (i.e. 2 hours ago) NPM package	`date` (Date)	`string`

The Light example shows how the utility library’s util.color.miredToRGB() function can be used.

Troubleshooting

If you’re running into any difficulties with Floorplan, below is a list of things you can try.

First of all, check the indentation of the floorplan config to ensure the YAML is valid.
The recommended Web browser to use is Google Chrome. Pressing F12 displays the Developer Tools. When you press F5 to reload your floorplan page, the Console pane will show any errors that may have occurred. Also check the Network tab to see if any of the files failed to load.
If you’re not seeing latest changes that you’ve made, try clearing the Web browser cache. This can also be done in the Chrome Developer Tools. Select the Network tab, right click and select Clear browser cache.
If you’re not able to access the floorplan in your Web browser at all, it could be that you’ve been locked out of Home Assistant due to too many failed login attempts. Check the file ip_bans.yaml in the root Home Assistant config directory and remove your IP address if it’s in there.
If you encounter any issues with your entities not appearing, or not correctly showing state changes, firstly make sure you enable logging in your floorplan config. It will report any SVG elements that are missing, misspelt, etc.
If you’re adding your own CSS classes for styling your entities, make sure you escape the dot character in the id, by prefixing it with a backlash:
```
#light\.hallway:hover {
}
```