diff --git a/Gemfile b/Gemfile index f213d9565a3..85457e9947c 100644 --- a/Gemfile +++ b/Gemfile @@ -15,6 +15,7 @@ group :development do gem 'execjs' gem 'therubyracer', :platforms => :ruby gem 'coderay' + gem 'pry' end group :jekyll_plugins do diff --git a/Gemfile.lock b/Gemfile.lock index a31cd5b321c..edcea1a3d9a 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -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) diff --git a/plugins/active_link.rb b/plugins/active_link.rb new file mode 100644 index 00000000000..15dd8273c24 --- /dev/null +++ b/plugins/active_link.rb @@ -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'" : '' + "#{@title}" + end + end +end + +Liquid::Template.register_tag('active_link', Jekyll::ActiveLinkTag) diff --git a/sass/custom/_paulus.scss b/sass/custom/_paulus.scss index 56e200dd4cb..807d70631b9 100644 --- a/sass/custom/_paulus.scss +++ b/sass/custom/_paulus.scss @@ -411,3 +411,8 @@ p.note { margin-bottom: 8px; font-size: .8em; } + +ul.sidebar-menu a.active { + color: #000; + font-weight: bold; +} diff --git a/source/_includes/asides/developers_navigation.html b/source/_includes/asides/developers_navigation.html new file mode 100644 index 00000000000..14174ade9c5 --- /dev/null +++ b/source/_includes/asides/developers_navigation.html @@ -0,0 +1,44 @@ +
+ {% include edit_github.html %} + +
+

Development Guide

+ +
+
diff --git a/source/_includes/custom/navigation.html b/source/_includes/custom/navigation.html index 7f90d7cc0bd..02c0394a6ee 100644 --- a/source/_includes/custom/navigation.html +++ b/source/_includes/custom/navigation.html @@ -11,23 +11,8 @@
  • Components
    • -
  • Examples
    • -
  • - Developers - -
    • +
  • Examples
    • +
  • Developers
  • Blog
  • Need help?
    • diff --git a/source/_includes/edit_github.html b/source/_includes/edit_github.html index 51600423fc3..95f3b4c0977 100644 --- a/source/_includes/edit_github.html +++ b/source/_includes/edit_github.html @@ -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' %}
    Edit this page on GitHub
    -{% endif %} \ No newline at end of file +{% endif %} diff --git a/source/_includes/site/sidebar.html b/source/_includes/site/sidebar.html index e7b0e2dbaaa..b0282fd3369 100644 --- a/source/_includes/site/sidebar.html +++ b/source/_includes/site/sidebar.html @@ -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 %} diff --git a/source/_layouts/default.html b/source/_layouts/default.html index 1991e6ec968..d8dbf9ae450 100644 --- a/source/_layouts/default.html +++ b/source/_layouts/default.html @@ -36,11 +36,6 @@ {% include site/footer.html %} - - {% include javascripts/scripts.html %} - \ No newline at end of file diff --git a/source/_layouts/page.html b/source/_layouts/page.html index 9701938066a..faaa20dece7 100644 --- a/source/_layouts/page.html +++ b/source/_layouts/page.html @@ -3,10 +3,7 @@ layout: default ---
    - {% 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 %}
    diff --git a/source/developers/add_new_platform.html b/source/developers/add_new_platform.html deleted file mode 100644 index 50ffdbb0745..00000000000 --- a/source/developers/add_new_platform.html +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/source/developers/add_new_platform.markdown b/source/developers/add_new_platform.markdown index 439fdadfa60..0e17acc7a0c 100644 --- a/source/developers/add_new_platform.markdown +++ b/source/developers/add_new_platform.markdown @@ -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). - -

    -This option is currently limited to built-in components. -

    diff --git a/source/developers/api.html b/source/developers/api.html deleted file mode 100644 index 0c882b8e930..00000000000 --- a/source/developers/api.html +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/source/developers/api.markdown b/source/developers/api.markdown deleted file mode 100644 index dd2edce9be9..00000000000 --- a/source/developers/api.markdown +++ /dev/null @@ -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). - diff --git a/source/developers/architecture.html b/source/developers/architecture.html deleted file mode 100644 index 4a7b0f2e9df..00000000000 --- a/source/developers/architecture.html +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/source/developers/architecture.markdown b/source/developers/architecture.markdown index 7da43611436..68ceb355552 100644 --- a/source/developers/architecture.markdown +++ b/source/developers/architecture.markdown @@ -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 Overview of the Home Assistant core architecture

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

    - - - - Overview of the full Home Assistant architecture with a couple of loaded components and platforms. -

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

    - - - - Overview of the Home Assistant architecture for multiple devices. -

    - -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() -``` - -

    -Because each slave maintains its own Service Registry it is possible to have multiple slaves respond to one service call. -

    diff --git a/source/developers/architecture_components.markdown b/source/developers/architecture_components.markdown new file mode 100644 index 00000000000..a2f7f056bed --- /dev/null +++ b/source/developers/architecture_components.markdown @@ -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. + +

    + + + + Overview of the full Home Assistant architecture with a couple of loaded components and platforms. +

    + +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. diff --git a/source/developers/creating_components.html b/source/developers/creating_components.html deleted file mode 100644 index 397b81b2243..00000000000 --- a/source/developers/creating_components.html +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/source/developers/creating_components.markdown b/source/developers/creating_components.markdown index 7dc8478925a..f869a434f9c 100644 --- a/source/developers/creating_components.markdown +++ b/source/developers/creating_components.markdown @@ -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 diff --git a/source/developers/credits.html b/source/developers/credits.html deleted file mode 100644 index edc81609998..00000000000 --- a/source/developers/credits.html +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/source/developers/credits.markdown b/source/developers/credits.markdown index c6ecb4585ee..fc63f4c7ed9 100644 --- a/source/developers/credits.markdown +++ b/source/developers/credits.markdown @@ -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 diff --git a/source/developers/development_environment.markdown b/source/developers/development_environment.markdown new file mode 100644 index 00000000000..ca34842238b --- /dev/null +++ b/source/developers/development_environment.markdown @@ -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/) + diff --git a/source/developers/frontend.html b/source/developers/frontend.html deleted file mode 100644 index 20ba1fc49cb..00000000000 --- a/source/developers/frontend.html +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/source/developers/frontend.markdown b/source/developers/frontend.markdown index 4bf7589a117..d6c2f759c9b 100644 --- a/source/developers/frontend.markdown +++ b/source/developers/frontend.markdown @@ -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 Polymer build architecture diagram Polymer build architecture diagram

    - -# {% 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. - -![Cards in the frontend](/images/frontend/frontend-cards1.png) - -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. - -![Badges in the frontend](/images/frontend/frontend-badges.png) - -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 `` 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. - -

    - - The more info dialog for a light allows the user to control the color and the brightness. -

    - -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 `` to [more-info-content.html](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/more-infos/more-info-content.html) diff --git a/source/developers/frontend_add_card.markdown b/source/developers/frontend_add_card.markdown new file mode 100644 index 00000000000..8f39ed3232e --- /dev/null +++ b/source/developers/frontend_add_card.markdown @@ -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. + +![Cards in the frontend](/images/frontend/frontend-cards1.png) + +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. + +![Badges in the frontend](/images/frontend/frontend-badges.png) + +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 `` to [state-card-content.html](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/state-summary/state-card-content.html). \ No newline at end of file diff --git a/source/developers/frontend_add_more_info.markdown b/source/developers/frontend_add_more_info.markdown new file mode 100644 index 00000000000..38686a8172d --- /dev/null +++ b/source/developers/frontend_add_more_info.markdown @@ -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. + +

    + + The more info dialog for a light allows the user to control the color and the brightness. +

    + +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 `` to [more-info-content.html](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/more-infos/more-info-content.html) diff --git a/source/developers/index.markdown b/source/developers/index.markdown index d1cc8003612..769a8361ce4 100644 --- a/source/developers/index.markdown +++ b/source/developers/index.markdown @@ -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! diff --git a/source/developers/multiple_instances.markdown b/source/developers/multiple_instances.markdown new file mode 100644 index 00000000000..9774ccd0254 --- /dev/null +++ b/source/developers/multiple_instances.markdown @@ -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. + +

    + + + + Overview of the Home Assistant architecture for multiple devices. +

    + +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() +``` + +

    +Because each slave maintains its own Service Registry it is possible to have multiple slaves respond to one service call. +

    diff --git a/source/developers/platform_discovery.markdown b/source/developers/platform_discovery.markdown new file mode 100644 index 00000000000..78f19ffbb40 --- /dev/null +++ b/source/developers/platform_discovery.markdown @@ -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 +--- + +

    +This option is only available to built-in components. +

    + +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). diff --git a/source/developers/python_api.html b/source/developers/python_api.html deleted file mode 100644 index c5857548eed..00000000000 --- a/source/developers/python_api.html +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/source/developers/python_api.markdown b/source/developers/python_api.markdown index f40aec0aa17..d779562bbcc 100644 --- a/source/developers/python_api.markdown +++ b/source/developers/python_api.markdown @@ -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 diff --git a/source/developers/rest_api.html b/source/developers/rest_api.html deleted file mode 100644 index 59fcf663760..00000000000 --- a/source/developers/rest_api.html +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/source/developers/rest_api.markdown b/source/developers/rest_api.markdown index 610b18cad62..197c1d0648e 100644 --- a/source/developers/rest_api.markdown +++ b/source/developers/rest_api.markdown @@ -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 diff --git a/source/developers/server_sent_events.markdown b/source/developers/server_sent_events.markdown index b8f14537fc2..06a0048e127 100644 --- a/source/developers/server_sent_events.markdown +++ b/source/developers/server_sent_events.markdown @@ -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 diff --git a/source/developers/website.html b/source/developers/website.html deleted file mode 100644 index ddb4bd03585..00000000000 --- a/source/developers/website.html +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/source/developers/website.markdown b/source/developers/website.markdown index d1fcbe2ce9b..310295488d2 100644 --- a/source/developers/website.markdown +++ b/source/developers/website.markdown @@ -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