Home Assistant For Beginners Part One: Configuration.yaml

Note: To connect to Home Assistant and edit configuration files I am using Notepad++.  There is a blog post outlining the setup of Notepad++ here.

98% of Home Assistant configuration is done within configuration.yaml* (a .yaml file is a file formatted in a way that information is represented both hierarchically and in a human readable state.  The hierarchical nature allows us to “tell” Home Assistant what we want from it).

Below is a copy of the default configuration.yaml (found on your system at /home/haadmin/.homeassistant/configuration.yaml).  I have added some comments that are not part of the default file.  You can identify these comments by the fact that they start with 4 comment hashes “####”

The structure of a .yaml document in Home Assistant is fairly straight forward, however yaml is white space specific.  Tabs are not used, indents are done with double spaces.

The main building blocks of configuration.yaml are components. You can think about a component as a topic, each topic keeps information about a specific configuration item.  The amount of information in, and structure of a component is dictated by the component itself.  some components (like discovery) have no information in them at all. Other components (like group) could have 100’s of lines of information.

Data is represented in three main ways in configuration.yaml

Component (or component section):  Single word followed by a colon.

component:

Key-Pair, or dictionary:  A key and value separated by a colon (and a single space).

Key: value

List: A list of items denoted by “- ” in front of each item in the list.

List:
– item one
– item two
– item three

A sample component might look like this:

media_player:
  - platform: sonos
    hosts:
      - 192.167.0.11
      - 192.167.0.12
      - 192.167.0.13
      - 192.167.0.14
      - 192.167.0.15
      - 192.167.0.16

@ There can be more than one type of media_player platform (sonos and itunes for example).  when more than one type is represented each type is a list item.

homeassistant:
  # Name of the location where Home Assistant is running
  name: Home
  # Location required to calculate the time the sun rises and sets
  #### Initial location values for latitude, logitude, elevation, usint_system, and time_zone are calculated from the IP address used when installation occured.  
  #### Easiest place to get precice info is - http://www.gps-coordinates.net/
  latitude: 39.9872
  longitude: -75.2471
  # Impacts weather/sunrise data (altitude above sea level in meters)
  elevation: 65
  # metric for Metric, imperial for Imperial
  unit_system: imperial
  # Pick yours from here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
  time_zone: America/New_York

# Show links to resources in log and frontend
#### This will be removed once you are comfortable with the front end.  It includes links back to home-assistant.io for help topics.
introduction:

# Enables the frontend
#### 99% chance you will never need to disable this.
#### There are no configuration values within the frontend: component 
frontend:

http:
  # Uncomment this to add a password (recommended!)
  #### This component controls which port Home Assistant run on, SSL configuration, and other tpc/ip and web server configurations.  We will walk through this in future videos.
  #### Component definition https://home-assistant.io/components/http/
  # api_password: PASSWORD

# Checks for available updates
updater:

# Discover some devices automatically
#### This component will try to automatically add 11 different uPnP devices.  This includes Chromecast, Wemo Switches, Hue Lights, Netgear routers, Plex, Viera, Roku, Sonos, Yamaha media player, Squeezebox, DirectTV
#### I have found this to work about 75% of the time, also this can be slow.  I recommend adding the components manually (We will add Sonos, Philips Hue in the next walk-through)
discovery:

# Allows you to issue voice commands from the frontend in enabled browsers
conversation:

# Enables support for tracking state changes over time.
#### this is great for seeing usage overtime, and understanding when things might not be working exactly the way you want them to
##   If you are having resource issues and do not use this function, it is safe to disable.
history:

# View all events in a logbook
#### this is great for seeing usage overtime, and understanding when things might not be working exactly the way you want them to.  Similar in a way to history
logbook:

# Track the sun
sun:

# Weather Prediction
####  This is the default weather sensor.  It gets it's data from the Norwegian Meteorological Institute.  It is a good demo, but we will change to Weather Underground in the next walk-through
####  The sensor component can show more than weather, it shows state information (such as temprature) from other entities.  We will walk through entities in the next walk-throughs
sensor:
  platform: yr

*There are techniques to break configuration.yaml into multiple files, we will use these techniques heavily, in the end Home Assistant combines these files into one large configuation.yaml file.

Resources:

Full discussion regarding .yaml
https://en.wikipedia.org/wiki/YAML#Basic_components

Configuration.yaml discussion from the Home Assistant website:
https://home-assistant.io/getting-started/yaml/