jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-25 18:26:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

Added blog post, updated styles

Browse Source
This commit is contained in:
Paulus Schoutsen 2014-12-26 00:03:31 -08:00
parent f3cc5e337b
commit 3579458b40
24 changed files with 206 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Gemfile
View File

@ -14,6 +14,7 @@ group :development do
gem 'rubypants', '~> 0.2.0'
gem 'rb-fsevent', '~> 0.9'
gem 'stringex', '~> 1.4.0'
gem 'jekyll-time-to-read'
end
gem 'sinatra', '~> 1.4.2'

3
_config.yml
View File

@ -42,6 +42,9 @@ rdiscount:
- smart
highlighter: pygments # default python pygments have been replaced by pygments.rb
gems:
- jekyll-time-to-read
paginate: 10 # Posts per page on the blog index
paginate_path: "blog/posts/:num" # Directory base for pagination URLs eg. /posts/2/
recent_posts: 5 # Posts in the sidebar Recent Posts section

71
sass/custom/_paulus.scss
View File

@ -25,7 +25,7 @@
}
}
article.post, article.page {
article.post, article.page, article.listing {
img, table {
border-radius: 3px;
box-shadow: rgba(0,0,0,0.06) 0 0 10px;
@ -39,46 +39,65 @@ article.post, article.page {
& > table {
background-color: #F3FCF5;
}
p.img {
background-color: #FFF;
border-radius: 5px;
text-align: center;
padding-bottom: 3px;
font-size: .9rem;
box-shadow: rgba(0,0,0,0.06) 0 0 10px;
img {
display: block;
box-shadow: none;
margin: 0 auto;
}
}
li {
margin-bottom: 10px;
&:last-child {
margin-bottom: 0;
}
}
}
.note {
p.note {
position: relative;
background: #e7f2fa;
padding: 12px;
margin-bottom: 24px;
padding: 40px 12px 6px 12px;
box-shadow: rgba(0,0,0,0.06) 0 0 10px;
.title::before {
&::before {
font-family: "FontAwesome";
content: "\f05a";
margin-right: 5px;
}
content: "\f05a" " Note " attr(data-title);
background-color: #6ab0de;
color: white;
font-weight: bold;
.title {
border-top-left-radius: 3px;
border-top-right-radius: 3px;
font-weight: bold;
display: block;
color: #fff;
background: #6ab0de;
margin: -12px;
padding: 6px 12px;
margin-bottom: 12px;
box-sizing: border-box;
}
padding: 6px 14px;
.content {
margin-bottom: 0;
line-height: 1.5em;
position: absolute;
top: 0;
left: 0;
right: 0;
}
&.warning {
background-color: #F7F9E1;
.title {
&::before {
background-color: rgb(187, 185, 13);;
}
.title::before {
content: "\f071";
content: "\f071" " Warning " attr(data-title);
}
}
}
}

3
sass/oscailte/base/_global.scss
View File

@ -40,7 +40,8 @@ a {
}
article.post,
article.page {
article.page,
article.listing {
img {
border: 5px solid #fff;
border-radius: 3px;

3
sass/oscailte/base/_post.scss
View File

@ -70,7 +70,8 @@ article {
font-size: 12px;
padding: 0 0 5px;
> * {
margin-right: 20px;
margin-right: 15px;
white-space: nowrap;
&:last-child {
margin-right: 0;

9
source/_includes/blog/post/article.html
View File

@ -11,10 +11,11 @@
<div class="meta clearfix">
{% include blog/post/date.html %}{{ time }}
{% include post/author.html %}
{% include post/time_to_read.html %}
{% include blog/post/tags.html %}
{% if site.disqus_short_name and page.comments != false and post.comments != false and site.disqus_show_comment_count == true %}
<a class="pull-right" href="{% if index %}{{ root_url }}{{ post.url }}{% endif %}#disqus_thread">
Comments <i class="icon-comment"></i>
<a href="{% if index %}{{ root_url }}{{ post.url }}{% endif %}#disqus_thread">
<i class="icon-comment"></i> Comments
</a>
{% endif %}
</div>
@ -26,8 +27,8 @@
{% if excerpted == 'true' and index %}
<div class="entry-content clearfix">
{{ content | excerpt }}
<a class="btn pull-right" href="{{ root_url }}{{ post.url }}">{{ site.excerpt_link }}</a>
<a class="btn pull-right" href="{{ root_url }}{{ post.url }}#read-more">{{ site.excerpt_link }}</a>
</div>
{% else %}
{{ content }}
{{ content | replace: site.excerpt_separator, '<a name="read-more"></a>' }}
{% endif %}

1
source/_includes/post/time_to_read.html Normal file
View File

@ -0,0 +1 @@
<span><i class='icon-time'></i> {{ content | reading_time_as_s }} reading time</span>

2
source/_layouts/post.html
View File

@ -9,7 +9,7 @@ is_post: true
{% if site.disqus_short_name and page.comments == true %}
<section id="disqus">
<h1 class="indent title">Comments</h1>
<h3 class="indent title">Comments</h3>
<div id="disqus_thread" aria-live="polite">{% include blog/post/disqus_thread.html %}</div>
</section>
{% endif %}

1
source/_posts/2014-12-18-website-launched.markdown
View File

@ -5,7 +5,6 @@ date: 2014-12-18 23:24:45 -0800
date_formatted: "December 18, 2014"
comments: true
categories: website
author: "Paulus Schoutsen"
---
I finally took the time to setup a simple website to help people getting started with Home Assistant. The process was super smooth thanks to the great tools [Jekyll](http://jekyllrb.com) and [Octopress](http://octopress.org) and the great services [GitHub Pages](https://pages.github.com) and [CloudFlare](https://cloudflare.com).

67
source/_posts/2014-12-25-home-control-home-automation-and-the-smart-home.markdown Normal file
View File

@ -0,0 +1,67 @@
---
layout: post
title: "Home Control, Automation &amp; the Smart Home"
date: 2014-12-25 10:23:13 -0800
date_formatted: December 25, 2014
comments: true
categories:
---
The internet has been buzzing over the last year about home automation. A lot of different terms fly around like the internet of things, home automation and the smart home.
This article will try to explain how they all relate.
The first thing to introduce is the **Internet of Things** (IoT). This refers to a new generation of devices that cannot only be controlled by humans via buttons or remotes but also provide an interface to communicate with other devices and applications. For example, an IoT-capable coffee machine could receive commands to create different types of coffee and be able to broadcast the amount of water left in its resevoir.
There is no widely adopted open standard for smart device communication. This prevents a lot of devices to communicate with one another. And even if they could, most devices are not designed to manage other devices. To solve this we need a device to be able to communicate with and manage all these connected devices. This device is called a **hub**.
As a bare minimum a hub has to keep track of the state of each device and should be able to control them if possible. For example, it has to know which lights are on or off and offer a way to control the lights. For a sensor it only has to know the value. A hub with these capabilities offers **home control**.
<p class='img'>
<a href='{{site_root}}/images/screenshots/nexus_7_dashboard.png'>
<img alt='Hub dashboard example'
src='{{site_root}}/images/screenshots/nexus_7_dashboard.png' />
</a>
Example of a hub's dashboard. Showing the state of 2 persons, 4 lights and the sun.
</p>
<!--more-->
A step up from home control is to have the user setup triggers to send commands based on information in the home control layer. For example, to turn on the lights when a person arrives home. A hub with these capabilities is capable of **home automation**.
Most hubs on the market today offer this in various degrees of functionality and usability. Some IoT-capable devices offer this too, but only control themselves and are usually limited to location and time-based events.
The last category, and this is still very much in the future, is the **smart home**. A self-learning and adopting system that will decide which events should impact other devices.
An example of a smart home in action is that it observes that when person A comes home, the lights in the living room and the kitchen switch on. While if person B comes home, the lights in the living room and the study room are switched on. The next time person A or B comes home, the smart home will turn on its preferred lights without any configuration being set by the user.
A glimpse today at how the future can look is the [Nest thermostat](https://nest.com/). A thermostat smart enough to learn your schedule and adjust its own temperature accordingly.
All this results in the following overview of Home Automation.
<p class='img'>
<a href='{{site_root}}/images/architecture/home_automation_landscape.png'>
<img alt='Home Automation landscape'
src='{{site_root}}/images/architecture/home_automation_landscape.png' />
</a>
Overview of the home automation landscape.
</p>
### Challenges
You are probably wondering, this all seems relatively simple, why don't I have my very own smart home yet? There are a couple of challenges today that keep us from stepping into the future.
#### More Internet of Things-capable devices
The majority of the IoT products out there are either lights, switches or presence detection. That's not enough for your home to be very smart about. We need televisions, fridges, ovens and more to join the party to increase the number of devices that we can control.
#### More data
Most first generation IoT devices are only exposing information that is needed for controlling it. We need to be able to track all interactions with each device for our smart home to learn how interaction with devices influence other things. For example, we need to be able to track how many cups of coffee were made or how often the fridge was open. This will increase the information flow and open up a whole bunch of new possibilities. For example, the smart home can order new coffee when you're running low.
#### Easy to use, open software that we can trust
To increase adoption we will need people to trust their smart home system. It will be very tought to convince people to upgrade all their devices and upload all interactions with each of them to the cloud. This data could reveal their whole life including all bad habits. That's why such a system should be simple and open-source so people can validate that their data generated at home stay home.
Anoter important booster for adoption is that the software should be easy to set up and use by the average user. A lot of people are not burning their hands yet on Home Automation because they are scared of having to configure it all.
Home Assistant is trying to be this software. It is not there yet but trying hard. Device discovery and a user interface for configuring home automation are problems we hope to tackle in 2015 while not sacrificing modularity or usability.
Happy new year!

1
source/blog/index.html
View File

@ -1,5 +1,6 @@
---
layout: default
sidebar: false
---
{% assign index = true %}
{% for post in paginator.posts %}

2
source/components/index.markdown
View File

@ -3,7 +3,7 @@ layout: page
title: "Components"
date: 2014-12-21 13:35
sidebar: false
comments: true
comments: false
sharing: true
footer: true
---

6
source/developers/add_new_platform.markdown
View File

@ -3,7 +3,7 @@ layout: page
title: "Adding support for a new platform"
date: 2014-12-21 13:27
sidebar: false
comments: true
comments: false
sharing: true
footer: true
---
@ -20,6 +20,6 @@ For example, the built-in `switch` component consists of the following files in
If you are planning to add support for a new type of device to an existing component, you can get away with only writing platform logic. Have a look at how the component works with other platforms and create a similar file for the platform that you would like to add.
<div class='note'><p class='title'>Note</p><p class='content'>
<p class='note'>
Platform logic should not interface directly with the devices but use a third-party Python 3 library that speaks the actual API.
</p></div>
</p>

14
source/developers/api.markdown
View File

@ -3,7 +3,7 @@ layout: page
title: "Rest API"
date: 2014-12-21 13:27
sidebar: false
comments: true
comments: false
sharing: true
footer: true
---
@ -17,9 +17,9 @@ In the package [`homeassistant.remote`](https://github.com/balloob/home-assistan
The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header `X-HA-Access: YOUR_PASSWORD` (as specified in your `home-assistant.conf`).
<div class='note'><p class='title'>Note</p><p class='content'>
<p class='note'>
You can append <code>?api_password=YOUR_PASSWORD</code> to any url to log in automatically.
</p></div>
</p>
Successful calls will return status code 200 or 201. Other status codes that can return are:
@ -193,9 +193,9 @@ Returns a list of states that have changed while the service was being executed.
]
```
<div class='note'><p class='title'>Note</p><p class='content'>
<p class='note'>
The result will include any changed states that changed while the service was being executed, even if their change was the result of something else happening in the system.
</p></div>
</p>
#### POST /api/event_forwarding
Setup event forwarding to another Home Assistant instance.
@ -239,6 +239,6 @@ It will return a message if event forwarding was cancelled successful.
}
```
<div class='note'><p class='title'>Note</p><p class='content'>
<p class='note'>
If your client does not support <code>DELETE</code> HTTP requests you can add an optional attribute <code>_METHOD</code> and set its value to <code>DELETE</code>.
</p></div>
</p>

66
source/developers/architecture.markdown
View File

@ -3,28 +3,55 @@ layout: page
title: "Architecture"
date: 2014-12-18 21:49
sidebar: false
comments: true
comments: false
sharing: true
footer: true
---
<a href='{{ root_url }}/images/ha_architecture.png'>
<img src='{{ root_url }}/images/ha_architecture.png' class='no-shadow' />
</a>
Before we dive into the Home Assistant architecture, it is important to get a clear overview of the home automation landscape as a whole. This will allow us to show how the different parts of Home Assistant fit in the picture. For a more lengthy discussion about what each part in this overview is responsible for, <a href='{{ root_url }}/blog/2014/12/25/home-control-home-automation-and-the-smart-home/'>check out our blog</a>. A tl;dr version of the blog:
The core of Home Assistant exists of the following parts.
* Home Control is responsible for collecting information on- and controlling devices.
* Home Automation triggers commands based on user configurations.
* Smart Home triggers commands based on previous behavior.
The **Event Bus** facilitates the firing and listening of events. This is the beating heart of Home Assistant.
<p class='img'>
<a href='{{site_root}}/images/architecture/home_automation_landscape.png'>
<img alt='Home Automation landscape'
src='{{site_root}}/images/architecture/home_automation_landscape.png' />
</a>
Overview of the home automation landscape.
</p>
The **State Machine** keeps track of the states of things. Fires a state_changed event when a state has been changed.
The core of Home Assistant is responsible for the Home Control part and is made up:
The **Service Registry** listens on the event bus for call_service events and allows other code to register services.
* The **Event Bus** facilitates the firing and listening of events. This is the beating heart of Home Assistant.
* The **State Machine** keeps track of the states of things. Fires a `state_changed` event when a state has been changed.
* The **Service Registry** listens on the event bus for `call_service` events and allows other code to register services.
* The **Timer** will send every 10 seconds a `time_changed` event on the event bus.
The **Timer** will send every 10 seconds a time_changed event on the event bus.
<p class='img'>
<a href='{{ root_url }}/images/architecture/ha_architecture.png'>
<img src='{{ root_url }}/images/architecture/ha_architecture.png' />
</a>
Overview of the Home Assistant architecture
</p>
Take for example the device_tracker component. This component is responsible for keeping track which devices are home. It checks which devices are home every time a time_changed event is fired on the event bus. It will then update the state machine with the information for each device.
Home Assistant can be extended by **components**. Each component is responsible for a specific domain within Home Assistant. Components can listen for- or trigger events, offer services and maintain states. Components are written in Python and can do all the goodness that Python has to offer. Out of the box, Home Assistant offers a bunch of [built-in components]({{site_root}}/components/).
This setup allows us to create simple yet powerful logic for controlling your home:
We can differentiate between two different types of
components within Home Assistant.
#### Components that interact with an Internet of Things domain
These components will track devices within a specific domain and make this information available via the State Machine and the Event Bus. The component will also register services in the Service Registry to expose control of the devices. Each of these components exist of a core part and small pieces of platform specific logic.
For example, one of the built-in components is the `switch` component. This component is responsible for interaction with different types of switches.
If you are planning to add support for a new platform, please check out the [add new platform section]({{root_url}}/developers/add_new_platform.html).
#### Components that respond to events that happen within Home Assistant
These components provide small pieces of home automation logic or services that do common tasks within your house.
For example the `device_sun_light_trigger` component tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and there are people home. The component uses logic along the following lines:
In the event that device 'Paulus Nexus 5' changes to the 'Home' state:
If the sun has set and the lights are not on:
@ -42,15 +69,18 @@ This setup allows us to create simple yet powerful logic for controlling your ho
If the lights are off and the combined state of all tracked device equals 'Home':
Turn on the lights
By using the Bus as a central communication hub between components it is easy to replace components or add functionality. If you would want to change the way devices are detected you only have to write a component that updates the device states in the State Machine.
Another example of a home automation component can be found in [`/config/custom_components/example.py`](https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py).
## Multiple connected instances
Home Assistant supports running multiple synchronzied instances using a master-slave model. Slaves forward all local events fired and states set to the master instance which will then replicate it to each slave.
Home Assistant supports running multiple synchronzied instances using a master-slave model. Slaves forward all local fired events and set states to the master instance which will then replicate it to each slave.
<a href='{{ root_url }}/images/architecture-remote.png'>
<img src='{{ root_url }}/images/architecture-remote.png' class='no-shadow' />
</a>
<p class='img'>
<a href='{{ root_url }}/images/architecture/architecture-remote.png'>
<img src='{{ root_url }}/images/architecture/architecture-remote.png' />
</a>
Overview of the Home Assistant architecture for multiple devices.
</p>
A slave instance can be started with the following code and has the same support for components as a master-instance.
@ -68,6 +98,6 @@ hass.start()
hass.block_till_stopped()
```
<div class='note'><p class='title'>Note</p><p class='content'>
<p class='note'>
Because each slave maintains its own ServiceRegistry it is possible to have multiple slaves respond to one service call.
</p></div>
</p>

34
source/developers/creating_components.markdown
View File

@ -3,7 +3,7 @@ layout: page
title: "Creating components"
date: 2014-12-21 13:32
sidebar: false
comments: true
comments: false
sharing: true
footer: true
---
@ -11,30 +11,6 @@ footer: true
Home Assistant offers [built-in components]({{site_root}}/components/) but it
is easy to built your own.
Each component is responsible for a specific domain within Home Assistant.
Components can listen for- or trigger events, offer services and maintain
states. Components are written in Python and can do all the goodness that
Python has to offer.
We can differentiate between two different types of
components within Home Assistant.
#### Components that interact with devices
These components are keeping track of devices within a specific domain. It will also provide services to control those devices.
For example, one of the built-in components is the `switch` component. This component is responsible for interaction with different types of switches.
If you are planning on adding support for a new platform, do not forget to check out the [add new platform section]({{root_url}}/developers/add_new_platform.html).
#### Components that respond to events that happen within Home Assistant
These components can provide automation logic or services that do common tasks within your house.
For example the `device_sun_light_trigger` component tracks the state of
devices and the sun to make sure that the lights are turned on when it gets
dark and there are people home.
An example of such a component can be found in [`/config/custom_components/example.py`](https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py).
## Loading components
A component will be loaded on start if a section (ie. `[light]`) for it exists in the config file. A component can also be loaded if another component is loaded that depends on it. When loading a component Home Assistant will check the following paths:
@ -44,13 +20,13 @@ A component will be loaded on start if a section (ie. `[light]`) for it exists i
Once loaded, a component will only be setup if all dependencies can be loaded and are able to setup. Keep an eye on the logs to see if your component could be loaded and initialized.
<div class='note warning'><p class='title'>Warning</p><p class='content'>
<p class='note warning'>
You can override a built-in component by having a component with the same name in your <code>config/custom_components</code> folder. This is not recommended and will probably break things!
</p></div>
</p>
<div class='note'><p class='title'>Note</p><p class='content'>
<p class='note'>
Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the <code>config</code> folder in your current work directory. You can use a different folder by running Home Assistant with the --config argument: <code>python3 homeassistant --config /YOUR/CONFIG/PATH/</code>.
</p></div>
</p>
## Initializing components

6
source/developers/frontend.markdown
View File

@ -3,7 +3,7 @@ layout: page
title: "Frontend development"
date: 2014-12-21 13:32
sidebar: false
comments: true
comments: false
sharing: true
footer: true
---
@ -21,9 +21,9 @@ development=1
After turning on development mode, you will have to install the webcomponents that the frontend depends on. You can do this by running the `build_frontend` script.
<div class='note warning'><p class='title'>Warning</p><p class='content'>
<p class='note warning'>
Do not use development mode in production. Home Assistant uses aggresive caching to improve the mobile experience. This is disabled during development so that you do not have to restart the server in between changes.
</p></div>
</p>
# Building the frontend

2
source/developers/index.markdown
View File

@ -3,7 +3,7 @@ layout: page
title: "Developers"
date: 2014-12-21 13:32
sidebar: false
comments: true
comments: false
sharing: true
footer: true
---

18
source/getting-started/index.markdown
View File

@ -3,7 +3,7 @@ layout: page
title: "Getting Started"
date: 2014-12-18 22:57
sidebar: false
comments: true
comments: false
sharing: true
footer: true
---
@ -28,13 +28,13 @@ docker run -d --name="home-assistant" -v /path/to/homeassistant/config:/config -
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.
<div class='note'><p class='title'>Note</p><p class='content'>
<p class='note'>
You can append <code>?api_password=YOUR_PASSWORD</code> to any url to log in automatically.
</p></div>
</p>
<div class='note'><p class='title'>Note</p><p class='content'>
<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></div>
</p>
### Philips Hue
To get Philips Hue working you will have to connect Home Assistant to the Hue bridge.
@ -64,13 +64,13 @@ username=admin
password=MY_PASSWORD
```
<div class='note'><p class='title'>Note on Tomato</p><p class='content'>
<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></div>
</p>
<div class='note'><p class='title'>Note on Luci</p><p class='content'>
<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></div>
</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.

0
source/images/architecture-remote.png → source/images/architecture/architecture-remote.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 77 KiB

After

Width:  |  Height:  |  Size: 77 KiB

0
source/images/ha_architecture.png → source/images/architecture/ha_architecture.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 31 KiB

BIN
source/images/architecture/home_automation_landscape.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

BIN
source/images/screenshots/nexus_7_dashboard.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 123 KiB

3
source/index.html
View File

@ -1,8 +1,7 @@
---
layout: page
# title: "This is the title for your homepage"
date: 2014-12-18 22:39
comments: true
comments: false
show_title: false
sidebar: false
hero_unit: true