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

Fix HTML/Markdown formatting

Browse source
This commit is contained in:
Paulus Schoutsen 2015-10-28 21:56:55 -07:00
parent 8a49892248
commit 08d65ba714
10 changed files with 303 additions and 326 deletions
Download patch file Download diff file Expand all files Collapse all files

116
source/getting-started/autostart.html
View file

@ -1,116 +0,0 @@
---
layout: page
title: "Launch Home Assistant on boot"
description: "Instructions how to setup Home Assistant to launch on boot on various platforms.."
date: 2015-9-1 22:57
sidebar: false
comments: false
sharing: true
footer: true
---
<div class='advanced-installs-container'>
<input name='advanced-installs' type='radio' id='upstart-install' checked>
<input name='advanced-installs' type='radio' id='systemd-install'>
<input name='advanced-installs' type='radio' id='osx-install'>
<label class='menu-selector upstart' for='upstart-install'>Upstart Daemon</label>
<label class='menu-selector systemd' for='systemd-install'>Systemd Daemon</label>
<label class='menu-selector osx' for='osx-install'>OS X</label>
<div class='advanced-installs upstart'>
<p>Many linux distributions use the Upstart system (or similar) for managing daemons. Typically, systems based on Debian 7 or previous use Upstart. This includes Ubuntu releases before 15.04 and all current Raspian releases. If you are unsure if your system is using Upstart, you may check with the following command:</p>
<pre class='CodeRay'>$ ps -p 1 -o comm=</pre>
<p>If the preceding command returns the string <code>init</code>, you are likely using Upstart.</p>
<p>Upstart will launch init scripts that are located in the directory <code>/etc/init.d/</code>. A sample init script for systems using Upstart is <a href="https://raw.githubusercontent.com/balloob/home-assistant/dev/script/hass-daemon">maintained by this project</a>.</p>
<p>To install this script, download it, tweak it to you liking, and install it by following the directions in the header. This script will setup Home Assistant to run when the system boots. To start/stop Home Assistant manually, issue the following commands:</p>
<pre class='CodeRay'>$ sudo service hass-daemon start
$ sudo service hass-daemon stop
</pre>
<p>When running Home Assistant with this script, the configuration directory will be located at <code>/var/opt/homeassistant</code>. This directory will contain a verbose log rather than simply an error log.</p>
<p>When running daemons, it is good practice to have the daemon run under its own user name rather than the default user's name. Instructions for setting this up are outside the scope of this document.</p>
</div> <!-- UPSTART -->
<div class='advanced-installs systemd'>
<p>Newer linux distributions are trending towards using systemd for managing daemons. Typically, systems based on Fedora or Debian 8 or later use systemd. This includes Ubuntu releases including and after 15.04, CentOS, and Red Hat. If you are unsure if your system is using systemd, you may check with the following command:</p>
<pre class='CodeRay'>$ ps -p 1 -o comm=</pre>
<p>If the preceding command returns the string <code>systemd</code>, you are likely using systemd.</p>
<p>If you want Home Assistant to be launched automatically, an extra step is needed to setup systemd. You need a service file to control Home Assistant with systemd.</p>
<pre class='CodeRay'>$ su -c 'cat &lt;&lt;EOF >> /lib/systemd/system/home-assistant.service
[Unit]
Description=Home Assistant
After=network.target
[Service]
Type=simple
ExecStart=/usr/local/bin/hass
# Next line is to run as a specific user
# for Raspberry Pi users, keep it at 'pi'
User=pi
[Install]
WantedBy=multi-user.target
EOF'
</pre>
<p>You need to reload systemd to make the daemon aware of the new configuration. Enable and launch Home Assistant after that.</p>
<pre class='CodeRay'>$ sudo systemctl --system daemon-reload
$ sudo systemctl enable home-assistant
$ sudo systemctl start home-assistant
</pre>
<p>If everything went well, <code>sudo systemctl start home-assistant</code> should give you a positive feedback.</p>
<pre class='CodeRay'>$ sudo systemctl status home-assistant -l
● home-assistant.service - Home Assistant
Loaded: loaded (/usr/lib/systemd/system/home-assistant.service; disabled; vendor preset: disabled)
Active: active (running) since Thu 2015-06-25 23:38:37 CEST; 3min 13s ago
Main PID: 8557 (python3.4)
CGroup: /system.slice/home-assistant.service
└─8557 /usr/bin/python3.4 -m homeassistant
[...]
</pre>
<p>To get Home Assistant's logging output, simple use <code>journalctl</code>.</p>
<pre class='CodeRay'>$ sudo journalctl -f -u home-assistant</pre>
</div> <!-- SYSTEMD -->
<div class='advanced-installs osx'>
<p>Setting up Home Assistant to run as a background service is simple. OS X will
start it on boot and make sure it's always running.</p>
<p>To get Home Assistant installed as a background service, run:</p>
<pre class='CodeRay'>$ hass --install-osx
Home Assistant has been installed. Open it here: http://localhost:8123
</pre>
<p>Home Assistant will log to <code>~/Library/Logs/homeassistant.log</code></p>
<p>To uninstall the service, run:</p>
<pre class='CodeRay'>$ hass --uninstall-osx
Home Assistant has been uninstalled.
</pre>
</div> <!-- OSX -->
<h3><a href='/getting-started/'>&laquo; Back to Getting Started</a></h3>

135
source/getting-started/autostart.markdown Normal file
View file

@ -0,0 +1,135 @@
---
layout: page
title: "Launch Home Assistant on boot"
description: "Instructions how to setup Home Assistant to launch on boot on various platforms.."
date: 2015-9-1 22:57
sidebar: false
comments: false
sharing: true
footer: true
---
<div class='advanced-installs-container' markdown='0'>
<input name='advanced-installs' type='radio' id='upstart-install' checked>
<input name='advanced-installs' type='radio' id='systemd-install'>
<input name='advanced-installs' type='radio' id='osx-install'>
<label class='menu-selector upstart' for='upstart-install'>Upstart Daemon</label>
<label class='menu-selector systemd' for='systemd-install'>Systemd Daemon</label>
<label class='menu-selector osx' for='osx-install'>OS X</label>
<div class='advanced-installs upstart' markdown='1'>
Many linux distributions use the Upstart system (or similar) for managing daemons. Typically, systems based on Debian 7 or previous use Upstart. This includes Ubuntu releases before 15.04 and all current Raspian releases. If you are unsure if your system is using Upstart, you may check with the following command:
```bash
$ ps -p 1 -o comm=
```
If the preceding command returns the string `init`, you are likely using Upstart.
Upstart will launch init scripts that are located in the directory `/etc/init.d/`. A sample init script for systems using Upstart is <a href="https://raw.githubusercontent.com/balloob/home-assistant/dev/script/hass-daemon">maintained by this project</a>.
To install this script, download it, tweak it to you liking, and install it by following the directions in the header. This script will setup Home Assistant to run when the system boots. To start/stop Home Assistant manually, issue the following commands:
```bash
$ sudo service hass-daemon start
$ sudo service hass-daemon stop
```
When running Home Assistant with this script, the configuration directory will be located at `/var/opt/homeassistant`. This directory will contain a verbose log rather than simply an error log.
When running daemons, it is good practice to have the daemon run under its own user name rather than the default user's name. Instructions for setting this up are outside the scope of this document.
</div> <!-- UPSTART -->
<div class='advanced-installs systemd' markdown='1'>
Newer linux distributions are trending towards using systemd for managing daemons. Typically, systems based on Fedora or Debian 8 or later use systemd. This includes Ubuntu releases including and after 15.04, CentOS, and Red Hat. If you are unsure if your system is using systemd, you may check with the following command:
```bash
$ ps -p 1 -o comm=
```
If the preceding command returns the string `systemd`, you are likely using systemd.
If you want Home Assistant to be launched automatically, an extra step is needed to setup systemd. You need a service file to control Home Assistant with systemd.
```bash
$ su -c 'cat <<EOF >> /lib/systemd/system/home-assistant.service
[Unit]
Description=Home Assistant
After=network.target
[Service]
Type=simple
ExecStart=/usr/local/bin/hass
# Next line is to run as a specific user
# for Raspberry Pi users, keep it at 'pi'
User=pi
[Install]
WantedBy=multi-user.target
EOF'
```
You need to reload systemd to make the daemon aware of the new configuration. Enable and launch Home Assistant after that.
```bash
$ sudo systemctl --system daemon-reload
$ sudo systemctl enable home-assistant
$ sudo systemctl start home-assistant
```
If everything went well, `sudo systemctl start home-assistant` should give you a positive feedback.
```bash
$ sudo systemctl status home-assistant -l
● home-assistant.service - Home Assistant
Loaded: loaded (/usr/lib/systemd/system/home-assistant.service; disabled; vendor preset: disabled)
Active: active (running) since Thu 2015-06-25 23:38:37 CEST; 3min 13s ago
Main PID: 8557 (python3.4)
CGroup: /system.slice/home-assistant.service
└─8557 /usr/bin/python3.4 -m homeassistant
[...]
```
To get Home Assistant's logging output, simple use `journalctl`.
```bash
$ sudo journalctl -f -u home-assistant
```
</div> <!-- SYSTEMD -->
<div class='advanced-installs osx' markdown='1'>
Setting up Home Assistant to run as a background service is simple. OS X will start it on boot and make sure it's always running.
To get Home Assistant installed as a background service, run:
```bash
$ hass --install-osx
Home Assistant has been installed. Open it here: http://localhost:8123
```
Home Assistant will log to `~/Library/Logs/homeassistant.log`
To uninstall the service, run:
```bash
$ hass --uninstall-osx
Home Assistant has been uninstalled.
```
</div> <!-- OSX -->
</div>
### [&laquo; Back to Getting Started](/getting-started/)

89
source/getting-started/index.html
View file

@ -1,89 +0,0 @@
---
layout: page
title: "Getting Started"
description: "Step by step guide to get started with Home Assistant."
date: 2014-12-18 22:57
sidebar: false
comments: false
sharing: true
footer: true
---
<div class='install-instructions-container'>
<input name='install-instructions' type='radio' id='normal-install' checked>
<input name='install-instructions' type='radio' id='raspberry-install'>
<input name='install-instructions' type='radio' id='docker-install'>
<label class='menu-selector normal' for='normal-install'>Install on local machine</label>
<label class='menu-selector raspberry' for='raspberry-install'>Install on a Raspberry Pi</label>
<label class='menu-selector docker' for='docker-install'>Install using Docker</label>
<div class='install-instructions normal'>
<p>Installing and running Home Assistant on your local machine is easy. Make sure you have <a href='https://www.python.org/downloads/' target="_blank">Python 3.4</a> installed and execute the following code in a console:</p>
<pre class='CodeRay'>$ pip3 install homeassistant
$ hass --open-ui
</pre>
<p>Running these commands will:</p>
<ol>
<li>Install Home Assistant</li>
<li>Launch Home Assistant and serve web interface on
<a href='http://localhost:8123' target="_blank">http://localhost:8123</a></li>
</ol>
</div> <!-- INSTALL-INSTRUCTIONS NORMAL -->
<div class='install-instructions docker'>
<p>Installation with Docker is straightforward. Adjust the following command so that <code>/path/to/your/config/</code> points at the folder where you want to store your config and run it:</p>
<pre class='CodeRay'><code>$ docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host balloob/home-assistant
</code></pre>
<p>This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.</p>
<p class='note'>
When using boot2docker on OS X you are unable to map the local time to your Docker container. Replace <code>-v /etc/localtime:/etc/localtime:ro</code> with <code>-e "TZ=America/Los_Angeles"</code> (replacing America/Los_Angeles with <a href='http://en.wikipedia.org/wiki/List_of_tz_database_time_zones' target="_blank">your timezone</a>)
</p>
</div> <!-- INSTALL-INSTRUCTIONS DOCKER -->
<div class='install-instructions raspberry'>
<p>Home Assistant requires the Raspberry Pi to run <a href='https://www.raspberrypi.org/downloads/raspbian/'>Raspbian Jessie</a>. This version has been released on September 24, 2015 and comes by default with Python 3.4 which is required for Home Assistant.</p>
<p>Execute the following code in a console:</p>
<pre class='CodeRay'><code>$ pip3 install homeassistant
$ hass --open-ui
</code></pre>
<p>Running these commands will:</p>
<ol>
<li>Install Home Assistant</li>
<li>Launch Home Assistant and serve web interface on <a href='http://localhost:8123'>http://localhost:8123</a></li>
</ol>
</div> <!-- INSTALL-INSTRUCTIONS RASPBERRY -->
<h3 id='troubleshooting'>Troubleshooting</h3>
<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 three sources:</p>
<ol>
<li><a href='https://gitter.im/balloob/home-assistant'>Gitter Chatroom</a> for general Home Assistant discussions and questions.</li>
<li><a href='https://groups.google.com/forum/#!forum/home-assistant-dev'>Development Mailing List</a> for development related questions and discussing new features.</li>
<li><a href='https://github.com/balloob/home-assistant/issues'>GitHub Page</a> for issue reporting.</li>
</ol>
<h3>What's next</h3>
<p>If you want to have Home Assistant start on boot, <a href='/getting-started/autostart/'>autostart instructions</a> can be found here.</p>
<p>To see what Home Assistant can do, launch demo mode: <code>hass --demo-mode</code></p>
<p>To update Home Assistant to the latest release: <code>pip3 install --upgrade homeassistant</code></p>
<h3><a href='/getting-started/configuration/'>Next step: Configuring Home Assistant &raquo;</a></h3>

89
source/getting-started/index.markdown Normal file
View file

@ -0,0 +1,89 @@
---
layout: page
title: "Getting Started"
description: "Step by step guide to get started with Home Assistant."
date: 2014-12-18 22:57
sidebar: false
comments: false
sharing: true
footer: true
---
<div class='install-instructions-container' markdown='0'>
<input name='install-instructions' type='radio' id='normal-install' checked>
<input name='install-instructions' type='radio' id='raspberry-install'>
<input name='install-instructions' type='radio' id='docker-install'>
<label class='menu-selector normal' for='normal-install'>Install on local machine</label>
<label class='menu-selector raspberry' for='raspberry-install'>Install on a Raspberry Pi</label>
<label class='menu-selector docker' for='docker-install'>Install using Docker</label>
<div class='install-instructions normal' markdown='1'>
Installing and running Home Assistant on your local machine is easy. Make sure you have [Python 3.4](https://www.python.org/downloads/) installed and execute the following code in a console:
```bash
$ pip3 install homeassistant
$ hass --open-ui
```
Running these commands will:
- Install Home Assistant
- Launch Home Assistant and serve web interface on [http://localhost:8123](http://localhost:8123)
</div> <!-- INSTALL-INSTRUCTIONS NORMAL -->
<div class='install-instructions docker' markdown='1'>
Installation with Docker is straightforward. Adjust the following command so that `/path/to/your/config/` points at the folder where you want to store your config and run it:
```bash
$ docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host balloob/home-assistant
```
This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.
<p class='note'>
When using boot2docker on OS X you are unable to map the local time to your Docker container. Replace `-v /etc/localtime:/etc/localtime:ro` with `-e "TZ=America/Los_Angeles"` (replacing America/Los_Angeles with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones))
</p>
</div> <!-- INSTALL-INSTRUCTIONS DOCKER -->
<div class='install-instructions raspberry' markdown='1'>
Home Assistant requires the Raspberry Pi to run [Raspbian Jessie](https://www.raspberrypi.org/downloads/raspbian/). This version has been released on September 24, 2015 and comes by default with Python 3.4 which is required for Home Assistant.
Execute the following code in a console:
```bash
$ pip3 install homeassistant
$ hass --open-ui
```
Running these commands will:
- Install Home Assistant
- Launch Home Assistant and serve web interface on [http://localhost:8123](http://localhost:8123)
</div> <!-- INSTALL-INSTRUCTIONS RASPBERRY -->
</div>
### {% linkable_title Troubleshooting %}
If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues.
For additional help, in addition to this site, there are three sources:
- [Gitter Chatroom](https://gitter.im/balloob/home-assistant) for general Home Assistant discussions and questions.
- [Development Mailing List](https://groups.google.com/forum/#!forum/home-assistant-dev) for development related questions and discussing new features.
- [GitHub Page](https://github.com/balloob/home-assistant/issues) for issue reporting.
### What's next
If you want to have Home Assistant start on boot, [autostart instructions](/getting-started/autostart/) can be found here.
To see what Home Assistant can do, launch demo mode: `hass --demo-mode`
To update Home Assistant to the latest release: `pip3 install --upgrade homeassistant`
### [Next step: Configuring Home Assistant &raquo;](/getting-started/configuration/)

61
source/getting-started/troubleshooting-configuration.markdown
View file

@ -9,23 +9,17 @@ sharing: true
footer: true
---
It can happen that you run into trouble while configuring Home Assistant. A component is not
showing up or is acting weird. This page will discuss a few of the most common problems.
It can happen that you run into trouble while configuring Home Assistant. A component is not showing up or is acting weird. This page will discuss a few of the most common problems.
Before we dive into common issues, make sure you know where your configuration directory is.
Home Assistant will print out the configuration directory it is using when starting up.
Before we dive into common issues, make sure you know where your configuration directory is. Home Assistant will print out the configuration directory it is using when starting up.
Whenever a component or configuration option results in a warning, it will be stored in
`home-assistant.log`. This file is reset on start of Home Assistant.
Whenever a component or configuration option results in a warning, it will be stored in `home-assistant.log`. This file is reset on start of Home Assistant.
### {% linkable_title YAML %}
Home Assistant uses the YAML syntax for configuration. YAML can be confusing at start but it is really
powerful in allowing you to express complex configurations.
Home Assistant uses the YAML syntax for configuration. YAML can be confusing at start but it is really powerful in allowing you to express complex configurations.
The basics of YAML are lists and lookup tables containing key-value pairs. Lists will have each item
start with a `-` while lookup tables will have the format `key: value`. The last value for a key is
used in case you specify a duplicate key.
The basics of YAML are lists and lookup tables containing key-value pairs. Lists will have each item start with a `-` while lookup tables will have the format `key: value`. The last value for a key is used in case you specify a duplicate key.
```yaml
# A list
@ -52,26 +46,20 @@ sensor:
state_topic: sensor2/topic
```
Indentation is used to specify which objects are nested under one anohter. Getting the right indentation
can be tricky if you're not using an editor with a fixed width font. You can test your
configuration using [this online YAML parser](http://yaml-online-parser.appspot.com/).
Indentation is used to specify which objects are nested under one anohter. Getting the right indentation can be tricky if you're not using an editor with a fixed width font. You can test your configuration using [this online YAML parser](http://yaml-online-parser.appspot.com/).
To learn more about the quirks of YAML, read
[YAML IDIOSYNCRASIES](https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html)
by SaltStack.
To learn more about the quirks of YAML, read [YAML IDIOSYNCRASIES](https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html) by SaltStack.
### {% linkable_title My component does not show up %}
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 `home-assistant.log` file and see if there are any errors
related to your component you are trying to set up.
**Problems with the configuration<br>**
`configuration.yaml` does not allow multiple sections to have the same name. If you want a
specific component to be loaded twice, append a number to the name.
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 `home-assistant.log` file and see if there are any errors related to your component you are trying to set up.
**Problems with the configuration**
`configuration.yaml` does not allow multiple sections to have the same name. If you want a specific component to be loaded twice, append a number to the name.
```yaml
sensor:
platform: mqtt
platform: forecast
[…]
sensor 2:
@ -79,27 +67,18 @@ sensor 2:
[…]
```
Another common problem is that a required configuration setting is missing. If this is the
case, the component will report this to `home-assistant.log`. You can have a look at
[the component page](/components/) for instructions how to setup the components.
Another common problem is that a required configuration setting is missing. If this is the case, the component will report this to `home-assistant.log`. You can have a look at [the component page](/components/) for instructions how to setup the components.
If you find any errors or want to expand the documentation, please
[let us know](https://github.com/balloob/home-assistant.io/issues).
If you find any errors or want to expand the documentation, please [let us know](https://github.com/balloob/home-assistant.io/issues).
**Problems with dependencies<br>**
Almost all components have external dependencies to communicate with your devices and services.
Sometimes Home Assistant is unable to install the necessary dependencies. If this is the case, it
should show up in `home-assistant.log`.
**Problems with dependencies**
Almost all components have external dependencies to communicate with your devices and services. Sometimes Home Assistant is unable to install the necessary dependencies. If this is the case, it should show up in `home-assistant.log`.
First step is trying to restart Home Assistant and see if the problem persists. If it does, please
[report it](https://github.com/balloob/home-assistant/issues) so we can investigate what is going on.
First step is trying to restart Home Assistant and see if the problem persists. If it does, please [report it](https://github.com/balloob/home-assistant/issues) so we can investigate what is going on.
**Problems with components<br>**
It can happen that some components either do not work right away or stop working after Home
Assistant has been running for a while. If this happens to you, please
[report it](https://github.com/balloob/home-assistant/issues) so that we can have a look.
**Problems with components**
It can happen that some components either do not work right away or stop working after Home Assistant has been running for a while. If this happens to you, please [report it](https://github.com/balloob/home-assistant/issues) so that we can have a look.
<p class='note'>
Whenever you report an issue, be aware that we are a group of volunteers that do not have access to
every single device in the world nor unlimited time to fix every problem out there.
Whenever you report an issue, be aware that we are a group of volunteers that do not have access to every single device in the world nor unlimited time to fix every problem out there.
</p>