Reorganize the getting started and component pages

This commit is contained in:
Paulus Schoutsen 2015-01-24 18:47:04 -08:00
parent e134f73933
commit 759d107680
23 changed files with 831 additions and 144 deletions

113
plugins/directory_tag.rb Normal file
View File

@ -0,0 +1,113 @@
# Title: Dynamic directories for Jekyll
# Author: Tommy Sullivan http://superawesometommy.com, Robert Park http://exolucere.ca
# Description: The directory tag lets you iterate over files at a particular path. If files conform to the standard Jekyll format, YYYY-MM-DD-file-title, then those attributes will be populated on the yielded file object. The `forloop` object maintains [its usual context](http://wiki.shopify.com/UsingLiquid#For_loops).
#
# Syntax:
#
# {% directory path: path/from/source [reverse] [exclude] %}
# {{ file.url }}
# {{ file.name }}
# {{ file.date }}
# {{ file.slug }}
# {{ file.title }}
# {% enddirectory %}
#
# Options:
#
# - `reverse` - Defaults to 'false', ordering files the same way `ls` does: 0-9A-Za-z.
# - `exclude` - Defaults to '.html$', a Regexp of files to skip.
#
# File Attributes:
#
# - `url` - The absolute path to the published file
# - `name` - The basename
# - `date` - The date extracted from the filename, otherwise the file's creation time
# - `slug` - The basename with date and extension removed
# - `title` - The titlecase'd slug
#
module Jekyll
class DirectoryTag < Liquid::Block
include Convertible
MATCHER = /^(.+\/)*(\d+-\d+-\d+)-(.*)(\.[^.]+)$/
attr_accessor :content, :data
def initialize(tag_name, markup, tokens)
attributes = {}
# Parse parameters
markup.scan(Liquid::TagAttributes) do |key, value|
attributes[key] = value
end
@path = attributes['path'] || '.'
@exclude = Regexp.new(attributes['exclude'] || '.html$', Regexp::EXTENDED | Regexp::IGNORECASE)
@rev = attributes['reverse'].nil?
super
end
def render(context)
context.registers[:directory] ||= Hash.new(0)
source_dir = context.registers[:site].source
directory_files = File.join(source_dir, @path, "*")
files = Dir.glob(directory_files).reject{|f| f =~ @exclude }
files.sort! {|x,y| @rev ? x <=> y : y <=> x }
length = files.length
result = []
context.stack do
files.each_with_index do |filename, index|
basename = File.basename(filename)
filepath = [@path, basename] - ['.']
path = filepath.join '/'
url = '/' + filepath.join('/')
m, cats, date, slug, ext = *basename.match(MATCHER)
if m
date = Time.parse(date)
ext = ext
slug = slug
else
date = File.ctime(filename)
ext = basename[/\.[a-z]+$/, 0]
slug = basename.sub(ext, '')
end
context['file'] = {
'date' => date,
'name' => basename,
'slug' => slug,
'url' => url
}
context['forloop'] = {
'name' => 'directory',
'length' => length,
'index' => index + 1,
'index0' => index,
'rindex' => length - index,
'rindex0' => length - index - 1,
'first' => (index == 0),
'last' => (index == length - 1)
}
result << render_all(@nodelist, context)
end
end
result
end
end
end
Liquid::Template.register_tag('directory', Jekyll::DirectoryTag)

View File

@ -58,6 +58,10 @@ article.post, article.page, article.listing {
li {
margin-bottom: 10px;
& > p {
margin-bottom: 0;
}
&:last-child {
margin-bottom: 0;
}

View File

@ -0,0 +1,138 @@
---
layout: page
title: "Automation"
description: "Instructions how to setup automation within Home Assistant."
date: 2015-01-20 22:36
sidebar: false
comments: false
sharing: true
footer: true
---
This page will talk about automating Home Assistant using the `automation` component. For more advanced ways of automation, see the [create a component]({{site_root}}/developers/creating_components.html) page.
Each part of automation consists of two parts: the trigger part and the action part. The final result will look something like this:
```
[automation]
# Optional alias that the logs will use to refer to the entry
alias=Sunset notification
# Type of trigger and informatino for the trigger
platform=state
state_entity_id=sun.sun
state_from=above_horizon
state_to=below_horizon
# Action to be done when trigger activated
execute_service=notify.notify
service_data={"message":"The sun has set"}
```
## Setting up triggers
#### Time-based automation
This allows you to trigger actions whenever the time matches your filter. You can setup filters to match on hours, minutes and seconds. Any filter that you omit will match all values.
Here are some example values:
```
# Match at the start of every hour
platform=time
time_minutes=0
time_seconds=0
# Match at 4pm
platform=time
time_hours=16
time_minutes=0
time_seconds=0
```
<p class='note warning'>
Home Assistant checks your time filters every 3 seconds. That means that the value of seconds will only be 0, 3, 6, 9…60. Setting up a filter for `time_seconds=10` will never fire!
</p>
#### State-based automation
This allows you to trigger actions based on state changes of any entity within Home Assistant. You can omit the `state_from` and `state_to` to match all.
```
# Match when the sun sets
platform=state
state_entity_id=sun.sun
state_from=above_horizon
state_to=below_horizon
# Match when a person comes home
platform=state
state_entity_id=device_tracker.Paulus_OnePlus_One
state_from=not_home
state_to=home
# Match when a light turns on
platform=state
state_entity_id=light.Ceiling
state_from=off
state_to=on
```
## Setting up the action
Currently the only supported action is calling a service. Services are what devices expose to be controlled, so this will allow us to control anything that Home Assistant can control.
```
# Turn the lights Ceiling and Wall on.
execute_service=light.turn_on
service_entity_id=light.Ceiling,light.Wall
# Turn the lights Ceiling and Wall on and turn them red.
execute_service=light.turn_on
service_entity_id=light.Ceiling,light.Wall
service_data={"rgb_color": [255, 0, 0]}
# Notify the user
execute_service=notify.notify
service_data={"message":"YAY"}
```
## Putting it all together
For every combination of a trigger and an action we will have to combine the configuration lines and add it to an `automation` component entry in `home-assistant.conf`. You can add an optional `alias` key to the configuration to make the logs more understandable. To setup multiple entries, append 2, 3 etc to the section name. An example of a `home-assistant.conf` file:
```
[automation]
alias=Sunset notification
platform=state
state_entity_id=sun.sun
state_from=above_horizon
state_to=below_horizon
execute_service=notify.notify
service_data={"message":"The sun has set"}
[automation 2]
alias=Turn lights off at 8am in the morning
platform=time
time_hours=8
time_minutes=0
time_seconds=0
execute_service=light.turn_off
[automation 3]
alias=Turn lights in study room on when Paulus comes home
platform=state
state_entity_id=device_tracker.Paulus_OnePlus
state_from=not_home
state_to=home
execute_service=homeassistant.turn_on
service_entity_id=group.Study_Room
```
<p class='note'>
All configuration entries have to be sequential. If you have <code>[automation]</code>, <code>[automation 2]</code> and <code>[automation 4]</code> then the last one will not be processed.
</p>

View File

@ -0,0 +1,24 @@
---
layout: page
title: "Browser"
description: "Instructions how to setup the browser component with Home Assistant."
date: 2015-01-24 14:39
sidebar: false
comments: false
sharing: true
footer: true
---
The browser component provides a service to open urls in the default browser on the host machine.
To load this component, add the following lines to your `home-assistant.conf`:
```
[browser]
```
#### Service `browser/browse_url`
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `url` | no | The url to open

View File

@ -0,0 +1,49 @@
---
layout: page
title: "Chromecast"
description: "Instructions how to setup your chromecasts with Home Assistant."
date: 2015-01-24 14:39
sidebar: false
comments: false
sharing: true
footer: true
---
<p class='note warning'>
Chromecasts have recently received a new API which is not yet supported by Home Assistant. Therefore we currently can only detect them and do not know what they are up to.
</p>
Interacts with Chromecasts on your network. Will be automatically discovered if you setup [the discovery component]({{site_root}}/components/discovery.html). Can also be forced to load by adding the following lines to your `home-assistant.conf`:
```
[chromecast]
```
## Services
### Media control services
Available services: `turn_off`, `volume_up`, `volume_down`, `media_play_pause`, `media_play`, `media_pause`, `media_next_track`
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | Target a specific chromecast. Defaults to all.
### Media play services
There are three services to start playing YouTube video's on the ChromeCast.
#### Service `chromecast/play_youtube_video`
Service to start playing a YouTube vide on the Chromecast.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | Target a specific chromecast. Defaults to all.
| `video` | no | YouTube video to be played, ie. `L0MK7qz13bU`
#### Service `chromecast/start_fireplace` and `chromecast/start_epic_sax`
Will either start a fireplace or Epic Sax Guy 10h on the Chromecast.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | Target a specific chromecast. Defaults to all.

View File

@ -0,0 +1,32 @@
---
layout: page
title: "Automating your lights"
description: "Instructions how to automate your lights with Home Assistant."
date: 2015-01-20 22:36
sidebar: false
comments: false
sharing: true
footer: true
---
Home Assistant has a built-in component called `device_sun_light_trigger` to help you automate your lights. The component will:
* Fade in the lights when the sun is setting and there are people home
* Turn on the lights when people get home after the sun has set
* Turn off the lights when all people leave the house
This component requires the components [sun]({{site_root/components/sun.html}}), [device_tracker]({{site_root}}/components/device_tracker.html) and [light]({{site_root}}/components/light.html) to be enabled.
To enable this component, add the following lines to your `home-assistant.conf`:
```
[device_sun_light_trigger]
# Specify a specific light/group of lights that has to be turned on
light_group=group.living_room
# Specify which light profile to use when turning lights on
light_profile=relax
# Disable lights being turned off when everybody leaves the house
disable_turn_off=1
```
The options `light_group`, `light_profile` and `disable_turn_off` are optional.

View File

@ -0,0 +1,38 @@
---
layout: page
title: "Device tracking"
description: "Instructions how to setup device tracking within Home Assistant."
date: 2015-01-20 22:36
sidebar: false
comments: false
sharing: true
footer: true
---
Home Assistant can get information from your wireless router to track which devices are connected. There are three different types of supported wireless routers: tomato, netgear and luci (OpenWRT). To get started add the following lines to your `home-assistant.conf` (example for Netgear):
```
[device_tracker]
platform=netgear
host=192.168.1.1
username=admin
password=MY_PASSWORD
```
<p class='note' data-title='on Tomato'>
Tomato requires an extra config variable called `http_id`. The value can be obtained by logging in to the Tomato admin interface and search for `http_id` in the page source code.
</p>
<p class='note' data-title='on Luci'>
Before the Luci scanner can be used you have to install the luci RPC package on OpenWRT: <code>opkg install luci-mod-rpc</code>.
</p>
Once tracking, the `device_tracker` component will maintain a file in your config dir called `known_devices.csv`. Edit this file to adjust which devices have to be tracked. Here you can also setup a url for each device to be used as the entity picture.
As an alternative to the router-based device tracking, it is possible to directly scan the network for devices by using nmap. The IP addresses to scan can be specified in any format that nmap understands, including the network-prefix notation (`192.168.1.1/24`) and the range notation (`192.168.1.1-255`).
```
[device_tracker]
platform=nmap_tracker
hosts=192.168.1.1/24
```

View File

@ -0,0 +1,26 @@
---
layout: page
title: "Discovery"
description: "Instructions how to setup Home Assistant to discover new devices."
date: 2015-01-24 14:39
sidebar: false
comments: false
sharing: true
footer: true
---
Home Assistant can discover and automatically configure zeroconf/mDNS and uPnP devices on your network. Currently the `discovery` component can detect:
* Google Chromecast
* Belkin WeMo switches
* Philips Hue
It will be able to add Google Chreomcasts and Belkin WeMo switches automatically, for Philips Hue it will require some configuration from the user.
To load this component, add the following lines to your `home-assistant.conf`:
```
[discovery]
```
If you are developing a new platform, please read [how to make your platform discoverable]({{site_root}}/developers/add_new_platform.html#discovery).

View File

@ -0,0 +1,28 @@
---
layout: page
title: "Downloader"
description: "Instructions how to setup the downloader component with Home Assistant."
date: 2015-01-24 14:39
sidebar: false
comments: false
sharing: true
footer: true
---
The `downloader` component provides a service to download files. It will raise an error and not continue to set itself up when the download directory does not exist.
To enable it, add the following lines to your `home-assistant.conf`:
```
[downloader]
download_dir=downloads
```
#### Service `downloader/download_file`
Download the specified url.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `url` | no | The url of the file to download.

View File

@ -9,97 +9,8 @@ sharing: true
footer: true
---
### sun
Tracks the state of the sun and when the next sun rising and setting will occur.
Home Assistant consists of the following built-in components:
Depends on: config variables common/latitude and common/longitude
* Maintains state of `weather.sun` including attributes `next_rising` and `next_setting`
### device_tracker
Keeps track of which devices are currently home.
* Sets the state per device and maintains a combined state called `all_devices`.
* Keeps track of known devices in the file `config/known_devices.csv`.
Supported platforms:
* `netgear` for Netgear routers that support their SOAP API
* `luci` for routers running OpenWRT
* `tomato` for routers running Tomato
* `nmap` for using nmap to scan IP ranges on the network
### light
Keeps track which lights are turned on and can control the lights. It has [4 built-in light profiles](https://github.com/balloob/home-assistant/blob/master/homeassistant/components/light/light_profiles.csv) which you're able to extend by putting a light_profiles.csv file in your config dir.
* Maintains a state per light and a combined state `all_light`.
* Registers services `light/turn_on` and `light/turn_off` to control the lights.
Optional service data:
- `entity_id` - only act on specified lights. Else targets all.
- `transition_seconds` - seconds to take to switch to new state.
- `profile` - which light profile to use.
- `xy_color` - two comma seperated floats that represent the color in XY
- `rgb_color` - three comma seperated integers that represent the color in RGB
- `brightness` - integer between 0 and 255 for how bright the color should be
- `flash` - tell light to flash, can be either value `short` or `long`
Supported platforms:
* `hue` for Philips Hue
### switch
Keeps track which switches are in the network, their state and allows you to control them.
* Maintains a state per switch and a combined state `all_switches`.
* Registers services `switch/turn_on` and `switch/turn_off` to control switches.
Optional service data:
- `entity_id` - only act on specific switch. Else targets all.
Supported platforms:
* `wemo` for Belkin WeMo switches
* `tellstick` for Tellstick switches
### device_sun_light_trigger
Turns lights on or off using a light control component based on state of the sun and devices that are home.
Depends on: light control, track_sun, device_tracker
* Turns lights off when all devices leave home.
* Turns lights on when a device is home while sun is setting.
* Turns lights on when a device gets home after sun set.
### chromecast
Registers 7 services to control playback on a Chromecast: `turn_off`, `volume_up`, `volume_down`, `media_play_pause`, `media_play`, `media_pause`, `media_next_track`.
Registers three services to start playing YouTube video's on the ChromeCast.
Service `chromecast/play_youtube_video` starts playing the specified video on the YouTube app on the ChromeCast. Specify video using `video` in service_data.
Service `chromecast/start_fireplace` will start a YouTube movie simulating a fireplace and the `chromecast/start_epic_sax` service will start playing Epic Sax Guy 10h version.
### keyboard
Registers services that will simulate key presses on the keyboard. It currently offers the following Buttons as a Service (BaaS): `keyboard/volume_up`, `keyboard/volume_down` and `keyboard/media_play_pause`
This actor depends on: PyUserInput
### downloader
Registers service `downloader/download_file` that will download files. File to download is specified in the `url` field in the service data.
### browser
Registers service `browser/browse_url` that opens `url` as specified in event_data in the system default browser.
### tellstick_sensor
Shows the values of that sensors that is connected to your Tellstick.
### simple_alarm
Will provide simple alarm functionality. Will flash a light shortly if a known device comes home. Will flash the lights red if the lights turn on while no one is home.
Depends on device_tracker, light.
Config options:
known_light: entity id of the light/light group to target to flash when a known device comes home
unknown_light: entity if of the light/light group to target when a light is turned on while no one is at home.
{% directory path:components exclude:index %}
* [{{ file.slug | replace: '_',' ' | capitalize }}]({{ file.slug | prepend: '/components/' | append: '.html' }})
{% enddirectory %}

View File

@ -0,0 +1,25 @@
---
layout: page
title: "Keyboard"
description: "Instructions how to simulate key presses with Home Assistant."
date: 2015-01-24 14:39
sidebar: false
comments: false
sharing: true
footer: true
---
The `keyboard` component simulates key presses on the host machine. It currently offers the following Buttons as a Service (BaaS):
* `keyboard/volume_up`
* `keyboard/volume_down`
* `keyboard/volume_mute`
* `keyboard/media_play_pause`
* `keyboard/media_next_track`
* `keyboard/media_prev_track`
To load this component, add the following lines to your `home-assistant.conf`:
```
[keyboard]
```

View File

@ -0,0 +1,54 @@
---
layout: page
title: "Lights"
description: "Instructions how to setup your lights with Home Assistant."
date: 2015-01-24 14:39
sidebar: false
comments: false
sharing: true
footer: true
---
This component allows you to track and control various light bulbs.
It has [4 built-in light profiles](https://github.com/balloob/home-assistant/blob/master/homeassistant/components/light/light_profiles.csv) which you're able to extend by putting a `light_profiles.csv` file in your config dir.
It supports the following platforms:
* `hue` for Philips Hue
* `wink` for Wink
Preferred way to setup the Philips Hue platform is through the [the discovery component]({{site_root}}/components/discovery.html). For the Wink light platform enable [the wink component]({{site_root}}/components/wink.html).
If you really feel like enabling the light component directly, add the following lines to your `home-assistant.conf`:
```
[light]
platform=hue
```
<p class='note'>
The light component supports multiple entries in <code>home-assistant.conf</code> by appending a sequential number to the section: <code>[light 2]</code>, <code>[light 3]</code> etc.
</p>
### Service `light.turn_on`
Turns one or multiple lights on.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | Only act on specified lights. Else targets all.
| `transition_seconds` | no | Seconds to take to switch to new state.
| `profile` | no | Which light profile to use.
| `xy_color` | no | Two comma seperated floats that represent the color in XY
| `rgb_color` | no | Three comma seperated integers that represent the color in RGB
| `brightness` | no | Integer between 0 and 255 for how bright the color should be
| `flash` | no | Tell light to flash, can be either value `short` or `long`
### Service `light.turn_off`
Turns one or multiple lights off.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | Only act on specified lights. Else targets all.

View File

@ -0,0 +1,41 @@
---
layout: page
title: "Notifications"
description: "Instructions how to add user notifications to Home Assistant."
date: 2015-01-20 22:36
sidebar: false
comments: false
sharing: true
footer: true
---
One of the things most people want at some point in their home automation is to get notified when certain events occur. For this reason there is a `notify` component in Home Assistant.
Home Assistant currently supports the awesome [PushBullet](https://www.pushbullet.com/), a free service to send information between your phones, browsers and friends.
To add PushBullet to your installation, add the following to your `home-assistant.conf` file:
```
[notify]
platform=pushbullet
api_key=YOUR_API_KEY
```
### Automation example
Notifications are great to be used within Home Automation. Below is a an example configuration that you can add to your `home-assistant.conf` to be notified when the sun sets.
```
[automation]
alias=Sun set notification
platform=state
state_entity_id=sun.sun
state_from=above_horizon
state_to=below_horizon
execute_service=notify.notify
service_data={"message":"YAY"}
```
For more automation examples, see the [getting started with automation page]({{site_root}}/components/automation.html).

View File

@ -0,0 +1,24 @@
---
layout: page
title: "Intruder Alerts"
description: "Instructions how to receive intruder alerts from Home Assistant."
date: 2015-01-20 22:36
sidebar: false
comments: false
sharing: true
footer: true
---
The component `simple_alarm` is capable of detecting intruders. It does so by checking if lights are being turned on while there is no one at home. When this happens it will turn the lights red, flash them for 30 seconds and send a message via [the notifiy component]({{site_root}}/components/notify.html). It will also flash a specific light when a known person comes home.
This component depends on the compoments [device_tracker]({{site_root}}/components/device_tracker.html) and [light]({{site_root}}/components/light.html) being setup.
To set it up, add the following lines to your `home-assistant.conf`:
```
[simple_alarm]
# Which light/light group has to flash when a known device comes home
known_light=light.Bowl
# Which light/light group has to flash red when light turns on while no one home
unknown_light=group.living_room
```

View File

@ -0,0 +1,40 @@
---
layout: page
title: "Tracking the Sun"
description: "Instructions how to track the sun within Home Assistant."
date: 2015-01-24 14:39
sidebar: false
comments: false
sharing: true
footer: true
---
The `sun` component will use your current location to track if the sun is above or below the horizon. This is a common ingredient within Home Automation.
To set it up, add the following lines to your `home-assistant.conf`:
```
[homeassistant]
latitude=32.87336
longitude=-117.22743
```
<p class='img'>
<img src='{{site_root}}/images/screenshots/more-info-dialog-sun.png' />
</p>
### Implementation Details
#### Maintains entity `sun.sun`.
| Possible state | Description |
| --------- | ----------- |
| `above_horizon` | When the sun is above the horizon.
| `below_horizon` | When the sun is below the horizon.
| State Attributes | Description |
| --------- | ----------- |
| `next_rising` | Date and time of the next sun rising
| `nest_setting` | Date and time of the next sun setting

View File

@ -0,0 +1,24 @@
---
layout: page
title: "Lights"
description: "Instructions how to setup your lights with Home Assistant."
date: 2015-01-24 14:39
sidebar: false
comments: false
sharing: true
footer: true
---
Keeps track which switches are in the network, their state and allows you to control them.
* Maintains a state per switch and a combined state `all_switches`.
* Registers services `switch/turn_on` and `switch/turn_off` to control switches.
Optional service data:
- `entity_id` - only act on specific switch. Else targets all.
Supported platforms:
* `wemo` for Belkin WeMo switches
* `tellstick` for Tellstick switches

View File

@ -0,0 +1,22 @@
---
layout: page
title: "Tellstick Sensors"
description: "Instructions how to setup tellstick sensors with Home Assistant."
date: 2015-01-24 14:39
sidebar: false
comments: false
sharing: true
footer: true
---
Shows the values of that sensors that is connected to your Tellstick.
To enable it, add the following lines to your `home-assistant.conf`:
```
[tellstick_sensor]
```
<p class='note warning'>
This component is going to be merged into the sensor component.
</p>

View File

@ -0,0 +1,25 @@
---
layout: page
title: "Adding thermostats"
description: "Instructions how to setup thermostats tracking within Home Assistant."
date: 2015-01-20 22:36
sidebar: false
comments: false
sharing: true
footer: true
---
Thermostats offer Home Assistant a peek into the current and target temperature in a house. Some thermostats will also offer an away mode that will lower use of heating/cooling. The only supported thermostat right now is the Nest thermostat.
To set it up, add the following information to your `home-assistant.conf` file:
```
[thermostat]
platform=nest
username=myemail@mydomain.com
password=mypassword
```
<p class='img'>
<img src='{{site_root}}/images/screenshots/nest-thermostat-card.png' />
</p>

View File

@ -0,0 +1,34 @@
---
layout: page
title: "Wink hub"
description: "Instructions how to setup the Wink hub within Home Assistant."
date: 2015-01-20 22:36
sidebar: false
comments: false
sharing: true
footer: true
---
Wink is a home automation hub that can control a whole wide range of devices on the market. Or, as they say in their own words:
<blockquote>Wink offers one, quick and simple way to connect people with the products they rely on every day in their home.</blockquote>
Home Assistant integrates the Wink hub and allows you to get the status and control connected switches, lights and sensors.
To get started with the Wink API, you will first need to get yourself an API access token. Because it is very difficult right now to get access to their API, John McLaughlin has created the form below to get you one.
<iframe src="https://winkbearertoken.appspot.com"
style='width: 100%; height: 200px; border: 0; margin: 0 auto 15px; border-left: 2px solid #049cdb; padding-left: 15px;'></iframe>
After you have gotten your access token, add the following to your `home-assitant.conf`:
```
[wink]
access_token=YOUR_ACCESS_TOKEN
```
This will connect to the Wink hub and automatically set up any lights, switches and sensors that it finds.
<p class='note'>
The Wink hub can only be accessed via the cloud. This means it requires an active internet connection and you will experience delays when controlling devices (~3s) and getting an updated device state (~15s).
</p>

View File

@ -10,7 +10,20 @@ footer: true
---
Home Assistant offers [built-in components]({{site_root}}/components/) but it
is easy to built your own.
is easy to built your own. If you are the kind of person that likes to learn from code rather then guide then head over to the [`config/custom_compnents`](https://github.com/balloob/home-assistant/tree/master/config/custom_components) folder in the repository for two example components.
The first is [hello_world.py](https://github.com/balloob/home-assistant/blob/master/config/custom_components/hello_world.py), which is the classic Hello World example for Home Assistant. The second one is [example.py](https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py) which showcases various ways you can tap into Home Assistant to be notified when certain events occur.
If you want to load these components in Home Assistant, add the following lines to your `home-assistant.conf` file:
```
[hello_world]
[example]
target=TARGET_ENTITY
```
`TARGET_ENTITY` should be one of your devices that can be turned on and off, ie a light or a switch. Example value could be `light.Ceiling` or `switch.AC` (if you have these devices with those names).
## Loading components

View File

@ -9,76 +9,80 @@ sharing: true
footer: true
---
Installing Home Assistant and running it is easy. Make sure you have [Python 3](https://www.python.org/downloads/) installed and execute the following code in your console:
Installing and running Home Assistant is easy. Make sure you have [Python 3.4](https://www.python.org/downloads/) and [git](http://git-scm.com/downloads) installed and execute the following code in a console:
```bash
git clone --recursive https://github.com/balloob/home-assistant.git
cd home-assistant
pip3 install -r requirements.txt
python3 -m homeassistant
python3 -m pip install -r requirements.txt
python3 -m homeassistant --open-ui
```
This will start the Home Assistant server and create an initial configuration file `config/home-assistant.conf` that is setup for demo mode. It will launch its web interface on [http://127.0.0.1:8123](http://127.0.0.1:8123). The default password is 'password'.
Running these commands will:
1. Download Home Assistant
2. Navigate to downloaded files
3. Install the dependencies
4. Launch Home Assistant and serve web interface on [http://localhost:8123](http://localhost:8123)
If you run into any issues, please see the [troubleshooting page]({{site_root}}/getting-started/troubleshooting.html).
<p class='note'>
You can run Home Assistant in demo mode by appending <code>--demo-mode</code> to line 4.
</p>
<p class='note'>
If you want to update to the latest version in the future, run: <code>scripts/update</code>.
</p>
If you're using Docker, you can use
```bash
docker run -d --name="home-assistant" -v /path/to/homeassistant/config:/config -v /etc/localtime:/etc/localtime:ro --net=host balloob/home-assistant
```
After you got the demo mode running it is time to customize your configuration and enable some [built-in components]({{site_root}}/components/). See [`/config/home-assistant.conf.example`](https://github.com/balloob/home-assistant/blob/master/config/home-assistant.conf.example) for an example configuration.
## Configuring Home Assistant
The configuration for Home Assistant lives by default in the `config` folder. The file `home-assistant.conf` is the main file that contains which components will be loaded and what their configuration is. An example configuration file is located at [`config/home-assistant.conf.example`](https://github.com/balloob/home-assistant/blob/master/config/home-assistant.conf.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.
<p class='note'>
You will have to restart Home Assistant for changes in <code>home-assistant.conf</code> to take effect.
</p>
### Password protecting the web interface
The first thing you want to add is a password for the web interface. Use your favourite text editor to open the file `/config/home-assistant.conf`. Look for the line that says `[http]` and add the line `api_password=YOUR_PASSWORD` below. Your configuration should now look like this:
```
[http]
api_password=YOUR_PASSWORD
[discovery]
```
<p class='note'>
You can append <code>?api_password=YOUR_PASSWORD</code> to any url to log in automatically.
</p>
<p class='note'>
For the light and switch component, you can specify multiple platforms by using sequential sections: [switch], [switch 2], [switch 3] etc
</p>
### Adding devices and services
### Philips Hue
To get Philips Hue working you will have to connect Home Assistant to the Hue bridge.
Home Assistant will be able to automatically discover and configure any Google Chromecasts, Belkin WeMo switches and Philips Hue bridges in your network if you have [the discovery component]({{site_root}}/components/discovery.html) enabled (which is by default).
Run the following command from your config dir and follow the instructions:
Not all devices can be discovered, so if you hae any of the following devices or services, please see their respective pages for installation instructions:
```bash
python3 -m phue --host HUE_BRIDGE_IP_ADDRESS --config-file-path phue.conf
```
* [Nest thermostat]({{site_root}}/components/thermostat.html)
* [Wink hub]({{site_root}}/components/wink.html)
* [PushBullet]({{site_root}}/components/notify.html)
* [Device tracking]({{site_root}}/components/device_tracker.html)
* [Sun]({{site_root}}/components/sun.html)
* [Add support for your own device or service]({{site_root}}/developers/add_new_platform.html)
After that add the following lines to your `home-assistant.conf`:
### Setting up Home Automation
```
[light]
platform=hue
```
When all your devices are set up it's time to put the cherry on the pie: automation. There are many ways to automate your home with Home Assistant so we have divided it into a couple of topics:
### Wireless router
Your wireless router is used to track which devices are connected. Three different types of wireless routers are currently supported: tomato, netgear and luci (OpenWRT). To get started add the following lines to your `home-assistant.conf` (example for Netgear):
```
[device_tracker]
platform=netgear
host=192.168.1.1
username=admin
password=MY_PASSWORD
```
<p class='note' data-title='on Tomato'>
Tomato requires an extra config variable called `http_id`. The value can be obtained by logging in to the Tomato admin interface and search for `http_id` in the page source code.
</p>
<p class='note' data-title='on Luci'>
Before the Luci scanner can be used you have to install the luci RPC package on OpenWRT: <code>opkg install luci-mod-rpc</code>.
</p>
Once tracking, the `device_tracker` component will maintain a file in your config dir called `known_devices.csv`. Edit this file to adjust which devices have to be tracked. Here you can also setup a url for each device to be used as the entity picture.
As an alternative to the router-based device tracking, it is possible to directly scan the network for devices by using nmap. The IP addresses to scan can be specified in any format that nmap understands, including the network-prefix notation (`192.168.1.1/24`) and the range notation (`192.168.1.1-255`).
```
[device_tracker]
platform=nmap_tracker
hosts=192.168.1.1/24
```
* [Automatic light control based on the sun and if people are home]({{site_root}}/components/device_sun_light_trigger.html) (built-in component)
* [Intruder alerts]({{site_root}}/components/simple_alarm.html) (built-in component)
* [Setup your own automation rules]({{site_root}}/components/automation.html) (using configuration file)
* [Create your own automation component]({{site_root}}/developers/creating_components.html) (writing Python code)

View File

@ -0,0 +1,18 @@
---
layout: page
title: "Troubleshooting"
description: "Common problems and their solutions."
date: 2015-01-20 22:36
sidebar: false
comments: false
sharing: true
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.
Check if Python3 is installed by running `python3 --version`. If it is not installed, install it here.
Pip should come bundled with the latest Python3 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 Python3: `python3 get-pip.py`.
Check if Git is installed by running `git --version`. If you are unable to run this command you can install it by following [these instructions](http://git-scm.com/downloads).

Binary file not shown.

After

Width:  |  Height:  |  Size: 33 KiB