diff --git a/source/_cookbook/automation_for_rainy_days.markdown b/source/_cookbook/automation_for_rainy_days.markdown index 1fc64a1a03d..4447f4cc386 100644 --- a/source/_cookbook/automation_for_rainy_days.markdown +++ b/source/_cookbook/automation_for_rainy_days.markdown @@ -40,6 +40,7 @@ automation: And then of course turn off the lamp when it stops raining but only if it's within an hour before sunset. ```yaml +automation 2: alias: 'Rain is over' trigger: - platform: state diff --git a/source/_cookbook/automation_sun.markdown b/source/_cookbook/automation_sun.markdown index 81cd31059e1..fb8201f9e35 100644 --- a/source/_cookbook/automation_sun.markdown +++ b/source/_cookbook/automation_sun.markdown @@ -27,7 +27,9 @@ automation: ``` #### Natural wake up light + _Note, Philips Hue is currently the only light platform that support transitions._ + ```yaml automation: trigger: diff --git a/source/_posts/2015-10-11-measure-temperature-with-esp8266-and-report-to-mqtt.markdown b/source/_posts/2015-10-11-measure-temperature-with-esp8266-and-report-to-mqtt.markdown index cafced9f697..f21c0145728 100644 --- a/source/_posts/2015-10-11-measure-temperature-with-esp8266-and-report-to-mqtt.markdown +++ b/source/_posts/2015-10-11-measure-temperature-with-esp8266-and-report-to-mqtt.markdown @@ -10,11 +10,11 @@ categories: how-to mqtt esp8266 og_image: /images/blog/2015-10-esp8266-temp/ha-sensor.png --- -I recently learned about the ESP8266, a $5 chip that includes WiFi and is Arduino compatible. This means -that all your DIY projects can now be done for a fraction of the price. +{::options coderay_line_numbers="table" /} -For this tutorial, I'll walk through how to get going with ESP8266, get the temperature and humidity and -report it to MQTT where Home Asssistant can pick it up. +I recently learned about the ESP8266, a $5 chip that includes WiFi and is Arduino compatible. This means that all your DIY projects can now be done for a fraction of the price. + +For this tutorial, I'll walk through how to get going with ESP8266, get the temperature and humidity and report it to MQTT where Home Asssistant can pick it up.

@@ -36,8 +36,7 @@ I've been using Adafruit for my shopping: - [Adafruit HDC1008 Temperature & Humidity Sensor Breakout Board](http://www.adafruit.com/product/2635) ([assembly instructions](https://learn.adafruit.com/adafruit-hdc1008-temperature-and-humidity-sensor-breakout/assembly)) - [MQTT server](/components/mqtt/#picking-a-broker) -_Besides this, you will need the usual hardware prototype equipment: a breadboard, some wires, -soldering iron + wire, Serial USB cable._ +_Besides this, you will need the usual hardware prototype equipment: a breadboard, some wires, soldering iron + wire, Serial USB cable._ ### Connections @@ -54,11 +53,9 @@ _I picked `#2` and `14` myself, you can configure them in the sketch._ ### Preparing your IDE -Follow [these instructions](https://github.com/esp8266/Arduino#installing-with-boards-manager) on how -to install and prepare the Arduino IDE for ESP8266 development. +Follow [these instructions](https://github.com/esp8266/Arduino#installing-with-boards-manager) on how to install and prepare the Arduino IDE for ESP8266 development. -After you're done installing, open the Arduino IDE, in the menu click on `sketch` -> `include library` -> -`manage libraries` and install the following libraries: +After you're done installing, open the Arduino IDE, in the menu click on `sketch` -> `include library` -> `manage libraries` and install the following libraries: - PubSubClient by Nick 'O Leary - Adafruit HDC1000 @@ -71,16 +68,11 @@ If you have followed the previous steps, you're all set. - Copy and paste the below sketch to the Arduino IDE - Adjust the values line 6 - 14 to match your setup - Optional: If you want to connect to an MQTT server without a username or password, adjust line 63. - - To have the ESP8266 accept our new sketch, we have to put it in upload mode. On the ESP8266 device - keep the GPIO0 button pressed while pressing the reset button. The red led will glow half bright to - indicate it is in upload mode. + - To have the ESP8266 accept our new sketch, we have to put it in upload mode. On the ESP8266 device keep the GPIO0 button pressed while pressing the reset button. The red led will glow half bright to indicate it is in upload mode. - Press the upload button in Arduino IDE - Open the serial monitor (`Tools` -> `Serial Monitor`) to see the output from your device -This sketch will connect to your WiFi network and MQTT broker. It will read the temperature and humidity -from the sensor every second. It will report it to the MQTT server if the difference is > 1 since last -reported value. Reports to the MQTT broker are sent with retain set to `True`. This means that anyone -connecting to the MQTT topic will automatically be notified of the last reported value. +This sketch will connect to your WiFi network and MQTT broker. It will read the temperature and humidity from the sensor every second. It will report it to the MQTT server if the difference is > 1 since last reported value. Reports to the MQTT broker are sent with retain set to `True`. This means that anyone connecting to the MQTT topic will automatically be notified of the last reported value. ```cpp #include @@ -196,8 +188,7 @@ void loop() { ### Configuring Home Assistant -The last step is to integrate the sensor values into Home Assistant. This can be done by setting up -Home Assistant to connect to the MQTT broker and subscribe to the sensor topics. +The last step is to integrate the sensor values into Home Assistant. This can be done by setting up Home Assistant to connect to the MQTT broker and subscribe to the sensor topics. ```yaml mqtt: diff --git a/source/cookbook/index.markdown b/source/cookbook/index.markdown index f4d2fef99eb..6c213e6a3d5 100644 --- a/source/cookbook/index.markdown +++ b/source/cookbook/index.markdown @@ -10,8 +10,7 @@ footer: true regenerate: true --- -This is a community currated list of `configuration.yaml` examples. New recipes can be added via -the [home-assistant.io repository](https://github.com/balloob/home-assistant.io/tree/master/source/_cookbook). +This is a community currated list of `configuration.yaml` examples. New recipes can be added via the [home-assistant.io repository](https://github.com/balloob/home-assistant.io/tree/master/source/_cookbook). {% for recipe in site.cookbook %} * [{{recipe.title}}]({{recipe.url}}) diff --git a/source/developers/index.markdown b/source/developers/index.markdown index 5e17dfea53f..93e0f53133e 100644 --- a/source/developers/index.markdown +++ b/source/developers/index.markdown @@ -22,9 +22,9 @@ Home Assistant is open-source and MIT licensed. The source can be found here: You will need to setup a development environment if you want to start developing a new feature or component for Home Assistant perform theses steps ```bash -git clone https://github.com/balloob/home-assistant.git -cd home-assistant -script/setup +$ git clone https://github.com/balloob/home-assistant.git +$ cd home-assistant +$ script/setup ``` After following these steps, running `hass` will invoke your local installation. @@ -36,15 +36,15 @@ requests. 1. Go to [the Home Assistant repository](https://github.com/balloob/home-assistant) and click fork in the top right. 2. Follow steps in the previous section but with your forked repository. - 3. Create a new branch to hold your changes
+ 3. Create a new branch to hold your changes `git checkout -b some-feature` 4. Make the changes you want - 5. Check your changes for style violations
+ 5. Check your changes for style violations `./script/lint` - 6. Commit the changes
- `git add .`
+ 6. Commit the changes + `git add .` `git commit -m "Added some-feature"` - 7. Push your commited changes back to your fork on Github
+ 7. Push your commited changes back to your fork on Github `git push origin HEAD` 8. Follow [these steps](https://help.github.com/articles/creating-a-pull-request/) to create your pull request. diff --git a/source/getting-started/automation.markdown b/source/getting-started/automation.markdown index 47ab59b90e5..dd252b41bae 100644 --- a/source/getting-started/automation.markdown +++ b/source/getting-started/automation.markdown @@ -9,33 +9,23 @@ sharing: true footer: true --- -When all your devices are set up it's time to put the cherry on the pie: automation. Home Assistant -offers [a few built-in automations](/components/#automation) but mainly you'll be using -[the automation component](/components/automation/) to set up your own rules. +When all your devices are set up it's time to put the cherry on the pie: automation. Home Assistant offers [a few built-in automations](/components/#automation) but mainly you'll be using [the automation component](/components/automation/) to set up your own rules. ### {% linkable_title The basics of automation %} Every automation rule consists of triggers, an action to be performed and optional conditions. -Triggers can be anything observed in Home Assistant. For example, it can be a certain point in time -or a person coming home, which can be observed by the state changing from `not_home` to `home`. +Triggers can be anything observed in Home Assistant. For example, it can be a certain point in time or a person coming home, which can be observed by the state changing from `not_home` to `home`. -Actions will call services within Home Assistant. For example, turn a light on, set the temperature -on your thermostat or activate a scene. +Actions will call services within Home Assistant. For example, turn a light on, set the temperature on your thermostat or activate a scene. -Conditions are used to prevent actions from firing unless certain conditions are met. For example, -it is possible to only turn on the light if someone comes home and it is after a certain point in -time. +Conditions are used to prevent actions from firing unless certain conditions are met. For example, it is possible to only turn on the light if someone comes home and it is after a certain point in time. -The difference between a condition and a trigger can be confusing. The difference is that the trigger -looks at the event that is happening, ie a car engine turning on. Conditions looks at the current state -of the system, ie is the car engine on. +The difference between a condition and a trigger can be confusing. The difference is that the trigger looks at the event that is happening, ie a car engine turning on. Conditions looks at the current state of the system, ie is the car engine on. ### {% linkable_title Exploring the internal state %} -Automation rules are based on the internal state of Home Assistant. This is available for exploring -in the app using the developer tools. The first icon will show you the available services and the -second icon will show you the current devices. +Automation rules are based on the internal state of Home Assistant. This is available for exploring in the app using the developer tools. The first icon will show you the available services and the second icon will show you the current devices. Each device is represented in Home Assistant as an entity consisting of the following parts: @@ -45,19 +35,13 @@ Each device is represented in Home Assistant as an entity consisting of the foll | State | The current state of the device. | `home` | Attributes | Extra data related to the device and/or current state. | `brightness` -A service can be called to have Home Assistant perform an action. Turn on a light, run a script or -enable a scene. Each service has a domain and a name. For example the service `light.turn_on` is -capable of turning on any light device in your system. Services can be passed parameters to for -example tell which device to turn on or what color to use. +A service can be called to have Home Assistant perform an action. Turn on a light, run a script or enable a scene. Each service has a domain and a name. For example the service `light.turn_on` is capable of turning on any light device in your system. Services can be passed parameters to for example tell which device to turn on or what color to use. ## {% linkable_title Creating your first automation rule %} -Before we dive deeper into what every piece of automation _can_ do, let's look at a simple automation -rule: **Turn on the lights when the sun sets** +Before we dive deeper into what every piece of automation _can_ do, let's look at a simple automation rule: **Turn on the lights when the sun sets** -In this example, we are defining a trigger to track the sunset and tell it to fire when the sun is -setting. When this event is triggered, the service `light.turn_on` is called without any -parameters. Because we specify no parameters, it will turn on all the lights. +In this example, we are defining a trigger to track the sunset and tell it to fire when the sun is setting. When this event is triggered, the service `light.turn_on` is called without any parameters. Because we specify no parameters, it will turn on all the lights. ```yaml # Example configuration.yaml entry @@ -70,10 +54,7 @@ automation: service: light.turn_on ``` -After a few days of running this automation rule you come to realize that this automation rule is not -good enough. It was already dark when the lights went on and the one day you weren't home, the lights -turned on anyway. Time for some tweaking. Let's add an offset to the sunset trigger and a condition -to only turn on the lights if anyone is home. +After a few days of running this automation rule you come to realize that this automation rule is not good enough. It was already dark when the lights went on and the one day you weren't home, the lights turned on anyway. Time for some tweaking. Let's add an offset to the sunset trigger and a condition to only turn on the lights if anyone is home. ```yaml # Example configuration.yaml entry @@ -91,18 +72,11 @@ automation: service: light.turn_on ``` -Now you're happy and all is good. You start to like this automation business and buy some more lights, -this time you put them in the bedroom. But what you now realize is that when the sun is setting, the -lights in the bedroom are also being turned on! Time to tweak the automation to only turn on the living -room lights. +Now you're happy and all is good. You start to like this automation business and buy some more lights, this time you put them in the bedroom. But what you now realize is that when the sun is setting, the lights in the bedroom are also being turned on! Time to tweak the automation to only turn on the living room lights. -The first thing you do is to look at the entities in the developer tools (second icon) in the app. -You see the names of your lights and you write them down: `light.table_lamp`, `light.bedroom`, -`light.ceiling`. +The first thing you do is to look at the entities in the developer tools (second icon) in the app. You see the names of your lights and you write them down: `light.table_lamp`, `light.bedroom`, `light.ceiling`. -Instead of hard coding the entity ids of the lights in the automation rule, we will set up a group. -This will allow us to see the living room separate in the app and be able to address it from -automation rules. +Instead of hard coding the entity ids of the lights in the automation rule, we will set up a group. This will allow us to see the living room separate in the app and be able to address it from automation rules. So we tweak the config to add the group and have the automation rule only turn on the group. @@ -128,14 +102,9 @@ automation: entity_id: group.living_room ``` -Christmas is coming along and you decide to buy a remote switch to control the christmas lights from -Home Assistant. You can't claim to live in the house of the future if you're still manually turn on -your christmas lights! +Christmas is coming along and you decide to buy a remote switch to control the christmas lights from Home Assistant. You can't claim to live in the house of the future if you're still manually turn on your christmas lights! -We hook the switch up to Home Assistant and grab the entity id from the developer tools: -`switch.christmas_lights`. We will update the group to include the switch and will change our action. -We are no longer able to call `light.turn_on` because we also want to turn on a switch. This is -where `homeassistant.turn_on` comes to the rescue. This service is capable of turning any entity on. +We hook the switch up to Home Assistant and grab the entity id from the developer tools: `switch.christmas_lights`. We will update the group to include the switch and will change our action. We are no longer able to call `light.turn_on` because we also want to turn on a switch. This is where `homeassistant.turn_on` comes to the rescue. This service is capable of turning any entity on. ```yaml # Example configuration.yaml entry @@ -162,8 +131,7 @@ automation: ### {% linkable_title Further reading %} -We went over the basics of creating a home automation rule. From here no longer any hand holding, -go automate! +We went over the basics of creating a home automation rule. From here no longer any hand holding, go automate! - Learn about the available [automation triggers](/components/automation/#triggers) - Learn about the available [automation conditions](/components/automation/#conditions) diff --git a/source/getting-started/autostart.html b/source/getting-started/autostart.html new file mode 100644 index 00000000000..5a2e6412fd9 --- /dev/null +++ b/source/getting-started/autostart.html @@ -0,0 +1,116 @@ +--- +layout: page +title: "Launch Home Assistant on boot" +description: "Instructions how to setup Home Assistant to launch on boot on various platforms.." +date: 2015-9-1 22:57 +sidebar: false +comments: false +sharing: true +footer: true +--- + +

+ + + + + + + + +
+

Many linux distributions use the Upstart system (or similar) for managing daemons. Typically, systems based on Debian 7 or previous use Upstart. This includes Ubuntu releases before 15.04 and all current Raspian releases. If you are unsure if your system is using Upstart, you may check with the following command:

+ +
$ ps -p 1 -o comm=
+ +

If the preceding command returns the string init, you are likely using Upstart.

+ +

Upstart will launch init scripts that are located in the directory /etc/init.d/. A sample init script for systems using Upstart is maintained by this project.

+ +

To install this script, download it, tweak it to you liking, and install it by following the directions in the header. This script will setup Home Assistant to run when the system boots. To start/stop Home Assistant manually, issue the following commands:

+ +
$ sudo service hass-daemon start
+$ sudo service hass-daemon stop
+
+ +

When running Home Assistant with this script, the configuration directory will be located at /var/opt/homeassistant. This directory will contain a verbose log rather than simply an error log.

+ +

When running daemons, it is good practice to have the daemon run under its own user name rather than the default user's name. Instructions for setting this up are outside the scope of this document.

+
+ + + +
+

Newer linux distributions are trending towards using systemd for managing daemons. Typically, systems based on Fedora or Debian 8 or later use systemd. This includes Ubuntu releases including and after 15.04, CentOS, and Red Hat. If you are unsure if your system is using systemd, you may check with the following command:

+ +
$ ps -p 1 -o comm=
+ +

If the preceding command returns the string systemd, you are likely using systemd.

+ +

If you want Home Assistant to be launched automatically, an extra step is needed to setup systemd. You need a service file to control Home Assistant with systemd.

+ +
$ su -c 'cat <<EOF >> /lib/systemd/system/home-assistant.service
+[Unit]
+Description=Home Assistant
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=/usr/local/bin/hass
+# Next line is to run as a specific user
+# for Raspberry Pi users, keep it at 'pi'
+User=pi
+
+[Install]
+WantedBy=multi-user.target
+EOF'
+
+ +

You need to reload systemd to make the daemon aware of the new configuration. Enable and launch Home Assistant after that.

+ +
$ sudo systemctl --system daemon-reload
+$ sudo systemctl enable home-assistant
+$ sudo systemctl start home-assistant
+
+ +

If everything went well, sudo systemctl start home-assistant should give you a positive feedback.

+ +
$ sudo systemctl status home-assistant -l
+● home-assistant.service - Home Assistant
+   Loaded: loaded (/usr/lib/systemd/system/home-assistant.service; disabled; vendor preset: disabled)
+   Active: active (running) since Thu 2015-06-25 23:38:37 CEST; 3min 13s ago
+ Main PID: 8557 (python3.4)
+   CGroup: /system.slice/home-assistant.service
+           └─8557 /usr/bin/python3.4 -m homeassistant
+[...]
+
+ +

To get Home Assistant's logging output, simple use journalctl.

+ +
$ sudo journalctl -f -u home-assistant
+ +
+ +
+

Setting up Home Assistant to run as a background service is simple. OS X will +start it on boot and make sure it's always running.

+ +

To get Home Assistant installed as a background service, run:

+ +
$ hass --install-osx
+
+Home Assistant has been installed.         Open it here: http://localhost:8123
+
+ +

Home Assistant will log to ~/Library/Logs/homeassistant.log

+ +

To uninstall the service, run:

+ +
$ hass --uninstall-osx
+
+Home Assistant has been uninstalled.
+
+ +
+ +

« Back to Getting Started

diff --git a/source/getting-started/autostart.markdown b/source/getting-started/autostart.markdown deleted file mode 100644 index a0cdd6f6458..00000000000 --- a/source/getting-started/autostart.markdown +++ /dev/null @@ -1,128 +0,0 @@ ---- -layout: page -title: "Launch Home Assistant on boot" -description: "Instructions how to setup Home Assistant to launch on boot on various platforms.." -date: 2015-9-1 22:57 -sidebar: false -comments: false -sharing: true -footer: true ---- - -
- - - - - - - - -
-Many linux distributions use the Upstart system (or similar) for managing daemons. Typically, systems based on Debian 7 or previous use Upstart. This includes Ubuntu releases before 15.04 and all current Raspian releases. If you are unsure if your system is using Upstart, you may check with the following command: - -```bash -ps -p 1 -o comm= -``` - -If the preceding command returns the string `init`, you are likely using Upstart. - -Upstart will launch init scripts that are located in the directory /etc/init.d/. A sample init script for systems using Upstart is maintained by this project. - -To install this script, download it, tweak it to you liking, and install it by following the directions in the header. This script will setup Home Assistant to run when the system boots. To start/stop Home Assistant manually, issue the following commands: -```bash -sudo service hass-daemon start -sudo service hass-daemon stop -``` - -When running Home Assistant with this script, the configuration directory will be located at /var/opt/homeassistant. This directory will contain a verbose log rather than simply an error log. - -When running daemons, it is good practice to have the daemon run under its own user name rather than the default user's name. Instructions for setting this up are outside the scope of this document. -
- - - -
-Newer linux distributions are trending towards using systemd for managing daemons. Typically, systems based on Fedora or Debian 8 or later use systemd. This includes Ubuntu releases including and after 15.04, CentOS, and Red Hat. If you are unsure if your system is using systemd, you may check with the following command: - -```bash -ps -p 1 -o comm= -``` - -If the preceding command returns the string `systemd`, you are likely using systemd. - -If you want Home Assistant to be launched automatically, an extra step is needed to setup systemd. You need a service file to control Home Assistant with systemd. - -```bash -su -c 'cat <> /lib/systemd/system/home-assistant.service -[Unit] -Description=Home Assistant -After=network.target - -[Service] -Type=simple -ExecStart=/usr/local/bin/hass -# Next line is to run as a specific user -# for Raspberry Pi users, keep it at 'pi' -User=pi - -[Install] -WantedBy=multi-user.target -EOF' -``` - -You need to reload systemd to make the daemon aware of the new configuration. Enable and launch Home Assistant after that. - -```bash -sudo systemctl \-\-system daemon-reload -sudo systemctl enable home-assistant -sudo systemctl start home-assistant -``` - -If everything went well, sudo systemctl start home-assistant should give you a positive feedback. - -```bash -$ sudo systemctl status home-assistant -l -● home-assistant.service - Home Assistant - Loaded: loaded (/usr/lib/systemd/system/home-assistant.service; disabled; vendor preset: disabled) - Active: active (running) since Thu 2015-06-25 23:38:37 CEST; 3min 13s ago - Main PID: 8557 (python3.4) - CGroup: /system.slice/home-assistant.service - └─8557 /usr/bin/python3.4 -m homeassistant -[...] -``` - -To get Home Assistant's logging output, simple use journalctl. - -```bash -sudo journalctl -f -u home-assistant -``` -
- -
-Setting up Home Assistant to run as a background service is simple. OS X will -start it on boot and make sure it's always running. - -To get Home Assistant installed as a background service, run: - -```bash -$ hass --install-osx - -Home Assistant has been installed. Open it here: http://localhost:8123 - -``` - -Home Assistant will log to `~/Library/Logs/homeassistant.log` - -To uninstall the service, run: - -```bash -$ hass --uninstall-osx - -Home Assistant has been uninstalled. - -``` - -
- -###[« Back to Getting Started](/getting-started/index/) diff --git a/source/getting-started/configuration.markdown b/source/getting-started/configuration.markdown index 00f92e6dc5e..aefe67fa5b6 100644 --- a/source/getting-started/configuration.markdown +++ b/source/getting-started/configuration.markdown @@ -9,20 +9,13 @@ sharing: true footer: true --- -Home Assistant will create a configuration folder when it is run for the first time. Location depends -on operating system: on OS X/Linux it is `~/.homeassistant` and on Windows it is `%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. Location depends on operating system: on OS X/Linux it is `~/.homeassistant` and on Windows it is `%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. 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. 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 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. -If you are running into troubles while configuring Home Assistant, have a look at -[the configuration troubleshoot page](/getting-started/troubleshooting-configuration/). +If you are running into troubles while configuring Home Assistant, have a look at [the configuration troubleshoot page](/getting-started/troubleshooting-configuration/).

You will have to restart Home Assistant for changes in configuration.yaml to take effect. @@ -30,9 +23,7 @@ If you are running into troubles while configuring Home Assistant, have a look a ### {% 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`: +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`: ```yaml homeassistant: @@ -57,7 +48,7 @@ homeassistant: The first thing you want to add is a password for the web interface. Use your favourite text editor to open the file `/config/configuration.yaml` and add the following to the bottom: -``` +```yaml http: api_password: YOUR_PASSWORD ``` @@ -68,12 +59,8 @@ Home Assistant runs as a self hosted web application. Home Assistant contains su ### {% linkable_title Remote access %} -To make Home Assistant accessible while away from home, you will have to setup port forwarding from -your router to port 8123 on the computer that is hosting Home Assistant. Instructions how to do this -can be found by searching ` port forwarding instructions`. +To make Home Assistant accessible while away from home, you will have to setup port forwarding from your router to port 8123 on the computer that is hosting Home Assistant. Instructions how to do this can be found by searching ` port forwarding instructions`. -Some internet service providers will only offer dynamic IPs. This can cause you to be unable to -access Home Assistant while being remote. You can solve this by using a free Dynamic DNS service -like [DuckDNS](https://www.duckdns.org/). +Some internet service providers will only offer dynamic IPs. This can cause you to be unable to access Home Assistant while being remote. You can solve this by using a free Dynamic DNS service like [DuckDNS](https://www.duckdns.org/). -###[Next step: Setting up devices »](/getting-started/devices/) \ No newline at end of file +### [Next step: Setting up devices »](/getting-started/devices/) diff --git a/source/getting-started/devices.markdown b/source/getting-started/devices.markdown index 43f237c53df..99a3346eff8 100644 --- a/source/getting-started/devices.markdown +++ b/source/getting-started/devices.markdown @@ -9,25 +9,19 @@ sharing: true footer: true --- -Home Assistant will be able to automatically discover and configure any Google Chromecasts, Netgear -routers, Belkin WeMo switches, Philips Hue bridges and Sonos speakers in your network if you have -[the discovery component]({{site_root}}/components/discovery/) enabled (which is by default). +Home Assistant will be able to automatically discover and configure any Google Chromecasts, Netgear routers, Belkin WeMo switches, Philips Hue bridges and Sonos speakers in your network if you have [the discovery component]({{site_root}}/components/discovery/) enabled (which is by default). + +See the [components overview page](/components/) to find installation instructions for your devices and services. Many components use the `sensor` platform. Sensors need to be added into the `configuration.yaml` as `sensor:`, `sensor 2:`, `sensor 3:`, etc. There should not be gaps in the sequence or your sensors might not load correctly. -See the [components overview page](/components/) to find installation instructions for your devices -and services. Many components use the `sensor` platform. Sensors need to be added into the `configuration.yaml` as `sensor:`, `sensor 2:`, `sensor 3:`, etc. There should not be gaps in the sequence or your sensors might not load correctly.

Most components that support multiple entries within the configuration.yaml follow the component:, component 2: format.

-If you can't find support for your favorite device or service, -[consider adding support](/developers/add_new_platform/) +If you can't find support for your favorite device or service, [consider adding support](/developers/add_new_platform/) ### {% linkable_title Grouping devices %} -Once you get a bunch of devices set up, it is time to organize them. This can be done using groups. -Each group exists of a name and a list of entity IDs. Entity IDs can be retrieved from the web interface -by using the Set State page in the Developer Tools (icon in the middle). - +Once you get a bunch of devices set up, it is time to organize them. This can be done using groups. Each group exists of a name and a list of entity IDs. Entity IDs can be retrieved from the web interface by using the Set State page in the Developer Tools (icon in the middle). ```yaml # Example configuration.yaml entry @@ -40,9 +34,7 @@ group: ### {% linkable_title Customizing devices and services %} -By default, all of your devices will be visible and have a default icon determined by their domain. -You may find it desireable to customize the look and feel of your front page by altering some -of these parameters. This can be done by adding the following config to the `homeassistant:` section. +By default, all of your devices will be visible and have a default icon determined by their domain. You may find it desireable to customize the look and feel of your front page by altering some of these parameters. This can be done by adding the following config to the `homeassistant:` section. Entity_pictures, badges, device_tracker pictures, etc can either be a URL or `/local/file.jpg`, which points to directory `www` in the HASS configuration directory. @@ -59,5 +51,4 @@ homeassistant: friendly_name: My better name ``` - -###[Next step: Setting up presence detection »](/getting-started/presence-detection/) +### [Next step: Setting up presence detection »](/getting-started/presence-detection/) diff --git a/source/getting-started/index.html b/source/getting-started/index.html new file mode 100644 index 00000000000..d796cc8ba2d --- /dev/null +++ b/source/getting-started/index.html @@ -0,0 +1,89 @@ +--- +layout: page +title: "Getting Started" +description: "Step by step guide to get started with Home Assistant." +date: 2014-12-18 22:57 +sidebar: false +comments: false +sharing: true +footer: true +--- + +
+ + + + + + + + +
+

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:

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

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:

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

+ +

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

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

Troubleshooting

+ +

If you run into any issues, please see the troubleshooting page. It contains solutions to many of the more commonly encountered issues.

+ +

For additional help, in addition to this site, there are three sources:

+
    +
  1. Gitter Chatroom for general Home Assistant discussions and questions.
    2. +
  2. Development Mailing List for development related questions and discussing new features.
    3. +
  3. GitHub Page for issue reporting.
    4. +
+ +

What's next

+

If you want to have Home Assistant start on boot, autostart instructions can be found here.

+ +

To see what Home Assistant can do, launch demo mode: hass --demo-mode

+ +

To update Home Assistant to the latest release: pip3 install --upgrade homeassistant

+ +

Next step: Configuring Home Assistant »

diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown deleted file mode 100644 index 5d2d12bb858..00000000000 --- a/source/getting-started/index.markdown +++ /dev/null @@ -1,101 +0,0 @@ ---- -layout: page -title: "Getting Started" -description: "Step by step guide to get started with Home Assistant." -date: 2014-12-18 22:57 -sidebar: false -comments: false -sharing: true -footer: true ---- - -
- - - - - - - - -
-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: - -

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

-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 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: - - - Install Home Assistant - - Launch Home Assistant and serve web interface on [http://localhost:8123](http://localhost:8123) - -
- -### {% linkable_title Troubleshooting %} - -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 three sources: - - - [Gitter Chatroom](https://gitter.im/balloob/home-assistant) for general Home Assistant discussions and questions. - - [Development Mailing List](https://groups.google.com/forum/#!forum/home-assistant-dev) for development related questions and discussing new features. - - [GitHub Page](https://github.com/balloob/home-assistant) for issue reporting. - -### {% linkable_title What's next %} -If you want to have Home Assistant start on boot, [autostart instructions](/getting-started/autostart/) can be found here. - -To see what Home Assistant can do, launch demo mode: -```bash -hass \-\-demo-mode -``` - -To update Home Assistant to the latest release: -```bash -pip3 install \-\-upgrade homeassistant -``` - -###[Next step: Configuring Home Assistant »](/getting-started/configuration/) diff --git a/source/getting-started/presence-detection.markdown b/source/getting-started/presence-detection.markdown index ad4e727f10c..546551e3a84 100644 --- a/source/getting-started/presence-detection.markdown +++ b/source/getting-started/presence-detection.markdown @@ -13,9 +13,7 @@ footer: true We care about privacy. Collected data is only stored in your instance of Home Assistant.

-Presence detection detects if people are home, an important input for automation. The most important -piece of information is to know if anyone is home. But knowing who is home or where they are will open -a whole range of other automation options: +Presence detection detects if people are home, an important input for automation. The most important piece of information is to know if anyone is home. But knowing who is home or where they are will open a whole range of other automation options: - Send me a notification when the kid arrives at school - Turn on AC when I leave work @@ -27,19 +25,11 @@ Screenshot of Home Assistant showing a school, work and home zone and two people ## {% linkable_title Setting it up %} -The device tracker component offers presence detection for Home Assistant. It supports two different -methods for presence detection: scan for connected devices on the local network and connect to third -party service. +The device tracker component offers presence detection for Home Assistant. It supports two different methods for presence detection: scan for connected devices on the local network and connect to third party service. -Scanning for connected devices is easy to setup. See the instructions for our [supported routers][routers] -or [scan the network using nmap][nmap]. This approach does have its limitations. It will only be able -to detect if a device is home. It also struggles with iPhones because they disconnect from the WiFi if -idle, marking them as not home while they are not. +Scanning for connected devices is easy to setup. See the instructions for our [supported routers][routers] or [scan the network using nmap][nmap]. This approach does have its limitations. It will only be able to detect if a device is home. It also struggles with iPhones because they disconnect from the WiFi if idle, marking them as not home while they are not. -Home Assistant currently supports one third party service for presence detection: [OwnTracks](http://www.owntracks.org). -OwnTracks is an app that you install on your iPhone or Android phone that allows you to push the location -of your device to Home Assistant using an MQTT broker. An MQTT broker is an Internet of Things communication -platform that you can [freely host yourself][mqtt-self] or get [a private instance for free in the cloud](/components/mqtt/#run-your-own). +Home Assistant currently supports one third party service for presence detection: [OwnTracks](http://www.owntracks.org). OwnTracks is an app that you install on your iPhone or Android phone that allows you to push the location of your device to Home Assistant using an MQTT broker. An MQTT broker is an Internet of Things communication platform that you can [freely host yourself][mqtt-self] or get [a private instance for free in the cloud](/components/mqtt/#run-your-own).

OwnTracks communicates directly with your MQTT broker, no data will pass through their servers. @@ -48,14 +38,12 @@ OwnTracks communicates directly with your MQTT broker, no data will pass through #### {% linkable_title Zones %} -Home Assistant will know about the location for your device if you are using OwnTracks. By [setting up -zones][zone] you will be able to add names to locations of your devices. This way you can easily -spot on the state page where the people in your house are and use it as [triggers][trigger] and -[conditions][condition] for automation. -###[Next step: Setting up automation »](/getting-started/automation/) +Home Assistant will know about the location for your device if you are using OwnTracks. By [setting up zones][zone] you will be able to add names to locations of your devices. This way you can easily spot on the state page where the people in your house are and use it as [triggers][trigger] and [conditions][condition] for automation. -[routers]: /components/#presence +### [Next step: Setting up automation »](/getting-started/automation/) + +[routers]: /components/#presence-detection [nmap]: /components/device_tracker.nmap_scanner/ [ha-owntracks]: /components/device_tracker.owntracks/ [mqtt-self]: /components/mqtt/#run-your-own diff --git a/source/getting-started/troubleshooting.markdown b/source/getting-started/troubleshooting.markdown index f11e64aa0a7..34b427c23b5 100644 --- a/source/getting-started/troubleshooting.markdown +++ b/source/getting-started/troubleshooting.markdown @@ -12,60 +12,61 @@ footer: true It can happen that you run into trouble while installing Home Assistant. This page is here to help you figure out the most common problems. -**pip3: command not found**
-This utility should have been installed as part of the Python 3.4 installation. Check if Python 3.4 -is installed by running `python3 --version`. If it is not installed, -[download it here](https://www.python.org/getit/). +**pip3: command not found** +This utility should have been installed as part of the Python 3.4 installation. Check if Python 3.4 is installed by running `python3 --version`. If it is not installed, [download it here](https://www.python.org/getit/). -If you are able to successfully run `python3 --version` but not `pip3`, run the following command instead -to install Home Assistant: `python3 -m pip install homeassistant`. +If you are able to successfully run `python3 --version` but not `pip3`, run the following command instead to install Home Assistant: -**No module named pip**
-[Pip](https://pip.pypa.io/en/stable/) should come bundled with the latest Python 3 but is ommitted -by some distributions. If you are unable to run `python3 -m pip --version` you can install `pip` by -[downloading the installer](https://bootstrap.pypa.io/get-pip.py) and run it with Python 3: -`python3 get-pip.py`. +```bash +$ python3 -m pip install homeassistant +``` -**distutils.errors.DistutilsOptionError: must supply either home or prefix/exec-prefix -- not both**
-This is a known issue if you're on a Mac using Homebrew to install Python. Please follow -[these instructions](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Homebrew-and-Python.md#note-on-pip-install---user) -to resolve it. +**No module named pip** +[Pip](https://pip.pypa.io/en/stable/) should come bundled with the latest Python 3 but is ommitted by some distributions. If you are unable to run `python3 -m pip --version` you can install `pip` by [downloading the installer](https://bootstrap.pypa.io/get-pip.py) and run it with Python 3: -**CentOS and Python 3**
-To run Python 3.x on [CentOS](https://www.centos.org/) or RHEL, [Software Collections](https://www.softwarecollections.org/en/scls/rhscl/rh-python34/) needs to be activated.

+```bash +$ python3 get-pip.py +``` -**Run the development version**
-If you want to stay on top of the development of Home Assistant then you can upgrade to the dev branch using -`pip3 install --upgrade git+git://github.com/balloob/home-assistant.git@dev`. Keep in mind, that stable releases -of Home Assistant are published often. +**distutils.errors.DistutilsOptionError: must supply either home or prefix/exec-prefix -- not both** +This is a known issue if you're on a Mac using Homebrew to install Python. Please follow [these instructions](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Homebrew-and-Python.md#note-on-pip-install---user) to resolve it. -**No access to the frontend**
-In newer Linux distributions (at least Fedora 22/CentOS 7) the access to a host is very limited. -This means that you can't access the Home Assistant Frontend that is running on a host outside of the -host machine. Windows and OSX machines may also have issues with this. +**CentOS and Python 3** +To run Python 3.x on [CentOS](https://www.centos.org/) or RHEL, [Software Collections](https://www.softwarecollections.org/en/scls/rhscl/rh-python34/) needs to be activated. -To fix this you will need to open your machine's firewall for TCP traffic over port 8123. The method -for doing this will vary depending on your operating system and the firewall you have installed. -Below are some suggestions to try. Google is your friend here. +**No access to the frontend** +In newer Linux distributions (at least Fedora 22/CentOS 7) the access to a host is very limited. This means that you can't access the Home Assistant Frontend that is running on a host outside of the host machine. Windows and OSX machines may also have issues with this. -[Windows instructions](http://windows.microsoft.com/en-us/windows/open-port-windows-firewall#1TC=windows-7)
+To fix this you will need to open your machine's firewall for TCP traffic over port 8123. The method for doing this will vary depending on your operating system and the firewall you have installed. Below are some suggestions to try. Google is your friend here. + +[Windows instructions](http://windows.microsoft.com/en-us/windows/open-port-windows-firewall#1TC=windows-7) [Mac OSX instructions](https://support.apple.com/en-us/HT201642) For firewalld systems (Fedora, RHEL, etc.): + ```bash -sudo firewall-cmd --permanent --add-port=8123/tcp -sudo firewall-cmd --reload +$ sudo firewall-cmd --permanent --add-port=8123/tcp +$ sudo firewall-cmd --reload ``` For UFW systems (Ubuntu, Debian, Raspbian, etc.): + ```bash -sudo ufw allow 8123/tcp +$ sudo ufw allow 8123/tcp ``` For iptables systems (usually the default): + ```bash -iptables -I INPUT -p tcp --dport 8123 -j ACCEPT -iptables-save > /etc/network/iptables.rules # your rules may be saved elsewhere +$ iptables -I INPUT -p tcp --dport 8123 -j ACCEPT +$ iptables-save > /etc/network/iptables.rules # your rules may be saved elsewhere ``` -###[« Back to Getting Started](/getting-started/index/) +**Run the development version** +If you want to stay on top of the development of Home Assistant then you can upgrade to the dev branch. This can result in an unstable system, loss of data etc etc. + +```bash +$ pip3 install --upgrade git+git://github.com/balloob/home-assistant.git@dev +``` + +### [« Back to Getting Started](/getting-started/index/)