From fe2b6264467038cc95815cc3991261792c683ae4 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Sun, 30 Aug 2015 21:55:49 -0700 Subject: [PATCH] Adjust getting started section for 0.7 --- source/_includes/custom/welcome.html | 2 +- source/getting-started/configuration.markdown | 40 +++++++++--- source/getting-started/index.markdown | 60 +++++++----------- .../troubleshooting-configuration.markdown | 63 +++++++++++++++++++ .../getting-started/troubleshooting.markdown | 55 ++++++---------- 5 files changed, 136 insertions(+), 84 deletions(-) create mode 100644 source/getting-started/troubleshooting-configuration.markdown diff --git a/source/_includes/custom/welcome.html b/source/_includes/custom/welcome.html index c36c0b43ccd..0edba7be7df 100644 --- a/source/_includes/custom/welcome.html +++ b/source/_includes/custom/welcome.html @@ -10,4 +10,4 @@ Home Assistant is an open-source home automation platform running on Python 3. T View demo Get started Browse code on GitHub -

\ No newline at end of file +

diff --git a/source/getting-started/configuration.markdown b/source/getting-started/configuration.markdown index 6a9f70f8085..c445e577838 100644 --- a/source/getting-started/configuration.markdown +++ b/source/getting-started/configuration.markdown @@ -9,15 +9,19 @@ sharing: true footer: true --- -The configuration for Home Assistant lives by default in the `config` folder. The file `configuration.yaml` is the main file that contains which components will be loaded and what their configuration is. An example configuration file is located at [`config/configuration.yaml.example`](https://github.com/balloob/home-assistant/blob/master/config/configuration.yaml.example). +By default, Home Assistant will create a configuration folder. Depending on your operating system this is `~/.homeassistant` (OS X/Linux) or `%APPDATA%/.homeassistant` (Windows). If you want to use a different folder for configuration, run `hass --config path/to/config`.

+ +Inside your configuration folder is the file `configuration.yaml`. This is the main file that contains which components will be loaded and what their configuration is. An example configuration file is located at [`here`](https://github.com/balloob/home-assistant/blob/master/config/configuration.yaml.example). 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. +If you are running into troubles while configuring Home Assistant, have a look at [the configuration troubleshoot page](/getting-started/troubleshooting-configuration.html). +

You will have to restart Home Assistant for changes in configuration.yaml to take effect.

-### Setting up the basic info +### {% linkable_title Setting up the basic info %} 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 `configuration.yaml`: @@ -40,7 +44,7 @@ homeassistant: name: Home ``` -### Password protecting the web interface +### {% linkable_title Password protecting the web interface %} The first thing you want to add is a password for the web interface. Use your favourite text editor to open the file `/config/configuration.yaml` and add the following to the bottom: @@ -51,7 +55,9 @@ http: ### {% linkable_title Adding devices and services %} -Home Assistant will be able to automatically discover and configure any Google Chromecasts, Belkin WeMo switches and Philips Hue bridges in your network if you have [the discovery component]({{site_root}}/components/discovery.html) enabled (which is by default). +Home Assistant will be able to automatically discover and configure any Google Chromecasts, Netgear routers, +Belkin WeMo switches and Philips Hue bridges in your network if you have +[the discovery component]({{site_root}}/components/discovery.html) enabled (which is by default). Not all devices can be discovered, so if you have any of the following devices or services, please see their respective pages for installation instructions: @@ -66,15 +72,30 @@ Not all devices can be discovered, so if you have any of the following devices o See the [components overview page](/components/) for a complete list of supported devices. +### {% linkable_title Grouping devices %} + +Once you get a bunch of devices set up, it is time to organize them. This can be done using groups. +Each group exists of a name and a list of entity IDs. Entity IDs can be retrieved from the web interface +by using the Set State page in the Developer Tools (one in the middle). + + +```yaml +group: + living_room: light.table_lamp, switch.ac + bedroom: + - light.bedroom + - media_player.nexus_player +``` + ### {% linkable_title Customizing devices and services %} By default, most of your devices will be visible on the Home Assistant States -page and have a default icon determined by their domain. You may find it +page and have a default icon determined by their domain. You may find it desireable to customize the look and feel of your front page by altering some of these parameters. -By adding the following parameters to the *homeassistant* section of your -*configuration.yaml* file, you can customize the attributes of any state on +By adding the following parameters to the `homeassistant:` section of your +`configuration.yaml`, you can customize the attributes of any state on your front page. ```yaml @@ -83,14 +104,13 @@ homeassistant: # Add this to your existing configuration customize: - SOME_ENTITY_ID: + some.entity_id: hidden: true entity_picture: http://URL.TO/PICTURE friendly_name: SOME CUSTOM NAME ``` -Entity IDs can be retrieved from the web interface by using the Set State page -in the Developer Tools. +

Customizations are currently unavailable for device tracker entities.

### {% linkable_title Setting up Home Automation %} diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index 582e9ffa44c..044e632db49 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -30,20 +30,20 @@ footer: true
-Installing and running Home Assistant on your local machine is easy. Make sure you have Python 3.4 and git installed and execute the following code in a console: +Installing and running Home Assistant on your local machine is easy. Make sure you have Python 3.4 installed and execute the following code in a console:
-

The preparation of a Fedora 22 host will only take a couple of minutes. First install Python 3.4, git and the other needed packages out of the Fedora Package Collection. This ensure that you receive updates in the future.

+

The preparation of a Fedora 22 host will only take a couple of minutes. First install Python 3.4 and the other needed packages out of the Fedora Package Collection. This ensure that you receive updates in the future.

It's assumed that your user has an entry in the sudoers file. Otherwise, run the commands which needs more privileges as root.

```bash -sudo dnf -y install python3 python3-devel git gcc +sudo dnf -y install python3 python3-devel gcc ```
@@ -87,19 +87,13 @@ scl enable rh-python34 bash

```bash -git clone --recursive https://github.com/balloob/home-assistant.git -python3 -m venv home-assistant -cd home-assistant -source bin/activate -python3 -m homeassistant --open-ui +pip3 install homeassistant +hass --open-ui ```

Running these commands will:

    -
  1. Download Home Assistant
    2. -
  2. Setup an isolated environment
    3. -
  3. Navigate to downloaded files
    4. -
  4. Activate the isolated environment (on Windows, run Scripts/activate.bat)
    5. +
  5. Install Home Assistant
  6. Launch Home Assistant and serve web interface on http://localhost:8123

@@ -113,20 +107,15 @@ python3 -m homeassistant --open-ui - +

There is nothing else to do. If you run into any issues, please see the troubleshooting page.

-

- You can run Home Assistant in demo mode by appending --demo-mode to line 5. -

- -

- If you want to update to the latest version in the future, run: scripts/update. -

+

If you want to see what Home Assistant can do, you can start the demo mode by running hass --demo-mode.

+

In the future, if you want to update to the latest version, run pip3 install --upgrade home-assistant.

@@ -139,7 +128,11 @@ sudo firewall-cmd --reload ```

Home Assistant will serve its web interface on http://[IP address of the host]:8123.

-

If you want that Home Assistant is lauched automatically, an extra step is needed to setup systemd. You need a service file to control Home Assistant with systemd. The WorkingDirectory and the PYTHONPATH must point to your clone git repository.

+

If you want that Home Assistant is lauched automatically, an extra step is needed to setup systemd. You need a service file to control Home Assistant with systemd.

+ + + ```bash su -c 'cat <> /lib/systemd/system/home-assistant.service @@ -149,8 +142,6 @@ After=network.target [Service] Type=simple -WorkingDirectory=/home/fab/home-assistant/ -Environment="PYTHONPATH=/home/fab/home-assistant/" ExecStart=/usr/bin/python3.4 -m homeassistant [Install] @@ -185,10 +176,7 @@ $ sudo systemctl status home-assistant -l sudo journalctl -f -u home-assistant ``` -

- If you want to update to the latest version in the future, run: scripts/update and restart Home Assistant. -

- +

In the future, if you want to update to the latest version, run pip3 install --upgrade home-assistant.

Those instructions were written for Fedora 22 Server and Workstation. They may work for Cloud flavor as well but this was not tested. @@ -276,27 +264,25 @@ pyenv install 3.4.2 pyenv virtualenv 3.4.2 homeassistant ``` -

Step 5. Clone the source

-```bash -git clone --recursive https://github.com/balloob/home-assistant.git -``` - -

Step 6. Set the virtual environment

+

Step 5. Set the virtual environment

```bash cd home-assistant pyenv local homeassistant ``` +

Step 6. Install Home Assistant

+```bash +pip3 install homeassistant +``` +

Step 7. Start it up

```bash -python3 -m homeassistant +hass ```

It will be up and running on port 8123

-

- If you want to update to the latest version in the future, run: scripts/update. -

+

In the future, if you want to update to the latest version, run pip3 install --upgrade home-assistant.

diff --git a/source/getting-started/troubleshooting-configuration.markdown b/source/getting-started/troubleshooting-configuration.markdown new file mode 100644 index 00000000000..4582726de67 --- /dev/null +++ b/source/getting-started/troubleshooting-configuration.markdown @@ -0,0 +1,63 @@ +--- +layout: page +title: "Troubleshooting your configuration" +description: "Common problems with tweaking your configuration and their solutions." +date: 2015-01-20 22:36 +sidebar: false +comments: false +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. + +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. + +### {% 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
** + +`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 + […] + +sensor 2: + platform: bitcoin + […] +``` + +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). + +**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. + +**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. + +

+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. +

diff --git a/source/getting-started/troubleshooting.markdown b/source/getting-started/troubleshooting.markdown index 6590e7f9bb9..b3588e679d9 100644 --- a/source/getting-started/troubleshooting.markdown +++ b/source/getting-started/troubleshooting.markdown @@ -1,7 +1,7 @@ --- layout: page -title: "Troubleshooting" -description: "Common problems and their solutions." +title: "Troubleshooting installation problems" +description: "Common installation problems and their solutions." date: 2015-01-20 22:36 sidebar: false comments: false @@ -9,43 +9,26 @@ sharing: true footer: true --- -It can happen that you run into trouble while installing Home Assistant. This page is here to help you figure out the most common problems. +It can happen that you run into trouble while installing Home Assistant. This page is here to help +you figure out the most common problems. -**python3: command not found**
-Check if Python 3.4 is installed by running `python3 --version`. If it is not installed, [download it here](https://www.python.org/getit/). +**pip3: command not found**
+This utility should have been installed as part of the Python 3.4 installation. Check if Python 3.4 +is installed by running `python3 --version`. If it is not installed, +[download it here](https://www.python.org/getit/). + +If you are to succesfully run `python3 --version` but not `pip3`, run the following command instead +to install Home Assistant: `python3 -m pip install homeassistant`. **No module named pip**
-[Pip](https://pip.pypa.io/en/stable/) should come bundled with the latest Python 3 but is ommitted by some distributions. If you are unable to run `python3 -m pip --version` you can install `pip` by [downloading the installer](https://bootstrap.pypa.io/get-pip.py) and run it with Python 3: `python3 get-pip.py`. - -**git: command not found**
-Check if Git is installed by running `git --version`. If you are unable to run this command you can install it by following [these instructions](http://git-scm.com/downloads). - -**No module named 'pytz'**
-There is a problem with installing dependencies on the fly. Install the dependencies manually in advance. - -```bash -python3 -m pip install --upgrade pip -python3 -m pip install --upgrade -r requirements.txt -``` - -**Ubuntu 14.04: ... returned non-zero exit status**
-There is a known issue with installing on Ubuntu 14.04 and possibly many other newer Debian based distributions. The `venv` Python 3.4 package that has been bundled in the apt-get repository are known to be broken. This has been documented [in this bug report](https://bugs.launchpad.net/ubuntu/+source/python3.4/+bug/1290847). If you are encountering an error that looks like the following while creating the virtual environment, you are experiencing this bug. - -```bash -Error: Command '['home-assistant/bin/python3.4', '-Im', 'ensurepip', '--upgrade', '--default-pip']' returned non-zero exit status -``` - -This error can be fixed permanently by running the following commands. - -```bash -cd ~/Downloads -wget https://gist.githubusercontent.com/rmkraus/c3972492a9de875203c6/raw/46629b63857537deedc85ec4a11cd8284816e2a0/install_ensurepip.py -sudo python3 install_ensurepip.py -rm install_ensurepip.py -``` - -After these commands have been successfully executed, the `venv` package will be fixed system-wide. +[Pip](https://pip.pypa.io/en/stable/) should come bundled with the latest Python 3 but is ommitted +by some distributions. If you are unable to run `python3 -m pip --version` you can install `pip` by +[downloading the installer](https://bootstrap.pypa.io/get-pip.py) and run it with Python 3: +`python3 get-pip.py`. **No access to the frontend**
-In newer Linux distributions (at least Fedora 22/CentOS 7) the access to a host are very limited. This means that you can't access the Home Assistant Frontend that is running on a host in your network. Check the Post-installation section on the [Getting started]({{site_root}}/getting-started/index.html) page and follow the instruction that match your distribution to allow access to port 8123. +In newer Linux distributions (at least Fedora 22/CentOS 7) the access to a host are very limited. +This means that you can't access the Home Assistant Frontend that is running on a host in your +network. Check the Post-installation section on the [Getting started](/getting-started/) page and +follow the instruction that match your distribution to allow access to port 8123.