jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

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
Download patch file Download diff file Expand all files Collapse all files

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