From 1ec3fd2ab7a2c1a717e5ccade5ce3d43a8ef8d30 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Sat, 3 Oct 2015 18:24:55 -0700 Subject: [PATCH] Update documentation for 0.7.4 --- source/components/automation.markdown | 68 ++++++++++++--- .../device_tracker.owntracks.markdown | 6 +- source/components/mqtt.markdown | 82 +++++++++++++++++-- source/components/sensor.rpi_gpio.markdown | 2 +- source/components/switch.rpi_gpio.markdown | 3 +- source/getting-started/index.markdown | 37 +++++---- .../troubleshooting-configuration.markdown | 50 +++++++++-- 7 files changed, 205 insertions(+), 43 deletions(-) diff --git a/source/components/automation.markdown b/source/components/automation.markdown index fcbbd51f131..f1c48bc0706 100644 --- a/source/components/automation.markdown +++ b/source/components/automation.markdown @@ -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' ```

@@ -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 diff --git a/source/components/device_tracker.owntracks.markdown b/source/components/device_tracker.owntracks.markdown index e2838c3ebe1..821ea9bf1ce 100644 --- a/source/components/device_tracker.owntracks.markdown +++ b/source/components/device_tracker.owntracks.markdown @@ -10,7 +10,11 @@ footer: true --- -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: diff --git a/source/components/mqtt.markdown b/source/components/mqtt.markdown index e42d79ca3f5..6c06c29add5 100644 --- a/source/components/mqtt.markdown +++ b/source/components/mqtt.markdown @@ -9,9 +9,8 @@ sharing: true footer: true --- -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.

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

-## 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
(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: + port: + username: + password: +``` + +

+Home Assistant will automatically load the correct certificate if you connect to an encrypted channel +of CloudMQTT (port range 20 000 - 30 000). +

+ +## {% 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: diff --git a/source/components/sensor.rpi_gpio.markdown b/source/components/sensor.rpi_gpio.markdown index 5b3a6337ce3..92789655b23 100644 --- a/source/components/sensor.rpi_gpio.markdown +++ b/source/components/sensor.rpi_gpio.markdown @@ -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.

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

diff --git a/source/components/switch.rpi_gpio.markdown b/source/components/switch.rpi_gpio.markdown index c1350b4e9a0..0d4206c2b73 100644 --- a/source/components/switch.rpi_gpio.markdown +++ b/source/components/switch.rpi_gpio.markdown @@ -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.

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

- diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index 7d1ebfbb1e5..f876131c861 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -18,9 +18,6 @@ footer: true -

Installation

- -
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: @@ -33,44 +30,50 @@ hass \-\-open-ui

Running these commands will:

  1. Install Home Assistant
    2. -
  2. Launch Home Assistant and serve web interface on http://localhost:8123
    3. +
  3. Launch Home Assistant and serve web interface on +http://localhost:8123
-

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:

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

This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.

+This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.

-When using boot2docker on OS X you are unable to map the local time to your Docker container. Replace -v /etc/localtime:/etc/localtime:ro with -e "TZ=America/Los_Angeles" (replacing America/Los_Angeles with your timezone) +When using boot2docker on OS X you are unable to map the local time to your Docker container. Replace +-v /etc/localtime:/etc/localtime:ro with -e "TZ=America/Los_Angeles" +(replacing America/Los_Angeles with your timezone)

+
-

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 install Python 3.4. -Once that is complete, 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: +Home Assistant requires the Raspberry Pi to run Raspbian Jessie. +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: -

```bash pip3 install homeassistant hass \-\-open-ui ``` -

-

Running these commands will:

-
    -
  1. Install Home Assistant
    2. -
  2. Launch Home Assistant and serve web interface on http://localhost:8123
    3. -
-
+Running these commands will: + + - Install Home Assistant + - Launch Home Assistant and serve web interface on [http://localhost:8123](http://localhost:8123) + + ### {% linkable_title Troubleshooting %} diff --git a/source/getting-started/troubleshooting-configuration.markdown b/source/getting-started/troubleshooting-configuration.markdown index dd48dad5d62..a434cd86964 100644 --- a/source/getting-started/troubleshooting-configuration.markdown +++ b/source/getting-started/troubleshooting-configuration.markdown @@ -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
** - `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
** Almost all components have external dependencies to communicate with your devices and services.