Site updated at 2016-04-09 06:05:38 UTC

getting-started/configuration/index.html

@@ -115,19 +115,80 @@
   <hr class="divider">
   
 
-  <p>Home Assistant will create a configuration folder when it is run for the first time. The location of the folder differs between operating systems: on OS X/Linux it’s <code>~/.homeassistant</code> and on Windows it’s <code>%APPDATA%/.homeassistant</code>. If you want to use a different folder for configuration, run <code>hass --config path/to/config</code>.</p>
+  <p>Home Assistant will create a configuration folder when it is run for the first time. The location of the folder differs between operating systems: on OS X and Linux it’s <code>~/.homeassistant</code> and on Windows it’s <code>%APPDATA%/.homeassistant</code>. If you want to use a different folder for configuration, run <code>hass --config path/to/config</code>.</p>
 
-<p>Inside your configuration folder is the file <code>configuration.yaml</code>. This is the main file that contains which components will be loaded and what their configuration is.<br />
-This file contains YAML code, which is explained briefly in <a href="/getting-started/troubleshooting-configuration/">the configuration troubleshooting page</a>. An example configuration file is located <a href="https://github.com/balloob/home-assistant/blob/master/config/configuration.yaml.example">here</a>.</p>
+<p>Inside your configuration folder is the file <code>configuration.yaml</code>. This is the main file that contains which components will be loaded and what their configuration is.  <br />
+This file contains YAML code, which is explained briefly below.  <br />
+<a href="https://github.com/balloob/home-assistant/blob/master/config/configuration.yaml.example">An example configuration file is located here</a>.</p>
 
-<p>When launched for the first time, Home Assistant will write a default configuration enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and show up in the interface.</p>
+<p>When launched for the first time, Home Assistant will write a default configuration file enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and show up in the user interface.</p>
 
 <p>If you run into trouble while configuring Home Assistant, have a look at <a href="/getting-started/troubleshooting-configuration/">the configuration troubleshooting page</a>.</p>
 
 <p class="note">
-You will have to restart Home Assistant for changes in <code>configuration.yaml</code> to take effect.
+  You will have to restart Home Assistant each time you make changes in <code>configuration.yaml</code> in order for these to take effect.
 </p>
 
+<h3><a class="title-link" name="yaml" href="#yaml"></a> YAML</h3>
+
+<p>Home Assistant uses the <a href="http://yaml.org/">YAML</a> syntax for configuration. YAML might take a while to get used to but is really powerful in allowing you to express complex configurations.</p>
+
+<p>For each component that you want to use in Home Assistant, you add code in your <code>configuraton.yaml</code> file to specify its settings.  <br />
+Example, the following code specifies that you want to use the <a href="/components/notify">notify component</a>  with the <a href="/components/notify.pushbullet">pushbullet platform</a>.</p>
+
+<div class="highlighter-coderay"><div class="CodeRay">
+  <div class="code"><pre><span class="key">notify</span>:
+  <span class="key">platform</span>: <span class="string"><span class="content">pushbullet</span></span>
+  <span class="key">api_key</span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">o.1234abcd</span><span class="delimiter">&quot;</span></span>
+  <span class="key">name</span>: <span class="string"><span class="content">pushbullet</span></span>
+</pre></div>
+</div>
+</div>
+
+<ul>
+  <li>A <strong>component</strong> provides the core logic for some functionality (like <code>notify</code> provides sending notifications).</li>
+  <li>A <strong>platform</strong> makes the connection to a specific software or hardware platform (like <code>pushbullet</code> works with the service from pushbullet.com).</li>
+</ul>
+
+<p>The basics of YAML syntax are block collections and mappings containing key-value pairs.  <br />
+Each item in a collection starts with a <code>-</code> while mappings have the format <code>key: value</code>. If you specify duplicate keys, the last value for a key is used.</p>
+
+<p>Note that indentation is an important part of specifying relationships using YAML. Things that are indented are nested “inside” things that are one level higher. So in the above example, <code>platform: pushbullet</code> is a property of (nested inside) the <code>notify</code> component.  <br />
+Getting the right indentation can be tricky if you’re not using an editor with a fixed width font. Tabs are not allowed to be used for indentation. Convention is to use 2 spaces for each level of indentation.</p>
+
+<p>Lines that start with <strong>#</strong> are comments and are ignored by the system.</p>
+
+<p>The next example shows an <a href="/components/input_select">input_select</a> component that uses a block collection for the options values.  <br />
+The other properties (like name) are specified using mappings. Note that the second line just has <code>threat:</code> with no value on the same line. Here threat is the name of the input_select and the values for it are everything nested below it.</p>
+
+<div class="highlighter-coderay"><div class="CodeRay">
+  <div class="code"><pre><span class="key">input_select</span>:
+  <span class="key">threat</span>:
+    <span class="key">name</span>: <span class="string"><span class="content">Threat level</span></span>
+<span class="comment"># A collection is used for options</span>
+    <span class="key">options</span>:
+     - <span class="string"><span class="content">0</span></span>
+     - <span class="string"><span class="content">1</span></span>
+     - <span class="string"><span class="content">2</span></span>
+     - <span class="string"><span class="content">3</span></span>
+    <span class="key">initial</span>: <span class="string"><span class="content">0</span></span>
+</pre></div>
+</div>
+</div>
+
+<p>The following example shows nesting a collection of mappings in a mapping.  <br />
+In Home Assistant, this would create two sensors that each use the MQTT platform but have different values for their <code>state_topic</code> (one of the properties used for MQTT sensors).</p>
+
+<div class="highlighter-coderay"><div class="CodeRay">
+  <div class="code"><pre><span class="key">sensor</span>:
+  - <span class="string"><span class="content">platform: mqtt</span></span>
+    <span class="key">state_topic</span>: <span class="string"><span class="content">sensor/topic</span></span>
+  - <span class="string"><span class="content">platform: mqtt</span></span>
+    <span class="key">state_topic</span>: <span class="string"><span class="content">sensor2/topic</span></span>
+</pre></div>
+</div>
+</div>
+
 <h3><a class="title-link" name="setting-up-the-basic-info" href="#setting-up-the-basic-info"></a> Setting up the basic info</h3>
 
 <p>By default Home Assistant will try to detect your location and will automatically select a temperature unit and time zone based on your location. You can overwrite this by adding the following information to your <code>configuration.yaml</code>:</p>
@@ -155,7 +216,7 @@ You will have to restart Home Assistant for changes in <code>configuration.yaml<
 
 <h3><a class="title-link" name="password-protecting-the-web-interface" href="#password-protecting-the-web-interface"></a> Password protecting the web interface</h3>
 
-<p>The first thing you want to add is a password for the web interface. Use your favourite text editor to open the file <code>configuration.yaml</code> and add the following to the <code>http</code> section:</p>
+<p>The first thing you will want to add is a password for the web interface. Use your favourite text editor to open <code>configuration.yaml</code> and edit the <code>http</code> section:</p>
 
 <div class="highlighter-coderay"><div class="CodeRay">
   <div class="code"><pre><span class="key">http</span>: