mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-24 09:46:59 +00:00
Update documentation for 0.7.4
This commit is contained in:
Paulus Schoutsen
parent
ce8f88145d
commit
1ec3fd2ab7
@ -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
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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>
|
||||
|
||||
|
||||
@ -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>
|
||||
|
||||
|
||||
@ -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 %}
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user