Update documentation for 0.7.4
This commit is contained in:
Paulus Schoutsen
parent
ce8f88145d
commit
1ec3fd2ab7
7 changed files with 205 additions and 43 deletions
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue