mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-13 20:36:52 +00:00
Split up development pages
This commit is contained in:
Paulus Schoutsen
parent
8bee265142
commit
a4adf87fe3
1
Gemfile
1
Gemfile
@ -15,6 +15,7 @@ group :development do
|
||||
gem 'execjs'
|
||||
gem 'therubyracer', :platforms => :ruby
|
||||
gem 'coderay'
|
||||
gem 'pry'
|
||||
end
|
||||
|
||||
group :jekyll_plugins do
|
||||
|
||||
@ -38,6 +38,7 @@ GEM
|
||||
rb-fsevent (>= 0.9.3)
|
||||
rb-inotify (>= 0.9)
|
||||
mercenary (0.3.5)
|
||||
method_source (0.8.2)
|
||||
octopress (3.0.11)
|
||||
jekyll (>= 2.0)
|
||||
mercenary (~> 0.3.2)
|
||||
@ -63,6 +64,10 @@ GEM
|
||||
octopress-tag-helpers (1.0.8)
|
||||
jekyll (>= 2.0)
|
||||
posix-spawn (0.3.11)
|
||||
pry (0.10.3)
|
||||
coderay (~> 1.1.0)
|
||||
method_source (~> 0.8.1)
|
||||
slop (~> 3.4)
|
||||
pygments.rb (0.6.3)
|
||||
posix-spawn (~> 0.3.6)
|
||||
yajl-ruby (~> 1.2.0)
|
||||
@ -87,6 +92,7 @@ GEM
|
||||
rack (~> 1.4)
|
||||
rack-protection (~> 1.4)
|
||||
tilt (>= 1.3, < 3)
|
||||
slop (3.6.0)
|
||||
stringex (1.4.0)
|
||||
therubyracer (0.12.2)
|
||||
libv8 (~> 3.16.14.0)
|
||||
@ -111,6 +117,7 @@ DEPENDENCIES
|
||||
octopress (~> 3.0)
|
||||
octopress-filters
|
||||
octopress-include-tag
|
||||
pry
|
||||
pygments.rb (~> 0.6.3)
|
||||
rake (~> 10.0)
|
||||
rb-fsevent (~> 0.9)
|
||||
|
||||
19
plugins/active_link.rb
Normal file
19
plugins/active_link.rb
Normal file
@ -0,0 +1,19 @@
|
||||
require 'pry'
|
||||
|
||||
module Jekyll
|
||||
class ActiveLinkTag < Liquid::Tag
|
||||
def initialize(tag_name, text, token)
|
||||
super
|
||||
parts = text.split(' ', 2)
|
||||
@href = parts[0]
|
||||
@title = parts[1]
|
||||
end
|
||||
|
||||
def render(context)
|
||||
cls = @href == context.registers[:page]["url"] ? "class='active'" : ''
|
||||
"<a #{cls} href='#{@href}'>#{@title}</a>"
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
Liquid::Template.register_tag('active_link', Jekyll::ActiveLinkTag)
|
||||
@ -411,3 +411,8 @@ p.note {
|
||||
margin-bottom: 8px;
|
||||
font-size: .8em;
|
||||
}
|
||||
|
||||
ul.sidebar-menu a.active {
|
||||
color: #000;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
44
source/_includes/asides/developers_navigation.html
Normal file
44
source/_includes/asides/developers_navigation.html
Normal file
@ -0,0 +1,44 @@
|
||||
<section class="aside-module grid__item one-whole lap-one-half">
|
||||
{% include edit_github.html %}
|
||||
|
||||
<div class='section'>
|
||||
<h1 class="title delta">Development Guide</h1>
|
||||
<ul class='divided sidebar-menu'>
|
||||
<li>
|
||||
{% active_link /developers/ Introduction %}
|
||||
<ul>
|
||||
<li>{% active_link /developers/architecture/ Architecture %}</li>
|
||||
<li>{% active_link /developers/architecture_components/ Components %}</li>
|
||||
<li>{% active_link /developers/development_environment/ Setup Dev Environment %}</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>
|
||||
Frontend Development
|
||||
<ul>
|
||||
<li>{% active_link /developers/frontend/ Setup Frontend Environment %}</li>
|
||||
<li>{% active_link /developers/frontend_add_card/ Add State Card %}</li>
|
||||
<li>{% active_link /developers/frontend_add_more_info/ Add More Info Dialog %}</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>
|
||||
Extending Home Assistant
|
||||
<ul>
|
||||
<li>{% active_link /developers/creating_components/ Creating Components %}</li>
|
||||
<li>{% active_link /developers/add_new_platform/ Adding Platform Support %}</li>
|
||||
<li>{% active_link /developers/platform_discovery/ Platform Discovery %}</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>
|
||||
API
|
||||
<ul>
|
||||
<li>{% active_link /developers/rest_api/ RESTful API %}</li>
|
||||
<li>{% active_link /developers/python_api/ Python API %}</li>
|
||||
<li>{% active_link /developers/server_sent_events/ Server-sent events %}</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>{% active_link /developers/multiple_instances/ Multiple Instances %}</li>
|
||||
<li>{% active_link /developers/website/ Home-Assitant.io %}</li>
|
||||
<li>{% active_link /developers/credits/ Credits %}</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
@ -11,23 +11,8 @@
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href='/components/'>Components</a></li>
|
||||
<li><a href='/cookbook'>Examples</a></li>
|
||||
<li>
|
||||
<a>Developers <i class="icon icon-caret-down"></i></a>
|
||||
<ul>
|
||||
<li><a href="/developers/">Setup Development</a></li>
|
||||
<li><a href="/developers/architecture/">Architecture</a></li>
|
||||
<li><a href="/developers/frontend/">Frontend Development</a></li>
|
||||
<li><a href="/developers/creating_components/">
|
||||
Creating Components
|
||||
</a></li>
|
||||
<li><a href="/developers/add_new_platform/">
|
||||
Adding Platform Support
|
||||
</a></li>
|
||||
<li><a href="/developers/api/">API and SSE</a></li>
|
||||
<li><a href="/developers/credits/">Credits</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href='/cookbook/'>Examples</a></li>
|
||||
<li><a href="/developers/">Developers</a></li>
|
||||
<li><a href="/blog/">Blog</a></li>
|
||||
<li><a href="/help/">Need help?</a></li>
|
||||
</ul>
|
||||
|
||||
@ -1,3 +1,7 @@
|
||||
{% if page.hide_github_edit != true %}
|
||||
{% assign url_parts = page.url | split: '/' %}
|
||||
{% if page.hide_github_edit != true and
|
||||
url_parts[1] != 'components' and
|
||||
url_parts[1] != 'cookbook' and
|
||||
url_parts[1] != 'developers' %}
|
||||
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.io/tree/master/source/{{ page.path }}'>Edit this page on GitHub</a></div>
|
||||
{% endif %}
|
||||
{% endif %}
|
||||
|
||||
@ -4,6 +4,8 @@
|
||||
{% include asides/component_navigation.html | compact_newlines %}
|
||||
{% elsif url_parts[1] == 'cookbook' %}
|
||||
{% include asides/cookbook_navigation.html | compact_newlines %}
|
||||
{% elsif url_parts[1] == 'developers' %}
|
||||
{% include asides/developers_navigation.html | compact_newlines %}
|
||||
{% else %}
|
||||
{% include asides/about.html %}
|
||||
|
||||
|
||||
@ -36,11 +36,6 @@
|
||||
{% include site/footer.html %}
|
||||
</footer>
|
||||
|
||||
<!--[if lt IE 7]>
|
||||
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
|
||||
<![endif]-->
|
||||
|
||||
{% include javascripts/scripts.html %}
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@ -3,10 +3,7 @@ layout: default
|
||||
---
|
||||
|
||||
<article class="page">
|
||||
{% assign url_parts = page.url | split: '/' %}
|
||||
{% if url_parts[1] != 'components' and url_parts[1] != 'cookbook' %}
|
||||
{% include edit_github.html %}
|
||||
{% endif %}
|
||||
{% include edit_github.html %}
|
||||
|
||||
{% if page.title and page.show_title != false %}
|
||||
<header>
|
||||
|
||||
@ -1 +0,0 @@
|
||||
<script>document.location = '/developers/add_new_platform/';</script>
|
||||
@ -3,7 +3,7 @@ layout: page
|
||||
title: "Adding support for a new platform"
|
||||
description: "Hints and tips for when you're adding a new platform to Home Assistant."
|
||||
date: 2014-12-21 13:27
|
||||
sidebar: false
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
@ -98,39 +98,3 @@ class AwesomeLight(Light):
|
||||
"""If light is on."""
|
||||
return self._light.is_on()
|
||||
```
|
||||
|
||||
## {% linkable_title Allowing your platform to be discovered %}
|
||||
|
||||
Home Assistant has a discovery service running in the background to discover new devices. Whenever a new device is discovered, an `SERVICE_DISCOVERED` event will be fired with the found service and the information. The `discovery` component has some knowledge about which components handle which type of services and will ensure those are loaded and listening before firing the `SERVICE_DISCOVERED` event.
|
||||
|
||||
### {% linkable_title Add discovery instructions %}
|
||||
|
||||
Device discovery for Home Assistant has been extracted into an external library called [NetDisco](https://github.com/balloob/netdisco). This library is integrated using [the `discovery` component](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py) and scans the network in intervals for uPnP and zeroconf/mDNS services.
|
||||
|
||||
To have your device be discovered, you will have to extend the NetDisco library to be able to find your device. This is done by adding a new discoverable. [See the repository for examples of existing discoverables.](https://github.com/balloob/netdisco/tree/master/netdisco/discoverables)
|
||||
|
||||
### {% linkable_title Listening to `SERVICE_DISCOVERED` events %}
|
||||
|
||||
From your component, you will have to set up the listening for specific services. Below an example how one would listen for discovered Chromecasts:
|
||||
|
||||
```python
|
||||
from homeassistant.loader import get_component
|
||||
|
||||
def setup(hass, config):
|
||||
discovery = get_component('discovery')
|
||||
|
||||
def chromecast_discovered(service, info):
|
||||
""" Called when a Chromecast has been discovered. """
|
||||
print("Discovered a new Chromecast: {}".format(info))
|
||||
|
||||
discovery.listen(
|
||||
hass, discovery.services.GOOGLE_CAST, chromecast_discovered)
|
||||
```
|
||||
|
||||
### {% linkable_title Auto-loading your component upon discovery %}
|
||||
|
||||
The Discovery component is capable of setting up your components before firing the `SERVICE_DISCOVERD` event. To do this you will have to update the [`SERVICE_HANDLERS`](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py#L29) constant in [the `discovery` component](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py).
|
||||
|
||||
<p class='note warning'>
|
||||
This option is currently limited to built-in components.
|
||||
</p>
|
||||
|
||||
@ -1 +0,0 @@
|
||||
<script>document.location = '/developers/api/';</script>
|
||||
@ -1,18 +0,0 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Home Assistant API/SSE"
|
||||
description: "Home Assistant API/SSE documentation"
|
||||
date: 2015-05-11 12:00
|
||||
sidebar: false
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Home Assistant is offering a RESTful API and a Python API for convenient access to a Home Assistant instance over HTTP.
|
||||
|
||||
- [RESTful API](/developers/rest_api/)
|
||||
- [Python API](/developers/python_api/)
|
||||
|
||||
There is also support for [server-sent events](/developers/server_sent_events).
|
||||
|
||||
@ -1 +0,0 @@
|
||||
<script>document.location = '/developers/architecture/';</script>
|
||||
@ -3,7 +3,7 @@ layout: page
|
||||
title: "Architecture"
|
||||
description: "Overview of the Home Assistant architecture."
|
||||
date: 2014-12-18 21:49
|
||||
sidebar: false
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
@ -36,91 +36,3 @@ The Home Assistant core is responsible for Home Control. It has four parts to ma
|
||||
</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.
|
||||
|
||||
#### {% linkable_title Components that interact with an Internet of Things domain %}
|
||||
|
||||
These components will track devices within a specific domain and consist 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.
|
||||
|
||||
A platform provides support for a particular kind/brand of device. For example, a switch could use a WeMo or Orvibo platform, and a light component might interact with the Hue or LiFX platform.
|
||||
|
||||
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](/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
|
||||
```
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
An extended example of a home automation component can be found [here](https://github.com/home-assistant/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='/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>
|
||||
|
||||
The platform logic for components uses 3rd party Python libraries to communicate with the devices. This is done so that we can leverage great device libraries that are out there in the Python community.
|
||||
|
||||
## {% linkable_title Multiple connected instances %}
|
||||
|
||||
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='/images/architecture/architecture-remote.png'>
|
||||
<img src='/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.
|
||||
|
||||
```python
|
||||
import homeassistant.remote as remote
|
||||
import homeassistant.bootstrap as bootstrap
|
||||
|
||||
# Location of the Master API: host, password, port.
|
||||
# Password and port are optional.
|
||||
remote_api = remote.API("127.0.0.1", "password", 8124)
|
||||
|
||||
# Initialize slave
|
||||
hass = remote.HomeAssistant(remote_api)
|
||||
|
||||
# To add an interface to the slave on localhost:8123
|
||||
bootstrap.setup_component(hass, 'frontend')
|
||||
|
||||
hass.start()
|
||||
hass.block_till_stopped()
|
||||
```
|
||||
|
||||
<p class='note'>
|
||||
Because each slave maintains its own Service Registry it is possible to have multiple slaves respond to one service call.
|
||||
</p>
|
||||
|
||||
63
source/developers/architecture_components.markdown
Normal file
63
source/developers/architecture_components.markdown
Normal file
@ -0,0 +1,63 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Components Architecture"
|
||||
description: "Overview of components within the Home Assistant architecture."
|
||||
date: 2016-04-16 14:24 -07:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
#### {% linkable_title Components that interact with an Internet of Things domain %}
|
||||
|
||||
These components will track devices within a specific domain and consist 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.
|
||||
|
||||
A platform provides support for a particular kind/brand of device. For example, a switch could use a WeMo or Orvibo platform, and a light component might interact with the Hue or LiFX platform.
|
||||
|
||||
If you are planning to add support for a new platform, please check out the [add new platform section](/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](/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
|
||||
```
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
An extended example of a home automation component can be found [here](https://github.com/home-assistant/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='/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>
|
||||
|
||||
The platform logic for components uses 3rd party Python libraries to communicate with the devices. This is done so that we can leverage great device libraries that are out there in the Python community.
|
||||
@ -1 +0,0 @@
|
||||
<script>document.location = '/developers/creating_components/';</script>
|
||||
@ -3,7 +3,7 @@ layout: page
|
||||
title: "Creating components"
|
||||
description: "Guidelines to get you create your first component for Home Assistant."
|
||||
date: 2014-12-21 13:32
|
||||
sidebar: false
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
|
||||
@ -1 +0,0 @@
|
||||
<script>document.location = '/developers/credits/';</script>
|
||||
@ -3,7 +3,7 @@ layout: page
|
||||
title: "Credits"
|
||||
description: "Credits for the developers who contributed to Home Assistant."
|
||||
date: 2015-06-19 09:30
|
||||
sidebar: false
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
|
||||
68
source/developers/development_environment.markdown
Normal file
68
source/developers/development_environment.markdown
Normal file
@ -0,0 +1,68 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Setup Development"
|
||||
description: "Everything to get you started developing for Home Assistant."
|
||||
date: 2014-12-21 13:32
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Home Assistant is built from the ground up to be easily-extensible by other developers using components. It uses [Python 3](https://www.python.org/) for the backend and [Polymer (Web components)](https://www.polymer-project.org/) for the frontend.
|
||||
|
||||
Home Assistant is open-source and MIT licensed. The source can be found here:
|
||||
|
||||
- [home-assistant](https://github.com/home-assistant/home-assistant) - Python server backend
|
||||
- [home-assistant-js](https://github.com/home-assistant/home-assistant-js) - JavaScript backend powering the client
|
||||
- [home-assistant-polymer](https://github.com/home-assistant/home-assistant-polymer) - Polymer UI
|
||||
|
||||
### {% linkable_title Starting development %}
|
||||
|
||||
You will need to set up a development environment if you want to start developing a new feature or component for Home Assistant. Please follow these steps to get setup.
|
||||
Visit the [the Home Assistant repository](https://github.com/home-assistant/home-assistant) first and click fork in the top right.
|
||||
|
||||
We suggest that you setup a [virtual environment](https://docs.python.org/3.4/library/venv.html) aka `venv` before running the setup script.
|
||||
|
||||
```bash
|
||||
$ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git
|
||||
$ cd home-assistant
|
||||
$ git remote add upstream https://github.com/home-assistant/home-assistant.git
|
||||
$ script/setup
|
||||
```
|
||||
|
||||
Testing your work requires `tox` to be installed:
|
||||
|
||||
```bash
|
||||
$ pip3 install tox
|
||||
```
|
||||
|
||||
After following these steps, running `hass` will invoke your local installation.
|
||||
|
||||
### {% linkable_title Submitting improvements %}
|
||||
|
||||
Improvements to Home Assistant should be submitted one feature at a time using GitHub [pull requests](https://help.github.com/articles/using-pull-requests).
|
||||
|
||||
1. From your fork, create a new branch to hold your changes
|
||||
`git checkout -b some-feature`
|
||||
2. Make the changes you want
|
||||
3. Test your changes and check for style violations
|
||||
`tox`
|
||||
4. Commit the changes
|
||||
`git add .`
|
||||
`git commit -m "Added some-feature"`
|
||||
5. Push your committed changes back to your fork on GitHub
|
||||
`git push origin HEAD`
|
||||
6. 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/)
|
||||
- [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/)
|
||||
- [Server-sent events](/developers/server_sent_events/)
|
||||
- [Website](/developers/website/)
|
||||
|
||||
@ -1 +0,0 @@
|
||||
<script>document.location = '/developers/frontend/';</script>
|
||||
@ -3,7 +3,7 @@ layout: page
|
||||
title: "Frontend development"
|
||||
description: "Tips and hints if you are starting on Home Assistant frontend development"
|
||||
date: 2014-12-21 13:32
|
||||
sidebar: false
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
@ -69,40 +69,3 @@ Building a new version of the frontend is as simple as running `script/build_fro
|
||||
<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 an icon, the name of the entity, when the state has last changed and the current state or a control to interact with it.
|
||||
|
||||
|
||||
|
||||
The different card types can be found [here](https://github.com/home-assistant/home-assistant-polymer/tree/master/src/state-summary).
|
||||
|
||||
Sensors, when not [grouped](/components/group/), are shown as so-called badges on top of the state cards.
|
||||
|
||||
|
||||
|
||||
The different badges are located in the file [`/src/components/entity/ha-state-label-badge.js`](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/components/entity/ha-state-label-badge.js).
|
||||
|
||||
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`:
|
||||
|
||||
1. Add `'camera'` to the array `DOMAINS_WITH_CARD` in the file [/util/state-card-type.js](https://github.com/home-assistant/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/home-assistant/home-assistant-polymer/tree/master/src/state-summary).
|
||||
3. Add `require('./state-card-camera')` to [state-card-content.js](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/state-summary/state-card-content.js).
|
||||
4. Add `<link rel="import" href="state-card-camera.html">` to [state-card-content.html](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/state-summary/state-card-content.html).
|
||||
|
||||
# {% linkable_title More info screens for custom types %}
|
||||
|
||||
Whenever the user taps or clicks on one of the cards, a more info dialog will show. The header of this dialog will be the state card, followed by the history of this entity for the last 24 hours. Below this the more info component is rendered for that entity. The more info component can show more information or allow more ways of control.
|
||||
|
||||
<p class='img' style='max-width: 400px; margin-left: auto; margin-right: auto;'>
|
||||
<img src='/images/frontend/frontend-more-info-light.png'>
|
||||
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`:
|
||||
|
||||
1. Add `'camera'` to the array `DOMAINS_WITH_MORE_INFO` in the file [util/state-more-info-type.js](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/util/state-more-info-type.js#L1).
|
||||
2. Create the files `more-info-camera.html` and `more-info-camera.js` in the folder [/more-infos](https://github.com/home-assistant/home-assistant-polymer/tree/master/src/more-infos).
|
||||
3. Add `require('./more-info-camera')` to [more-info-content.js](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/more-infos/more-info-content.js)
|
||||
4. Add `<link rel="import" href="more-info-camera.html">` to [more-info-content.html](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/more-infos/more-info-content.html)
|
||||
|
||||
29
source/developers/frontend_add_card.markdown
Normal file
29
source/developers/frontend_add_card.markdown
Normal file
@ -0,0 +1,29 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Adding state card"
|
||||
description: "Adding a state card to the frontend"
|
||||
date: 2016-04-16 14:40 -07:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
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 an icon, the name of the entity, when the state has last changed and the current state or a control to interact with it.
|
||||
|
||||
|
||||
|
||||
The different card types can be found [here](https://github.com/home-assistant/home-assistant-polymer/tree/master/src/state-summary).
|
||||
|
||||
Sensors, when not [grouped](/components/group/), are shown as so-called badges on top of the state cards.
|
||||
|
||||
|
||||
|
||||
The different badges are located in the file [`/src/components/entity/ha-state-label-badge.js`](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/components/entity/ha-state-label-badge.js).
|
||||
|
||||
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`:
|
||||
|
||||
1. Add `'camera'` to the array `DOMAINS_WITH_CARD` in the file [/util/state-card-type.js](https://github.com/home-assistant/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/home-assistant/home-assistant-polymer/tree/master/src/state-summary).
|
||||
3. Add `require('./state-card-camera')` to [state-card-content.js](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/state-summary/state-card-content.js).
|
||||
4. Add `<link rel="import" href="state-card-camera.html">` to [state-card-content.html](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/state-summary/state-card-content.html).
|
||||
24
source/developers/frontend_add_more_info.markdown
Normal file
24
source/developers/frontend_add_more_info.markdown
Normal file
@ -0,0 +1,24 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Adding more info dialogs"
|
||||
description: "Adding a more info dialog to the frontend"
|
||||
date: 2016-04-16 14:40 -07:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Whenever the user taps or clicks on one of the cards, a more info dialog will show. The header of this dialog will be the state card, followed by the history of this entity for the last 24 hours. Below this the more info component is rendered for that entity. The more info component can show more information or allow more ways of control.
|
||||
|
||||
<p class='img' style='max-width: 400px; margin-left: auto; margin-right: auto;'>
|
||||
<img src='/images/frontend/frontend-more-info-light.png'>
|
||||
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`:
|
||||
|
||||
1. Add `'camera'` to the array `DOMAINS_WITH_MORE_INFO` in the file [util/state-more-info-type.js](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/util/state-more-info-type.js#L1).
|
||||
2. Create the files `more-info-camera.html` and `more-info-camera.js` in the folder [/more-infos](https://github.com/home-assistant/home-assistant-polymer/tree/master/src/more-infos).
|
||||
3. Add `require('./more-info-camera')` to [more-info-content.js](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/more-infos/more-info-content.js)
|
||||
4. Add `<link rel="import" href="more-info-camera.html">` to [more-info-content.html](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/more-infos/more-info-content.html)
|
||||
@ -1,68 +1,12 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Setup Development"
|
||||
description: "Everything to get you started developing for Home Assistant."
|
||||
date: 2014-12-21 13:32
|
||||
sidebar: false
|
||||
title: "Developers"
|
||||
description: "Everything you need to know to get started with Home Assistant development."
|
||||
date: 2016-04-16 10:28 +07:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Home Assistant is built from the ground up to be easily-extensible by other developers using components. It uses [Python 3](https://www.python.org/) for the backend and [Polymer (Web components)](https://www.polymer-project.org/) for the frontend.
|
||||
|
||||
Home Assistant is open-source and MIT licensed. The source can be found here:
|
||||
|
||||
- [home-assistant](https://github.com/home-assistant/home-assistant) - Python server backend
|
||||
- [home-assistant-js](https://github.com/home-assistant/home-assistant-js) - JavaScript backend powering the client
|
||||
- [home-assistant-polymer](https://github.com/home-assistant/home-assistant-polymer) - Polymer UI
|
||||
|
||||
### {% linkable_title Starting development %}
|
||||
|
||||
You will need to set up a development environment if you want to start developing a new feature or component for Home Assistant. Please follow these steps to get setup.
|
||||
Visit the [the Home Assistant repository](https://github.com/home-assistant/home-assistant) first and click fork in the top right.
|
||||
|
||||
We suggest that you setup a [virtual environment](https://docs.python.org/3.4/library/venv.html) aka `venv` before running the setup script.
|
||||
|
||||
```bash
|
||||
$ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git
|
||||
$ cd home-assistant
|
||||
$ git remote add upstream https://github.com/home-assistant/home-assistant.git
|
||||
$ script/setup
|
||||
```
|
||||
|
||||
Testing your work requires `tox` to be installed:
|
||||
|
||||
```bash
|
||||
$ pip3 install tox
|
||||
```
|
||||
|
||||
After following these steps, running `hass` will invoke your local installation.
|
||||
|
||||
### {% linkable_title Submitting improvements %}
|
||||
|
||||
Improvements to Home Assistant should be submitted one feature at a time using GitHub [pull requests](https://help.github.com/articles/using-pull-requests).
|
||||
|
||||
1. From your fork, create a new branch to hold your changes
|
||||
`git checkout -b some-feature`
|
||||
2. Make the changes you want
|
||||
3. Test your changes and check for style violations
|
||||
`tox`
|
||||
4. Commit the changes
|
||||
`git add .`
|
||||
`git commit -m "Added some-feature"`
|
||||
5. Push your committed changes back to your fork on GitHub
|
||||
`git push origin HEAD`
|
||||
6. 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/)
|
||||
- [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/)
|
||||
- [Server-sent events](/developers/server_sent_events/)
|
||||
- [Website](/developers/website/)
|
||||
|
||||
Welcome to the Home Assistant development documentation. This is the place to learn all about how Home Assistant works and how you can extend it with support for your devices and services!
|
||||
|
||||
43
source/developers/multiple_instances.markdown
Normal file
43
source/developers/multiple_instances.markdown
Normal file
@ -0,0 +1,43 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Multiple Instances"
|
||||
description: "Quick primer on how multiple instances work together."
|
||||
date: 2016-04-16 14:24 -07:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
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='/images/architecture/architecture-remote.png'>
|
||||
<img src='/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.
|
||||
|
||||
```python
|
||||
import homeassistant.remote as remote
|
||||
import homeassistant.bootstrap as bootstrap
|
||||
|
||||
# Location of the Master API: host, password, port.
|
||||
# Password and port are optional.
|
||||
remote_api = remote.API("127.0.0.1", "password", 8124)
|
||||
|
||||
# Initialize slave
|
||||
hass = remote.HomeAssistant(remote_api)
|
||||
|
||||
# To add an interface to the slave on localhost:8123
|
||||
bootstrap.setup_component(hass, 'frontend')
|
||||
|
||||
hass.start()
|
||||
hass.block_till_stopped()
|
||||
```
|
||||
|
||||
<p class='note'>
|
||||
Because each slave maintains its own Service Registry it is possible to have multiple slaves respond to one service call.
|
||||
</p>
|
||||
44
source/developers/platform_discovery.markdown
Normal file
44
source/developers/platform_discovery.markdown
Normal file
@ -0,0 +1,44 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Platform Discovery"
|
||||
description: "How to make platform discovery work."
|
||||
date: 2016-04-16 14:24 -07:00
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
<p class='note warning'>
|
||||
This option is only available to built-in components.
|
||||
</p>
|
||||
|
||||
Home Assistant has a discovery service running in the background to discover new devices. Whenever a new device is discovered, an `SERVICE_DISCOVERED` event will be fired with the found service and the information. The `discovery` component has some knowledge about which components handle which type of services and will ensure those are loaded and listening before firing the `SERVICE_DISCOVERED` event.
|
||||
|
||||
### {% linkable_title Add discovery instructions %}
|
||||
|
||||
Device discovery for Home Assistant has been extracted into an external library called [NetDisco](https://github.com/home-assistant/netdisco). This library is integrated using [the `discovery` component](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py) and scans the network in intervals for uPnP and zeroconf/mDNS services.
|
||||
|
||||
To have your device be discovered, you will have to extend the NetDisco library to be able to find your device. This is done by adding a new discoverable. [See the repository for examples of existing discoverables.](https://github.com/home-assistant/netdisco/tree/master/netdisco/discoverables)
|
||||
|
||||
### {% linkable_title Listening to `SERVICE_DISCOVERED` events %}
|
||||
|
||||
From your component, you will have to set up the listening for specific services. Below an example how one would listen for discovered Chromecasts:
|
||||
|
||||
```python
|
||||
from homeassistant.loader import get_component
|
||||
|
||||
def setup(hass, config):
|
||||
discovery = get_component('discovery')
|
||||
|
||||
def chromecast_discovered(service, info):
|
||||
""" Called when a Chromecast has been discovered. """
|
||||
print("Discovered a new Chromecast: {}".format(info))
|
||||
|
||||
discovery.listen(
|
||||
hass, discovery.services.GOOGLE_CAST, chromecast_discovered)
|
||||
```
|
||||
|
||||
### {% linkable_title Auto-loading your component upon discovery %}
|
||||
|
||||
The Discovery component is capable of setting up your components before firing the `SERVICE_DISCOVERD` event. To do this you will have to update the [`SERVICE_HANDLERS`](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py#L29) constant in [the `discovery` component](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py).
|
||||
@ -1 +0,0 @@
|
||||
<script>document.location = '/developers/python_api/';</script>
|
||||
@ -3,7 +3,7 @@ layout: page
|
||||
title: "Python API"
|
||||
description: "Home Assistant Python API documentation"
|
||||
date: 2015-05-11 12:00
|
||||
sidebar: false
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
|
||||
@ -1 +0,0 @@
|
||||
<script>document.location = '/developers/rest_api/';</script>
|
||||
@ -3,7 +3,7 @@ layout: page
|
||||
title: "RESTful API"
|
||||
description: "Home Assistant RESTful API documentation"
|
||||
date: 2014-12-21 13:27
|
||||
sidebar: false
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
|
||||
@ -3,7 +3,7 @@ layout: page
|
||||
title: "Server-sent events"
|
||||
description: "Home Assistant Server-sent events documentation"
|
||||
date: 2016-04-08 07:00
|
||||
sidebar: false
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
|
||||
@ -1 +0,0 @@
|
||||
<script>document.location = '/developers/website/';</script>
|
||||
@ -3,7 +3,7 @@ layout: page
|
||||
title: "Website home-assistant.io"
|
||||
description: "home-assistant.io web presence"
|
||||
date: 2015-06-17 08:00
|
||||
sidebar: false
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user