jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

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

Browse source
This commit is contained in:
Travis CI 2016-04-09 06:05:38 +00:00
parent c7eefae4a6
commit 6308b09c5f
18 changed files with 282 additions and 243 deletions
Download patch file Download diff file Expand all files Collapse all files

73
getting-started/configuration/index.html
View file

@ -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>:

8
getting-started/index.html
View file

@ -440,17 +440,17 @@ That’s it… you’re all set to go</p>
<p>If you run into any issues, please see <a href="/getting-started/troubleshooting/">the troubleshooting page</a>. It contains solutions to many of the more commonly encountered issues.</p>
<p>For additional help, in addition to this site, there are four sources:</p>
<p>In addition to this site, check out these sources for additional help:</p>
<ul>
<li><a href="https://community.home-assistant.io/">Forum</a></li>
<li><a href="https://gitter.im/balloob/home-assistant">Gitter Chatroom</a> for general Home Assistant discussions and questions.</li>
<li><a href="https://community.home-assistant.io">Forum</a> for Home Assistant discussions and questions.</li>
<li><a href="https://gitter.im/balloob/home-assistant">Gitter Chat Room</a> for real-time chat about Home Assistant.</li>
<li><a href="https://github.com/balloob/home-assistant/issues">GitHub Page</a> for issue reporting.</li>
</ul>
<h3><a class="title-link" name="whats-next" href="#whats-next"></a> What’s next</h3>
<p>If you want to have Home Assistant start on boot, autostart instructions can be found <a href="/getting-started/autostart/">here</a>.</p>
<p>If you want to have Home Assistant start on boot, <a href="/getting-started/autostart/">autostart instructions can be found here</a>.</p>
<p>To see what Home Assistant can do, launch demo mode: <code>hass --demo-mode</code> or visit the <a href="/demo">demo page</a>.</p>

50
getting-started/troubleshooting-configuration/index.html
View file

@ -121,53 +121,19 @@
<p>Whenever a component or configuration option results in a warning, it will be stored in <code>home-assistant.log</code> in the configuration directory. This file is reset on start of Home Assistant.</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 can be confusing to start with but is really powerful in allowing you to express complex configurations.</p>
<p>The basics of YAML are block collections and mappings containing key-value pairs. Collections will have each item start with a <code>-</code> while mappings will have the format <code>key: value</code>. The last value for a key is used in case you specify a duplicate key. <br />
Note that the indentation is an important part of specifying relationships using YAML.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="comment"># A collection</span>
- <span class="string"><span class="content">hello</span></span>
- <span class="string"><span class="content">how</span></span>
- <span class="string"><span class="content">are</span></span>
- <span class="string"><span class="content">you</span></span>
<span class="comment"># Lookup mapping</span>
<span class="key">beer</span>: <span class="string"><span class="content">ice cold</span></span> <span class="comment"># &lt;-- will be ignored because key specified twice</span>
<span class="key">beer</span>: <span class="string"><span class="content">warm</span></span>
<span class="key">wine</span>: <span class="string"><span class="content">room temperature</span></span>
<span class="key">water</span>: <span class="string"><span class="content">cold</span></span>
<span class="comment"># Nesting mappings (note the indentation)</span>
<span class="key">device_tracker</span>:
<span class="key">platform</span>: <span class="string"><span class="content">mqtt</span></span>
<span class="comment"># Nesting a collection of mappings in a mapping</span>
<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>
<p>Indentation is used to specify which objects are nested under one another. 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.</p>
<ul>
<li>To learn more about the quirks of YAML, read <a href="https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html">YAML IDIOSYNCRASIES</a> by SaltStack.</li>
<li>You can test your configuration using <a href="http://yaml-online-parser.appspot.com/">this online YAML parser</a> or <a href="http://www.yamllint.com/">YAML Lint</a>.</li>
</ul>
<h3><a class="title-link" name="my-component-does-not-show-up" href="#my-component-does-not-show-up"></a> My component does not show up</h3>
<p>When a component does not show up, many different things can be the case. Before you try any of these steps, make sure to look at the <code>home-assistant.log</code> file and see if there are any errors related to your component you are trying to set up.</p>
<h4><a class="title-link" name="problems-with-the-configuration" href="#problems-with-the-configuration"></a> Problems with the configuration</h4>
<p>One of the most common problems with Home Assistant is an invalid <code>configuration.yaml</code> file.</p>
<ul>
<li>You can test your configuration using <a href="http://yaml-online-parser.appspot.com/">this online YAML parser</a> or <a href="http://www.yamllint.com/">YAML Lint</a>.</li>
<li>To learn more about the quirks of YAML, read <a href="https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html">YAML IDIOSYNCRASIES</a> by SaltStack (the examples there are specific to SaltStack, but do explain YAML issues well).</li>
</ul>
<p><code>configuration.yaml</code> does not allow multiple sections to have the same name. If you want a specific platform to be loaded twice, append a <a href="/getting-started/devices/#style-2">number or string</a> to the name or nest them using <a href="/getting-started/devices/#style-1">this style</a>.</p>
<div class="highlighter-coderay"><div class="CodeRay">
@ -206,7 +172,7 @@ Note that the indentation is an important part of specifying relationships using
</pre></div>
</div>
</div>
<p>Contents of <code>lights.yaml</code>:</p>
<p>Contents of <code>lights.yaml</code> (notice it does not contain <code>light: </code>):</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>- <span class="string"><span class="content">platform: hyperion</span></span>