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

Merge branch 'jekyll-3'

Browse source 
Conflicts:
	.gitignore
	Gemfile.lock
	source/_components/media_player.plex.markdown
	source/_includes/site/head.html
This commit is contained in:
Paulus Schoutsen 2015-10-29 00:08:22 -07:00
commit a08459ec8f
296 changed files with 1518 additions and 2884 deletions
Download patch file Download diff file Expand all files Collapse all files

1
source/developers/add_new_platform.html Normal file
View file

@ -0,0 +1 @@
<script>document.location = '/developers/add_new_platform/';</script>

24
source/developers/add_new_platform.markdown
View file

@ -23,35 +23,21 @@ If you are planning to add support for a new type of device to an existing compo
### {% linkable_title Interfacing with devices %}
One of the rules for Home Assistant is that platform logic should never interface directly with
devices but use a third-party Python 3 library to do so. This way Home Assistant is able to share
code with the Python community and we can keep the project maintainable.
One of the rules for Home Assistant is that platform logic should never interface directly with devices but use a third-party Python 3 library to do so. This way Home Assistant is able to share code with the Python community and we can keep the project maintainable.
Platforms can specify dependencies and requirements the same way as a component does. Please see
[the component page](/developers/creating_components.html#dependencies) for more information.
Platforms can specify dependencies and requirements the same way as a component does. Please see [the component page](/developers/creating_components/#dependencies) for more information.
### {% linkable_title Creating Entities %}
Home Assistant will call a function with the following signature to initialize
your new platform. This function must exist in the platform module you create.
Home Assistant will call a function with the following signature to initialize your new platform. This function must exist in the platform module you create.
```python
def setup_platform(hass, config, add_devices, discovery_info=None)
```
In this function, your platform should create the appropriate entities and
register them with the Home Assistant core. Entities are Home Assistant's
representation of lights, switches, sensors, etc. and are derived from the
[Entity Abstract Class](https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py).
This abstract class contains logic for integrating most standard features into
your entities, such as visibility, entity IDs, updates, and many more.
In this function, your platform should create the appropriate entities and register them with the Home Assistant core. Entities are Home Assistant's representation of lights, switches, sensors, etc. and are derived from the [Entity Abstract Class](https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py). This abstract class contains logic for integrating most standard features into your entities, such as visibility, entity IDs, updates, and many more.
A list of entities can be registered with Home Assistant using the *add_devices*
function that is provided as an input to *setup_platform*. Once entities are
registered with with Home Assistant their updates will be provided to the core
and the core will have control over them. For more information on how Entities
can be customized, take a look at the [Entity Abstract
Class](https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py#L18).
A list of entities can be registered with Home Assistant using the *add_devices* function that is provided as an input to *setup_platform*. Once entities are registered with with Home Assistant their updates will be provided to the core and the core will have control over them. For more information on how Entities can be customized, take a look at the [Entity Abstract Class](https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py#L18).
## {% linkable_title Allowing your platform to be discovered %}

1
source/developers/api.html Normal file
View file

@ -0,0 +1 @@
<script>document.location = '/developers/api/';</script>

4
source/developers/api.markdown
View file

@ -12,5 +12,5 @@ footer: true
Home Assistant is offering a RESTful API and a Python API for convenient access to
a Home Assistant instance over HTTP.
- [Rest API](/developers/rest_api.html)
- [Python API](/developers/python_api.html)
- [Rest API](/developers/rest_api/)
- [Python API](/developers/python_api/)

1
source/developers/architecture.html Normal file
View file

@ -0,0 +1 @@
<script>document.location = '/developers/architecture/';</script>

35
source/developers/architecture.markdown
View file

@ -9,7 +9,7 @@ sharing: true
footer: true
---
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/26/home-control-home-automation-and-the-smart-home/'>check out our blog</a>. A tl;dr version of the blog:
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='/blog/2014/12/26/home-control-home-automation-and-the-smart-home/'>check out our blog</a>. A tl;dr version of the blog:
* Home Control is responsible for collecting information on- and controlling devices.
* Home Automation triggers commands based on user configurations.
@ -31,54 +31,57 @@ The Home Assistant core is responsible for Home Control. It has four parts to ma
* The **Timer** will send every 1 second 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 href='/images/architecture/ha_architecture.png'>
<img src='/images/architecture/ha_architecture.png' />
</a>
Overview of the Home Assistant core architecture
</p>
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/).
We can differentiate between two different types of
components within Home Assistant.
We can differentiate between two different types ofcomponents within Home Assistant.
#### {% linkable_title Components that interact with an Internet of Things domain %}
These components will track devices within a specific domain and exist of a core part and platform specific logic. These components make their 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.
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).
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/).
#### {% linkable_title 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:
For example the [`device_sun_light_trigger` component](/components/device_sun_light_trigger/) 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:
```plain
In the event that device 'Paulus Nexus 5' changes to the 'Home' state:
If the sun has set and the lights are not on:
Turn on the lights
```
<!-- comment to separate markdown blockquotes -->
```plain
In the event that the combined state of all tracked devices changes to 'Not Home':
If the lights are on:
Turn off the lights
```
<!-- comment to separate markdown blockquotes -->
```plain
In the event of the sun setting:
If the lights are off and the combined state of all tracked device equals 'Home':
Turn on the lights
```
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).
An extended example of a home automation component can be found [here](https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py).
### {% linkable_title The full picture %}
When we put all the different pieces of Home Assistant together we see that we match pretty close to the initial sketched home automation overview. The smart home AI is not implemented yet and therefore omitted from the following picture.
<p class='img'>
<a href='{{ root_url }}/images/architecture/ha_full_architecture.png'>
<img src='{{ root_url }}/images/architecture/ha_full_architecture.png' />
<a href='/images/architecture/ha_full_architecture.png'>
<img src='/images/architecture/ha_full_architecture.png' />
</a>
Overview of the full Home Assistant architecture with a couple of loaded components and platforms.
</p>
@ -90,8 +93,8 @@ Component's platform logic uses 3rd party Python libraries to communicate with t
Home Assistant supports running multiple synchronized instances using a master-slave model. Whenever `events.fire` or `states.set` is called on the salve it will forward it to the master. The master will replicate all events and changed states to its slaves.
<p class='img'>
<a href='{{ root_url }}/images/architecture/architecture-remote.png'>
<img src='{{ root_url }}/images/architecture/architecture-remote.png' />
<a href='/images/architecture/architecture-remote.png'>
<img src='/images/architecture/architecture-remote.png' />
</a>
Overview of the Home Assistant architecture for multiple devices.
</p>

1
source/developers/creating_components.html Normal file
View file

@ -0,0 +1 @@
<script>document.location = '/developers/creating_components/';</script>

35
source/developers/creating_components.markdown
View file

@ -26,10 +26,10 @@ example:
## {% linkable_title 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:
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:
* <code>&lt;config directory>/custom_components/&lt;component name></code>
* <code>homeassistant/components/&lt;component name></code> (built-in components)
* `<config directory>/custom_components/<component name>`
* `homeassistant/components/<component name>` (built-in components)
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.
@ -47,28 +47,27 @@ Home Assistant allows components and platforms to specify their dependencies and
Dependencies are other Home Assistant components that should be setup before the platform is loaded. An example is the MQTT sensor component, which requires an active connection to an MQTT broker. If Home Assistant is unable to load and setup the MQTT component, it will not setup the MQTT sensor component.
Requirements are Python libraries that you would normally install using `pip`. Each entry in a requirement list is a pip compatible string. For example, the media player Cast platform depends on the Python package PyChromecast thus `REQUIREMENTS = ['pychromecast==0.6.12']`. If Home Assistant is unable to install the package or verify it is installed, the component will fail to
load.
Requirements are Python libraries that you would normally install using `pip`. Each entry in a requirement list is a pip compatible string. For example, the media player Cast platform depends on the Python package PyChromecast thus `REQUIREMENTS = ['pychromecast==0.6.12']`. If Home Assistant is unable to install the package or verify it is installed, the component will fail to load.
## {% linkable_title Initializing components %}
After loading, the bootstrapper will call `setup(hass, config)` method on the component to initialize it. The following parameters are passed in:
After loading, the bootstrapper will call `setup(hass, config)` method on the component to initialize it.
| Parameter | Description |
| --------- | ----------- |
| <code>hass</code> | The Home Assistant object. Call its methods to track time, register services, listen for events or track states: [Overview of available methods.](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L55) |
| <code>config</code> | A dict containing the configuration. The keys of the config-dict are component names and the value is another dict with the component configuration.: [Details](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L687) |
### {% linkable_title `hass`: the Home Assistant instance %}
### {% linkable_title Guidance on using the Home Assistant object %}
The Home Assistant object contains three objects to help you interact with the system.
The Home Assistant instace contains three objects to help you interact with the system.
| Object | Description |
| ------ | ----------- |
| <code>hass.states</code> | This is the StateMachine. It allows you to set states and track when they are changed. [See available methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L434). |
| <code>hass.bus</code> | This is the EventBus. It allows you to trigger and listen for events.<br>[See available methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L229). |
| <code>hass.services</code> | This is the ServiceRegistry. It allows you to register services.<br>[See available methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L568). |
| `hass.config` | This is the core configuration of Home Assistant exposing location, temperature preferences and config directory path. [Details](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L687)
| `hass.states` | This is the StateMachine. It allows you to set states and track when they are changed. [See available methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L434). |
| `hass.bus` | This is the EventBus. It allows you to trigger and listen for events.<br>[See available methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L229). |
| `hass.services` | This is the ServiceRegistry. It allows you to register services.<br>[See available methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L568). |
### {% linkable_title `config`: User given configuration. %}
The `config` paramter is a dictionary containing the user supplied configuration. The keys of the dictionary are the component names and the value is another dictionary with the component configuration.
### {% linkable_title Example on using the configuration parameter %}
If your configuration file contains the following lines:
```yaml
@ -77,3 +76,7 @@ example:
```
Then in the setup method of your component you will be able to refer to `config['example']['host']` to get the value `paulusschoutsen.nl`.
## {% linkable_title Responding to events %}
Home Assistant has different ways of responding to events that occur in Home Assistant. These have been organized in [helper methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/helpers/event.py). Examples are `track_state_change`, `track_point_in_time`, `track_time_change`.

1
source/developers/credits.html Normal file
View file

@ -0,0 +1 @@
<script>document.location = '/developers/credits/';</script>

1
source/developers/frontend.html Normal file
View file

@ -0,0 +1 @@
<script>document.location = '/developers/frontend/';</script>

47
source/developers/frontend.markdown
View file

@ -11,9 +11,9 @@ footer: true
Home Assistant uses [Polymer](https://www.polymer-project.org/) for the UI and [NuclearJS](http://optimizely.github.io/nuclear-js/) for all data management.
* Polymer allows building encapsulated custom HTML elements.
* Polymer allows building encapsulated custom HTML elements.
[Home-Assistant-Polymer source code on GitHub.](https://github.com/balloob/home-assistant-polymer)
* NuclearJS is a reactive flux built with ImmutableJS data structures.
* NuclearJS is a reactive flux built with ImmutableJS data structures.
[Home-Assistant-JS source code on GitHub.](https://github.com/balloob/home-assistant-js)
<p class='note warning'>
@ -28,39 +28,29 @@ http:
development: 1
```
Next step is to get the frontend code. When you clone the Home Assistant repository, the frontend
repository is not cloned by default. You will have to trigger this manually by running from the
command line:
Next step is to get the frontend code. When you clone the Home Assistant repository, the frontend repository is not cloned by default. You will have to do this by running from the command line:
```bash
git submodule update --init
$ git submodule update --init
```
After checking out the frontend code, you will have to install the frontend dependencies. Firing off
a build of the frontend by running `script/build_frontend` will ensure they get installed.
After checking out the frontend code, you will have to install the frontend dependencies. Firing off a build of the frontend by running `script/build_frontend` will ensure they get installed.
Once this is done, you can start editting the webcomponents in the folder
`homeassistant/components/frontend/www_static/home-assistant-polymer/src`. To see the changes you've
made, simply refresh your browser.
Once this is done, you can start editting the webcomponents in the folder `homeassistant/components/frontend/www_static/home-assistant-polymer/src`. To see the changes you've made, simply refresh your browser.
## {% linkable_title Enabling JavaScript backend development %}
Polymer is only providing a UI toolkit for Home Assistant. All data management and interaction with
the server is done by `home-assistant-js` leveraging NuclearJS. To enable JavaScript development:
Polymer is only providing a UI toolkit for Home Assistant. All data management and interaction with the server is done by `home-assistant-js` leveraging NuclearJS. To enable JavaScript development:
```bash
cd homeassistant/components/frontend/www_static/home-assistant-polymer/
npm run setup_js_dev
npm run js_dev
$ cd homeassistant/components/frontend/www_static/home-assistant-polymer/
$ npm run setup_js_dev
$ npm run js_dev
```
`npm run js_dev` will start the process that will ensure that your latest changes to the JavaScript
files will be loaded when you refresh the page. This command has to be always running while working
on home-assistant-js.
`npm run js_dev` will start the process that will ensure that your latest changes to the JavaScript files will be loaded when you refresh the page. This command has to be always running while working on home-assistant-js.
After your changes have been accepted into the `home-assistant-js` repository, we'll have to update
Home Assistant Polymer to use the latest version. This can be done by updating `package.json`. Look
for the line that contains `home-assistant-js` and update the SHA to the SHA of your commit.
After your changes have been accepted into the `home-assistant-js` repository, we'll have to update Home Assistant Polymer to use the latest version. This can be done by updating `package.json`. Look for the line that contains `home-assistant-js` and update the SHA to the SHA of your commit.
# {% linkable_title Building the Polymer frontend %}
@ -73,26 +63,23 @@ Building a new version of the frontend is as simple as running `script/build_fro
* Vulcanize all Webcomponents to `frontend.vulcan.html`.
* Minify `frontend.vulcan.html` and save it as `frontend.html`.
* Copy the webcomponents polyfill `webcomponents-lite.min.js` from **home-assistant-polymer** to `components/frontend/www_static/webcomponents-lite.min.js`.
* Copy the final frontend build `frontend.html` from **home-assistant-polymer** to `components/frontend/www_static/frontend.html`.
* Copy the final frontend build `frontend.html` from **home-assistant-polymer** to `components/frontend/www_static/frontend/`.
* Generate MD5 hash of `frontend.html` to signal caches to redownload the UI.
<p class='img'>
<img src='/images/frontend/polymer-build-architecture.png' alt='Polymer build architecture diagram' />
Polymer build architecture diagram
</p>
# {% linkable_title Adding state cards %}
The main interface of Home Assistant is a list of the current entities and their states. For each entity in the system, a state card will be rendered. State cards will show a state badge, the name of the entity, when the state has last changed and the current state or a control to interact with it.
<img src='/images/frontend/frontend-cards.png' />
Some domains will be filtered out of the main view and are available through separate menu options. Examples are `group`, `script`, `scene`.
![Cards in the frontend](/images/frontend/frontend-cards.png)
The different card types can be found [here](https://github.com/balloob/home-assistant-polymer/tree/master/src/state-summary).
Adding a custom card type can be done with a few simple steps. For this example we will add a new
state card for the domain `camera`:
_(All files in this example link to their source-code)_
Adding a custom card type can be done with a few simple steps. For this example we will add a new state card for the domain `camera`: _(All files in this example link to their source-code)_
1. Add `'camera'` to the array `DOMAINS_WITH_CARD` in the file [`/util/state-card-type.js`](https://github.com/balloob/home-assistant-polymer/blob/master/src/util/state-card-type.js#L3-L4).
2. Create the files `state-card-camera.html` and `state-card-camera.js` in the folder [`/state-summary/`](https://github.com/balloob/home-assistant-polymer/tree/master/src/state-summary).
@ -108,7 +95,7 @@ Whenever the user taps or clicks on one of the cards, a more info dialog will sh
The more info dialog for a light allows the user to control the color and the brightness.
</p>
The instructions to add a more info dialog are very similar to adding a new card type. This example will add a new more info component for the domain `camera`:
The instructions to add a more info dialog are very similar to adding a new card type. This example will add a new more info component for the domain `camera`:
_(All files in this example link to their source-code)_
1. Add `'camera'` to the array `DOMAINS_WITH_MORE_INFO` in the file [`util/state-more-info-type.js`](https://github.com/balloob/home-assistant-polymer/blob/master/src/util/state-more-info-type.js#L1).

28
source/developers/index.markdown
View file

@ -22,9 +22,9 @@ Home Assistant is open-source and MIT licensed. The source can be found here:
You will need to setup a development environment if you want to start developing a new feature or component for Home Assistant perform theses steps
```bash
git clone https://github.com/balloob/home-assistant.git
cd home-assistant
script/setup
$ git clone https://github.com/balloob/home-assistant.git
$ cd home-assistant
$ script/setup
```
After following these steps, running `hass` will invoke your local installation.
@ -36,25 +36,25 @@ requests.
1. Go to [the Home Assistant repository](https://github.com/balloob/home-assistant) and click fork in the top right.
2. Follow steps in the previous section but with your forked repository.
3. Create a new branch to hold your changes<br>
3. Create a new branch to hold your changes
`git checkout -b some-feature`
4. Make the changes you want
5. Check your changes for style violations<br>
5. Check your changes for style violations
`./script/lint`
6. Commit the changes<br>
`git add .`<br>
6. Commit the changes
`git add .`
`git commit -m "Added some-feature"`
7. Push your commited changes back to your fork on Github<br>
7. Push your commited changes back to your fork on Github
`git push origin HEAD`
8. Follow [these steps](https://help.github.com/articles/creating-a-pull-request/) to create your
pull request.
### {% linkable_title Further reading %}
- [Home Assistant Architecture](/developers/architecture.html)
- [Frontend development](/developers/frontend.html)
- [Creating a custom component](/developers/creating_components.html)
- [Adding support for a new platform](/developers/add_new_platform.html)
- [Rest API](/developers/api.html)
- [Website](/developers/website.html)
- [Home Assistant Architecture](/developers/architecture/)
- [Frontend development](/developers/frontend/)
- [Creating a custom component](/developers/creating_components/)
- [Adding support for a new platform](/developers/add_new_platform/)
- [Rest API](/developers/api/)
- [Website](/developers/website/)

1
source/developers/python_api.html Normal file
View file

@ -0,0 +1 @@
<script>document.location = '/developers/python_api/';</script>

2
source/developers/python_api.markdown
View file

@ -9,7 +9,7 @@ sharing: true
footer: true
---
In the package [`homeassistant.remote`](https://github.com/balloob/home-assistant/blob/master/homeassistant/remote.py) a Python API on top of the [HTTP API](/developers/api.html) can be found.
In the package [`homeassistant.remote`](https://github.com/balloob/home-assistant/blob/master/homeassistant/remote.py) a Python API on top of the [HTTP API](/developers/api/) can be found.
This page is not a full documentation it's more a collection of some example. A simple way to get all current entities is to visit the "Set State" page in the "Developer Tools". For the examples below just choose one from the available entries. Here the sensor `sensor.office_temperature` and the switch `switch.livingroom_pin_2` are used.

1
source/developers/rest_api.html Normal file
View file

@ -0,0 +1 @@
<script>document.location = '/developers/rest_api/';</script>

1
source/developers/website.html Normal file
View file

@ -0,0 +1 @@
<script>document.location = '/developers/website/';</script>