Templating in Home Assistant

Overview

YAML is (mostly1) great for configuration that is easily parsed by both computers and people, and Jinja is a decent templating language. But using Jinja inside of YAML is kind of a terrible way to program. It's a half solution, that combines the worst of both and not a whole lot of the good parts.

Selecting entities

We have a good naming standard, and its more useful if we use it. Unfortuantely, Jinja is a bit limited at working with iterators as it lacks list comprehensions like standard Python has.

Selecting based on entity_id

Jinja provides a useful collection of filters2, and we can match entity_id using filters and regular expressions. This selects all media_player.sonos_ entities:

{{
  states.media_player
    | selectattr("entity_id", "match", "^media_player\.sonos_")
}}

And this selects all light.bedroom_ entities:

{{
  states.light
    | selectattr("entity_id", "match", "^light\.bedroom_")
}}

The selectattr filter3 (and its inverse rejectattr) accepts an iterator and a test (argument passed as a string, here "match") to each item, filtering the list.

The regex tests used in the filter are direct mappings to the the Python Standard Library module re4, "match" is equivalent to re.match.

Likewise, you can also use "search":

{{
  states.light
    | selectattr("entity_id", "search", "light\.bedroom_")
}}

This is equivalent to using re.search.

Note that match requires you to match the string from the start so this won't match anything:

selectattr("entity_id", "match", "\.bedroom_")

Instead you need to do:

selectattr("entity_id", "match", "^.*\.bedroom_")

# you can drop the ^ token, this will also match
selectattr("entity_id", "match", ".*\.bedroom_")

Using search, the regex doesn't need to match from the start of the string, and you can use:

selectattr("entity_id", "search", "\.bedroom_")

Using search, you don't need to match the literal . after the domain, since for example "bedroom_" is a valid regex. However that could match other entities that don't start with "bedroom_", something like sensor.foo_bedroom_bar or sensor.notbedroom_foo will also match.

Technically we don't need to iterate over states.light since the regex is already matching the light domain -- we can also iterate over states directly:

{{
  states
    | selectattr("entity_id", "match", "^light\.bedroom_")
}}

# less iterating, more regex
{{
  states.light
    | selectattr("entity_id", "match", "^.*\.bedroom_[a-z_]+$")
}}

Optionally we can use the expand function

# using re.match
{{
  states
    | selectattr("entity_id", "match", "^light\.bedroom_")
}}
{{
  expand(states)
    | selectattr("entity_id", "match", "^light\.bedroom_")
}}
{{
  expand(states.light)
    | selectattr("entity_id", "match", "^.*\.bedroom_")
}}

# using re.search
{{
  states.light
    | selectattr("entity_id", "search", "\.bedroom_")
}}
{{
  expand(states.light)
    | selectattr("entity_id", "search", "\.bedroom_")
}}

All of these return the same entities. Using expand() will expand a group of entities before other filters are evaluated, so depending on how you construct the expression this can cause Jinja to listen to a higher number of state events.

The Home Assistant documentation on templating5 uses expand in most examples.

Selecting based on domain

It's also possible to filter based on the domain attribute, if you are tolerant to passing operators as strings/data:

{{
  states
   | selectattr("domain", "==", "light")
   | selectattr("entity_id", "match", "^.*\.bedroom_")
}}

If you are fine with using string-aliases for operators, you can also write this as selectattr("domain", "eq", "light"). This is arguably even worse, but you'll inevitably find a whole bunch of examples on the Home Assistant forums using notation like this.

Selecting based on area

You can also select based on areas, and this actually feels more natural in the Home Asssitant templating. But assigning devices or entities to areas can only be done in the UI and cannot be managed in code, which kind of negates that.

The first building blocks to using this are area_entitites and area_devices. This will return lists with the state of all entities for an area, and all the states of all devices for an area respectively:

{{ expand(area_entities("bedroom")) }}
{{ expand(device_entities("bedroom")) }}

If you want to get all light entity states in an area:

{{
  expand(area_entities("bedroom")
    | selectattr("domain", "==", "light")
}}

Which doesnt rely on the entity_id following a naming standard, but does rely on it having been assigned to the correct area in the UI.

Selecting based on label

The new labels in Home Assistant are a pleasantly powerful tool to organize entities and devices. While they can only be assigned to entities using the UI, it’s possible to read them in templates:

{{
  label_entities(label)
    | select("match", "^sensor.")
    | select("is_state", state)
    | list
    | count
    | round(0)
}}

Returns the number of sensor entities labeled with label that have a given state.

References