mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-24 17:57:14 +00:00
Reorganize the getting started and component pages
This commit is contained in:
Paulus Schoutsen
parent
e134f73933
commit
759d107680
113
plugins/directory_tag.rb
Normal file
113
plugins/directory_tag.rb
Normal 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)
|
||||
@ -58,6 +58,10 @@ article.post, article.page, article.listing {
|
||||
li {
|
||||
margin-bottom: 10px;
|
||||
|
||||
& > p {
|
||||
margin-bottom: 0;
|
||||
}
|
||||
|
||||
&:last-child {
|
||||
margin-bottom: 0;
|
||||
}
|
||||
|
||||
138
source/components/automation.markdown
Normal file
138
source/components/automation.markdown
Normal 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>
|
||||
24
source/components/browser.markdown
Normal file
24
source/components/browser.markdown
Normal 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
|
||||
49
source/components/chromecast.markdown
Normal file
49
source/components/chromecast.markdown
Normal 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.
|
||||
32
source/components/device_sun_light_trigger.markdown
Normal file
32
source/components/device_sun_light_trigger.markdown
Normal 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.
|
||||
38
source/components/device_tracker.markdown
Normal file
38
source/components/device_tracker.markdown
Normal 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
|
||||
```
|
||||
26
source/components/discovery.markdown
Normal file
26
source/components/discovery.markdown
Normal 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).
|
||||
28
source/components/downloader.markdown
Normal file
28
source/components/downloader.markdown
Normal 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.
|
||||
|
||||
@ -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 %}
|
||||
|
||||
25
source/components/keyboard.markdown
Normal file
25
source/components/keyboard.markdown
Normal 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]
|
||||
```
|
||||
54
source/components/light.markdown
Normal file
54
source/components/light.markdown
Normal 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.
|
||||
41
source/components/notify.markdown
Normal file
41
source/components/notify.markdown
Normal 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).
|
||||
24
source/components/simple_alarm.markdown
Normal file
24
source/components/simple_alarm.markdown
Normal 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
|
||||
```
|
||||
40
source/components/sun.markdown
Normal file
40
source/components/sun.markdown
Normal 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
|
||||
24
source/components/switch.markdown
Normal file
24
source/components/switch.markdown
Normal 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
|
||||
22
source/components/tellstick_sensor.markdown
Normal file
22
source/components/tellstick_sensor.markdown
Normal 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>
|
||||
25
source/components/thermostat.markdown
Normal file
25
source/components/thermostat.markdown
Normal 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>
|
||||
34
source/components/wink.markdown
Normal file
34
source/components/wink.markdown
Normal 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>
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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)
|
||||
|
||||
18
source/getting-started/troubleshooting.markdown
Normal file
18
source/getting-started/troubleshooting.markdown
Normal 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).
|
||||
BIN
source/images/screenshots/more-info-dialog-sun.png
Normal file
BIN
source/images/screenshots/more-info-dialog-sun.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
Loading…
x
Reference in New Issue
Block a user