Made README and website contributions match, added more detail to website contribution setup details, updated forum link, re-organised getting started and troubleshooting with respect to YAML
This commit is contained in:
Lindsay Ward
parent
7fcca47d19
commit
c581168e49
7 changed files with 116 additions and 84 deletions
|
|
@ -9,19 +9,74 @@ sharing: true
|
|||
footer: true
|
||||
---
|
||||
|
||||
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 `~/.homeassistant` and on Windows it's `%APPDATA%/.homeassistant`. If you want to use a different folder for configuration, run `hass --config path/to/config`.
|
||||
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 `~/.homeassistant` and on Windows it's `%APPDATA%/.homeassistant`. 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.
|
||||
This file contains YAML code, which is explained briefly in [the configuration troubleshooting page](/getting-started/troubleshooting-configuration/). An example configuration file is located [here](https://github.com/balloob/home-assistant/blob/master/config/configuration.yaml.example).
|
||||
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.
|
||||
This file contains YAML code, which is explained briefly below.
|
||||
[An example configuration file is located 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.
|
||||
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.
|
||||
|
||||
If you run into trouble while configuring Home Assistant, have a look at [the configuration troubleshooting page](/getting-started/troubleshooting-configuration/).
|
||||
|
||||
<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>
|
||||
|
||||
### {% linkable_title YAML %}
|
||||
|
||||
Home Assistant uses the [YAML](http://yaml.org/) syntax for configuration. YAML might take a while to get used to but is really powerful in allowing you to express complex configurations.
|
||||
|
||||
For each component that you want to use in Home Assistant, you add code in your `configuraton.yaml` file to specify its settings.
|
||||
Example, the following code specifies that you want to use the [notify component](/components/notify) with the [pushbullet platform](/components/notify.pushbullet).
|
||||
|
||||
|
||||
```yaml
|
||||
notify:
|
||||
platform: pushbullet
|
||||
api_key: "o.1234abcd"
|
||||
name: pushbullet
|
||||
```
|
||||
|
||||
- A **component** provides the core logic for some functionality (like `notify` provides sending notifications).
|
||||
- A **platform** makes the connection to a specific software or hardware platform (like `pushbullet` works with the service from pushbullet.com).
|
||||
|
||||
The basics of YAML syntax are block collections and mappings containing key-value pairs.
|
||||
Each item in a collection starts with a `-` while mappings have the format `key: value`. If you specify duplicate keys, the last value for a key is used.
|
||||
|
||||
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, `platform: pushbullet` is a property of (nested inside) the `notify` component.
|
||||
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.
|
||||
|
||||
Lines that start with **#** are comments and are ignored by the system.
|
||||
|
||||
The next example shows an [input_select](/components/input_select) component that uses a block collection for the options values.
|
||||
The other properties (like name) are specified using mappings. Note that the second line just has `threat:` 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.
|
||||
|
||||
```yaml
|
||||
input_select:
|
||||
threat:
|
||||
name: Threat level
|
||||
# A collection is used for options
|
||||
options:
|
||||
- 0
|
||||
- 1
|
||||
- 2
|
||||
- 3
|
||||
initial: 0
|
||||
```
|
||||
|
||||
The following example shows nesting a collection of mappings in a mapping.
|
||||
In Home Assistant, this would create two sensors that each use the MQTT platform but have different values for their `state_topic` (one of the properties used for MQTT sensors).
|
||||
|
||||
```yaml
|
||||
sensor:
|
||||
- platform: mqtt
|
||||
state_topic: sensor/topic
|
||||
- platform: mqtt
|
||||
state_topic: sensor2/topic
|
||||
```
|
||||
|
||||
|
||||
### {% 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`:
|
||||
|
|
@ -47,7 +102,7 @@ homeassistant:
|
|||
|
||||
### {% 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 `configuration.yaml` and add the following to the `http` section:
|
||||
The first thing you will want to add is a password for the web interface. Use your favourite text editor to open `configuration.yaml` and edit the `http` section:
|
||||
|
||||
```yaml
|
||||
http:
|
||||
|
|
|
|||
|
|
@ -289,15 +289,15 @@ $ python3/pip3 install --upgrade homeassistant
|
|||
|
||||
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 four sources:
|
||||
In addition to this site, check out these sources for additional help:
|
||||
|
||||
- [Forum](https://community.home-assistant.io/)
|
||||
- [Gitter Chatroom](https://gitter.im/balloob/home-assistant) for general Home Assistant discussions and questions.
|
||||
- [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions.
|
||||
- [Gitter Chat Room](https://gitter.im/balloob/home-assistant) for real-time chat about Home Assistant.
|
||||
- [GitHub Page](https://github.com/balloob/home-assistant/issues) for issue reporting.
|
||||
|
||||
### {% linkable_title What's next %}
|
||||
|
||||
If you want to have Home Assistant start on boot, autostart instructions can be found [here](/getting-started/autostart/).
|
||||
If you want to have Home Assistant start on boot, [autostart instructions can be found here](/getting-started/autostart/).
|
||||
|
||||
To see what Home Assistant can do, launch demo mode: `hass --demo-mode` or visit the [demo page](/demo).
|
||||
|
||||
|
|
|
|||
|
|
@ -15,49 +15,17 @@ Before we dive into common issues, make sure you know where your configuration d
|
|||
|
||||
Whenever a component or configuration option results in a warning, it will be stored in `home-assistant.log` in the configuration directory. This file is reset on start of Home Assistant.
|
||||
|
||||
### {% linkable_title YAML %}
|
||||
|
||||
Home Assistant uses the [YAML](http://yaml.org/) syntax for configuration. YAML can be confusing to start with but is really powerful in allowing you to express complex configurations.
|
||||
|
||||
The basics of YAML are block collections and mappings containing key-value pairs. Collections will have each item start with a `-` while mappings will have the format `key: value`. The last value for a key is used in case you specify a duplicate key.
|
||||
Note that the indentation is an important part of specifying relationships using YAML.
|
||||
|
||||
```yaml
|
||||
# A collection
|
||||
- hello
|
||||
- how
|
||||
- are
|
||||
- you
|
||||
|
||||
# Lookup mapping
|
||||
beer: ice cold # <-- will be ignored because key specified twice
|
||||
beer: warm
|
||||
wine: room temperature
|
||||
water: cold
|
||||
|
||||
# Nesting mappings (note the indentation)
|
||||
device_tracker:
|
||||
platform: mqtt
|
||||
|
||||
# Nesting a collection of mappings in a mapping
|
||||
sensor:
|
||||
- platform: mqtt
|
||||
state_topic: sensor/topic
|
||||
- platform: mqtt
|
||||
state_topic: sensor2/topic
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
- To learn more about the quirks of YAML, read [YAML IDIOSYNCRASIES](https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html) by SaltStack.
|
||||
- You can test your configuration using [this online YAML parser](http://yaml-online-parser.appspot.com/) or [YAML Lint](http://www.yamllint.com/).
|
||||
|
||||
### {% 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.
|
||||
|
||||
#### {% linkable_title Problems with the configuration %}
|
||||
|
||||
One of the most common problems with Home Assistant is an invalid `configuration.yaml` file.
|
||||
|
||||
- You can test your configuration using [this online YAML parser](http://yaml-online-parser.appspot.com/) or [YAML Lint](http://www.yamllint.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 (the examples there are specific to SaltStack, but do explain YAML issues well).
|
||||
|
||||
`configuration.yaml` does not allow multiple sections to have the same name. If you want a specific platform to be loaded twice, append a [number or string](/getting-started/devices/#style-2) to the name or nest them using [this style](/getting-started/devices/#style-1).
|
||||
|
||||
```yaml
|
||||
|
|
@ -92,7 +60,7 @@ If you are using multiple files for your setup, make sure that the pointers are
|
|||
light: !include devices/lights.yaml
|
||||
sensor: !include devices/sensors.yaml
|
||||
```
|
||||
Contents of `lights.yaml`:
|
||||
Contents of `lights.yaml` (notice it does not contain `light: `):
|
||||
|
||||
```yaml
|
||||
- platform: hyperion
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue