Misc tricks

YAML

I wrote a short description of how YAML works aimed at people who normally don't program. Some texts here will repeat some of the things in that description.

Node anchors

YAML node anchors is a simple way to reuse code in Home Assistant configuration files. Basically, you store the value of a key in an anchor while defining it:

# When you write:
key: &anchor value

# It will be interpreted as:
key: value

And then you can reuse it as many times as you want:

# When you write:
another_key: *anchor
yet_another_key: *anchor

# It will be interpreted as:
another_key: value
yet_another_key: value

anchor should be a single word, but may contain underscores.

value can be any valid YAML structure, strings, numbers, sequences or mappings.

Merge key <<:

The merge key can be used in yaml to merge a mapping into another:

# When you write:
key1: value1
key2: value2
<<:
  key3: value3
  key4: value4

# It will be interpreted as:
key1: value1
key2: value2
key3: value3
key4: value4

This is very useful in combination with node anchors:

# When you write:
thing_a:
  key1: value1
  <<: &common_things
    key2: value2
    key3: value3

thing_b:
  key1: valueA
  <<: *common_things


# It will be interpreted as:
thing_a:
  key1: value1
  key2: value2
  key3: value3
thing_b:
  key1: valueA
  key2: value2
  key3: value3

Node anchors in Home Assistant

Package attribute

Probably the most common usage of node anchors in Home Assistant is in packages. People like to add a configuration section to their packages which contain something like:

homeassistant:
  customize:
    package.node_anchors:
      common: &common
        package: "my package"

    sensor.my_sensor:
      <<: *common

This will add the attribute package with the value "my package" to every entity where it's been specified. The point of this is that if you open up the more-info dialog of the entity, or find it in the dev-states list, you can easily see where it's definition can be found.

Note that the package.node_anchors "entity" is just a dummy to have somewhere to define the node anchor. It could just as well be defined in the first real entity.

Value reuse

Another good use for node anchors is as a variable for any repeated value. In my coffee maker control package, I define a node anchor &cfe_switch which contains the entity id of the coffee maker outlet switch. I then use *cfe_switch in several automations to minimize the risk of me mistyping the entity.

Translations / user customization

If you design a very good package, you may want to distribute it to other users. It might then be a good idea to put a number of definitions near the top of the code, in a customize: section, for example, with values the user may want to customize. This might be things like output messages, time offsets, entity ids etc.

Lovelace

Card/Element/Entity row triality

IMPORTANT

Since Home Assistant 0.107 this trick is not guaranteed to work. This comes down to optimization which decreases the Lovelace interface load times at the cost of having to load a few cards, rows and entities later.

However, with one(sic!) more line of configuration, hui-element can be used instead.

---

In Lovelace, there are three things that can be replaced with custom elements. Those are cards, picture-elements elements and entities rows (I'll just call them "things").

To replace either of them with a custom element you set the type: attribute of the thing to custom:<tag> where <tag> is the html element name of the thing, such as card-modder, slider-entity-row or radial-menu.

Now here's the magic part. All things have the same interface, and can be used interchangeably. They are not meant to be, but it is possible. Furthermore, all built-in things have a <tag> that can be used to put them anywhere in the same way. The tag is usually on the form hui-<name>-<thing>, such as hui-glance-card or hui-state-icon-element. The best way to find the names are from the names of the source files for cards, elements and entity rows (there's also a few special rows).

Example:

- type: entities
  entities:
    - light.bed_light
    - type: custom:hui-glance-card
      entities:
        - light.bed_light
        - light.kithen_lights
    - light.kitchen_lights

- type: custom:hui-state-icon-element
  entity: light.bed_light

- type: picture-elements
  image: http://placekitten.com/g/800/600
  elements:
    - type: custom:hui-markdown-card
      style:
        # Note that left and top are required, but any style added here will be applied to the thing
        # The google search word you're looking for is "CSS"
        left: 50%
        top: 50%
        border: solid 5xp red
        # Any variable that can be used in a theme can be used as well, but preceded with two dashes and enclosed in quotes
        "--ha-card-background": rgba(0,0,128,0.5)
        "--primary-text-color": white
      content: |
        # Hello!