Home Assistant Configuration.yaml File Basics

If you are like me and find yaml files difficult to read then this tutorial we hopefully be of use.

Before you read this I recommend you get familiar with the yaml format by reading the first part of this guide.

The first thing to understand is the data types which are

• Boolean.
• Numbers.
• Strings.
• Dates.
• Timestamp.
• Arrays.
• Maps.
• Null.

The ones that I find difficult to read are the Arrays and Maps. These correspond to Lists and dictionaries in Python.

The yaml file is effectively a python dictionary, and each integration e.g MQTT,Sensor is also a list  of dictionaries.

This can be seen when you convert the YAML file to JSON.

Data in the  yaml file is represented as key and value pair e.g.

payload_off: "OFF"

For a list /array then each element is proceeded with a dash (-)
If we look my configuration.yaml file entries.

  sensor: 
    - name: bed_temp
      unique_id: "bedroom_temp"
      unit_of_measurement: "%C"
      state_topic: "home/bedroom/temperature"
      device_class:  "temperature"
      value_template: "{{value_json.temperature | round(1)}}"
    - name: "kitchen_temp"
      unique_id: "kitchen_temp"
      device_class:  "temperature"
      unit_of_measurement: "%C"
      state_topic: "home/kitchen/temperature"
      availability:
        - topic: "home/kitchen/temperature/available"
    - name: "Livingroom temp"
      unique_id: "livingroom_temp"
      device_class:  "temperature"
      unit_of_measurement: "%C"
      state_topic: "home/livingroom/temperature"
      availability:
        - topic: "home/livingroom/temperature/available"
    - name: "outside temp"
      unique_id: "outside_temp"  
      device_class:  "temperature"
      unit_of_measurement: "%C"
      state_topic: "home/outside/temperature"
      availability:
        - topic: "home/outside/temperature/available"
      device:
        name: "outside monitor"
        identifiers: "outside_monitor-1001"
        hw_version: 1001
        suggested_area: "outside"
        manufacturer: "abc company"

notice that we have several -name entries. These are array elements.
If we convert this to JSON we get:

{
  "sensor": [
    {
      "name": "bed_temp",
      "unique_id": "bedroom_temp",
      "unit_of_measurement": "%C",
      "state_topic": "home/bedroom/temperature",
      "device_class": "temperature",
      "value_template": "{{value_json.temperature | round(1)}}"
    },
    {
      "name": "kitchen_temp",
      "unique_id": "kitchen_temp",
      "device_class": "temperature",
      "unit_of_measurement": "%C",
      "state_topic": "home/kitchen/temperature",
      "availability": [
        {
          "topic": "home/kitchen/temperature/available"
        }
      ]
    },
    {
      "name": "Livingroom temp",
      "unique_id": "livingroom_temp",
      "device_class": "temperature",
      "unit_of_measurement": "%C",
      "state_topic": "home/livingroom/temperature",
      "availability": [
        {
          "topic": "home/livingroom/temperature/available"
        }
      ]
    },
    {
      "name": "outside temp",
      "unique_id": "outside_temp",
      "device_class": "temperature",
      "unit_of_measurement": "%C",
      "state_topic": "home/outside/temperature",
      "availability": [
        {
          "topic": "home/outside/temperature/available"
        }
      ],
      "device": {
        "name": "outside monitor",
        "identifiers": "outside_monitor-1001",
        "hw_version": 1001,
        "suggested_area": "outside",
        "manufacturer": "abc company"
      }
    }
  ]
}

You can see that the sensor key is an array of objects (JavaScript) or dictionaries (Python). Notice the closing square bracket (]) near the end that closes the array.

The key sensor starts the file and is a key to an array as shown above.

"sensor": [

The first element is a dictionary (Python) or object (JavaScript)

 { "name": "bed_temp", "unique_id": "bedroom_temp", "unit_of_measurement": "%C", "state_topic": "home/bedroom/temperature", "device_class": "temperature", "value_template": "{{value_json.temperature | round(1)}}" },

and consists of key name pairs.

Also the availability entries are also arrays:

"availability": [ { "topic": "home/outside/temperature/available" } ],

At the end we have the sensor with a device entry which is a map (dictionary)

  "device": {
        "name": "outside monitor",
        "identifiers": "outside_monitor-1001",
        "hw_version": 1001,
        "suggested_area": "outside",
        "manufacturer": "abc company"
      }

If you look at the documentation for the device entry you can see it describes the data as a map.

and if you look at the documentation for the availability key you see that it is a list.

Summary

YAML files aren’t the easiest to understand especially when you don’t deal with them on a regular basis.

Personally I find it helpful to convert the file to JSON to understand it. You also need to pay attention toe the documentation and the datas types for the properties you are trying to configure.

Related Tutorials and Resources:

• Adding a MQTT Sensor To Home Assistant
• Running Home Assistant in a Docker Container
• Adding an MQTT Device to Home Assistant