Update documentation for 0.7.4

This commit is contained in:
Paulus Schoutsen 2015-10-03 18:24:55 -07:00
parent ce8f88145d
commit 1ec3fd2ab7
7 changed files with 205 additions and 43 deletions

View File

@ -19,15 +19,21 @@ full configuration but only the relevant part.
```yaml
# Example of entry in configuration.yaml
automation:
# Turns on lights 1 hour before sunset if people are home
# and if people get home between 16:00-23:00
- alias: 'Rule 1 Light on in the evening'
trigger:
# Prefix the first line of each trigger configuration
# with a '-' to enter multiple
- platform: sun
event: sunset
offset: "-01:00:00"
offset: '-01:00:00'
- platform: state
entity_id: group.all_devices
state: home
condition:
# Prefix the first line of each condition configuration
# with a '-'' to enter multiple
- platform: state
entity_id: group.all_devices
state: home
@ -37,20 +43,31 @@ automation:
action:
service: homeassistant.turn_on
entity_id: group.living_room
# Turn off lights when everybody leaves the house
- alias: 'Rule 2 - Away Mode'
trigger:
- platform: state
entity_id: group.all_devices
state: 'not_home'
condition: use_trigger_values
condition:
platform: state
entity_id: group.all_devices
state: 'not_home'
action:
service: light.turn_off
entity_id: group.all_lights
service: light.turn_off
entity_id: group.all_lights
# Notify when Paulus leaves the house in the evening
- alias: 'Leave Home notification'
trigger:
platform: zone
event: leave
zone: zone.home
entity_id: device_tracker.paulus
condition:
platform: time
after: '20:00'
action:
service: notify.notify
data:
message: 'Paulus left the house'
```
<p class='note'>
@ -166,6 +183,22 @@ Valid values for `weekday` are (`sun`, `mon`, `tue`, `wed`, `thu`, `fri` & `sat`
The above example will trigger on Saturday and Sunday every hour on the 5 (2:05, 3:05, 4:05, etc).
#### {% linkable_title Zone trigger %}
Zone triggers can trigger when an entity is entering or leaving the zone. For zone automation to work,
you need to have setup a device tracker platform that supports reporting GPS coordinates. Currently
this is limited to the [OwnTracks platform](/components/device_tracker.owntracks.html).
```yaml
automation:
trigger:
platform: zone
entity_id: device_tracker.paulus
zone: zone.home
# Event is either enter or leave
event: enter
```
## {% linkable_title Conditions %}
Conditions are an optional part of an automation rule and be used to prevent an action from happening
@ -234,6 +267,19 @@ automation:
Valid values for `weekday` are (sun, mon, tue, wed, thu, fri & sat)
#### {% linkable_title Zone condition %}
Zone conditions test if an entity is in a certain zone. For zone automation to work,
you need to have setup a device tracker platform that supports reporting GPS coordinates. Currently
this is limited to the [OwnTracks platform](/components/device_tracker.owntracks.html).
```yaml
automation:
condition:
platform: zone
entity_id: device_tracker.paulus
zone: zone.home
```
## {% linkable_title Actions %}
When an automation rule fires, it calls a service. For this service you can specify an entity id it

View File

@ -10,7 +10,11 @@ footer: true
---
<img src='/images/supported_brands/owntracks.png' class='brand pull-right' />
This platform allows you to detect presence by monitoring MQTT topics uses by [Owntracks](http://owntracks.org/) for new locations.
This platform allows you to detect presence using [Owntracks](http://owntracks.org/). OwnTracks allows
users to track their location on Android and iOS phones and publish it to a MQTT broker. This platform
will connect to the broker and monitor for new locations.
This component requires [the MQTT component](/components/mqtt.html) to be set up.
To integrate Owntracks in Home Assistant, add the following section to your `configuration.yaml` file:

View File

@ -9,9 +9,8 @@ sharing: true
footer: true
---
<img src='/images/supported_brands/mqtt.png' class='brand pull-right' />
MQTT (aka MQ Telemetry Transport) is a machine-to-machine or "Internet of Things" connectivity protocol on top of TCP/IP. It allows extremely lightweight publish/subscribe messaging transport.
The MQTT component needs an MQTT broker like [Mosquitto](http://mosquitto.org/) or [Mosca](http://www.mosca.io/). The Eclipse Foundation is running a public MQTT broker at [iot.eclipse.org](http://iot.eclipse.org/getting-started) or the Mosquitto Project under [test.mosquitto.org](http://test.mosquitto.org). If you prefer to use a public, keep in mind to adjust the topic and that your messages may be publicly accessible.
MQTT (aka MQ Telemetry Transport) is a machine-to-machine or "Internet of Things" connectivity protocol
on top of TCP/IP. It allows extremely lightweight publish/subscribe messaging transport.
To integrate MQTT into Home Assistant, add the following section to your `configuration.yaml` file:
@ -24,6 +23,7 @@ mqtt:
keepalive: 60
username: USERNAME
password: PASSWORD
certificate: /home/paulus/dev/addtrustexternalcaroot.crt
```
Configuration variables:
@ -34,20 +34,90 @@ Configuration variables:
- **keepalive** (*Optional*): The keep alive in seconds for this client. Default is 60.
- **username** (*Optional*): The username to use with your MQTT broker.
- **password** (*Optional*): The corresponding password for the username to use with your MQTT broker.
- **certificate** (*Optional*): Certificate to use to encrypt communication with the broker.
## {% linkable_title Picking a broker %}
The MQTT component needs you to run an MQTT broker for Home Assistant to connect to.
There are three options, each with various degrees of ease of setup and privacy.
#### {% linkable_title Run your own %}
Most private option but requires a bit more work. There are two free and open-source brokers to pick
from: [Mosquitto](http://mosquitto.org/) and [Mosca](http://www.mosca.io/).
```yaml
# Example configuration.yaml entry
mqtt:
broker: 192.168.1.100
port: 1883
client_id: home-assistant-1
keepalive: 60
username: USERNAME
password: PASSWORD
```
#### {% linkable_title Public MQTT %}
The Mosquitto project runs a [public broker](http://test.mosquitto.org). Easiest to setup but there
is 0 privacy as all messages are public. Use this only for testing purposes and not for real tracking
of your devices.
```yaml
mqtt:
broker: test.mosquitto.org
port: 1883
# Optional, if you want encryption
# (doesn't really matter because broker is public)
port: 8883
# Download certificate from http://test.mosquitto.org/ssl/mosquitto.org.crt
certificate: /home/paulus/downloads/mosquitto.org.crt
```
#### {% linkable_title CloudMQTT %}
[CloudMQTT](https://www.cloudmqtt.com) is a hosted private MQTT instance that is free up to 10
connected devices. This is enough to get started with for example
[OwnTracks](/components/device_tracker.owntracks.html) and give you a taste of what is possible.
<p class='note'>
The MQTT component has no TLS support at the moment. This means that only plain-text communication is possible.
Home Assistant is not affiliated with CloudMQTT nor will receive any kickbacks.
</p>
## Building on top of MQTT
1. [Create an account](https://customer.cloudmqtt.com/login) (no payment details needed)
2. [Create a new CloudMQTT instance](https://customer.cloudmqtt.com/subscription/create)
(Cute Cat is the free plan)
3. From the control panel, click on the _Details_ button.
4. Create unique users for Home Assistant and each phone to connect<br>(CloudMQTT does not allow two
connections from the same user)
a. Under manage users, fill in username, password and click add
b. Under ACLs, select user, topic `#`, check 'read access' and 'write access'
5. Copy the instance info to your configuration.yaml:
```yaml
mqtt:
broker: <Server>
port: <SSL Port>
username: <User>
password: <Password>
```
<p class='note'>
Home Assistant will automatically load the correct certificate if you connect to an encrypted channel
of CloudMQTT (port range 20 000 - 30 000).
</p>
## {% linkable_title Building on top of MQTT %}
- [MQTT Sensor](/components/sensor.mqtt.html)
- [MQTT Switch](/components/switch.mqtt.html)
- [MQTT Device Tracker](/components/device_tracker.mqtt.html)
- [OwnTracks Device Tracker](/components/device_tracker.owntracks.html)
- [MQTT-automation rule](/components/automation.html#mqtt-based-automation)
- Integrating it into a component. See the [MQTT example component](https://github.com/balloob/home-assistant/blob/dev/config/custom_components/mqtt_example.py) how to do this.
## Testing
## {% linkable_title Testing your setup %}
For debugging purposes `mosquitto` is shipping commandline tools to send and recieve MQTT messages. For sending test messages to a broker running on localhost:

View File

@ -29,6 +29,6 @@ sensor:
For more details about the GPIO layout, visit the Wikipedia [article](https://en.wikipedia.org/wiki/Raspberry_Pi#GPIO_connector) about the Raspberry Pi.
<p class='note warning'>
As this requires access to the GPIO, you will need to run Home Assistant as root.
If you are not running Raspbian Jessie, you will need to run Home Assistant as root.
</p>

View File

@ -26,6 +26,5 @@ switch:
For more details about the GPIO layout, visit the Wikipedia [article](https://en.wikipedia.org/wiki/Raspberry_Pi#GPIO_connector) about the Raspberry Pi.
<p class='note warning'>
As this requires access to the GPIO, you will need to run Home Assistant as root.
If you are not running Raspbian Jessie, you will need to run Home Assistant as root.
</p>

View File

@ -18,9 +18,6 @@ footer: true
<label class='menu-selector docker' for='docker-install'>Install using Docker</label>
<h3>Installation</h3>
<div class='install-instructions normal'>
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:
@ -33,44 +30,50 @@ hass \-\-open-ui
<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>
<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>
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
```
<p>This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.</p>
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 <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>)
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 uses Python 3.4 which is not shipped with the current Raspbian distibution for the Raspberry Pi. Before installing Home Assistant, you will have to <a href="https://www.raspberrypi.org/forums/viewtopic.php?f=32&t=113961#p779265" target="_blank">install Python 3.4</a>.
Once that is complete, 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:
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.
Execute the following code in a console:
<p>
```bash
pip3 install homeassistant
hass \-\-open-ui
```
</p>
<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 RASPBERRY -->
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 -->
### {% linkable_title Troubleshooting %}

View File

@ -18,13 +18,54 @@ Home Assistant will print out the configuration directory it is using when start
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.
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
- hello
- how
- are
- you
# Lookup table
beer: ice cold # <-- will be ignored because key specified twice
beer: warm
wine: room temperature
water: cold
# Nesting tables
device_tracker:
platform: mqtt
# Nesting a list of tables in a table
sensor:
- platform: mqtt
state_topic: sensor/topic
- platform: mqtt
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/).
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.
@ -40,11 +81,10 @@ 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.
[the component page](/components/) for instructions how to setup the components.
Incorrect indentation within the `configuration.yaml` can also create issues. [Online YAML parsers](http://yaml-online-parser.appspot.com/) are available to verify your text is properly formatted. If there are errors, you will also see the tracebacks in the `home-assistant.log` referencing the line number from `configuration.yaml`. This information along with the YAML parsers can be a fast way to resolve small validation issues.
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.