|
Floorplan for Home Assistant
Background
Out of the box, the Home Assistant front end provides a great way of viewing and interacting with your entities. This project builds on top of that, allowing you to extend the user interface by adding your own visuals.
With Floorplan for Home Assistant, you can:
- Integrate with Home Assistant as either a state card or a custom panel
- Display any number of entities (i.e. binary sensors, lights, cameras, etc.)
- Style each entity's states using CSS
- Gradually transition between states using color gradients
- Display the last triggered binary sensor using CSS
- Display hover-over text for each entity
- Call a service or display a popup dialog when an entity is clicked
Despite its title, Floorplan for Home Assistant can be used as a general purpose user interface for just about anything you want to present in a visual way.
The concept is quite simple. You create an SVG file and simply add shapes/images to represent your Home Assistant entities. As long as the ids match up, your SVG comes to life and displays your entities' states in real time. Your entities also become clickable, so they act as shortcuts to opening the built-in 'more info' popups that are normally displayed by Home Assistant. This means clicking on a camera icon, for example, opens the Home Assistant 'more info' popup that displays the live camera feed. Hovering over the entitiy displays a tooltip showing all the information related to the entity.
Although using it as a floorplan is the most common use case, you can go even further and create visuals of real world components. Some examples are:
- An SVG image of a remote control with each button click triggering a service in Home Assistant
- An SVG image of a Ring doorbell with the sensor and camera mapped to sensors in Home Assistant
- An SVG image of a Logitech Squeezebox media player with the screen text mapped to the state, current song, etc. in Home Assistant
Usage
To get started, copy the following files from this repo to your Home Assistant directory:
www/custom_ui/floorplan/ha-floorplan.html
www/custom_ui/floorplan/floorplan.svg
www/custom_ui/floorplan/floorplan.css
www/custom_ui/floorplan/lib/jquery-3.2.1.min.js
www/custom_ui/floorplan/lib/moment.min.js
www/custom_ui/floorplan/lib/svg-pan-zoom.min.js
Although a sample floorplan SVG file is included in this repo, you will want to create your own. See the appendix for more information.
You then have two options for how you want to the floorplan to appear in Home Assistant:
- custom state card
- custom panel
Of course, you can choose to have it displayed in both places. If you have several floorplans to display (i.e. different levels of a house), that is supported too.
Option 1: Floorplan custom state card
To display the floorplan as a custom state card, copy the following file from this repo to your Home Assistant directory:
www/custom_ui/state-card-floorplan.html
To allow the above file to be served by Home Assistant, add it to the frontend section of your Home Assistant configuration:
frontend:
extra_html_url:
- /local/custom_ui/state-card-floorplan.html
Since Home Assistant requires a single entity to be used as the target for a state card, create a virtual entity to represent the overall floorplan. You can choose any type of entity for this, such as the MQTT binary sensor. Add the following to your Home Assistant configuration:
binary_sensor:
- platform: mqtt
state_topic: dummy/floorplan/sensor
name: Floorplan
Then, add the following to get Home Assistant to display this new virtual entity using the floorplan custom state card:
homeassistant:
customize:
binary_sensor.floorplan:
custom_ui_state_card: state-card-floorplan
config: !include floorplan.yaml
To actually display the floorplan custom state card in the front end, add the virtual entity to one of your groups:
group:
zones:
name: Zones
entities:
- binary_sensor.floorplan
You can also add a 'last motion' entity to keep track of which binary sensor was triggered last. See the appendix for more information.
Option 2: Floorplan custom panel
To display the floorplan as a custom panel, copy the following file from this repo to your Home Assistant directory:
panels/floorplan.html
Then, add the following to your Home Assistant configuration:
panel_custom:
- name: floorplan
sidebar_title: Floorplan
sidebar_icon: mdi:home
url_path: floorplan
config: !include floorplan.yaml
Configure the floorplan
Whether your floorplan is being displayed as a custom state card or as a custom panel, the same configuration file floorplan.yaml is used. This is where you tell Home Assistant which entities you want to display on your floorplan.
The example floorplan.yaml included in this repo shows how to add various entities to your floorplan and style their appearance based on their states.
At the top of the file, you provide a name for the floorplan, as well as the location of the SVG and CSS files:
name: Demo Floorplan
image: /local/custom_ui/floorplan/floorplan.svg
stylesheet: /local/custom_ui/floorplan/floorplan.css
If you want the floorplan to display any warnings (i.e. SVG file does not contain required elements), add the following:
warnings:
If you want to support panning and zooming within your SVG file, add the following:
pan_zoom:
If you want to hide the main application toolbar and display the floorplan in true fullscreen mode (when used as a custom panel), add the following:
hide_app_toolbar:
To set the date format displayed in the hover-over text, add the following:
date_format: DD-MMM-YYYY
If you want to display a 'last motion' entity, you can include that in the next section of the file. You specify the name of the entity, as well as the CSS class used to style its appearance:
last_motion_entity: sensor.template_last_motion
last_motion_class: last-motion
The remainder of the file is where you add your floorplan groups. These floorplan groups are not to be confused with Home Assistant entity groups that are used to combine multiple entities into one.
groups:
You need to place each of your entities into a floorplan group, since configuration is performed at a floorplan group level. The floorplan groups can be given any name, and have no purpose other than to allow for configuration of multiple items in one place.
If you've already created some Home Assistant entity groups, you can actually include those groups in two different ways:
-
single - the group will be represented as a single entity (
group.pantry_lightsin the example below). These sorts of Home Assistant entity groups get added beneathentities:). -
exploded - the group will be exploded into separate entities (
group.living_area_lightsin the example below). These sorts of Home Assistant entity groups get added beneathgroups:).
- name: Lights
entities:
- light.kitchen
- group.pantry_lights
groups:
- group.living_area_lights
In addition to monitoring your entities in real time, you can also trigger actions when your entities are clicked. Below is an example of such an action. Whenever one of the lights in the group is clicked, an action is triggered that calls the Home Assistant 'toggle' service. See the appendix for more information.
- name: Lights
entities:
- light.kitchen
- group.pantry_lights
groups:
- group.living_area_lights
action:
service: toggle
Below are some examples of groups, showing how to configure different types of entities in the floorplan.
Sensors
Below is an example of a 'Sensors' group, showing how to add a temperature sensor (as text) to your floorplan. in the screenshot above, this can be seen as an SVG text element displaying the current temperature (i.e. '9.0°').
The sensor's state is displayed using a text_template. As you can see, it contains some embedded code that determines which actual text to display.
The sensor's CSS class is determined dynamically using a class_template. In the example below, the CSS class is determined based on the actual temperature value.
See the appendix for more information on how to use template literals in your configuration.
- name: Sensors
entities:
- sensor.melbourne_now
- group.major_city_temp_sensors
text_template: '${entity.state ? entity.state : "unknown"}'
class_template: '
var temp = parseFloat(entity.state.replace("°", ""));
if (temp < 10)
return "temp-low";
else if (temp < 30)
return "temp-medium";
else
return "temp-high";
'
Below is an example of using dynamic images which are swapped out at runtime, based on the sensor's current state. In the example below, the sensor.home_dark_sky_icon entitiy is mapped to a <rect> in the SVG file with the same id (which simply acts as a placeholder). Whenever the temperature sensor changes state, the image_template is evaluated to determine which SVG image should be emebedded within the bounds of the <rect>. Also you need to make sure that the placeholder is placed directly within the svg (e.g. not in a layer in inkscape) or else the calculated coordinates will be wrong.
groups:
- name: Dark Sky Sensors
entities:
- sensor.home_dark_sky_icon
image_template: '
var imageName = "";
switch (entity.state) {
case "clear-day":
imageName = "day";
break;
case "clear-night":
imageName = "night";
break;
case "partly-cloudy-day":
imageName = "cloudy-day-1";
break;
case "partly-cloudy-night":
imageName = "cloudy-night-1";
break;
case "cloudy":
imageName = "cloudy";
break;
case "rain":
imageName = "rainy-1";
break;
case "snow":
imageName = "snowy-1";
break;
}
return "/local/custom_ui/floorplan/images/weather/" + imageName + ".svg";
'
Switches
Below is an example of a 'Switches' group, showing how to add switches to your floorplan. The appearance of each switch is styled using the appropriate CSS class, based on its current state.
- name: Switches
entities:
- switch.doorbell
states:
- state: 'on'
class: 'doorbell-on'
- state: 'off'
class: 'doorbell-off'
action:
domain: switch
service: toggle
Lights
Below is an example of a 'Lights' group, showing how to add lights to your floorplan. The appearance of each light is styled using the appropriate CSS class, based on its current state.
- name: Lights
entities:
- light.hallway
- light.living_room
- light.patio
states:
- state: 'on'
class: 'light-on'
- state: 'off'
class: 'light-off'
Alarm Panel
Below is an example of an 'Alarm Panel' group, showing how to add an alarm panel (as text) to your floorplan. The appearance of the alarm panel is styled using the appropriate CSS class, based on its current state. In the screenshot above, this can be seen as an SVG text element displaying the current alarm status (i.e. 'disarmed').
- name: Alarm Panel
entities:
- alarm_control_panel.alarm
states:
- state: 'armed_away'
class: 'alarm-armed'
- state: 'armed_home'
class: 'alarm-armed'
- state: 'disarmed'
class: 'alarm-disarmed'
Binary Sensors
Below is an example of a 'Binary sensors' group, showing how to add binary sensors to your floorplan. The appearance of each binary sensor is styled using the appropriate CSS class, based on its current state. In the screenshot above, these can be seen as SVG paths (i.e. rooms/zones of the house).
The state_transitions section is optional, and allows your binary sensors to visually transition from one state to another, using the fill colors defined in the CSS classes associated with each state. You can specify the duration (in seconds) for the transition from one color to the other.
- name: Binary Sensors
entities:
- binary_sensor.front_hallway
- binary_sensor.kitchen
- binary_sensor.master_bedroom
- binary_sensor.theatre_room
states:
- state: 'off'
class: 'info-background'
- state: 'on'
class: 'warning-background'
state_transitions:
- name: On to off
from_state: 'on'
to_state: 'off'
duration: 10
Cameras
Below is an example of a 'Cameras' group, showing how to add cameras to your floorplan. The appearance of each camera is styled using the appropriate CSS class, based on its current state. In the screenshot above, these can be seen as camera icons, which were imported from an external SVG image.
- name: Cameras
entities:
- camera.hallway
- camera.driveway
- camera.front_door
- camera.backyard
states:
- state: 'idle'
class: 'camera-idle'
Media Players
Below is an example of a 'Media Players' group, showing how to add media players to your floorplan. The appearance of each media player is styled using the appropriate CSS class, based on its current state. In the screenshot above, these can be seen as Logitech Squeezebox icons, which were imported from an external SVG image.
- name: Media Players
entities:
- media_player.alfresco
- media_player.ensuite
- media_player.salon
states:
- state: 'off'
class: 'squeezebox-off'
- state: 'idle'
class: 'squeezebox-off'
- state: 'paused'
class: 'squeezebox-off'
- state: 'playing'
class: 'squeezebox-on'
Toggling the visibility of entities
If you'd like to control the visibility of your entities, you can create a layer in your SVG file (using the <g> element) that contains the entities you want show/hide, along with a button (using <rect>, for example) that is actually used to toggle the visiblity. Below is an example of a button media_players_button that toggles the visibility of all media players in the floorplan (i.e. those that are contained within the media_players_layer layer). The floorplan toggles between the two CSS classes whenever the button is clicked.
- name: Media Players
elements:
- media_players_button
action:
domain: class
service: toggle
data:
elements:
- media_players_layer
classes:
- layer-visible
- layer-hidden
default_class: layer-hidden
Appendix
Creating a floorplan SVG file
Inkscape is a free application that lets you create vector images. You can make your floorplan as simple or as detailed as you want. The only requirement is that you create an element (i.e. rect, path, text, etc.) for each entity ( i.e. binary sensor, switch, camera, etc.) you want to display on your floorplan. Each of these elements needs to have its id set to the corresponding entity name in Home Assistant.
For example, below is what the SVG element looks like for a Front Hallway binary sensor. The id of the shape is set to the entity name binary_sensor.front_hallway. This allows the shape to automatically get hooked up to the right entity when the floorplan is displayed.
<path id="binary_sensor.front_hallway" d="M650 396 c0 -30 4 -34 31 -40 17 -3 107 -6 200 -6 l169 0 0 40 0 40
-200 0 -200 0 0 -34z"/>If you need a good source of SVG files for icons or images, you can check out the following resources : Material Design Icons, Noun Project and Flat Icon
Adding a last motion entity to your floorplan
As an optional step, you can create a 'last motion' entity to keep track of which binary sensor was triggered last. To do so, add the following:
sensor:
- platform: template
sensors:
template_last_motion:
friendly_name: 'Last Motion'
value_template: >
{%- set sensors = [states.binary_sensor.theatre_room, states.binary_sensor.back_hallway, states.binary_sensor.front_hallway, states.binary_sensor.kitchen] %}
{% for sensor in sensors %}
{% if as_timestamp(sensor.last_changed) == as_timestamp(sensors | map(attribute='last_changed') | max) %}
{{ sensor.name }}
{% endif %}
{% endfor %}
To actually display the 'last motion' entity', add it to one of your groups:
group:
zones:
name: Zones
entities:
- sensor.template_last_motion
- binary_sensor.floorplan
Using template literals in your configuration
The settings text_template, class_template, and action_template allow you to inject your own expressions and code using JavaScript template literals. Within these template literals, you have full access to the entity's state object, which allows you to access other properties such as last_changed, attributes.friendly_name, etc. The full set of objects available to your template literals is shown below:
entity- the state object for the current entityentities- the state objects for all entitieshass- the hass objectconfig- the floorplan configuration
- name: Sensors
entities:
- sensor.melbourne_now
text_template: '${entity.state ? entity.state : "unknown"}'
class_template: '
var temp = parseFloat(entity.state.replace("°", ""));
if (temp < 10)
return "temp-low";
else if (temp < 30)
return "temp-medium";
else
return "temp-high";
'
Triggering actions
Within each group, you can define an action that triggers a call to the specified Home Assistant service when an entity is clicked. The domain is optional, and defaults to either the domain of the entity being clicked (for regular entities, i.e. 'light'), or to 'homeassistant' (for Home Assistant group entities).
In its simplest form, an action can be used to toggle an enity (or a group of entities, in the case of a Home assistant group).
action:
service: toggle
You can also explictly set the domain if you want to call a service from a particular domain.
action:
domain: homeassistant
service: toggle
The ability to specify a domain means you can kick off just about any service available in Home Assistant (scripts, automations, notifcations, shell commands, TTS, etc.).
action:
domain: script
service: sound_frontdoor_chime
For services that support additional data, you can include that as well. Below is an example of setting the transition and brightness when switching on a light.
action:
domain: light
service: turn_on
data:
transition: 50
brightness: 75
When an entity is clicked, it can actually trigger an action on another entity. The example below shows how clicking on a light triggers a different light to be switched on, by supplying the other's light's entity_id as part of the action.
action:
domain: light
service: turn_on
data:
entity_id: light.some_other_light
transition: 50
brightness: 75
For more flexibility, you can use the data_template to dynamically generate data required for your action. The example below shows how a JSON object is dynamically created and populated with data. Thanks to template literals, you can inject code to evaluate expressions at runtime. Just for the purposes of illustration, the example shows the use of the JavaScript Math.min() function being used in conjunction with another entity's current state.
action:
domain: light
service: turn_on
data_template: '
{
"entity_id": "light.some_other_light",
"brightness": ${Math.min(entities["zone.home"].attributes.radius, 50)}
}
'
Troubleshooting
First of all, check the indentation of the floorplan config. All the examples above show the correct level of indentantion, so make sure that's done before proceedeing further.
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 scripts failed to load. Ad-blockers have been known to prevent some scripts from loading.
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 browswer 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 that warnings: is added to 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 {
}
Resources
Check out Patrik's tutorial on how to create a custom floorplan SVG
More information
For discussions and more information, check out the thread on the Home Assistant forums.