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

Site updated at 2017-03-18 17:12:07 UTC

Browse source
This commit is contained in:
Travis CI 2017-03-18 17:12:07 +00:00
parent 7573fcba68
commit 67179bf8fe
994 changed files with 1768 additions and 68252 deletions
Download patch file Download diff file Expand all files Collapse all files

49
developers/add_new_platform/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Adding support for a new platform - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Hints and tips for when you're adding a new platform to Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/add_new_platform/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Adding support for a new platform">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Hints and tips for when you're adding a new platform to Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Adding support for a new platform">
<meta name="twitter:description" content="Hints and tips for when you're adding a new platform to Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,70 +53,39 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Adding Support for a New Platform
</h1>
</header>
<hr class="divider">
<p>Components that interact with devices are called “<a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/entity_component.py">Entity Components</a>.” They are structured in core and platform logic, which means different brands can use the same logic to handle a light.</p>
<p>For example, the built-in <code class="highlighter-rouge">switch</code> component consists of various platforms in <a href="https://github.com/home-assistant/home-assistant/tree/master/homeassistant/components/switch"><code class="highlighter-rouge">homeassistant/components/switch/</code></a>. The file <code class="highlighter-rouge">__init__.py</code> contains the core logic of all platforms and the <code class="highlighter-rouge">vendor_name.py</code> files contain only the relevant platform code.</p>
<p>If you’re planning to add support for a new type of device to an existing component, you can get away with only writing platform logic. Have a look at how the component works with other platforms and create a similar file for the platform that you want to add:</p>
<ul>
<li><a href="/developers/platform_example_sensor">Example sensor platform</a>: hello world of platforms.</li>
<li><a href="/developers/platform_example_light">Example light platform</a>: showing best practices.</li>
</ul>
<h3><a class="title-link" name="interfacing-with-devices" href="#interfacing-with-devices"></a> Interfacing with devices</h3>
<p>One Home Assistant rule is that platform logic should never interface directly with devices. Instead, use a third-party Python 3 library. This way, Home Assistant can share code with the Python community and keep the project maintainable.</p>
<p>To integrate the third-party library, create an <a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/entity.py">Entity class</a> for your device. Entities are Home Assistant’s representations of lights, switches, sensors, etc. and are derived from the <a href="https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/entity.py">Entity Abstract Class</a>. This abstract class contains logic for integrating most standard features into your entities, such as visibility, entity IDs, updates, and much more.</p>
<h3><a class="title-link" name="requirements-and-dependencies" href="#requirements-and-dependencies"></a> Requirements and dependencies</h3>
<p>Platforms can specify dependencies and requirements <a href="/developers/component_deps_and_reqs">the same way as components</a>:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">REQUIREMENTS</span> <span class="o">=</span> <span class="p">[</span><span class="s">'some-package==2.0.0'</span><span class="p">,</span> <span class="s">'some-other-package==2.5.0'</span><span class="p">]</span>
<span class="n">DEPENDENCIES</span> <span class="o">=</span> <span class="p">[</span><span class="s">'mqtt'</span><span class="p">]</span>
</code></pre>
</div>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/add_new_platform.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -216,13 +174,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -232,7 +187,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -244,7 +198,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -252,4 +205,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

41
developers/api/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>API - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Home Assistant API">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/api/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="API">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Home Assistant API">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="API">
<meta name="twitter:description" content="Home Assistant API">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,53 +53,30 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
API
</h1>
</header>
<hr class="divider">
<p>Home Assistant provides various APIs. For detail please refer to <a href="https://dev-docs.home-assistant.io/en/dev/">Home Assistant API</a> documentation.</p>
<ul>
<li><a href="/developers/websocket_api/">Websocket API</a></li>
<li><a href="/developers/rest_api/">RESTful API</a></li>
<li><a href="/developers/python_api/">Python API</a></li>
<li><a href="/developers/server_sent_events/">Server-sent events</a></li>
</ul>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/api.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -199,13 +165,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -215,7 +178,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -227,7 +189,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -235,4 +196,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

45
developers/architecture/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Architecture - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Overview of the Home Assistant architecture.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/architecture/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Architecture">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Overview of the Home Assistant architecture.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Architecture">
<meta name="twitter:description" content="Overview of the Home Assistant architecture.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,76 +53,49 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Architecture
</h1>
</header>
<hr class="divider">
<p>Before we dive into the Home Assistant architecture, let’s get a clear overview of the home automation landscape as a whole. This way, we can show how the different parts of Home Assistant fit into the picture.</p>
<p>For more information about each part in this overview, <a href="/blog/2014/12/26/home-control-home-automation-and-the-smart-home/">check out our blog</a>. Here’s the tl;dr version of the blog:</p>
<ul>
<li>Home Control is responsible for collecting information and controlling devices.</li>
<li>Home Automation triggers commands based on user configurations.</li>
<li>Smart Home triggers commands based on previous behaviour.</li>
</ul>
<p class="img">
<a href="/images/architecture/home_automation_landscape.png" name="landscape">
<img alt="Home Automation landscape" src="/images/architecture/home_automation_landscape.png" />
</a>
Overview of the home automation landscape
</p>
<p>The Home Assistant core is responsible for Home Control. Home Assistant contains four parts which make this possible:</p>
<ul>
<li><strong>Event Bus</strong>: facilitates the firing and listening of events – the beating heart of Home Assistant.</li>
<li><strong>State Machine</strong>: keeps track of the states of things and fires a <code class="highlighter-rouge">state_changed</code> event when a state has been changed.</li>
<li><strong>Service Registry</strong>: listens on the event bus for <code class="highlighter-rouge">call_service</code> events and allows other code to register services.</li>
<li><strong>Timer</strong>: sends a <code class="highlighter-rouge">time_changed</code> event every 1 second on the event bus.</li>
</ul>
<p class="img">
<a href="/images/architecture/ha_architecture.png" name="architecture">
<img src="/images/architecture/ha_architecture.png" />
</a>
Overview of the Home Assistant core architecture
</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/architecture.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -222,13 +184,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -238,7 +197,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -250,7 +208,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -258,4 +215,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

65
developers/architecture_components/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Components Architecture - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Overview of components within the Home Assistant architecture.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/architecture_components/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Components Architecture">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Overview of components within the Home Assistant architecture.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Components Architecture">
<meta name="twitter:description" content="Overview of components within the Home Assistant architecture.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,96 +53,55 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Components Architecture
</h1>
</header>
<hr class="divider">
<p>Home Assistant can be extended with <strong>components</strong>. 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 <a href="/components/">built-in components</a>.</p>
<p class="img">
<img src="/images/architecture/component_interaction.png" alt="Diagram showing interaction between components and the Home Assistant core." />
Diagram showing interaction between components and the Home Assistant core
</p>
<p>There are two types of components within Home Assistant: components that interact with an Internet of Things domain, and components that respond to events that happen within Home Assistant. Read on to learn about each type!</p>
<h4><a class="title-link" name="components-that-interact-with-an-internet-of-things-domain" href="#components-that-interact-with-an-internet-of-things-domain"></a> Components that interact with an Internet-of-Things domain</h4>
<p>These components 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 components also register services in the Service Registry to expose control of the devices.</p>
<p>For example, the built-in <a href="/components/switch/"><code class="highlighter-rouge">switch</code> component</a> is responsible for interaction with different types of switches. A platform provides support for a particular kind or 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.</p>
<p>If you want to add support for a new platform, check out the <a href="/developers/add_new_platform/">add new platform section</a>.</p>
<h4><a class="title-link" name="components-that-respond-to-events-that-happen-within-home-assistant" href="#components-that-respond-to-events-that-happen-within-home-assistant"></a> Components that respond to events that happen within Home Assistant</h4>
<p>These components provide small pieces of home automation logic or involve services that do common tasks within your house.</p>
<p>For example, the <a href="/components/device_sun_light_trigger/"><code class="highlighter-rouge">device_sun_light_trigger</code> component</a> tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and people are home. The component uses logic like this:</p>
<pre><code class="language-plain"> In the event that device 'Paulus Nexus 5' changes to the 'Home' state:
<p>For example, the <a href="/components/device_sun_light_trigger/"><code class="highlighter-rouge">device_sun_light_trigger</code> component</a> tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and people are home. The component uses logic like this:</p><pre><code class="language-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
</code></pre>
<pre><code class="language-plain"> In the event that the combined state of all tracked devices changes to 'Not Home':
</code></pre><pre><code class="language-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
</code></pre>
<pre><code class="language-plain"> In the event of the sun setting:
</code></pre><pre><code class="language-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
</code></pre>
<p>Look <a href="https://github.com/home-assistant/home-assistant/blob/master/config/custom_components/example.py">here</a> for a comprehensive example of a home automation component.</p>
<h3><a class="title-link" name="the-full-picture" href="#the-full-picture"></a> The full picture</h3>
<p>When we put all the different pieces of Home Assistant together, it’s a close match for the initial home automation overview sketch. The smart home AI has not been implemented yet, so it’s not included in this picture.</p>
<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>
<p>The platform logic for components uses third-party Python libraries to communicate with the devices. Through this, we can leverage some of the best libraries in the Python community.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/architecture_components.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -242,13 +190,10 @@ Diagram showing interaction between components and the Home Assistant core
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -258,7 +203,6 @@ Diagram showing interaction between components and the Home Assistant core
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -270,7 +214,6 @@ Diagram showing interaction between components and the Home Assistant core
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -278,4 +221,4 @@ Diagram showing interaction between components and the Home Assistant core
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

46
developers/asyncio/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Asynchronous Programming - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Introduction to the asynchronous core of Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/asyncio/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Asynchronous Programming">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Introduction to the asynchronous core of Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Asynchronous Programming">
<meta name="twitter:description" content="Introduction to the asynchronous core of Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,58 +53,30 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Asynchronous Programming
</h1>
</header>
<hr class="divider">
<p>On September 29, 2016 we released <a href="https://home-assistant.io/blog/2016/09/29/async-sleepiq-emoncms-stocks/">Home Assistant 0.29</a> as part of our bi-weekly release schedule. This release introduced a complete overhaul of the core spearheaded by <a href="https://github.com/bbangert/">Ben Bangert</a>.</p>
<p>The old core was set up like a “traditional” threaded application. Each resource that was not thread safe (ie. the state of entities) would be protected by a lock. This caused a lot of waiting and potential inconsistency because a task could now end up waiting halfway through its job until some resource got freed.</p>
<p>Our new core is based on an Python’s built-in asyncio module. Instead of having all threads have access to the core API objects, access is now limited to a special thread called the event loop. All components will now schedule themselves as a task to be executed by the event loop. This gives us the guarantee that only one task is executed at once, meaning we no longer need any locks.</p>
<p>The only problem with running everything inside the event loop is when a task is doing blocking I/O, what most third-party Python libraries are doing. For example while requesting new information from a device, the core will stop running until we get a response from the device. To handle this, a task is able to suspend itself until the response is available after which it will be enqueued for the event loop to process the result.</p>
<p>For a task to be able to suspend itself, all code that it calls has to have this capability added. This means in practice that each device integration will need a full rewrite of the library that offers the integration! As this is not something that can be achieved, ever, a 100% backwards compatible API has been added so that no platform will require updating.</p>
<p>The backwards compatible API works by scheduling a task from a different thread and blocking that thread until the task has been processed by the event loop.</p>
<h3><a href="/developers/asyncio_categorizing_functions/">Next step: Categorizing Functions »</a></h3>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/asyncio.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -204,13 +165,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -220,7 +178,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -232,7 +189,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -240,4 +196,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

63
developers/asyncio_categorizing_functions/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Categorizing Functions - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="A categorization of functions to work with the asynchronous core of Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/asyncio_categorizing_functions/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Categorizing Functions">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="A categorization of functions to work with the asynchronous core of Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Categorizing Functions">
<meta name="twitter:description" content="A categorization of functions to work with the asynchronous core of Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,44 +53,25 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Categorizing Functions
</h1>
</header>
<hr class="divider">
<p>A piece of work within Home Assistant is represented by a function that will be invoked. It will either run inside our event loop or inside our thread pool, depending on if it is async safe.</p>
<p>Home Assistant uses the convention that all functions that must be run from within the event loop are prefixed with <code class="highlighter-rouge">async_</code>.</p>
<h2><a class="title-link" name="the-coroutine-function" href="#the-coroutine-function"></a> The coroutine function</h2>
<p>Coroutines are special functions based on Python’s generators syntax which allows them to suspend execution while waiting on a result.</p>
<p>Invoking a coroutine function will return a Generator object back, but will not actually begin execution. This object will execute the task when it is either yielded from (from within another coroutine) or it is scheduled on the event loop.</p>
<p>To declare a function a coroutine, import the coroutine annotation from the asyncio package and annotate your function.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">asyncio</span>
<span class="nd">@asyncio.coroutine</span>
@ -113,17 +83,11 @@
<span class="n">hass</span><span class="o">.</span><span class="n">loop</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span><span class="n">async_look_my_coroutine</span><span class="p">(</span><span class="s">"world"</span><span class="p">)</span>
</code></pre>
</div>
<p>In this example, we schedule the coroutine by calling <code class="highlighter-rouge">hass.loop.create_task</code>. This will add the coroutine to the queue of tasks to be run. When the event loop is running <code class="highlighter-rouge">async_look_my_coroutine</code> it will suspend the task when <code class="highlighter-rouge">yield from entity.async_turn_on()</code> is called. At that point a new task will be scheduled to execute <code class="highlighter-rouge">entity.async_turn_on()</code>. When that job has been executed, <code class="highlighter-rouge">async_look_my_coroutine</code> will resume.</p>
<h2><a class="title-link" name="the-callback-function" href="#the-callback-function"></a> The callback function</h2>
<p>This is a normal function that is considered safe to be run from within the event loop. A callback is unable to suspend itself and thus cannot do any I/O or call a coroutine. A callback is capable of scheduling a new task but it will not be able to wait for the results.</p>
<p>To declare a function as a callback, import the callback annotation from the core package and annotate your function.</p>
<p>A common use case for a callback in Home Assistant is as a listener for an event or a service call. It can process the incoming information and then schedule the right calls to be made. Example from the automation component.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">from</span> <span class="nn">homeassistant.core</span> <span class="kn">import</span> <span class="n">callback</span>
<span class="nd">@callback</span>
@ -134,42 +98,22 @@
<span class="n">hass</span><span class="o">.</span><span class="n">loop</span><span class="o">.</span><span class="n">create_task</span><span class="p">(</span><span class="n">entity</span><span class="o">.</span><span class="n">async_trigger</span><span class="p">(</span><span class="nb">vars</span><span class="p">,</span> <span class="bp">True</span><span class="p">))</span>
</code></pre>
</div>
<p>In this example, <code class="highlighter-rouge">entity.async_trigger</code> is a coroutine function. Invoking the coroutine function will return a coroutine task. The passed in parameters will be used when the task gets executed.</p>
<p>To execute the task we have to schedule it for execution on the event loop. This is done by calling <code class="highlighter-rouge">hass.loop.create_task</code>.</p>
<h3><a class="title-link" name="why-even-have-callbacks" href="#why-even-have-callbacks"></a> Why even have callbacks?</h3>
<p>You might wonder, if a coroutine can do everything a callback can do, why even have a callback. The reason is performance and better state consistency of the core API objects.</p>
<p>When coroutine A waits for coroutine B, it will suspend itself and schedule a new task to run B. This means that the event loop is now running A, B and then A again. If B is a callback, A will never have to suspend itself and thus the event loop is just running A. The consistency implication is that other events queued to run on the event loop continue to wait until callbacks complete, but will be interleaved when yielding to another coroutine.</p>
<h2><a class="title-link" name="event-loop-and-thread-safe" href="#event-loop-and-thread-safe"></a> Event loop and thread safe</h2>
<p>These are functions that are safe to run both in a thread and inside the event loop. These functions are usually performing a computation or transform data in memory. Anything that does I/O does not fall under this category. Many standard library functions fall in this category. For example generating the sum of a set of numbers using sum or merging two dictionaries.</p>
<p>There is no special annotation to mark functions as part of this category and care should be taken when using these functions from inside the event loop. When in doubt, look at their implementation.</p>
<h2><a class="title-link" name="other-functions" href="#other-functions"></a> Other functions</h2>
<p>These are all the functions that did not fit in the previous categories. These functions are either thread-safe or not considered safe to be run within the event loop. These are functions that use sleep, or perform I/O.</p>
<p>There is no special annotation necessary to be considered part of this category.</p>
<h3><a href="/developers/asyncio_working_with_async/">Next step: Working with Async »</a></h3>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/asyncio_categorizing_functions.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -258,13 +202,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -274,7 +215,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -286,7 +226,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -294,4 +233,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

43
developers/asyncio_misc/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Miscellaneous Async - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="A collection of miscellaneous topics about async that didn't fit on the other pages.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/asyncio_misc/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Miscellaneous Async">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="A collection of miscellaneous topics about async that didn't fit on the other pages.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Miscellaneous Async">
<meta name="twitter:description" content="A collection of miscellaneous topics about async that didn't fit on the other pages.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,53 +53,28 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Miscellaneous Async
</h1>
</header>
<hr class="divider">
<h2><a class="title-link" name="what-about-async-and-await-syntax" href="#what-about-async-and-await-syntax"></a> What about ‘async’ and ‘await’ syntax?</h2>
<p>Python 3.5 introduced new syntax to formalize the asynchronous pattern. This is however not compatible with Python 3.4. The minimum required Python version for Home Assistant is based on the Python version shipped with Debian stable, which is currently 3.4.2.</p>
<p>For more information, Brett Cannon wrote <a href="http://www.snarky.ca/how-the-heck-does-async-await-work-in-python-3-5">an excellent breakdown</a> on ‘async’ and ‘await’ syntax and how asynchronous programming works.</p>
<h2><a class="title-link" name="acknowledgements" href="#acknowledgements"></a> Acknowledgements</h2>
<p>Huge thanks to <a href="https://github.com/bbangert/">Ben Bangert</a> for starting the conversion of the core to async, guiding other contributors while taking their first steps with async programming and peer reviewing this documentation.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/asyncio_misc.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -199,13 +163,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -215,7 +176,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -227,7 +187,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -235,4 +194,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

74
developers/asyncio_working_with_async/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Working with Async - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="A breakdown of all the different ways to work with the asynchronous core of Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/asyncio_working_with_async/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Working with Async">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="A breakdown of all the different ways to work with the asynchronous core of Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Working with Async">
<meta name="twitter:description" content="A breakdown of all the different ways to work with the asynchronous core of Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,51 +53,30 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Working With Async
</h1>
</header>
<hr class="divider">
<p>Although we have a backwards compatible API, using the async core directly will be a lot faster. Most core components have already been rewritten to leverage the async core. This includes the EntityComponent helper (foundation of light, switch, etc), scripts, groups and automation.</p>
<h2><a class="title-link" name="interacting-with-the-core" href="#interacting-with-the-core"></a> Interacting with the core</h2>
<p><a href="https://dev-docs.home-assistant.io/en/master/api/core.html">All methods in the Home Assistant core</a> are implemented in two flavors: an async version and a version to be called from other threads. The versions for other are merely wrappers that call the async version in a threadsafe manner using <a href="https://dev-docs.home-assistant.io/en/dev/api/util.html#module-homeassistant.util.async">the available async utilities</a>.</p>
<p>So if you are making calls to the core (the hass object) from within a callback or coroutine, use the methods that start with async_. If you need to call an async_ function that is a coroutine, your task must also be a coroutine.</p>
<h2><a class="title-link" name="implementing-an-async-component" href="#implementing-an-async-component"></a> Implementing an async component</h2>
<p>To make a component async, implement an async_setup.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="k">def</span> <span class="nf">setup</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="n">config</span><span class="p">):</span>
<span class="c"># Setup your component outside of the event loop.</span>
</code></pre>
</div>
<p>Will turn into:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">asyncio</span>
<span class="nd">@asyncio.coroutine</span>
@ -116,18 +84,13 @@
<span class="c"># Setup your component inside of the event loop.</span>
</code></pre>
</div>
<h2><a class="title-link" name="implementing-an-async-platform" href="#implementing-an-async-platform"></a> Implementing an async platform</h2>
<p>For platforms we support async setup. Instead of setup_platform you need to have a coroutine async_setup_platform.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">setup_platform</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="n">config</span><span class="p">,</span> <span class="n">add_entities</span><span class="p">,</span> <span class="n">discovery_info</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="c"># Setup your platform outside of the event loop.</span>
</code></pre>
</div>
<p>Will turn into:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">asyncio</span>
<span class="nd">@asyncio.coroutine</span>
@ -136,22 +99,16 @@
<span class="c"># Setup your platform inside of the event loop</span>
</code></pre>
</div>
<p>The only difference with the original parameters is that the add_entities function has been replaced by the async friendly callback <code class="highlighter-rouge">async_add_entities</code>.</p>
<h2><a class="title-link" name="implementing-an-async-entity" href="#implementing-an-async-entity"></a> Implementing an async entity</h2>
<p>You can make your entity async friendly by converting your update method to be async. This requires the dependency of your entities to also be async friendly!</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="k">class</span> <span class="nc">MyEntity</span><span class="p">(</span><span class="n">Entity</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">update</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="s">"""Retrieve latest state."""</span>
<span class="bp">self</span><span class="o">.</span><span class="n">_state</span> <span class="o">=</span> <span class="n">fetch_state</span><span class="p">()</span>
</code></pre>
</div>
<p>Will turn into:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">asyncio</span>
<span class="k">class</span> <span class="nc">MyEntity</span><span class="p">(</span><span class="n">Entity</span><span class="p">):</span>
@ -161,15 +118,10 @@
<span class="bp">self</span><span class="o">.</span><span class="n">_state</span> <span class="o">=</span> <span class="k">yield</span> <span class="k">from</span> <span class="n">async_fetch_state</span><span class="p">()</span>
</code></pre>
</div>
<p>Make sure that all properties defined on your entity do not result in I/O being done. All data has to be fetched inside the update method and cached on the entity. This is because these properties are read from within the event loop and thus doing I/O will result in the core of Home Assistant waiting until your I/O is done.</p>
<h2><a class="title-link" name="calling-async-functions-from-threads" href="#calling-async-functions-from-threads"></a> Calling async functions from threads</h2>
<p>Sometimes it will happen that you’re in a thread and you want to call a function that is only available as async. Home Assistant includes a few async helper utilities to help with this.</p>
<p>In the following example, <code class="highlighter-rouge">say_hello</code> will schedule <code class="highlighter-rouge">async_say_hello</code> and block till the function has run and get the result back.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">from</span> <span class="nn">homeassistant.util.async</span> <span class="kn">import</span> <span class="n">run_callback_threadsafe</span>
<span class="k">def</span> <span class="nf">say_hello</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="n">target</span><span class="p">):</span>
@ -180,17 +132,11 @@
<span class="k">return</span> <span class="s">"Hello {}!"</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">target</span><span class="p">)</span>
</code></pre>
</div>
<h2><a class="title-link" name="dealing-with-passed-in-functions" href="#dealing-with-passed-in-functions"></a> Dealing with passed in functions</h2>
<p>If your code takes in functions from other code, you will not know which category the function belongs to and how they should be invoked. This usually only occurs if your code supplies an event helper like <code class="highlighter-rouge">mqtt.async_subscribe</code> or <code class="highlighter-rouge">track_state_change_listener</code>.</p>
<p>To help with this, there are two helper methods on the hass object that you can call from inside the event loop:</p>
<h4><a class="title-link" name="hassasync_run_job" href="#hassasync_run_job"></a> hass.async_run_job</h4>
<p>Use this method if the function should be called as soon as possible. This will call callbacks immediately, schedule coroutines for execution on the event loop and schedule other functions to be run inside the thread pool.</p>
<table>
<tbody>
<tr>
@ -207,11 +153,8 @@
</tr>
</tbody>
</table>
<h4><a class="title-link" name="hassasync_add_job" href="#hassasync_add_job"></a> hass.async_add_job</h4>
<p>Use this method if the function should be called but not get priority over already scheduled calls.</p>
<table>
<tbody>
<tr>
@ -228,21 +171,11 @@
</tr>
</tbody>
</table>
<h3><a href="/developers/asyncio_misc/">Next step: Miscellaneous »</a></h3>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/asyncio_working_with_async.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -331,13 +264,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -347,7 +277,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -359,7 +288,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -367,4 +295,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

47
developers/cla/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Contributor License Agreement - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="The Code of Conduct for Home Assistant projects.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/cla/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Contributor License Agreement">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="The Code of Conduct for Home Assistant projects.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Contributor License Agreement">
<meta name="twitter:description" content="The Code of Conduct for Home Assistant projects.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,34 +53,20 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Contributor License Agreement
</h1>
</header>
<hr class="divider">
<h1>Contributor License Agreement</h1>
<div class="highlighter-rouge"><pre class="highlight"><code>By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
@ -114,32 +89,17 @@
source license(s) involved.
</code></pre>
</div>
<h2>Attribution</h2>
<p>The text of this license is available under the <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>. It is based on the Linux <a href="http://elinux.org/Developer_Certificate_Of_Origin">Developer Certificate Of Origin</a>, but is modified to explicitly use the Apache 2.0 license
and not mention sign-off.</p>
<h2>Signing</h2>
<p>If you have not signed the CLA and you submit a pull request to a repository under the Home Assistant organization, a link will be automatically generated. Just follow the link and the instructions in the link.</p>
<h2>Adoption</h2>
<p>This Contributor License Agreement (CLA) was first announced on January 21st, 2017 in <a href="https://home-assistant.io/blog/2017/01/21/home-assistant-governance/">this</a> blog post and adopted January 28th, 2017.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/cla.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -228,13 +188,10 @@ and not mention sign-off.</p>
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -244,7 +201,6 @@ and not mention sign-off.</p>
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -256,7 +212,6 @@ and not mention sign-off.</p>
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -264,4 +219,4 @@ and not mention sign-off.</p>
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

62
developers/cla_sign/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>CLA Signature - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="The Home Assistant contributor license agreement (CLA) signature page">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/cla_sign/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="CLA Signature">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="The Home Assistant contributor license agreement (CLA) signature page">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="CLA Signature">
<meta name="twitter:description" content="The Home Assistant contributor license agreement (CLA) signature page">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,32 +53,19 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
CLA Signature
</h1>
</header>
<hr class="divider">
<style type="text/css">
.wrapper div {
margin-bottom: 15px;
@ -100,29 +76,23 @@
div > input[type='text'], div > input[type='email'] {
width: 77%;
}
div > label {
width: 20%;
}
#company_name_group {
display: none;
}
#signature_form {
display: none;
}
#complete {
display: none;
}
</style>
<div id="loading">
<div id="spinner"></div>
<p>Please wait while we complete authentication and load data from GitHub...</p>
</div>
<form action="#" id="signature_form">
<div class="wrapper">
<div>
@ -161,19 +131,16 @@
<button type="submit" class="btn btn-danger" id="submit">Sign CLA</button>
</div>
</form>
<div id="complete">
<h1>Thanks!</h1>
<p>Thank you for signing the Home Assistant Contributor license agreement. We are now redirecting you back to your pull request.</p>
</div>
<script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="https://unpkg.com/github-api/dist/GitHub.bundle.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/spin.js/2.3.2/spin.min.js" integrity="sha256-PieqE0QdEDMppwXrTzSZQr6tWFX3W5KkyRVyF1zN3eg=" crossorigin="anonymous"></script>
<script type="text/javascript">
// Countries
var country_arr = new Array("Afghanistan", "Albania", "Algeria", "American Samoa", "Angola", "Anguilla", "Antartica", "Antigua and Barbuda", "Argentina", "Armenia", "Aruba", "Ashmore and Cartier Island", "Australia", "Austria", "Azerbaijan", "Bahamas", "Bahrain", "Bangladesh", "Barbados", "Belarus", "Belgium", "Belize", "Benin", "Bermuda", "Bhutan", "Bolivia", "Bosnia and Herzegovina", "Botswana", "Brazil", "British Virgin Islands", "Brunei", "Bulgaria", "Burkina Faso", "Burma", "Burundi", "Cambodia", "Cameroon", "Canada", "Cape Verde", "Cayman Islands", "Central African Republic", "Chad", "Chile", "China", "Christmas Island", "Clipperton Island", "Cocos (Keeling) Islands", "Colombia", "Comoros", "Congo, Democratic Republic of the", "Congo, Republic of the", "Cook Islands", "Costa Rica", "Cote d'Ivoire", "Croatia", "Cuba", "Cyprus", "Czeck Republic", "Denmark", "Djibouti", "Dominica", "Dominican Republic", "Ecuador", "Egypt", "El Salvador", "Equatorial Guinea", "Eritrea", "Estonia", "Ethiopia", "Europa Island", "Falkland Islands (Islas Malvinas)", "Faroe Islands", "Fiji", "Finland", "France", "French Guiana", "French Polynesia", "French Southern and Antarctic Lands", "Gabon", "Gambia, The", "Gaza Strip", "Georgia", "Germany", "Ghana", "Gibraltar", "Glorioso Islands", "Greece", "Greenland", "Grenada", "Guadeloupe", "Guam", "Guatemala", "Guernsey", "Guinea", "Guinea-Bissau", "Guyana", "Haiti", "Heard Island and McDonald Islands", "Holy See (Vatican City)", "Honduras", "Hong Kong", "Howland Island", "Hungary", "Iceland", "India", "Indonesia", "Iran", "Iraq", "Ireland", "Ireland, Northern", "Israel", "Italy", "Jamaica", "Jan Mayen", "Japan", "Jarvis Island", "Jersey", "Johnston Atoll", "Jordan", "Juan de Nova Island", "Kazakhstan", "Kenya", "Kiribati", "Korea, North", "Korea, South", "Kuwait", "Kyrgyzstan", "Laos", "Latvia", "Lebanon", "Lesotho", "Liberia", "Libya", "Liechtenstein", "Lithuania", "Luxembourg", "Macau", "Macedonia, Former Yugoslav Republic of", "Madagascar", "Malawi", "Malaysia", "Maldives", "Mali", "Malta", "Man, Isle of", "Marshall Islands", "Martinique", "Mauritania", "Mauritius", "Mayotte", "Mexico", "Micronesia, Federated States of", "Midway Islands", "Moldova", "Monaco", "Mongolia", "Montserrat", "Morocco", "Mozambique", "Namibia", "Nauru", "Nepal", "Netherlands", "Netherlands Antilles", "New Caledonia", "New Zealand", "Nicaragua", "Niger", "Nigeria", "Niue", "Norfolk Island", "Northern Mariana Islands", "Norway", "Oman", "Pakistan", "Palau", "Panama", "Papua New Guinea", "Paraguay", "Peru", "Philippines", "Pitcaim Islands", "Poland", "Portugal", "Puerto Rico", "Qatar", "Reunion", "Romainia", "Russia", "Rwanda", "Saint Helena", "Saint Kitts and Nevis", "Saint Lucia", "Saint Pierre and Miquelon", "Saint Vincent and the Grenadines", "Samoa", "San Marino", "Sao Tome and Principe", "Saudi Arabia", "Scotland", "Senegal", "Seychelles", "Sierra Leone", "Singapore", "Slovakia", "Slovenia", "Solomon Islands", "Somalia", "South Africa", "South Georgia and South Sandwich Islands", "Spain", "Spratly Islands", "Sri Lanka", "Sudan", "Suriname", "Svalbard", "Swaziland", "Sweden", "Switzerland", "Syria", "Taiwan", "Tajikistan", "Tanzania", "Thailand", "Tobago", "Toga", "Tokelau", "Tonga", "Trinidad", "Tunisia", "Turkey", "Turkmenistan", "Tuvalu", "Uganda", "Ukraine", "United Arab Emirates", "United Kingdom", "Uruguay", "United States of America", "Uzbekistan", "Vanuatu", "Venezuela", "Vietnam", "Virgin Islands", "Wales", "Wallis and Futuna", "West Bank", "Western Sahara", "Yemen", "Yugoslavia", "Zambia", "Zimbabwe");
// States
var s_a = new Array();
s_a[0] = "";
@ -431,25 +398,17 @@
s_a[250] = "Kosovo|Montenegro|Serbia|Vojvodina";
s_a[251] = "Central|Copperbelt|Eastern|Luapula|Lusaka|North-Western|Northern|Southern|Western";
s_a[252] = "Bulawayo|Harare|ManicalandMashonaland Central|Mashonaland East|Mashonaland West|Masvingo|Matabeleland North|Matabeleland South|Midlands";
function populateStates(countryElementId, stateElementId) {
var selectedCountryIndex = document.getElementById(countryElementId).selectedIndex;
var stateElement = document.getElementById(stateElementId);
stateElement.length = 0; // Fixed by Julian Woods
stateElement.options[0] = new Option('Select State', '');
stateElement.selectedIndex = 0;
var state_arr = s_a[selectedCountryIndex].split("|");
for (var i = 0; i < state_arr.length; i++) {
stateElement.options[stateElement.length] = new Option(state_arr[i], state_arr[i]);
}
}
function populateCountries(countryElementId, stateElementId) {
// given the id of the <select> tag as function argument, it inserts <option> tags
var countryElement = document.getElementById(countryElementId);
@ -460,9 +419,7 @@
}
countryElement.selectedIndex = 239; // USA
populateStates(countryElementId, stateElementId);
// Assigned all countries. Now assign event listener for the states.
if (stateElementId) {
countryElement.onchange = function () {
populateStates(countryElementId, stateElementId);
@ -470,9 +427,7 @@
}
}
</script>
<script type="text/javascript">
function fill_fields(){
var token = localStorage.getItem("gh_token");
var gh = new GitHub({ token: token });
@ -498,13 +453,11 @@
});
});
}
function qs(key) {
key = key.replace(/[*+?^$.\[\]{}()|\\\/]/g, "\\$&"); // escape RegEx meta chars
var match = location.search.match(new RegExp("[?&]"+key+"=([^&]+)(&|$)"));
return match && decodeURIComponent(match[1].replace(/\+/g, " "));
}
$(document).ready(function(){
populateCountries("country", "region");
var spinner = new Spinner().spin(document.getElementById('spinner'));
@ -576,18 +529,10 @@
});
});
</script>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/cla_sign.html'>Edit this page on GitHub</a></div>
<div class='section'>
@ -676,13 +621,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -692,7 +634,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -704,7 +645,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -712,4 +652,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

40
developers/cla_sign_start/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>CLA Login - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="The Home Assistant contributor license agreement (CLA) signature page">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/cla_sign_start/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="CLA Login">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="The Home Assistant contributor license agreement (CLA) signature page">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="CLA Login">
<meta name="twitter:description" content="The Home Assistant contributor license agreement (CLA) signature page">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,36 +53,22 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
CLA Login
</h1>
</header>
<hr class="divider">
<p style="text-align: center">Please wait while we begin the signature process...</p>
<br>
<div id="spinner"></div>
<script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/spin.js/2.3.2/spin.min.js" integrity="sha256-PieqE0QdEDMppwXrTzSZQr6tWFX3W5KkyRVyF1zN3eg=" crossorigin="anonymous"></script>
<script type="text/javascript">
@ -106,18 +81,10 @@ $(document).ready(function(){
window.location = "https://github.com/login/oauth/authorize?client_id=44151bab2be25f885aa7&response_type=code&scope=user%3Aemail&redirect_uri=https%3A%2F%2Fhome-assistant.io%2Fdevelopers%2Fcla_sign%2F"
});
</script>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/cla_sign_start.html'>Edit this page on GitHub</a></div>
<div class='section'>
@ -206,13 +173,10 @@ $(document).ready(function(){
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -222,7 +186,6 @@ $(document).ready(function(){
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -234,7 +197,6 @@ $(document).ready(function(){
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -242,4 +204,4 @@ $(document).ready(function(){
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

58
developers/code_of_conduct/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Contributor Covenant Code of Conduct - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="The Code of Conduct for Home Assistant projects.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/code_of_conduct/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Contributor Covenant Code of Conduct">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="The Code of Conduct for Home Assistant projects.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Contributor Covenant Code of Conduct">
<meta name="twitter:description" content="The Code of Conduct for Home Assistant projects.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,46 +53,29 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Contributor Covenant Code of Conduct
</h1>
</header>
<hr class="divider">
<h2>Our Pledge</h2>
<p>In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
nationality, personal appearance, race, religion, or sexual identity and
orientation.</p>
<h2>Our Standards</h2>
<p>Examples of behavior that contributes to creating a positive environment
include:</p>
<ul>
<li>Using welcoming and inclusive language</li>
<li>Being respectful of differing viewpoints and experiences</li>
@ -111,9 +83,7 @@ include:</p>
<li>Focusing on what is best for the community</li>
<li>Showing empathy towards other community members</li>
</ul>
<p>Examples of unacceptable behavior by participants include:</p>
<ul>
<li>The use of sexualized language or imagery and unwelcome sexual attention or
advances</li>
@ -124,62 +94,41 @@ address, without explicit permission</li>
<li>Other conduct which could reasonably be considered inappropriate in a
professional setting</li>
</ul>
<h2>Our Responsibilities</h2>
<p>Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.</p>
<p>Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.</p>
<h2>Scope</h2>
<p>This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.</p>
<h2>Enforcement</h2>
<p>Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at <a href="mailto:safety@home-assistant.io">safety@home-assistant.io</a>. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.</p>
<p>Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project’s leadership.</p>
<h2>Attribution</h2>
<p>This Code of Conduct is adapted from the <a href="http://contributor-covenant.org">Contributor Covenant</a>, version 1.4,
available <a href="http://contributor-covenant.org/version/1/4/">here</a>.</p>
<h2>Adoption</h2>
<p>This Code of Conduct was first adopted January 21st, 2017 and announced in <a href="https://home-assistant.io/blog/2017/01/21/home-assistant-governance/">this</a> blog post.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/code_of_conduct.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -268,13 +217,10 @@ available <a href="http://contributor-covenant.org/version/1/4/">here</a>.</p>
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -284,7 +230,6 @@ available <a href="http://contributor-covenant.org/version/1/4/">here</a>.</p>
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -296,7 +241,6 @@ available <a href="http://contributor-covenant.org/version/1/4/">here</a>.</p>
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -304,4 +248,4 @@ available <a href="http://contributor-covenant.org/version/1/4/">here</a>.</p>
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

46
developers/code_review_component/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Checklist for creating a component - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="A list of things to pay attention to when code reviewing a component.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/code_review_component/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Checklist for creating a component">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="A list of things to pay attention to when code reviewing a component.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Checklist for creating a component">
<meta name="twitter:description" content="A list of things to pay attention to when code reviewing a component.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,36 +53,21 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Checklist for Creating a Component
</h1>
</header>
<hr class="divider">
<p>A checklist of things to do when you’re adding a new component.</p>
<h3><a class="title-link" name="requirements" href="#requirements"></a> Requirements</h3>
<ol>
<li>Requirement version pinned: <code class="highlighter-rouge">REQUIREMENTS = ['phue==0.8.1']</code></li>
<li>If requirement hosted on GitHub:
@ -103,16 +77,13 @@
</ul>
</li>
</ol>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">REQUIREMENTS</span> <span class="o">=</span> <span class="p">[</span>
<span class="s">'http://github.com/technicalpickles/python-nest'</span>
<span class="s">'/archive/e6c9d56a8df455d4d7746389811f2c1387e8cb33.zip'</span>
<span class="s">'#python-nest==3.0.3'</span><span class="p">]</span>
</code></pre>
</div>
<h3><a class="title-link" name="configuration" href="#configuration"></a> Configuration</h3>
<ol>
<li>Voluptuous schema present for config validation</li>
<li>Default parameters specified in voluptuous schema, not in <code class="highlighter-rouge">setup_platform(…)</code></li>
@ -120,25 +91,15 @@
<li>If having platforms, have a <code class="highlighter-rouge">PLATFORM_SCHEMA</code>, otherwise <code class="highlighter-rouge">CONFIG_SCHEMA</code>.</li>
<li>If <code class="highlighter-rouge">PLATFORM_SCHEMA</code>, import base from <code class="highlighter-rouge">homeassistant.helpers.config_validation</code></li>
</ol>
<h3><a class="title-link" name="componentplatform-communication" href="#componentplatform-communication"></a> Component/platform communication</h3>
<ol>
<li>If you need to share global data with platforms, use the dictionary <code class="highlighter-rouge">hass.data</code>.</li>
<li>If the component fetches data that causes related platform entities to update,</li>
</ol>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/code_review_component.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -227,13 +188,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -243,7 +201,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -255,7 +212,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -263,4 +219,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

51
developers/code_review_platform/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Checklist for creating a platform - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="A list of things to pay attention to when code reviewing a platform.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/code_review_platform/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Checklist for creating a platform">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="A list of things to pay attention to when code reviewing a platform.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Checklist for creating a platform">
<meta name="twitter:description" content="A list of things to pay attention to when code reviewing a platform.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,36 +53,21 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Checklist for Creating a Platform
</h1>
</header>
<hr class="divider">
<p>A checklist of things to do when you’re adding a new platform.</p>
<h3><a class="title-link" name="1-requirements" href="#1-requirements"></a> 1. Requirements</h3>
<ol>
<li>Requirement version pinned: <code class="highlighter-rouge">REQUIREMENTS = ['phue==0.8.1']</code></li>
<li>If requirement hosted on GitHub:
@ -103,29 +77,23 @@
</ul>
</li>
</ol>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">REQUIREMENTS</span> <span class="o">=</span> <span class="p">[</span>
<span class="s">'http://github.com/technicalpickles/python-nest'</span>
<span class="s">'/archive/e6c9d56a8df455d4d7746389811f2c1387e8cb33.zip'</span>
<span class="s">'#python-nest==3.0.3'</span><span class="p">]</span>
</code></pre>
</div>
<h3><a class="title-link" name="2-dependencies" href="#2-dependencies"></a> 2. Dependencies</h3>
<ol>
<li>If you depend on a component for the connection, add it to your dependencies: <code class="highlighter-rouge">DEPENDENCIES = ['nest']</code></li>
</ol>
<h3><a class="title-link" name="3-configuration" href="#3-configuration"></a> 3. Configuration</h3>
<ol>
<li>Volutpuous schema present for config validation</li>
<li>Voluptuous schema extends schema from component<br />(e.g. <code class="highlighter-rouge">light.hue.PLATFORM_SCHEMA</code> extends <code class="highlighter-rouge">light.PLATFORM_SCHEMA</code>)</li>
<li>Default parameters specified in voluptuous schema, not in <code class="highlighter-rouge">setup_platform(…)</code></li>
<li>Schema using as many generic config keys as possible from <code class="highlighter-rouge">homeassistant.const</code></li>
</ol>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">voluptuous</span> <span class="kn">as</span> <span class="nn">vol</span>
<span class="kn">from</span> <span class="nn">homeassistant.const</span> <span class="kn">import</span> <span class="n">CONF_FILENAME</span><span class="p">,</span> <span class="n">CONF_HOST</span>
@ -143,34 +111,22 @@
<span class="p">})</span>
</code></pre>
</div>
<h3><a class="title-link" name="4-setup-platform" href="#4-setup-platform"></a> 4. Setup Platform</h3>
<ol>
<li>Test if passed in info (user/pass/host etc.) works.</li>
<li>Group your calls to <code class="highlighter-rouge">add_devices</code> if possible.</li>
<li>If platform adds extra services, format should be <code class="highlighter-rouge">&lt;component&gt;.&lt;platform&gt;_&lt;service name&gt;</code>.</li>
</ol>
<h3><a class="title-link" name="5-entity" href="#5-entity"></a> 5. Entity</h3>
<ol>
<li>Extend entity from component, e.g. <code class="highlighter-rouge">class HueLight(Light)</code></li>
<li>Do not call <code class="highlighter-rouge">update()</code> in constructor, use <code class="highlighter-rouge">add_devices(devices, True)</code> instead.</li>
<li>Do not do any I/O inside properties. Cache values inside <code class="highlighter-rouge">update()</code> instead.</li>
</ol>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/code_review_platform.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -259,13 +215,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -275,7 +228,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -287,7 +239,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -295,4 +246,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

51
developers/component_deps_and_reqs/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Requirements & Dependencies - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Instructions how to define requirements and dependencies.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/component_deps_and_reqs/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Requirements & Dependencies">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Instructions how to define requirements and dependencies.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Requirements & Dependencies">
<meta name="twitter:description" content="Instructions how to define requirements and dependencies.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,80 +53,47 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Requirements & Dependencies
</h1>
</header>
<hr class="divider">
<p>Home Assistant allows components and platforms to specify their dependencies and requirements using the variables <code class="highlighter-rouge">DEPENDENCIES</code> and <code class="highlighter-rouge">REQUIREMENTS</code>. Both are lists that contain strings.</p>
<h2>Dependencies</h2>
<p>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.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">DEPENDENCIES</span> <span class="o">=</span> <span class="p">[</span><span class="s">'mqtt'</span><span class="p">]</span>
</code></pre>
</div>
<h2>Requirements</h2>
<p>Requirements are Python libraries that you would normally install using <code class="highlighter-rouge">pip</code> for your component. Home Assistant will try to install the requirements into the <code class="highlighter-rouge">deps</code> subdirectory of the Home Assistant configuration directory (<code class="highlighter-rouge">.home-assistant</code> by default) or verify it is already installed at startup. If that fails, the component will fail to load.</p>
<p>Requirements is a list of strings. Each entry is a pip compatible string. For example, the media player Cast platform depends on the Python package PyChromecast v0.6.12:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">REQUIREMENTS</span> <span class="o">=</span> <span class="p">[</span><span class="s">'pychromecast==0.6.12'</span><span class="p">]</span>
</code></pre>
</div>
<p>During development of a component, it can be useful to test against different versions of a requirement. This can be done in two steps, using pychromecast as an example:</p>
<ul>
<li><code class="highlighter-rouge">pip install pychromecast==0.6.13 --target ~/.homeassistant/deps</code></li>
<li><code class="highlighter-rouge">hass --skip-pip</code></li>
</ul>
<p>This will use the specified version, and prevent Home Assistant from trying to override it with what is currently in <code class="highlighter-rouge">REQUIREMENTS</code>.</p>
<p>If you need to make changes to a requirement to support your component, it’s also possible to pip install from a checkout of the requirement.</p>
<ul>
<li><code class="highlighter-rouge">git clone https://github.com/balloob/pychromecast.git</code></li>
<li><code class="highlighter-rouge">pip install ./pychromecast</code></li>
<li><code class="highlighter-rouge">hass --skip-pip</code></li>
</ul>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/component_deps_and_reqs.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -226,13 +182,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -242,7 +195,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -254,7 +206,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -262,4 +213,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

48
developers/component_discovery/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Component Discovery - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="How to make component discovery work.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/component_discovery/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Component Discovery">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="How to make component discovery work.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Component Discovery">
<meta name="twitter:description" content="How to make component discovery work.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,48 +53,28 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Component Discovery
</h1>
</header>
<hr class="divider">
<p class="note warning">
This option is only available for built-in components.
</p>
<p>Home Assistant has a discovery service running in the background to discover new devices. Whenever a new device is discovered, a <code class="highlighter-rouge">SERVICE_DISCOVERED</code> event will be fired with the found service and the information. The <code class="highlighter-rouge">discovery</code> component has some knowledge about which components handle which type of services and will ensure those are loaded and listening before firing the <code class="highlighter-rouge">SERVICE_DISCOVERED</code> event.</p>
<h3><a class="title-link" name="add-discovery-instructions" href="#add-discovery-instructions"></a> Add discovery instructions</h3>
<p>Device discovery for Home Assistant has been extracted into an external library called <a href="https://github.com/home-assistant/netdisco">NetDisco</a>. This library is integrated using <a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py">the <code class="highlighter-rouge">discovery</code> component</a> and scans the network in intervals for uPnP and zeroconf/mDNS services.</p>
<p>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. <a href="https://github.com/home-assistant/netdisco/tree/master/netdisco/discoverables">See the repository for examples of existing discoverable.</a></p>
<h3><a class="title-link" name="listening-to-service_discovered-events" href="#listening-to-service_discovered-events"></a> Listening to <code class="highlighter-rouge">SERVICE_DISCOVERED</code> events</h3>
<p>From your component, you will have to set up the listening for specific services. Given below is an example how one would listen for discovered Chromecasts:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">from</span> <span class="nn">homeassistant.loader</span> <span class="kn">import</span> <span class="n">get_component</span>
<span class="k">def</span> <span class="nf">setup</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="n">config</span><span class="p">):</span>
@ -119,22 +88,12 @@ This option is only available for built-in components.
<span class="n">hass</span><span class="p">,</span> <span class="n">discovery</span><span class="o">.</span><span class="n">services</span><span class="o">.</span><span class="n">GOOGLE_CAST</span><span class="p">,</span> <span class="n">chromecast_discovered</span><span class="p">)</span>
</code></pre>
</div>
<h3><a class="title-link" name="auto-loading-your-component-upon-discovery" href="#auto-loading-your-component-upon-discovery"></a> Auto-loading your component upon discovery</h3>
<p>The Discovery component is capable of setting up your components before firing the <code class="highlighter-rouge">SERVICE_DISCOVERD</code> event. To do this you will have to update the <a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py#L29"><code class="highlighter-rouge">SERVICE_HANDLERS</code></a> constant in <a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py">the <code class="highlighter-rouge">discovery</code> component</a>.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/component_discovery.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -223,13 +182,10 @@ This option is only available for built-in components.
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -239,7 +195,6 @@ This option is only available for built-in components.
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -251,7 +206,6 @@ This option is only available for built-in components.
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -259,4 +213,4 @@ This option is only available for built-in components.
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

39
developers/component_events/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Handling events - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Instructions how to handle events with your component.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/component_events/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Handling events">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Instructions how to handle events with your component.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Handling events">
<meta name="twitter:description" content="Instructions how to handle events with your component.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,45 +53,24 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Handling Events
</h1>
</header>
<hr class="divider">
<p>Home Assistant has different ways of responding to events that occur in Home Assistant. These have been organized in <a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/event.py">helper methods</a>. Examples are <code class="highlighter-rouge">track_state_change</code>, <code class="highlighter-rouge">track_point_in_time</code>, <code class="highlighter-rouge">track_time_change</code>.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/component_events.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -191,13 +159,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -207,7 +172,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -219,7 +183,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -227,4 +190,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

53
developers/component_generic_discovery/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Generic Platform Discovery - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Using generic platform discovery.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/component_generic_discovery/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Generic Platform Discovery">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Using generic platform discovery.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Generic Platform Discovery">
<meta name="twitter:description" content="Using generic platform discovery.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,62 +53,39 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Generic Platform Discovery
</h1>
</header>
<hr class="divider">
<p>New controller or hub components often need to add platforms in sub-components (i.e. Lights &amp; Switches) without additional configuration.
This can be achieved using the <code class="highlighter-rouge">load_platform</code> or <code class="highlighter-rouge">async_load_platform</code> methods from <code class="highlighter-rouge">homeassistant.helpers.discovery</code>:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="k">def</span> <span class="nf">load_platform</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="n">component</span><span class="p">,</span> <span class="n">platform</span><span class="p">,</span> <span class="n">discovered</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">hass_config</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
</code></pre>
</div>
<p>From more info on how this works, refer to the <a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/discovery.py#L136">load_platform</a> method.</p>
<h3><a class="title-link" name="example" href="#example"></a> Example</h3>
<p>Say you need to implement your new MyFlashyHub that controls both Switches &amp; Lights, you can follow these steps:</p>
<p>Configuration required for your new hub component:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">myflashyhub</span><span class="pi">:</span>
<span class="s">example</span><span class="pi">:</span> <span class="s">setting</span>
</code></pre>
</div>
<p>The source for your component can be located in your configuration directory for now:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>~/.homeassistant/custom_components/myflashyhub.py
~/.homeassistant/custom_components/light/myflashyhub.py
~/.homeassistant/custom_components/switch/myflashyhub.py
</code></pre>
</div>
<p>In the hub component <code class="highlighter-rouge">myflashyhub.py</code> you can call your light and switch components. To pass any non-serializable information to the platforms in the sub-component, you can use a global variable.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">from</span> <span class="nn">homeassistant.helpers.discovery</span> <span class="kn">import</span> <span class="n">load_platform</span>
<span class="n">DOMAIN</span> <span class="o">=</span> <span class="s">'myflashyhub'</span>
@ -134,9 +100,7 @@ This can be achieved using the <code class="highlighter-rouge">load_platform</co
<span class="n">load_platform</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="s">'switch'</span><span class="p">,</span> <span class="n">DOMAIN</span><span class="p">,</span> <span class="p">{</span><span class="s">'optional'</span><span class="p">:</span> <span class="s">'arguments'</span><span class="p">})</span>
</code></pre>
</div>
<p>Add your custom device specific code to the <code class="highlighter-rouge">setup_platform</code> method in <code class="highlighter-rouge">light/myflashyhub.py</code> and <code class="highlighter-rouge">switch/myflashyhub</code>.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">custom_components.myflashyhub</span> <span class="kn">as</span> <span class="nn">myflashyhub</span>
<span class="c"># 'switch' will receive discovery_info={'optional': 'arguments'} </span>
@ -146,27 +110,17 @@ This can be achieved using the <code class="highlighter-rouge">load_platform</co
<span class="c"># You can now use hass.data[myflashyhub.DATA_MFH]</span>
</code></pre>
</div>
<p>The <code class="highlighter-rouge">load_platform</code> method allows the platforms to be loaded with the need for any additional platform entries in your <code class="highlighter-rouge">configuration.yaml</code> file, which normally would have been:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="c1">#light:</span>
<span class="c1"># platform: myflashyhub</span>
<span class="c1">#switch:</span>
<span class="c1"># platform: myflashyhub</span>
</code></pre>
</div>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/component_generic_discovery.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -255,13 +209,10 @@ This can be achieved using the <code class="highlighter-rouge">load_platform</co
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -271,7 +222,6 @@ This can be achieved using the <code class="highlighter-rouge">load_platform</co
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -283,7 +233,6 @@ This can be achieved using the <code class="highlighter-rouge">load_platform</co
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -291,4 +240,4 @@ This can be achieved using the <code class="highlighter-rouge">load_platform</co
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

47
developers/component_initialization/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Initializing your components - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Instructions how to handle initialization of your component.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/component_initialization/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Initializing your components">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Instructions how to handle initialization of your component.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Initializing your components">
<meta name="twitter:description" content="Instructions how to handle initialization of your component.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,38 +53,22 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Initializing Your Components
</h1>
</header>
<hr class="divider">
<p>After loading, the bootstrapper will call <code class="highlighter-rouge">setup(hass, config)</code> method on the component to initialize it.</p>
<h3><a class="title-link" name="hass-the-home-assistant-instance" href="#hass-the-home-assistant-instance"></a> hass: the Home Assistant instance</h3>
<p>The Home Assistant instance contains four objects to help you interact with the system.</p>
<table>
<thead>
<tr>
@ -122,31 +95,18 @@
</tr>
</tbody>
</table>
<h3><a class="title-link" name="config-user-given-configuration" href="#config-user-given-configuration"></a> config: User given configuration.</h3>
<p>The <code class="highlighter-rouge">config</code> parameter 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.</p>
<p>If your configuration file contains the following lines:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">example</span><span class="pi">:</span>
<span class="s">host</span><span class="pi">:</span> <span class="s">paulusschoutsen.nl</span>
</code></pre>
</div>
<p>Then in the setup method of your component you will be able to refer to <code class="highlighter-rouge">config['example']['host']</code> to get the value <code class="highlighter-rouge">paulusschoutsen.nl</code>.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/component_initialization.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -235,13 +195,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -251,7 +208,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -263,7 +219,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -271,4 +226,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

43
developers/component_loading/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Loading your components - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Instructions how to get your component loaded by Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/component_loading/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Loading your components">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Instructions how to get your component loaded by Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Loading your components">
<meta name="twitter:description" content="Instructions how to get your component loaded by Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,60 +53,35 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Loading Your Components
</h1>
</header>
<hr class="divider">
<p>A component will be loaded on start if a section (ie. <code class="highlighter-rouge">light:</code>) 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:</p>
<ul>
<li><code class="highlighter-rouge">&lt;config directory&gt;/custom_components/&lt;component name&gt;</code></li>
<li><code class="highlighter-rouge">homeassistant/components/&lt;component name&gt;</code> (built-in components)</li>
</ul>
<p>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.</p>
<p class="note warning">
You can override a built-in component by having a component with the same name in your <code>config/custom_components</code> folder. If the build-in component is inside a subfolder, take care to place your customization in a folder with the same name in <code>config/custom_components/*folder*</code>. Note that overriding build-in components is not recommended and will probably break things!
</p>
<p class="note">
Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the <code>config</code> folder in your current work directory. You can use a different folder by running Home Assistant with the –config argument: <code>python3 homeassistant --config /YOUR/CONFIG/PATH/</code>.
</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/component_loading.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -206,13 +170,10 @@ Home Assistant will use the directory that contains your config file as the dire
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -222,7 +183,6 @@ Home Assistant will use the directory that contains your config file as the dire
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -234,7 +194,6 @@ Home Assistant will use the directory that contains your config file as the dire
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -242,4 +201,4 @@ Home Assistant will use the directory that contains your config file as the dire
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

43
developers/component_states/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Handling states - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Instructions how to handle states with your component.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/component_states/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Handling states">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Instructions how to handle states with your component.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Handling states">
<meta name="twitter:description" content="Instructions how to handle states with your component.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,57 +53,32 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Handling States
</h1>
</header>
<hr class="divider">
<p>It is the responsibility of the component to maintain the states of the devices in your domain. Each device should be a single state and, if possible, a group should be provided that tracks the combined state of the devices.</p>
<p>A state can have several attributes that will help the frontend in displaying your state:</p>
<ul>
<li><code class="highlighter-rouge">friendly_name</code>: this name will be used as the name of the device</li>
<li><code class="highlighter-rouge">entity_picture</code>: this picture will be shown instead of the domain icon</li>
<li><code class="highlighter-rouge">unit_of_measurement</code>: this will be appended to the state in the interface</li>
<li><code class="highlighter-rouge">hidden</code>: This is a suggestion to the frontend on if the state should be hidden</li>
</ul>
<p>These attributes are defined in <a href="https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/entity.py#L180">homeassistant.helpers.entity</a>.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/component_states.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -203,13 +167,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -219,7 +180,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -231,7 +191,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -239,4 +198,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

42
developers/component_visibility/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Handling visibility - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Instructions how to handle visibility with your component.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/component_visibility/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Handling visibility">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Instructions how to handle visibility with your component.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Handling visibility">
<meta name="twitter:description" content="Instructions how to handle visibility with your component.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,54 +53,30 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Handling Visibility
</h1>
</header>
<hr class="divider">
<p>Generally, when creating a new entity for Home Assistant you will want it to be a class that inherits the <a href="https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/entity.py">homeassistant.helpers.entity.Entity</a> class. If this is done, visibility will be handled for you.
You can set a suggestion for your entity’s visibility by setting the <code class="highlighter-rouge">hidden</code> property by doing something similar to the following.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">hidden</span> <span class="o">=</span> <span class="bp">True</span>
</code></pre>
</div>
<p>This will SUGGEST that the active frontend hides the entity. This requires that the active frontend support hidden cards (the default frontend does) and that the value of hidden be included in your attributes dictionary (see above). The Entity abstract class will take care of this for you.</p>
<p>Remember: The suggestion set by your component’s code will always be overwritten by user settings in the <code class="highlighter-rouge">configuration.yaml</code> file. This is why you may set hidden to be <code class="highlighter-rouge">False</code>, but the property may remain <code class="highlighter-rouge">True</code> (or vice-versa).</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/component_visibility.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -200,13 +165,10 @@ You can set a suggestion for your entity’s visibility by setting the <code cla
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -216,7 +178,6 @@ You can set a suggestion for your entity’s visibility by setting the <code cla
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -228,7 +189,6 @@ You can set a suggestion for your entity’s visibility by setting the <code cla
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -236,4 +196,4 @@ You can set a suggestion for your entity’s visibility by setting the <code cla
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

43
developers/creating_components/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Creating components - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Guidelines to get you create your first component for Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/creating_components/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Creating components">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Guidelines to get you create your first component for Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Creating components">
<meta name="twitter:description" content="Guidelines to get you create your first component for Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,38 +53,22 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Creating Components
</h1>
</header>
<hr class="divider">
<p>Alright, you’re ready to make your first component. AWESOME. Don’t worry, we’ve tried hard to keep it as easy as possible.</p>
<h3><a class="title-link" name="example-component" href="#example-component"></a> Example component</h3>
<p>Add <code class="highlighter-rouge">hello_state:</code> to your <code class="highlighter-rouge">configuration.yaml</code> file and create a file <code class="highlighter-rouge">&lt;config_dir&gt;/custom_components/hello_state.py</code> with the below code to test it locally.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">DOMAIN</span> <span class="o">=</span> <span class="s">'hello_state'</span>
<span class="k">def</span> <span class="nf">setup</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="n">config</span><span class="p">):</span>
@ -104,20 +77,11 @@
<span class="k">return</span> <span class="bp">True</span>
</code></pre>
</div>
<p>For more examples, see the <a href="/cookbook/#custom-python-component-examples">Custom Python Component Examples</a> on our examples page.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/creating_components.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -206,13 +170,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -222,7 +183,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -234,7 +194,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -242,4 +201,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

46
developers/credits/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Credits - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Credits for the developers who contributed to Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/credits/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Credits">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Credits for the developers who contributed to Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Credits">
<meta name="twitter:description" content="Credits for the developers who contributed to Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,44 +53,26 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Credits
</h1>
</header>
<hr class="divider">
<p>This page contains a list of people who have contributed in one way or another to Home Assistant. Hover over a username to see their contributions.</p>
<h3><a class="title-link" name="author" href="#author"></a> Author</h3>
<ul>
<li><a href="https://github.com/balloob" title="4870 total commits to the home-assistant organization, 3051 commits to home-assistant, 970 commits to home-assistant.github.io, 474 commits to home-assistant-polymer, 244 commits to home-assistant-js, 79 commits to netdisco, 33 commits to home-assistant-js-websocket, 8 commits to home-assistant-assets, 7 commits to micropython-home-assistant, 2 commits to lambda-home-assistant-github, 1 commit to home-assistant-iOS, 1 commit to home-assistant-notebooks">Paulus Schoutsen (@balloob)</a></li>
</ul>
<h3><a class="title-link" name="contributors" href="#contributors"></a> Contributors</h3>
<p>(in alphabetical order)</p>
<ul>
<li><a href="https://github.com/linville" title="1 total commits to the home-assistant organization, 1 commit to appdaemon">Aaron Linville (@linville)</a></li>
<li><a href="https://github.com/aaroncm" title="1 total commits to the home-assistant organization, 1 commit to home-assistant.github.io">Aaron Malone (@aaroncm)</a></li>
@ -822,22 +793,12 @@
<li><a href="https://github.com/zlu" title="4 total commits to the home-assistant organization, 4 commits to home-assistant.github.io">Zhao Lu (@zlu)</a></li>
<li><a href="https://github.com/oeysteinhansen" title="1 total commits to the home-assistant organization, 1 commit to home-assistant">Øystein Hansen (@oeysteinhansen)</a></li>
</ul>
<p>This page is irregularly updated using the <a href="https://github.com/home-assistant/home-assistant.github.io/tree/next/credits_generator"><code class="highlighter-rouge">credits_generator</code> tool</a>. If you think that you are missing, please let us know.</p>
<p><i>This page was last updated Saturday, February 11th 2017, 9:38:58 pm UTC.</i></p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/credits.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -926,13 +887,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -942,7 +900,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -954,7 +911,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -962,4 +918,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

44
developers/development/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Starting with Development - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Everything to get you started developing for Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/development/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Starting with Development">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Everything to get you started developing for Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Starting with Development">
<meta name="twitter:description" content="Everything to get you started developing for Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,44 +53,27 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Starting With Development
</h1>
</header>
<hr class="divider">
<p>Home Assistant is built from the ground up to be easily extensible using components. Home Assistant uses <a href="https://www.python.org/">Python 3</a> for the backend and <a href="https://www.polymer-project.org/">Polymer (Web components)</a> for the frontend.</p>
<p>Home Assistant is open-source and MIT-licensed. Here are links to the source:</p>
<ul>
<li><a href="https://github.com/home-assistant/home-assistant">home-assistant</a>: Python server backend.</li>
<li><a href="https://github.com/home-assistant/home-assistant-js">home-assistant-js</a>: JavaScript backend that powers the client.</li>
<li><a href="https://github.com/home-assistant/home-assistant-polymer">home-assistant-polymer</a>: Polymer UI.</li>
</ul>
<p>For those new to contributing to open source software, make sure you are familiar with all of the tools and concepts used in Home Assistant before you start.</p>
<p>When contributing Home Assistant code:</p>
<ul>
<li><a href="https://guides.github.com/activities/hello-world/">Github</a></li>
@ -112,23 +84,14 @@
<li><a href="http://tox.readthedocs.org/en/latest/">Tox</a></li>
<li><a href="https://travis-ci.org/">TravisCl</a></li>
</ul>
<p>When contributing 3rd Party code to be used by Home Assistant:</p>
<ul>
<li><a href="https://jeffknupp.com/blog/2013/08/16/open-sourcing-a-python-project-the-right-way/">Publishing your own PyPI package</a></li>
</ul>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/development.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -217,13 +180,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -233,7 +193,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -245,7 +204,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -253,4 +211,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

46
developers/development_catching_up/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Catching up with Reality - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Update your fork with the latest commit.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/development_catching_up/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Catching up with Reality">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Update your fork with the latest commit.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Catching up with Reality">
<meta name="twitter:description" content="Update your fork with the latest commit.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,69 +53,41 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Catching Up With Reality
</h1>
</header>
<hr class="divider">
<p>If it’s taking a while to develop your feature, and you want to catch up with what’s in the current Home Assistant <code class="highlighter-rouge">dev</code> branch, you can use <code class="highlighter-rouge">git rebase</code>. This will pull the latest Home Assistant changes locally, rewind your commits, bring in the latest changes from Home Assistant, and replay all of your commits on top.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="c"># Run this from your feature branch</span>
<span class="gp">$ </span>git fetch upstream dev <span class="c"># to pull the latest changes into a local dev branch</span>
<span class="gp">$ </span>git rebase upstream/dev <span class="c"># to put those changes into your feature branch before your changes</span>
</code></pre>
</div>
<p>If rebase detects conflicts, repeat this process until all changes have been resolved:</p>
<ol>
<li><code class="highlighter-rouge">git status</code> shows you the file with the conflict; edit the file and resolve the lines between <code class="highlighter-rouge">&lt;&lt;&lt;&lt; | &gt;&gt;&gt;&gt;</code></li>
<li>Add the modified file: <code class="highlighter-rouge">git add &lt;file&gt;</code> or <code class="highlighter-rouge">git add .</code></li>
<li>Continue rebase: <code class="highlighter-rouge">git rebase --continue</code></li>
<li>Repeat until you’ve resolved all conflicts</li>
</ol>
<p>Other workflows are covered in detail in the <a href="https://help.github.com/articles/fork-a-repo/">Github documentation</a>. Add an additional <code class="highlighter-rouge">remote</code> after you clone your fork.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git remote add upstream https://github.com/home-assistant/home-assistant.git
</code></pre>
</div>
<p>Then, <code class="highlighter-rouge">git pull --rebase upstream dev</code>.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/development_catching_up.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -215,13 +176,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -231,7 +189,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -243,7 +200,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -251,4 +207,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

41
developers/development_checklist/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Development Checklist - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Overview of the requirements for an improvement for Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/development_checklist/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Development Checklist">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Overview of the requirements for an improvement for Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Development Checklist">
<meta name="twitter:description" content="Overview of the requirements for an improvement for Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,34 +53,20 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Development Checklist
</h1>
</header>
<hr class="divider">
<p>Before you commit any changes, check your work against these requirements:</p>
<ul>
<li>All dependencies are included via the <code class="highlighter-rouge">REQUIREMENTS</code> variable in your platform or component and only imported inside functions that use them</li>
<li>New dependencies are added to <code class="highlighter-rouge">requirements_all.txt</code> (if applicable), using <code class="highlighter-rouge">script/gen_requirements_all.py</code></li>
@ -102,19 +77,10 @@
</ul>
</li>
</ul>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/development_checklist.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -203,13 +169,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -219,7 +182,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -231,7 +193,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -239,4 +200,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

60
developers/development_environment/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Set up Development Environment - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Set up your environment to start developing for Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/development_environment/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Set up Development Environment">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Set up your environment to start developing for Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Set up Development Environment">
<meta name="twitter:description" content="Set up your environment to start developing for Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,36 +53,21 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Set Up Development Environment
</h1>
</header>
<hr class="divider">
<p>You’ll need to set up a development environment if you want to develop a new feature or component for Home Assistant. Read on to learn how to set up.</p>
<h3><a class="title-link" name="setup-local-repository" href="#setup-local-repository"></a> Setup Local Repository</h3>
<p>Visit the <a href="https://github.com/home-assistant/home-assistant">Home Assistant repository</a> and click <strong>Fork</strong>.
Once forked, setup your local copy of the source using the commands:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git
@ -101,11 +75,8 @@ Once forked, setup your local copy of the source using the commands:</p>
<span class="gp">$ </span>git remote add upstream https://github.com/home-assistant/home-assistant.git
</code></pre>
</div>
<h3><a class="title-link" name="prepare-your-environment" href="#prepare-your-environment"></a> Prepare Your Environment</h3>
<h4><a class="title-link" name="core-dependencies" href="#core-dependencies"></a> Core dependencies</h4>
<p>Install the core dependencies.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>sudo apt-get install python3-pip python3-dev libssl-dev
</code></pre>
@ -113,31 +84,22 @@ Once forked, setup your local copy of the source using the commands:</p>
<p class="note">
Different distributions have different package installation mechanisms and sometimes packages names as well. For example Centos would use: <code class="highlighter-rouge">sudo yum install epel-release &amp;&amp; sudo yum install python34 python34-devel mysql-devel</code>
</p>
<p>Additional dependencies exist if you you plan to perform Frontend Development, please read the <a href="https://home-assistant.io/developers/frontend/">Frontend</a> section to learn more.</p>
<h4><a class="title-link" name="setting-up-virtual-environment-optional" href="#setting-up-virtual-environment-optional"></a> Setting up virtual environment (optional)</h4>
<p>If you plan on providing isolation to your environment using <a href="https://docs.python.org/3.4/library/venv.html"><code class="highlighter-rouge">venv</code></a>. Within the <code class="highlighter-rouge">home-assistant</code> directory, create and activate your virtual environment.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>python3 -m venv venv
<span class="gp">$ </span><span class="nb">source </span>venv/bin/activate
</code></pre>
</div>
<p>Note, Debian does not ship a full Python3 package and so requires you to install <code class="highlighter-rouge">venv</code> manually <code class="highlighter-rouge">sudo apt-get install python3-venv</code>.</p>
<h3><a class="title-link" name="setup-and-run" href="#setup-and-run"></a> Setup and Run</h3>
<ul>
<li>On Mac OS X and Linux:</li>
</ul>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span><span class="nb">cd </span>home-assistant
<span class="gp">$ </span>script/setup
</code></pre>
</div>
<ul>
<li>
<p>On Windows, you can use <code class="highlighter-rouge">python setup.py develop</code> instead of the setup script.</p>
@ -146,37 +108,22 @@ Different distributions have different package installation mechanisms and somet
<p>Run <code class="highlighter-rouge">hass</code> to invoke your local installation.</p>
</li>
</ul>
<h3><a class="title-link" name="logging" href="#logging"></a> Logging</h3>
<p>By default logging in home-assistant is tuned for operating in
production (set to INFO by default, with some modules set to even less
verbose logging levels).</p>
<p>You can use the <a href="/components/logger/">logger</a> component to adjust
logging to DEBUG to see even more details about what is going on.</p>
<h3><a class="title-link" name="developing-on-windows" href="#developing-on-windows"></a> Developing on Windows</h3>
<p>If you are using Windows as a development platform, make sure that you have the correct Microsoft Visual C++ build tools installed. Check the <a href="https://wiki.python.org/moin/WindowsCompilers">Windows Compilers</a> section on the <a href="https://www.python.org/">Python website</a> for details. Validation using <code class="highlighter-rouge">tox</code> will fail if this is not done correctly.</p>
<p>Also, make sure to install or upgrade the <code class="highlighter-rouge">setuptools</code> Python package. It contains compatibility improvements and adds automatic use of compilers:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>pip install --upgrade setuptools
</code></pre>
</div>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/development_environment.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -265,13 +212,10 @@ logging to DEBUG to see even more details about what is going on.</p>
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -281,7 +225,6 @@ logging to DEBUG to see even more details about what is going on.</p>
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -293,7 +236,6 @@ logging to DEBUG to see even more details about what is going on.</p>
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -301,4 +243,4 @@ logging to DEBUG to see even more details about what is going on.</p>
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

46
developers/development_submitting/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Submit your work - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Submit your work as Pull Request for Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/development_submitting/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Submit your work">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Submit your work as Pull Request for Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Submit your work">
<meta name="twitter:description" content="Submit your work as Pull Request for Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,38 +53,23 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Submit Your Work
</h1>
</header>
<hr class="divider">
<p>Submit your improvements, fixes, and new features to Home Assistant one at a time, using GitHub <a href="https://help.github.com/articles/using-pull-requests">Pull Requests</a>. Here are the steps:</p>
<ol>
<li>
<p>From your fork’s dev branch, create a new branch to hold your changes:</p>
<p><code class="highlighter-rouge">git checkout -b some-feature</code></p>
</li>
<li>
@ -106,18 +80,14 @@
</li>
<li>
<p>If everything looks good according to these <a href="/developers/development_checklist/">musts</a>, commit your changes:</p>
<p><code class="highlighter-rouge">git add .</code></p>
<p><code class="highlighter-rouge">git commit -m "Added some-feature"</code></p>
<ul>
<li>Consider adding tests to ensure that your code works.</li>
</ul>
</li>
<li>
<p>Push your committed changes back to your fork on GitHub:</p>
<p><code class="highlighter-rouge">git push origin HEAD</code></p>
</li>
<li>
@ -127,19 +97,10 @@
<p>Check for comments and suggestions on your pull request and keep an eye on the <a href="https://travis-ci.org/home-assistant/home-assistant/">CI output</a>.</p>
</li>
</ol>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/development_submitting.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -228,13 +189,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -244,7 +202,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -256,7 +213,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -264,4 +220,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

60
developers/development_testing/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Testing your code - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Make sure that your code passes the checks">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/development_testing/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Testing your code">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Make sure that your code passes the checks">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Testing your code">
<meta name="twitter:description" content="Make sure that your code passes the checks">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,101 +53,59 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Testing Your Code
</h1>
</header>
<hr class="divider">
<p>Home Assistant enforces strict <a href="https://www.python.org/dev/peps/pep-0008/">PEP8 style</a> compliance on all code submitted. We automatically test every pull request with <a href="https://coveralls.io/github/home-assistant/home-assistant">Coveralls</a> and <a href="https://travis-ci.org/home-assistant/home-assistant">Travis CI</a>.</p>
<h3><a class="title-link" name="local-testing" href="#local-testing"></a> Local testing</h3>
<p><strong>Important:</strong> Run tox before you create your pull request to avoid annoying fixes. Local testing requires installing tox.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>pip3 install tox
</code></pre>
</div>
<p>Start your code test with <code class="highlighter-rouge">tox</code>.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>tox
</code></pre>
</div>
<p>This will run unit tests against Python 3.4 and 3.5 (if both are available locally), as well as tests that validate <code class="highlighter-rouge">pep8</code> and <code class="highlighter-rouge">pylint</code> style.</p>
<h4><a class="title-link" name="testing-tips" href="#testing-tips"></a> Testing Tips</h4>
<p>You can run tests on only one tox target – just use <code class="highlighter-rouge">-e</code> to select an environment. For example, <code class="highlighter-rouge">tox -e lint</code> runs the linters only, and <code class="highlighter-rouge">tox -e py34</code> runs unit tests only on Python 3.4.</p>
<p>tox uses virtual environments under the hood to create isolated testing environments. The tox virtual environments will get out-of-date when requirements change, causing test errors. Run <code class="highlighter-rouge">tox -r</code> to create new tox virtual environments.</p>
<p>During development on a specific file, speed up your workflow by running tests and linting only for the file that you’re working on. To run individual files:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>flake8 homeassistant/core.py
<span class="gp">$ </span>pylint homeassistant/core.py
<span class="gp">$ </span>pydocstyle homeassistant/core.py
<span class="gp">$ </span>py.test tests/test_core.py
</code></pre>
</div>
<p>You can also run linting tests against all changed files, as reported by <code class="highlighter-rouge">git diff upstream/dev --name-only</code>, using the <code class="highlighter-rouge">lint</code> script:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>script/lint --changed
</code></pre>
</div>
<h3><a class="title-link" name="preventing-linter-errors" href="#preventing-linter-errors"></a> Preventing Linter Errors</h3>
<p>Save yourself the hassle of extra commits just to fix style errors by enabling the Flake8 git commit hook. Flake8 will check your code when you try to commit to the repository and block the commit if there are any style errors, which gives you a chance to fix them!</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>pip3 install flake8 flake8-docstrings
<span class="gp">$ </span>flake8 --install-hook<span class="o">=</span>git
</code></pre>
</div>
<p>The <code class="highlighter-rouge">flake8-docstrings</code> extension will check docstrings according to <a href="https://www.python.org/dev/peps/pep-0257/">PEP257</a> when running Flake8.</p>
<h3><a class="title-link" name="notes-on-pylint-and-pep8-validation" href="#notes-on-pylint-and-pep8-validation"></a> Notes on PyLint and PEP8 validation</h3>
<p>If you can’t avoid a PyLint warning, add a comment to disable the PyLint check for that line with <code class="highlighter-rouge"># pylint: disable=YOUR-ERROR-NAME</code>. An example of an unavoidable PyLint warning is not using the passed-in datetime if you’re listening for a time change.</p>
<h3><a class="title-link" name="maximum-line-length" href="#maximum-line-length"></a> Maximum Line Length</h3>
<p>As part of the linting process, all code is checked for a maximum line length of 79 characters. This comes directly from the <a href="https://www.python.org/dev/peps/pep-0008/#maximum-line-length">PEP8 style guide</a>, and is also used by the Python standard library. All code must pass these linting checks, and no exceptions will be made. There have already been numerous requests to increase the maximum line length, but after evaluating the options, the Home Assistant maintainers have decided to stay at 79 characters. This decision is final.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/development_testing.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -247,13 +194,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -263,7 +207,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -275,7 +218,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -283,4 +225,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

59
developers/development_validation/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Validate the input - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Validation of entries in configuration.yaml">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/development_validation/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Validate the input">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Validation of entries in configuration.yaml">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Validate the input">
<meta name="twitter:description" content="Validation of entries in configuration.yaml">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,38 +53,22 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Validate the Input
</h1>
</header>
<hr class="divider">
<p>The <code class="highlighter-rouge">configuration.yaml</code> file contains the configuration options for components and platforms. We use <a href="https://pypi.python.org/pypi/voluptuous">voluptuous</a> to make sure that the configuration provided by the user is valid. Some entries are optional or could be required to set up a platform or a component. Others must be a defined type or from an already-defined list.</p>
<p>We test the configuration to ensure that users have a great experience and minimise notifications if something is wrong with a platform or component setup before Home Assistant runs.</p>
<p>Besides <a href="https://pypi.python.org/pypi/voluptuous">voluptuous</a> default types, many custom types are available. For an overview, take a look at the <a href="https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/config_validation.py">config_validation.py</a> helper.</p>
<ul>
<li>Types: <code class="highlighter-rouge">string</code>, <code class="highlighter-rouge">byte</code>, and <code class="highlighter-rouge">boolean</code></li>
<li>Entity ID: <code class="highlighter-rouge">entity_id</code> and <code class="highlighter-rouge">entity_ids</code></li>
@ -103,25 +76,17 @@
<li>Time: <code class="highlighter-rouge">time</code>, <code class="highlighter-rouge">time_zone</code></li>
<li>Misc: <code class="highlighter-rouge">template</code>, <code class="highlighter-rouge">slug</code>, <code class="highlighter-rouge">temperature_unit</code>, <code class="highlighter-rouge">latitude</code>, <code class="highlighter-rouge">longitude</code>, <code class="highlighter-rouge">isfile</code>, <code class="highlighter-rouge">sun_event</code>, <code class="highlighter-rouge">ensure_list</code>, <code class="highlighter-rouge">port</code>, <code class="highlighter-rouge">url</code>, and <code class="highlighter-rouge">icon</code></li>
</ul>
<p>To validate plaforms using <a href="/components/mqtt/">MQTT</a>, <code class="highlighter-rouge">valid_subscribe_topic</code> and <code class="highlighter-rouge">valid_publish_topic</code> are available.</p>
<p>Some things to keep in mind:</p>
<ul>
<li>Use the constants defined in <code class="highlighter-rouge">const.py</code></li>
<li>Import <code class="highlighter-rouge">PLATFORM_SCHEMA</code> from the parent component and extend it</li>
<li>Preferred order is <code class="highlighter-rouge">required</code> first and <code class="highlighter-rouge">optional</code> second</li>
</ul>
<h3><a class="title-link" name="snippets" href="#snippets"></a> Snippets</h3>
<p>This section contains snippets for the validation we use.</p>
<h4><a class="title-link" name="default-name" href="#default-name"></a> Default name</h4>
<p>It’s common to set a default for a sensor if the user doesn’t provide a name to use.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">DEFAULT_NAME</span> <span class="o">=</span> <span class="s">'Sensor name'</span>
<span class="n">PLATFORM_SCHEMA</span> <span class="o">=</span> <span class="n">PLATFORM_SCHEMA</span><span class="o">.</span><span class="n">extend</span><span class="p">({</span>
@ -129,11 +94,8 @@
<span class="n">vol</span><span class="o">.</span><span class="n">Optional</span><span class="p">(</span><span class="n">CONF_NAME</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">DEFAULT_NAME</span><span class="p">):</span> <span class="n">cv</span><span class="o">.</span><span class="n">string</span><span class="p">,</span>
</code></pre>
</div>
<h4><a class="title-link" name="limit-the-values" href="#limit-the-values"></a> Limit the values</h4>
<p>You might want to limit the user’s input to a couple of options.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">DEFAULT_METHOD</span> <span class="o">=</span> <span class="s">'GET'</span>
<span class="n">PLATFORM_SCHEMA</span> <span class="o">=</span> <span class="n">PLATFORM_SCHEMA</span><span class="o">.</span><span class="n">extend</span><span class="p">({</span>
@ -141,11 +103,8 @@
<span class="n">vol</span><span class="o">.</span><span class="n">Optional</span><span class="p">(</span><span class="n">CONF_METHOD</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">DEFAULT_METHOD</span><span class="p">):</span> <span class="n">vol</span><span class="o">.</span><span class="n">In</span><span class="p">([</span><span class="s">'POST'</span><span class="p">,</span> <span class="s">'GET'</span><span class="p">]),</span>
</code></pre>
</div>
<h4><a class="title-link" name="port" href="#port"></a> Port</h4>
<p>All port numbers are from a range of 1 to 65535.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">DEFAULT_PORT</span> <span class="o">=</span> <span class="mi">993</span>
<span class="n">PLATFORM_SCHEMA</span> <span class="o">=</span> <span class="n">PLATFORM_SCHEMA</span><span class="o">.</span><span class="n">extend</span><span class="p">({</span>
@ -153,11 +112,8 @@
<span class="n">vol</span><span class="o">.</span><span class="n">Optional</span><span class="p">(</span><span class="n">CONF_PORT</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">DEFAULT_PORT</span><span class="p">):</span> <span class="n">cv</span><span class="o">.</span><span class="n">port</span><span class="p">,</span>
</code></pre>
</div>
<h4><a class="title-link" name="lists" href="#lists"></a> Lists</h4>
<p>If a sensor has a pre-defined list of available options, test to make sure the configuration entry matches the list.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">SENSOR_TYPES</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'article_cache'</span><span class="p">:</span> <span class="p">(</span><span class="s">'Article Cache'</span><span class="p">,</span> <span class="s">'MB'</span><span class="p">),</span>
<span class="s">'average_download_rate'</span><span class="p">:</span> <span class="p">(</span><span class="s">'Average Speed'</span><span class="p">,</span> <span class="s">'MB/s'</span><span class="p">),</span>
@ -169,18 +125,10 @@
<span class="n">vol</span><span class="o">.</span><span class="n">All</span><span class="p">(</span><span class="n">cv</span><span class="o">.</span><span class="n">ensure_list</span><span class="p">,</span> <span class="p">[</span><span class="n">vol</span><span class="o">.</span><span class="n">In</span><span class="p">(</span><span class="n">SENSOR_TYPES</span><span class="p">)]),</span>
</code></pre>
</div>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/development_validation.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -269,13 +217,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -285,7 +230,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -297,7 +241,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -305,4 +248,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

56
developers/frontend/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Frontend development - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Tips and hints if you are starting on Home Assistant frontend development">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/frontend/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Frontend development">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Tips and hints if you are starting on Home Assistant frontend development">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Frontend development">
<meta name="twitter:description" content="Tips and hints if you are starting on Home Assistant frontend development">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,82 +53,52 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Frontend Development
</h1>
</header>
<hr class="divider">
<p>Home Assistant is built on top of the <a href="https://www.polymer-project.org/">Polymer</a> webcomponents framework. Polymer allows building encapsulated custom HTML elements. <a href="https://github.com/home-assistant/home-assistant-polymer">Home-Assistant-Polymer source code on GitHub.</a></p>
<p class="note warning">
Do not use development mode in production. Home Assistant uses aggressive caching to improve the mobile experience. This is disabled during development so that you do not have to restart the server in between changes.
</p>
<h2><a class="title-link" name="setting-up-the-environment" href="#setting-up-the-environment"></a> Setting up the environment</h2>
<p>Home Assistant will by default serve the compiled version of the frontend. As everything is compiled into the file <code class="highlighter-rouge">frontend.html</code> you do not want to work with the compiled version but with the separate files during development. To enable development mode for Home Assistant, update your <code class="highlighter-rouge">configuration.yaml</code> to have these lines:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">http</span><span class="pi">:</span>
<span class="s">development</span><span class="pi">:</span> <span class="s">1</span>
</code></pre>
</div>
<p>Node.js is required to setup the frontend development environment. The preferred method of installing node.js is <a href="https://github.com/creationix/nvm">nvm</a>. Install nvm using the instructions in the <a href="https://github.com/creationix/nvm#install-script">README</a>, and install the correct node.js by running the following command from the <code class="highlighter-rouge">home-assistant-polymer</code> directory:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span><span class="nb">cd </span>homeassistant/components/frontend/www_static/home-assistant-polymer
<span class="gp">$ </span>nvm install &lt; .nvmrc
</code></pre>
</div>
<p><a href="https://yarnpkg.com/en/">Yarn</a> is used as the package manager for node modules. <a href="https://yarnpkg.com/en/docs/install">Install yarn using the instructions here.</a></p>
<p>Next step is to get the frontend code. When you clone the Home Assistant repository, the frontend repository is not cloned by default. You can setup the frontend development environment by running from the <code class="highlighter-rouge">home-assistant</code> directory:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>script/bootstrap_frontend
</code></pre>
</div>
<h2><a class="title-link" name="development" href="#development"></a> Development</h2>
<p>While you are developing, you need to have Rollup running to have changes you make to the JavaScript app-core made available.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span><span class="nb">cd </span>homeassistant/components/frontend/www_static/home-assistant-polymer
<span class="gp">$ </span>npm run js_dev
</code></pre>
</div>
<p>The source code for the frontend can be found in two different directories:</p>
<ul>
<li>UI: <code class="highlighter-rouge">homeassistant/components/frontend/www_static/home-assistant-polymer/src/</code></li>
<li>Panels: <code class="highlighter-rouge">homeassistant/components/frontend/www_static/home-assistant-polymer/panels/</code></li>
</ul>
<h1><a class="title-link" name="building-the-polymer-frontend" href="#building-the-polymer-frontend"></a> Building the Polymer frontend</h1>
<p>Building a new version of the frontend is as simple as running <code class="highlighter-rouge">script/build_frontend</code>. This fires off the following commands:</p>
<ul>
<li><strong>home-assistant-polymer</strong>: Install NPM dependencies.</li>
<li><strong>home-assistant-polymer</strong>: start frontend build.
@ -154,18 +113,10 @@ Do not use development mode in production. Home Assistant uses aggressive cachin
<li>Generate MD5 hashes of core and panel sources.</li>
<li>Create gzip versions of all the sources.</li>
</ul>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/frontend.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -254,13 +205,10 @@ Do not use development mode in production. Home Assistant uses aggressive cachin
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -270,7 +218,6 @@ Do not use development mode in production. Home Assistant uses aggressive cachin
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -282,7 +229,6 @@ Do not use development mode in production. Home Assistant uses aggressive cachin
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -290,4 +236,4 @@ Do not use development mode in production. Home Assistant uses aggressive cachin
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

46
developers/frontend_add_card/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Adding state card - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Adding a state card to the frontend">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/frontend_add_card/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Adding state card">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Adding a state card to the frontend">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Adding state card">
<meta name="twitter:description" content="Adding a state card to the frontend">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,63 +53,35 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Adding State Card
</h1>
</header>
<hr class="divider">
<p>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.</p>
<p><img src="/images/frontend/frontend-cards1.png" alt="Cards in the frontend" /></p>
<p>The different card types can be found <a href="https://github.com/home-assistant/home-assistant-polymer/tree/master/src/state-summary">here</a>.</p>
<p>Sensors, when not <a href="/components/group/">grouped</a>, are shown as so-called badges on top of the state cards.</p>
<p><img src="/images/frontend/frontend-badges.png" alt="Badges in the frontend" /></p>
<p>The different badges are located in the file <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/components/entity/ha-state-label-badge.html"><code class="highlighter-rouge">/src/components/entity/ha-state-label-badge.html</code></a>.</p>
<p>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 <code class="highlighter-rouge">camera</code>:</p>
<ol>
<li>Add <code class="highlighter-rouge">'camera'</code> to the array <code class="highlighter-rouge">DOMAINS_WITH_CARD</code> in the file <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/util/hass-util.html#L11">/util/hass-util.html</a>.</li>
<li>Create the files <code class="highlighter-rouge">state-card-camera.html</code> in the folder <a href="https://github.com/home-assistant/home-assistant-polymer/tree/master/src/state-summary">/state-summary/</a>.</li>
<li>Add <code class="highlighter-rouge">&lt;link rel="import" href="state-card-camera.html"&gt;</code> to <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/state-summary/state-card-content.html">state-card-content.html</a>.</li>
</ol>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/frontend_add_card.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -209,13 +170,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -225,7 +183,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -237,7 +194,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -245,4 +201,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

42
developers/frontend_add_more_info/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Adding more info dialogs - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Adding a more info dialog to the frontend">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/frontend_add_more_info/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Adding more info dialogs">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Adding a more info dialog to the frontend">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Adding more info dialogs">
<meta name="twitter:description" content="Adding a more info dialog to the frontend">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,58 +53,34 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Adding More Info Dialogs
</h1>
</header>
<hr class="divider">
<p>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>
<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>
<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 <code class="highlighter-rouge">camera</code>:</p>
<ol>
<li>Add <code class="highlighter-rouge">'camera'</code> to the array <code class="highlighter-rouge">DOMAINS_WITH_MORE_INFO</code> in the file <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/util/hass-util.html#L24">util/hass-util.html</a>.</li>
<li>Create the files <code class="highlighter-rouge">more-info-camera.html</code> in the folder <a href="https://github.com/home-assistant/home-assistant-polymer/tree/master/src/more-infos">/more-infos</a>.</li>
<li>Add <code class="highlighter-rouge">&lt;link rel="import" href="more-info-camera.html"&gt;</code> to <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/more-infos/more-info-content.html">more-info-content.html</a></li>
</ol>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/frontend_add_more_info.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -204,13 +169,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -220,7 +182,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -232,7 +193,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -240,4 +200,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

45
developers/frontend_creating_custom_panels/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Creating custom panels - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Introduction to create custom panels for Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/frontend_creating_custom_panels/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Creating custom panels">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Introduction to create custom panels for Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Creating custom panels">
<meta name="twitter:description" content="Introduction to create custom panels for Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,38 +53,22 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Creating Custom Panels
</h1>
</header>
<hr class="divider">
<p>Any component has the possibility to add a panel to the frontend. Panels will be rendered full screen and have real-time access to the Home Assistant object via JavaScript. Examples of this in the app are map, logbook and history.</p>
<p>Create a file called <code class="highlighter-rouge">hello.html</code> in your <config dir="">/panels/.</config></p>
<p>The <code class="highlighter-rouge">hello.html</code> contains the needed building blocks to create the elements inside the view.</p>
<div class="language-javascript highlighter-rouge"><pre class="highlight"><code><span class="o">&lt;</span><span class="nx">dom</span><span class="o">-</span><span class="nx">module</span> <span class="nx">id</span><span class="o">=</span><span class="s1">'ha-panel-hello'</span><span class="o">&gt;</span>
<span class="o">&lt;</span><span class="nx">template</span><span class="o">&gt;</span>
<span class="o">&lt;</span><span class="nx">style</span><span class="o">&gt;</span>
@ -143,9 +116,7 @@
<span class="o">&lt;</span><span class="sr">/script</span><span class="err">&gt;
</span></code></pre>
</div>
<p>Create an entry for the new panel in your <code class="highlighter-rouge">configuration.yaml</code> file:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">panel_custom</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">name</span><span class="pi">:</span> <span class="s">hello</span>
<span class="s">sidebar_title</span><span class="pi">:</span> <span class="s">Hello World</span>
@ -153,20 +124,11 @@
<span class="s">url_path</span><span class="pi">:</span> <span class="s">hello</span>
</code></pre>
</div>
<p>For more possibilities, see the <a href="/cookbook/#user-interface">Custom panel section</a> on our Examples page.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/frontend_creating_custom_panels.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -255,13 +217,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -271,7 +230,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -283,7 +241,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -291,4 +248,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

46
developers/frontend_creating_custom_ui/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Creating custom UI - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Introduction to create custom ui for Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/frontend_creating_custom_ui/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Creating custom UI">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Introduction to create custom ui for Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Creating custom UI">
<meta name="twitter:description" content="Introduction to create custom ui for Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,50 +53,31 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Creating Custom UI
</h1>
</header>
<hr class="divider">
<p>If you would like to use your own <a href="/developers/frontend_add_card/">State card</a> without merging your code into <a href="https://github.com/home-assistant/home-assistant-polymer/">home-assistant-polymer</a> you can create your own implementation.</p>
<ul>
<li>Put the element source file and its dependencies in <code class="highlighter-rouge">www/custom_ui/</code> directory under your homeassistant config directory.</li>
</ul>
<p>For example if creating a state card for the <code class="highlighter-rouge">light</code> domain named <code class="highlighter-rouge">my_custom_light_card</code> put <code class="highlighter-rouge">state-card-my_custom_light_card.html</code> in <code class="highlighter-rouge">www/custom_ui/</code>.</p>
<p>That file should implement <code class="highlighter-rouge">&lt;state-card-my_custom_light_card&gt;</code> tag with Polymer.</p>
<p>In <code class="highlighter-rouge">state-card-my_custom_light_card.html</code> you should use <code class="highlighter-rouge">&lt;link rel="import"&gt;</code> to import all the dependencies <strong>not</strong> used by Homeassistant UI.
Do not import any dependencies used by Homeassistant UI.
Importing those will work in <code class="highlighter-rouge">development: 1</code> mode, but will fail in production mode.</p>
<ul>
<li>In the <code class="highlighter-rouge">customize:</code> section of <code class="highlighter-rouge">configuration.yaml</code> put <code class="highlighter-rouge">custom_ui_state_card: &lt;element-name&gt;</code>.</li>
</ul>
<p>For example:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">homeassistant</span><span class="pi">:</span>
<span class="s">customize</span><span class="pi">:</span>
@ -115,20 +85,11 @@ Importing those will work in <code class="highlighter-rouge">development: 1</cod
<span class="s">custom_ui_state_card</span><span class="pi">:</span> <span class="s">my_custom_light_card</span>
</code></pre>
</div>
<p>For more possibilities, see the <a href="/cookbook/#user-interface">Custom UI section</a> on our Examples page.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/frontend_creating_custom_ui.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -217,13 +178,10 @@ Importing those will work in <code class="highlighter-rouge">development: 1</cod
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -233,7 +191,6 @@ Importing those will work in <code class="highlighter-rouge">development: 1</cod
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -245,7 +202,6 @@ Importing those will work in <code class="highlighter-rouge">development: 1</cod
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -253,4 +209,4 @@ Importing those will work in <code class="highlighter-rouge">development: 1</cod
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

40
developers/helpers/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Little online helpers - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="The little helpers for the development of Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/helpers/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Little online helpers">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="The little helpers for the development of Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Little online helpers">
<meta name="twitter:description" content="The little helpers for the development of Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,34 +53,20 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Little Online Helpers
</h1>
</header>
<hr class="divider">
<p>There are a bunch of online services which can help you if you are developing for Home Assistant or maintaining components. Some of these are directly connected to Pull Requests and the repositories, while others publish details and updates in our <a href="https://gitter.im/home-assistant/home-assistant/devs">Gitter.im</a> chatroom.</p>
<ul>
<li><a href="https://coveralls.io/github/home-assistant/home-assistant">Coveralls</a></li>
<li><a href="https://travis-ci.org/home-assistant/home-assistant">Travis CI</a></li>
@ -99,18 +74,10 @@
<li><a href="https://requires.io/github/home-assistant/home-assistant/requirements/?branch=dev">Requires.io</a></li>
<li><a href="https://www.pivotaltracker.com/n/projects/1250084">Pivotal Tracker</a></li>
</ul>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/helpers.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -199,13 +166,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -215,7 +179,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -227,7 +190,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -235,4 +197,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

43
developers/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Developers - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Everything you need to know to get started with Home Assistant development.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Developers">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Everything you need to know to get started with Home Assistant development.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Developers">
<meta name="twitter:description" content="Everything you need to know to get started with Home Assistant development.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,57 +53,32 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Developers
</h1>
</header>
<hr class="divider">
<p>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!</p>
<p class="img">
<img src="/images/architecture/component_interaction.png" alt="Diagram showing interaction between components and the Home Assistant core." />
Diagram showing interaction between components and the Home Assistant core.
</p>
<p>The best way to familiarize yourself with Home Assistant is to watch the PyCon 2016 talk about Home Assistant and read through the <a href="https://dev-docs.home-assistant.io">Python API docs</a>.</p>
<div class="videoWrapper">
<iframe width="560" height="315" src="https://www.youtube.com/embed/Cfasc9EgbMU" frameborder="0" allowfullscreen=""></iframe>
</div>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/index.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -203,13 +167,10 @@ Diagram showing interaction between components and the Home Assistant core.
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -219,7 +180,6 @@ Diagram showing interaction between components and the Home Assistant core.
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -231,7 +191,6 @@ Diagram showing interaction between components and the Home Assistant core.
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -239,4 +198,4 @@ Diagram showing interaction between components and the Home Assistant core.
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

40
developers/license/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>The Apache 2.0 License - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="The License that all Home Assistant projects are licensed under">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/license/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="The Apache 2.0 License">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="The License that all Home Assistant projects are licensed under">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="The Apache 2.0 License">
<meta name="twitter:description" content="The License that all Home Assistant projects are licensed under">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,34 +53,20 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
The Apache 2.0 License
</h1>
</header>
<hr class="divider">
<p>The Home Assistant source code is released under the following license.</p>
<div class="highlighter-rouge"><pre class="highlight"><code> Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
@ -295,18 +270,10 @@
limitations under the License.
</code></pre>
</div>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/license.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -395,13 +362,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -411,7 +375,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -423,7 +386,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -431,4 +393,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

50
developers/maintenance/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Maintenance - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Steps involved to maintain the current state of Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/maintenance/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Maintenance">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Steps involved to maintain the current state of Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Maintenance">
<meta name="twitter:description" content="Steps involved to maintain the current state of Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,73 +53,41 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Maintenance
</h1>
</header>
<hr class="divider">
<p>This page documents a couple of points for maintaining the Home Assistant code. Most of the tasks don’t need to be performed on a regular base thus the steps, used tools, or details are preserved here.</p>
<h3><a class="title-link" name="line-separator" href="#line-separator"></a> Line separator</h3>
<p>People are using various operating systems to develop components and platforms for Home Assistant. This could lead to different line endings on file. We prefer <code class="highlighter-rouge">LN</code>. Especially Microsoft Windows tools tend to use <code class="highlighter-rouge">CRLF</code>.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>find homeassistant -name <span class="s2">"*.py"</span> -exec file <span class="o">{}</span> <span class="se">\;</span> | grep BOM
<span class="gp">$ </span>find homeassistant -name <span class="s2">"*.py"</span> -exec file <span class="o">{}</span> <span class="se">\;</span> | grep CRLF
</code></pre>
</div>
<p>To fix the line separator, use <code class="highlighter-rouge">dos2unix</code> or <code class="highlighter-rouge">sed</code>.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>dos2unix homeassistant/components/notify/kodi.py
</code></pre>
</div>
<h3><a class="title-link" name="dependencies" href="#dependencies"></a> Dependencies</h3>
<p>A lot of components and platforms depends on third-party Python modules. The dependencies which are stored in the <code class="highlighter-rouge">requirements_*.txt</code> files are tracked by <a href="https://gemnasium.com/github.com/home-assistant/home-assistant">gemnasium</a> and <a href="https://requires.io/github/home-assistant/home-assistant/requirements/?branch=dev">Requires.io</a>.</p>
<p>If you update the requirements of a component/platform through the <code class="highlighter-rouge">REQUIREMENTS = ['modules-xyz==0.3']</code> entry, run the provided script to update the <code class="highlighter-rouge">requirements_*.txt</code> file(s).</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>script/gen_requirements_all.py
</code></pre>
</div>
<p>Start a test run of Home Assistant if that was successful include all files in a Pull Request. Add a short summary of the changes, a sample configuration entry, details about the tests, and other useful information to the description.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/maintenance.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -219,13 +176,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -235,7 +189,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -247,7 +200,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -255,4 +207,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

43
developers/multiple_instances/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Multiple Instances - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Quick primer on how multiple instances work together.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/multiple_instances/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Multiple Instances">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Quick primer on how multiple instances work together.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Multiple Instances">
<meta name="twitter:description" content="Quick primer on how multiple instances work together.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,43 +53,27 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Multiple Instances
</h1>
</header>
<hr class="divider">
<p>Home Assistant supports running multiple synchronised instances using a master-slave model. Whenever <code class="highlighter-rouge">events.fire</code> or <code class="highlighter-rouge">states.set</code> is called on the slave it will forward it to the master. The master will replicate all events and changed states to its slaves.</p>
<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>
<p>A slave instance can be started with the following code and has the same support for components as a master instance.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
<span class="kn">import</span> <span class="nn">homeassistant.bootstrap</span> <span class="kn">as</span> <span class="nn">bootstrap</span>
@ -118,22 +91,13 @@
<span class="n">hass</span><span class="o">.</span><span class="n">block_till_stopped</span><span class="p">()</span>
</code></pre>
</div>
<p class="note">
Because each slave maintains its own Service Registry it is possible to have multiple slaves respond to one service call.
</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/multiple_instances.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -222,13 +186,10 @@ Because each slave maintains its own Service Registry it is possible to have mul
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -238,7 +199,6 @@ Because each slave maintains its own Service Registry it is possible to have mul
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -250,7 +210,6 @@ Because each slave maintains its own Service Registry it is possible to have mul
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -258,4 +217,4 @@ Because each slave maintains its own Service Registry it is possible to have mul
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

44
developers/platform_example_light/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Example light platform - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Minimum implementation of a Home Assistant platform.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/platform_example_light/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Example light platform">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Minimum implementation of a Home Assistant platform.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Example light platform">
<meta name="twitter:description" content="Minimum implementation of a Home Assistant platform.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,38 +53,22 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Example Light Platform
</h1>
</header>
<hr class="divider">
<p>This example is for adding support for the imaginary Awesome Lights. It shows the different best practices for developing a platform.</p>
<p>Similar to Example Sensor Platform, copy the code below, and create it as a file in <code class="highlighter-rouge">&lt;config_dir&gt;/custom_components/light/awesomelights.py</code>.</p>
<p>Add the following to your configuration.yaml:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">light</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">platform</span><span class="pi">:</span> <span class="s">awesomelights</span>
<span class="s">host</span><span class="pi">:</span> <span class="s">HOST_HERE</span>
@ -103,9 +76,7 @@
<span class="s">password</span><span class="pi">:</span> <span class="s">PASSWORD_HERE_OR_secrets.yaml</span>
</code></pre>
</div>
<p>Note the <code class="highlighter-rouge">platform</code> name matches the filename for the source code.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">logging</span>
<span class="kn">import</span> <span class="nn">voluptuous</span> <span class="kn">as</span> <span class="nn">vol</span>
@ -202,18 +173,10 @@
<span class="bp">self</span><span class="o">.</span><span class="n">_brightness</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_light</span><span class="o">.</span><span class="n">brightness</span>
</code></pre>
</div>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/platform_example_light.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -302,13 +265,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -318,7 +278,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -330,7 +289,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -338,4 +296,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

45
developers/platform_example_sensor/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Example sensor platform - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Minimum implementation of a Home Assistant platform.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/platform_example_sensor/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Example sensor platform">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Minimum implementation of a Home Assistant platform.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Example sensor platform">
<meta name="twitter:description" content="Minimum implementation of a Home Assistant platform.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,48 +53,29 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Example Sensor Platform
</h1>
</header>
<hr class="divider">
<p>This is a minimum implementation of a platform for the sensor component.</p>
<h3><a class="title-link" name="installation" href="#installation"></a> Installation</h3>
<p>Copy the code below and create it as a file in <code class="highlighter-rouge">&lt;config_dir&gt;/custom_components/sensor/example.py</code>.</p>
<p>Add the following to your configuration.yaml:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="c1"># Example configuration.yaml entry</span>
<span class="s">sensor</span><span class="pi">:</span>
<span class="s">platform</span><span class="pi">:</span> <span class="s">example</span>
</code></pre>
</div>
<h3><a class="title-link" name="code" href="#code"></a> Code</h3>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">from</span> <span class="nn">homeassistant.const</span> <span class="kn">import</span> <span class="n">TEMP_CELSIUS</span>
<span class="kn">from</span> <span class="nn">homeassistant.helpers.entity</span> <span class="kn">import</span> <span class="n">Entity</span>
@ -145,18 +115,10 @@
<span class="bp">self</span><span class="o">.</span><span class="n">_state</span> <span class="o">=</span> <span class="mi">23</span>
</code></pre>
</div>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/platform_example_sensor.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -245,13 +207,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -261,7 +220,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -273,7 +231,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -281,4 +238,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

75
developers/python_api/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Python Remote API - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Home Assistant Python Remote API documentation">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/python_api/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Python Remote API">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Home Assistant Python Remote API documentation">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Python Remote API">
<meta name="twitter:description" content="Home Assistant Python Remote API documentation">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,49 +53,30 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Python Remote API
</h1>
</header>
<hr class="divider">
<p>In the package <a href="https://github.com/home-assistant/home-assistant/blob/master/homeassistant/remote.py"><code class="highlighter-rouge">homeassistant.remote</code></a> a Python API on top of the <a href="/developers/api/">HTTP API</a> can be found.</p>
<p>Note: This page is not full documentation for this API, but a collection of examples showing its use.</p>
<p>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 <code class="highlighter-rouge">sensor.office_temperature</code> and the switch <code class="highlighter-rouge">switch.livingroom_pin_2</code> are used.</p>
<p>First import the module and setup the basics:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.0.0.1'</span><span class="p">,</span> <span class="s">'password'</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">remote</span><span class="o">.</span><span class="n">validate_api</span><span class="p">(</span><span class="n">api</span><span class="p">))</span>
</code></pre>
</div>
<p>Here’s another way to use the <code class="highlighter-rouge">homeassistant.remote</code> package:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.0.0.1'</span><span class="p">,</span> <span class="s">'password'</span><span class="p">)</span>
@ -115,11 +85,8 @@
<span class="n">living_room</span> <span class="o">=</span> <span class="n">hass</span><span class="o">.</span><span class="n">states</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">'group.living_room'</span><span class="p">)</span>
</code></pre>
</div>
<h3><a class="title-link" name="get-configuration" href="#get-configuration"></a> Get configuration</h3>
<p>Get the current configuration of a Home Assistant instance:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.0.0.1'</span><span class="p">,</span> <span class="s">'password'</span><span class="p">)</span>
@ -127,11 +94,8 @@
<span class="k">print</span><span class="p">(</span><span class="n">remote</span><span class="o">.</span><span class="n">get_config</span><span class="p">(</span><span class="n">api</span><span class="p">))</span>
</code></pre>
</div>
<h3><a class="title-link" name="get-details-about-services-events-and-entitites" href="#get-details-about-services-events-and-entitites"></a> Get details about services, events, and entitites</h3>
<p>The output from this is similar to the output you’d find via the frontend, using the DevTools console.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.0.0.1'</span><span class="p">,</span> <span class="s">'YOUR_PASSWORD'</span><span class="p">)</span>
@ -152,11 +116,8 @@
<span class="k">print</span><span class="p">(</span><span class="n">entity</span><span class="p">)</span>
</code></pre>
</div>
<h3><a class="title-link" name="get-the-state-of-an-entity" href="#get-the-state-of-an-entity"></a> Get the state of an entity</h3>
<p>To get the details of a single entity, use <code class="highlighter-rouge">get_state</code>:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.0.0.1'</span><span class="p">,</span> <span class="s">'YOUR_PASSWORD'</span><span class="p">)</span>
@ -168,15 +129,11 @@
<span class="p">)</span>
</code></pre>
</div>
<p>This outputs the details which are stored for this entity, ie:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>Office Temperature is 19 °C.
</code></pre>
</div>
<p>Switches work the same way. The only difference is that both entities have different attributes.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.0.0.1'</span><span class="p">,</span> <span class="s">'YOUR_PASSWORD'</span><span class="p">)</span>
@ -187,11 +144,8 @@
<span class="p">)</span>
</code></pre>
</div>
<h3><a class="title-link" name="set-the-state-of-an-entity" href="#set-the-state-of-an-entity"></a> Set the state of an entity</h3>
<p>Of course, it’s possible to set the state as well:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
<span class="kn">from</span> <span class="nn">homeassistant.const</span> <span class="kn">import</span> <span class="n">STATE_ON</span>
@ -200,13 +154,9 @@
<span class="n">remote</span><span class="o">.</span><span class="n">set_state</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="s">'switch.livingroom_pin_2'</span><span class="p">,</span> <span class="n">new_state</span><span class="o">=</span><span class="n">STATE_ON</span><span class="p">)</span>
</code></pre>
</div>
<p>The state will be set to the new values until the next update occurs.</p>
<h3><a class="title-link" name="blinking-all-entities-of-a-domain" href="#blinking-all-entities-of-a-domain"></a> Blinking all entities of a domain</h3>
<p>If you want to turn on all entities of a domain, retrieve the service via <code class="highlighter-rouge">get_services</code> and act on that:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">time</span>
<span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
@ -218,11 +168,8 @@
<span class="n">remote</span><span class="o">.</span><span class="n">call_service</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="n">domain</span><span class="p">,</span> <span class="s">'turn_off'</span><span class="p">)</span>
</code></pre>
</div>
<h3><a class="title-link" name="control-a-single-entity" href="#control-a-single-entity"></a> Control a single entity</h3>
<p>To turn on or off a single switch, pass the ID of the entity:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">time</span>
<span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
@ -235,14 +182,11 @@
<span class="n">remote</span><span class="o">.</span><span class="n">call_service</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="n">domain</span><span class="p">,</span> <span class="s">'turn_off'</span><span class="p">,</span> <span class="p">{</span><span class="s">'entity_id'</span><span class="p">:</span> <span class="s">'{}'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">switch_name</span><span class="p">)})</span>
</code></pre>
</div>
<h3><a class="title-link" name="specify-a-timeout" href="#specify-a-timeout"></a> Specify a timeout</h3>
<p>The default timeout for an API call with <code class="highlighter-rouge">call_service</code> is 5 seconds. Services
taking longer than this to return will raise
<code class="highlighter-rouge">homeassistant.exceptions.HomeAssistantError: Timeout</code>, unless provided with a
longer timeout.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'host'</span><span class="p">,</span> <span class="s">'password'</span><span class="p">)</span>
@ -259,11 +203,8 @@ longer timeout.</p>
<span class="n">timeout</span><span class="o">=</span><span class="mi">11</span><span class="p">)</span>
</code></pre>
</div>
<h3><a class="title-link" name="send-a-notification" href="#send-a-notification"></a> Send a notification</h3>
<p>The example uses the Jabber notification platform to send a single message to the given recipient in the <code class="highlighter-rouge">configuration.yaml</code> file:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.0.0.1'</span><span class="p">,</span> <span class="s">'YOUR_PASSWORD'</span><span class="p">)</span>
@ -273,20 +214,11 @@ longer timeout.</p>
<span class="n">remote</span><span class="o">.</span><span class="n">call_service</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="n">domain</span><span class="p">,</span> <span class="s">'jabber'</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
</code></pre>
</div>
<p>For more details, please check the source of <a href="https://github.com/home-assistant/home-assistant/blob/master/homeassistant/remote.py">homeassistant.remote</a>.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/python_api.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -375,13 +307,10 @@ longer timeout.</p>
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -391,7 +320,6 @@ longer timeout.</p>
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -403,7 +331,6 @@ longer timeout.</p>
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -411,4 +338,4 @@ longer timeout.</p>
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

54
developers/releasing/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Releasing - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Steps involved publishing a new Home Assistant release.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/releasing/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Releasing">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Steps involved publishing a new Home Assistant release.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Releasing">
<meta name="twitter:description" content="Steps involved publishing a new Home Assistant release.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,36 +53,21 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Releasing
</h1>
</header>
<hr class="divider">
<p>This page describes the steps for publishing a new Home Assistant release.</p>
<h3><a class="title-link" name="github-3-days-before-release" href="#github-3-days-before-release"></a> GitHub (3 days before release)</h3>
<ol>
<li>Merge <code class="highlighter-rouge">master</code> into <code class="highlighter-rouge">dev</code> to make the PR mergeable.</li>
<li>Cut a release branch from <code class="highlighter-rouge">dev</code>. Example name <code class="highlighter-rouge">release-0-40</code>.</li>
@ -101,25 +75,19 @@
<li>Update <code class="highlighter-rouge">homeassistant/const.py</code> with the correct version number (remove the <code class="highlighter-rouge">dev</code> tag) and push that commit to release branch.</li>
<li>From now until the release branch has been merged, we tag bugfixes with the milestone for the release (create if doesn’t exist)</li>
</ol>
<h3><a class="title-link" name="website-3-days-before-release" href="#website-3-days-before-release"></a> Website (3 days before release)</h3>
<ol>
<li>Merge <code class="highlighter-rouge">current</code> into <code class="highlighter-rouge">next</code></li>
<li>Cut release branch of <code class="highlighter-rouge">next</code>. For example <code class="highlighter-rouge">release-0-40</code>.</li>
<li>Open a PR from release branch to <code class="highlighter-rouge">current</code> with the upcoming release number as the title.</li>
</ol>
<h3><a class="title-link" name="github" href="#github"></a> GitHub</h3>
<ol>
<li>Merge pull request (DO NOT SQUASH!).</li>
<li>Go to <a href="https://github.com/home-assistant/home-assistant/releases">releases</a> and tag a new release on the <code class="highlighter-rouge">master</code> branch. “Tag version” and “Release title” are the version number (<code class="highlighter-rouge">O.x</code> for major version, <code class="highlighter-rouge">0.x.y</code> for minor and bug fix releases). Release description is the text from PR. Press “Publish release” to finish the process.</li>
<li>Merge <code class="highlighter-rouge">master</code> into <code class="highlighter-rouge">dev</code>.</li>
</ol>
<h3><a class="title-link" name="website" href="#website"></a> Website</h3>
<ol>
<li>Create a blog post in the release branch and base it on the text of the PR in the main repository. Add images, additional text, links, etc. if it adds value. Tag each platform/component in a message to documentation.</li>
<li>Create missing documentation as stubs.</li>
@ -128,33 +96,18 @@
<li>Merge pull request (blog post, updated frontpage, and all new documentation) to <code class="highlighter-rouge">current</code>.</li>
<li>Merge <code class="highlighter-rouge">current</code> into <code class="highlighter-rouge">next</code>.</li>
</ol>
<h3><a class="title-link" name="docker-hub" href="#docker-hub"></a> Docker Hub</h3>
<p>Tags on Docker hub are automatically created when a release has been created on GitHub.</p>
<h3><a class="title-link" name="python-package-index" href="#python-package-index"></a> Python Package Index</h3>
<p>Checkout the <code class="highlighter-rouge">master</code> branch and run <code class="highlighter-rouge">script/release</code> to publish the new release on <a href="https://pypi.python.org">Python Package Index</a>.</p>
<h3><a class="title-link" name="social-media" href="#social-media"></a> Social media</h3>
<ol>
<li>Use <a href="https://hootsuite.com/dashboard">hootsuite</a> to publish a link to the release post on social media.</li>
</ol>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/releasing.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -243,13 +196,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -259,7 +209,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -271,7 +220,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -279,4 +227,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

132
developers/rest_api/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>RESTful API - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Home Assistant RESTful API documentation">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/rest_api/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="RESTful API">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Home Assistant RESTful API documentation">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="RESTful API">
<meta name="twitter:description" content="Home Assistant RESTful API documentation">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,52 +53,33 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
RESTful API
</h1>
</header>
<hr class="divider">
<p>Home Assistant runs a web server accessible on port 8123.</p>
<ul>
<li>http://IP_ADDRESS:8123/ is an interface to control Home Assistant.</li>
<li>http://IP_ADDRESS:8123/api/ is a Rest API.</li>
</ul>
<p>The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header <code class="highlighter-rouge">X-HA-Access: YOUR_PASSWORD</code> (YOUR_PASSWORD as specified in your <code class="highlighter-rouge">configuration.yaml</code> file in the <a href="/components/http/"><code class="highlighter-rouge">http:</code> section</a>).</p>
<p>There are multiple ways to consume the Home Assistant Rest API. One is with <code class="highlighter-rouge">curl</code>:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>curl -X GET <span class="se">\</span>
-H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
http://IP_ADDRESS:8123/ENDPOINT
</code></pre>
</div>
<p>Another option is to use Python and the <a href="http://docs.python-requests.org/en/latest/">Requests</a> module.</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">from</span> <span class="nn">requests</span> <span class="kn">import</span> <span class="n">get</span>
<span class="n">url</span> <span class="o">=</span> <span class="s">'http://localhost:8123/ENDPOINT'</span>
@ -120,43 +90,32 @@
<span class="k">print</span><span class="p">(</span><span class="n">response</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
</code></pre>
</div>
<p class="note">
You can append <code class="highlighter-rouge">?api_password=YOUR_PASSWORD</code> to any url to log in automatically.
</p>
<p>Successful calls will return status code 200 or 201. Other status codes that can return are:</p>
<ul>
<li>400 (Bad Request)</li>
<li>401 (Unauthorized)</li>
<li>404 (Not Found)</li>
<li>405 (Method not allowed)</li>
</ul>
<h3><a class="title-link" name="actions" href="#actions"></a> Actions</h3>
<p>The API supports the following actions:</p>
<h4><a class="title-link" name="get-api" href="#get-api"></a> GET /api/</h4>
<p>Returns a message if the API is up and running.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"API running."</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/
</code></pre>
</div>
<h4><a class="title-link" name="get-apiconfig" href="#get-apiconfig"></a> GET /api/config</h4>
<p>Returns the current configuration as JSON.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"components"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"recorder"</span><span class="p">,</span><span class="w">
@ -187,17 +146,13 @@ You can append <code class="highlighter-rouge">?api_password=YOUR_PASSWORD</code
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/config
</code></pre>
</div>
<h4><a class="title-link" name="get-apidiscovery_info" href="#get-apidiscovery_info"></a> GET /api/discovery_info</h4>
<p>Returns basic information about the Home Assistant instance as JSON.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"base_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"http://127.0.0.1:8123"</span><span class="p">,</span><span class="w">
</span><span class="nt">"location_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Home"</span><span class="p">,</span><span class="w">
@ -206,17 +161,13 @@ You can append <code class="highlighter-rouge">?api_password=YOUR_PASSWORD</code
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/discovery_info
</code></pre>
</div>
<h4><a class="title-link" name="get-apibootstrap" href="#get-apibootstrap"></a> GET /api/bootstrap</h4>
<p>Returns all data needed to bootstrap Home Assistant.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"config"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="err">...</span><span class="p">},</span><span class="w">
</span><span class="nt">"events"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="err">...</span><span class="p">],</span><span class="w">
@ -225,17 +176,13 @@ You can append <code class="highlighter-rouge">?api_password=YOUR_PASSWORD</code
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/bootstrap
</code></pre>
</div>
<h4><a class="title-link" name="get-apievents" href="#get-apievents"></a> GET /api/events</h4>
<p>Returns an array of event objects. Each event object contains event name and listener count.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"event"</span><span class="p">:</span><span class="w"> </span><span class="s2">"state_changed"</span><span class="p">,</span><span class="w">
@ -248,17 +195,13 @@ You can append <code class="highlighter-rouge">?api_password=YOUR_PASSWORD</code
</span><span class="p">]</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/events
</code></pre>
</div>
<h4><a class="title-link" name="get-apiservices" href="#get-apiservices"></a> GET /api/services</h4>
<p>Returns an array of service objects. Each object contains the domain and which services it contains.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"domain"</span><span class="p">:</span><span class="w"> </span><span class="s2">"browser"</span><span class="p">,</span><span class="w">
@ -276,17 +219,13 @@ You can append <code class="highlighter-rouge">?api_password=YOUR_PASSWORD</code
</span><span class="p">]</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/services
</code></pre>
</div>
<h4><a class="title-link" name="get-apihistoryperiodlttimestamp" href="#get-apihistoryperiodlttimestamp"></a> GET /api/history/period/&lt;timestamp&gt;</h4>
<p>Returns an array of state changes in the past. Each object contains further details for the entities.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">[</span><span class="w">
</span><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
@ -313,24 +252,19 @@ You can append <code class="highlighter-rouge">?api_password=YOUR_PASSWORD</code
</span><span class="p">]</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code class="highlighter-rouge">curl</code> commands:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00
</code></pre>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?filter_entity_id<span class="o">=</span>sensor.temperature
</code></pre>
</div>
<h4><a class="title-link" name="get-apistates" href="#get-apistates"></a> GET /api/states</h4>
<p>Returns an array of state objects. Each state has the following attributes: entity_id, state, last_changed and attributes.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:</span><span class="w"> </span><span class="p">{},</span><span class="w">
@ -347,17 +281,13 @@ You can append <code class="highlighter-rouge">?api_password=YOUR_PASSWORD</code
</span><span class="p">]</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/states
</code></pre>
</div>
<h4><a class="title-link" name="get-apistatesltentity_id" href="#get-apistatesltentity_id"></a> GET /api/states/&lt;entity_id&gt;</h4>
<p>Returns a state object for specified entity_id. Returns 404 if not found.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:{</span><span class="w">
</span><span class="nt">"azimuth"</span><span class="p">:</span><span class="mf">336.34</span><span class="p">,</span><span class="w">
@ -373,48 +303,36 @@ You can append <code class="highlighter-rouge">?api_password=YOUR_PASSWORD</code
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
http://localhost:8123/api/states/sensor.kitchen_temperature
</code></pre>
</div>
<h4><a class="title-link" name="get-apierror_log" href="#get-apierror_log"></a> GET /api/error_log</h4>
<p>Retrieve all errors logged during the current session of Home Assistant as a plaintext response.</p>
<div class="language-text highlighter-rouge"><pre class="highlight"><code>15-12-20 11:02:50 homeassistant.components.recorder: Found unfinished sessions
15-12-20 11:03:03 netdisco.ssdp: Error fetching description at http://192.168.1.1:8200/rootDesc.xml
15-12-20 11:04:36 homeassistant.components.alexa: Received unknown intent HelpIntent
</code></pre>
</div>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
http://localhost:8123/api/error_log
</code></pre>
</div>
<h4><a class="title-link" name="get-apicamera_proxycameraltentity_id" href="#get-apicamera_proxycameraltentity_id"></a> GET /api/camera_proxy/camera.&lt;entity_id&gt;</h4>
<p>Returns the data (image) from the specified camera entity_id.</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
http://localhost:8123/api/camera_proxy/camera.my_sample_camera?time<span class="o">=</span>1462653861261 -o image.jpg
</code></pre>
</div>
<h4><a class="title-link" name="post-apistatesltentity_id" href="#post-apistatesltentity_id"></a> POST /api/states/&lt;entity_id&gt;</h4>
<p>Updates or creates the current state of an entity.</p>
<p>Expects a JSON object that has at least a state attribute:</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"state"</span><span class="p">:</span><span class="w"> </span><span class="s2">"below_horizon"</span><span class="p">,</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
@ -424,9 +342,7 @@ You can append <code class="highlighter-rouge">?api_password=YOUR_PASSWORD</code
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The return code is 200 if the entity existed, 201 if the state of a new entity was set. A location header will be returned with the URL of the new resource. The response body will contain a JSON encoded State object.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nt">"next_rising"</span><span class="p">:</span><span class="s2">"2016-05-31T03:39:14+00:00"</span><span class="p">,</span><span class="w">
@ -439,48 +355,36 @@ You can append <code class="highlighter-rouge">?api_password=YOUR_PASSWORD</code
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X POST -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
-d <span class="s1">'{"state": "25", "attributes": {"unit_of_measurement": "°C"}}'</span> <span class="se">\</span>
http://localhost:8123/api/states/sensor.kitchen_temperature
</code></pre>
</div>
<h4><a class="title-link" name="post-apieventsltevent_type" href="#post-apieventsltevent_type"></a> POST /api/events/&lt;event_type&gt;</h4>
<p>Fires an event with event_type</p>
<p>You can pass an optional JSON object to be used as <code class="highlighter-rouge">event_data</code>.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"next_rising"</span><span class="p">:</span><span class="s2">"2016-05-31T03:39:14+00:00"</span><span class="p">,</span><span class="w">
</span><span class="err">}</span><span class="w">
</span></code></pre>
</div>
<p>Returns a message if successful.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Event download_file fired."</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h4><a class="title-link" name="post-apiservicesltdomainltservice" href="#post-apiservicesltdomainltservice"></a> POST /api/services/&lt;domain&gt;/&lt;service&gt;</h4>
<p>Calls a service within a specific domain. Will return when the service has been executed or after 10 seconds, whichever comes first.</p>
<p>You can pass an optional JSON object to be used as <code class="highlighter-rouge">service_data</code>.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"light.Ceiling"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Returns a list of states that have changed while the service was being executed.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:</span><span class="w"> </span><span class="p">{},</span><span class="w">
@ -497,48 +401,36 @@ You can append <code class="highlighter-rouge">?api_password=YOUR_PASSWORD</code
</span><span class="p">]</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X POST -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
-d <span class="s1">'{"entity_id": "switch.christmas_lights"}'</span> <span class="se">\</span>
http://localhost:8123/api/services/switch/turn_on
</code></pre>
</div>
<p class="note">
The result will include any states that changed while the service was being executed, even if their change was the result of something else happening in the system.
</p>
<h4><a class="title-link" name="post-apitemplate" href="#post-apitemplate"></a> POST /api/template</h4>
<p>Render a Home Assistant template. <a href="/topics/templating/">See template docs for more information.</a></p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"template"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Paulus is at {{ states('device_tracker.paulus') }}!"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Returns the rendered template in plain text.</p>
<div class="language-text highlighter-rouge"><pre class="highlight"><code>Paulus is at work!
</code></pre>
</div>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X POST -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
-d <span class="s1">'{"template": "It is !"}'</span> http://localhost:8123/api/template
</code></pre>
</div>
<h4><a class="title-link" name="post-apievent_forwarding" href="#post-apievent_forwarding"></a> POST /api/event_forwarding</h4>
<p>Set up event forwarding to another Home Assistant instance.</p>
<p>Requires a JSON object that represents the API to forward to.</p>
<div class="language-javascript highlighter-rouge"><pre class="highlight"><code><span class="p">{</span>
<span class="s2">"host"</span><span class="err">:</span> <span class="s2">"machine"</span><span class="p">,</span>
<span class="s2">"api_password"</span><span class="err">:</span> <span class="s2">"my_super_secret_password"</span><span class="p">,</span>
@ -546,20 +438,15 @@ The result will include any states that changed while the service was being exec
<span class="p">}</span>
</code></pre>
</div>
<p>It will return a message if event forwarding was set up successfully.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Event forwarding setup."</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h4><a class="title-link" name="delete-apievent_forwarding" href="#delete-apievent_forwarding"></a> DELETE /api/event_forwarding</h4>
<p>Cancel event forwarding to another Home Assistant instance.<br /></p>
<p>Requires a JSON object that represents the API to cancel forwarding to.</p>
<div class="language-javascript highlighter-rouge"><pre class="highlight"><code><span class="p">{</span>
<span class="s2">"host"</span><span class="err">:</span> <span class="s2">"machine"</span><span class="p">,</span>
<span class="s2">"api_password"</span><span class="err">:</span> <span class="s2">"my_super_secret_password"</span><span class="p">,</span>
@ -567,31 +454,19 @@ The result will include any states that changed while the service was being exec
<span class="p">}</span>
</code></pre>
</div>
<p>It will return a message if event forwarding was cancelled successfully.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Event forwarding cancelled."</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p class="note">
If your client does not support <code>DELETE</code> HTTP requests you can add an optional attribute <code>_METHOD</code> and set its value to <code>DELETE</code>.
</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/rest_api.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -680,13 +555,10 @@ If your client does not support <code>DELETE</code> HTTP requests you can add an
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -696,7 +568,6 @@ If your client does not support <code>DELETE</code> HTTP requests you can add an
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -708,7 +579,6 @@ If your client does not support <code>DELETE</code> HTTP requests you can add an
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -716,4 +586,4 @@ If your client does not support <code>DELETE</code> HTTP requests you can add an
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

56
developers/server_sent_events/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Server-sent events - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Home Assistant Server-sent events documentation">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/server_sent_events/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Server-sent events">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Home Assistant Server-sent events documentation">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Server-sent events">
<meta name="twitter:description" content="Home Assistant Server-sent events documentation">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,47 +53,28 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Server-sent Events
</h1>
</header>
<hr class="divider">
<p>The <a href="https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events">server-sent events</a> feature is a one-way channel from your Home Assistant server to a client which is acting as a consumer. For bi-directional communication check the <a href="/developers/rest_api/">RESTful API</a> and <a href="/developers/python_api/">Python API</a>.</p>
<p>The URI that is generating the data is <code class="highlighter-rouge">/api/stream</code>.</p>
<p>A requirement on the client-side is existing support for the <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventSource">EventSource</a> interface.</p>
<p>There are various ways to access the stream. One is <code class="highlighter-rouge">curl</code>:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/stream
</code></pre>
</div>
<p>You can create a convenient view for this by creating an HTML file (<code class="highlighter-rouge">sse.html</code>) in the <code class="highlighter-rouge">www</code> folder of your Home Assistant configuration directory (<code class="highlighter-rouge">.homeassistant</code>). Paste this snippet into the file:</p>
<div class="language-html highlighter-rouge"><pre class="highlight"><code><span class="cp">&lt;!DOCTYPE html&gt;</span>
<span class="nt">&lt;html&gt;</span>
<span class="nt">&lt;body&gt;</span>
@ -120,31 +90,20 @@
<span class="nt">&lt;/html&gt;</span>
</code></pre>
</div>
<p>Visit <a href="http://localhost:8123/local/sse.html">http://localhost:8123/local/sse.html</a> to see the stream of events.</p>
<h2><a class="title-link" name="examples" href="#examples"></a> Examples</h2>
<p>A simple way to consume server-sent events is to use a command-line http client like <a href="https://httpie.org/">httpie</a>. Installation info is on the site (if you use Homebrew, it’s <code class="highlighter-rouge">brew install httpie</code>). Once installed, run this snippet from your terminal:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>http --stream http://localhost:8123/api/stream x-ha-access:YOUR_PASSWORD content-type:application/json
</code></pre>
</div>
<h3><a class="title-link" name="website" href="#website"></a> Website</h3>
<p>The <a href="https://github.com/fabaff/home-assistant-sse">home-assistant-sse</a> repository contains a more advanced example.</p>
<h3><a class="title-link" name="python" href="#python"></a> Python</h3>
<p>If you want to test the server-sent events without creating a website, the Python module <a href="https://pypi.python.org/pypi/sseclient/"><code class="highlighter-rouge">sseclient</code> </a> can help. To install (assuming Python and pip3 are already installed):</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>pip3 install sseclient
</code></pre>
</div>
<p>A simple script to consume SSE in Python looks like this:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">from</span> <span class="nn">sseclient</span> <span class="kn">import</span> <span class="n">SSEClient</span>
<span class="n">messages</span> <span class="o">=</span> <span class="n">SSEClient</span><span class="p">(</span><span class="s">'http://localhost:8123/api/stream?api_password=YOUR_PASSWORD'</span><span class="p">)</span>
@ -152,18 +111,10 @@
<span class="k">print</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>
</code></pre>
</div>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/server_sent_events.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -252,13 +203,10 @@
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -268,7 +216,6 @@
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -280,7 +227,6 @@
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -288,4 +234,4 @@
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

75
developers/website/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Website home-assistant.io - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="home-assistant.io web presence">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/website/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Website home-assistant.io">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="home-assistant.io web presence">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Website home-assistant.io">
<meta name="twitter:description" content="home-assistant.io web presence">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,52 +53,31 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Website home-assistant.io
</h1>
</header>
<hr class="divider">
<p>The website you are reading now is the home of Home Assistant: <a href="https://home-assistant.io">https://home-assistant.io</a>. This is the place where we provide documentation and additional details about Home Assistant for end users and developers.</p>
<p>home-assistant.io is built using <a href="http://github.com/mojombo/jekyll">Jekyll</a> and <a href="https://pages.github.com/versions/">these available dependencies</a>. The pages are written in <a href="http://daringfireball.net/projects/markdown/">markdown</a>. To add a page, you don’t need to know about HTML.</p>
<p>You can use the “<strong>Edit this page on GitHub</strong>” link to edit pages without creating a fork. Keep in mind that you can’t upload images while working this way.</p>
<p>For larger changes, we suggest that you clone the website repository. This way, you can review your changes locally. The process for working on the website is no different from working on Home Assistant itself. You work on your change and propose it via a pull request.</p>
<p>To test your changes locally, you need to install <strong>Ruby</strong> and its dependencies (gems):</p>
<ul>
<li><a href="https://www.ruby-lang.org/en/documentation/installation/">Install Ruby</a> if you don’t have it already.</li>
<li>Install <code class="highlighter-rouge">bundler</code>, a dependency manager for Ruby: <code class="highlighter-rouge">$ gem install bundler</code></li>
<li>In your home-assistant.github.io root directory, run <code class="highlighter-rouge">$ bundle</code> to install the gems you need.</li>
</ul>
<p>Short cut for Fedora: <code class="highlighter-rouge">$ sudo dnf -y install gcc-c++ ruby ruby-devel rubygem-bundler &amp;&amp; bundle</code></p>
<p>Then you can work on the documentation:</p>
<ul>
<li>Fork home-assistant.io <a href="https://github.com/home-assistant/home-assistant.github.io">git repository</a>.</li>
<li>Create/edit/update a page in the directory <code class="highlighter-rouge">source/_components/</code> for your platform/component.</li>
@ -117,7 +85,6 @@
<li>Create a Pull Request (PR) against the <strong>next</strong> branch of home-assistant.github.io if your documentation is a new feature, platform, or component.</li>
<li>Create a Pull Request (PR) against the <strong>current</strong> branch of home-assistant.github.io if you fix stuff, create Cookbook entries, or expand existing documentation.</li>
</ul>
<p class="note">
It could be necessary that you run <code class="highlighter-rouge">rake generate</code> prior to <code class="highlighter-rouge">rake preview</code> for the very first preview.
</p>
@ -125,13 +92,9 @@ It could be necessary that you run <code class="highlighter-rouge">rake generate
Site generated by <code class="highlighter-rouge">rake</code> is only available locally. If you are developing on a headless machine use port forwarding:
<code class="highlighter-rouge">ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine</code>
</p>
<h3><a class="title-link" name="create-a-page" href="#create-a-page"></a> Create a page</h3>
<p>For a platform page, the fastest way is to make a copy of an existing page and edit it. The <a href="/components/">Component overview</a> and the <a href="/cookbook/">Examples section</a> are generated automatically, so there is no need to add a link to those pages.</p>
<p>If you start from scratch with a page, you need to add a header. Different sections of the documentation may need different headers.</p>
<div class="language-text highlighter-rouge"><pre class="highlight"><code>---
layout: page
title: "Website home-assistant.io"
@ -150,62 +113,42 @@ Content...Written in markdown.
...
</code></pre>
</div>
<p>There are <a href="https://jekyllrb.com/docs/variables/">pre-definied variables</a> available but usually, it’s not necessary to use them when writing documentation.</p>
<p>A couple of points to remember:</p>
<ul>
<li>Document the needed steps to retrieve API keys or access token for the third party service or device if needed.</li>
<li>Keep the configuration sample minimal by only adding the <code class="highlighter-rouge">Required</code> options. Full configuration details with further explanations should go into a seperate section.</li>
<li>The description of all the configuration variables should contains information about the used defaults.</li>
<li>If you’re adding a new component, for the <code class="highlighter-rouge">ha_release</code> part of the header, just increment off the current release. If the current release is 0.37, make <code class="highlighter-rouge">ha_release</code> 0.38.</li>
</ul>
<h3><a class="title-link" name="embedding-code" href="#embedding-code"></a> Embedding Code</h3>
<p>You can use the default markdown syntax to generate syntax highlighted code. For inline code wrap your code in `. For multi-line, syntax wrap your code as shown below.</p>
<div class="language-text highlighter-rouge"><pre class="highlight"><code> ```yaml
sensor:
platform: template
```
</code></pre>
</div>
<p>Note that you can replace <code class="highlighter-rouge">yaml</code> next to ``` with the language that is within the block.</p>
<p>When you’re writing code that is to be executed on the terminal, prefix it with <code class="highlighter-rouge">$</code>.</p>
<h3><a class="title-link" name="templates" href="#templates"></a> Templates</h3>
<p>For the <a href="/topics/templating/">configuration templating</a> is <a href="http://jinja.pocoo.org/">Jinja</a> used.</p>
<p>If you are using templates then those parts needs to be <a href="http://stackoverflow.com/a/24102537">escaped</a>. Otherwise they will be rendered and appear blank on the website.</p>
<h3><a class="title-link" name="html" href="#html"></a> HTML</h3>
<p>The direct usage of HTML is supported but not recommended. The note boxes are an exception.</p>
<div class="language-html highlighter-rouge"><pre class="highlight"><code><span class="nt">&lt;p</span> <span class="na">class=</span><span class="s">'note warning'</span><span class="nt">&gt;</span>
You need to enable telnet on your router.
<span class="nt">&lt;/p&gt;</span>
</code></pre>
</div>
<h3><a class="title-link" name="redirects" href="#redirects"></a> Redirects</h3>
<p>If you rename or move an existing platform or component, create the redirect. Add the old location of the page to the header of the new one.</p>
<pre><code class="language-test">---
<p>If you rename or move an existing platform or component, create the redirect. Add the old location of the page to the header of the new one.</p><pre><code class="language-test">---
...
redirect_from: /getting-started/android/
---
</code></pre>
<h3><a class="title-link" name="images-icons-and-logos" href="#images-icons-and-logos"></a> Images, icons, and logos</h3>
<p>The images which are displayed on the pages are stored in various directories according to their purpose.</p>
<table>
<thead>
<tr>
@ -224,20 +167,11 @@ redirect_from: /getting-started/android/
</tr>
</tbody>
</table>
<p>Not everything (product, component, etc.) has a logo. To show something for internal parts of Home Assistant we are using the <a href="https://materialdesignicons.com/">Material Design Icons</a>.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/website.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -326,13 +260,10 @@ redirect_from: /getting-started/android/
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -342,7 +273,6 @@ redirect_from: /getting-started/android/
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -354,7 +284,6 @@ redirect_from: /getting-started/android/
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -362,4 +291,4 @@ redirect_from: /getting-started/android/
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>

108
developers/websocket_api/index.html
View file

@ -3,17 +3,14 @@
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>WebSocket API - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Home Assistant WebSocket API documentation">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/websocket_api/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="WebSocket API">
<meta property="og:site_name" content="Home Assistant">
@ -21,39 +18,31 @@
<meta property="og:type" content="website">
<meta property="og:description" content="Home Assistant WebSocket API documentation">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="WebSocket API">
<meta name="twitter:description" content="Home Assistant WebSocket API documentation">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
@ -64,44 +53,27 @@
</ul>
</nav>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
WebSocket API
</h1>
</header>
<hr class="divider">
<p>Home Assistant contains a WebSocket API. This API can be used to stream information from a Home Assistant instance to any client that implements WebSocket. Implementations in different languages:</p>
<ul>
<li><a href="https://github.com/home-assistant/home-assistant-js-websocket">JavaScript</a> - powers the frontend</li>
<li><a href="https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket-client.py">Python</a> - CLI client using <a href="https://async-websockets.readthedocs.io/en/latest/"><code class="highlighter-rouge">asyncws</code></a></li>
<li><a href="https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket.html">JavaScript/HTML</a> - WebSocket connection in your browser</li>
</ul>
<p>Connect your websocket implementation to <code class="highlighter-rouge">ws://localhost:8123/api/websocket</code>.</p>
<h2><a class="title-link" name="server-states" href="#server-states"></a> Server states</h2>
<ol>
<li>Client connects</li>
<li>Authentication phase starts
@ -117,22 +89,16 @@ a. Client can send commands.
b. Server can send results of previous commands.</li>
<li>Client or server disconnects session.</li>
</ol>
<p>During the command phase, the client attaches a unique identifier to each message. The server will add this identifier to each message so that the client can link each message to it’s origin.</p>
<h2><a class="title-link" name="message-format" href="#message-format"></a> Message format</h2>
<p>Each API message is a JSON serialized object containing a <code class="highlighter-rouge">type</code> key. After the authentication phase messages also must contain an <code class="highlighter-rouge">id</code>, an integer that contains the number of interactions.</p>
<p>Example of an auth message:</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth"</span><span class="p">,</span><span class="w">
</span><span class="nt">"api_password"</span><span class="p">:</span><span class="w"> </span><span class="s2">"supersecret"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="w"> </span><span class="err">5,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="s2">"event"</span><span class="p">,</span><span class="w">
@ -145,57 +111,42 @@ b. Server can send results of previous commands.</li>
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h2><a class="title-link" name="authentication-phase" href="#authentication-phase"></a> Authentication phase</h2>
<p>When a client connects to the server, the server will test if the client is authenticated. Authentication will not be necessary if no api_password is set or if the user fulfills one of the other criteria for authentication (trusted network, password in url/header).</p>
<p>If no authentication is needed, the authentication phase will complete and the server will send an <code class="highlighter-rouge">auth_ok</code> message.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth_ok"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>If authentication is necessary, the server sends out <code class="highlighter-rouge">auth_required</code>.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth_required"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>This means that the next message from the client should be an auth message:</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth"</span><span class="p">,</span><span class="w">
</span><span class="nt">"api_password"</span><span class="p">:</span><span class="w"> </span><span class="s2">"supersecret"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>If the client supplies valid authentication, the authentication phase will complete by the server sending the <code class="highlighter-rouge">auth_ok</code> message:</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth_ok"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>If the data is incorrect, the server will reply with <code class="highlighter-rouge">auth_invalid</code> message and disconnect the session.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"auth_invalid"</span><span class="p">,</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Invalid password"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h2><a class="title-link" name="command-phase" href="#command-phase"></a> Command phase</h2>
<p>During this phase the client can give commands to the server. The server will respond to each command with a <code class="highlighter-rouge">result</code> message indicating when the command is done and if it was successful.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">6</span><span class="err">.</span><span class="w">
</span><span class="s2">"type"</span><span class="err">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
@ -205,11 +156,8 @@ b. Server can send results of previous commands.</li>
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h2><a class="title-link" name="subscribe-to-events" href="#subscribe-to-events"></a> Subscribe to events</h2>
<p>The command <code class="highlighter-rouge">subscribe_events</code> will subscribe your client to the event bus. You can either listen to all events or to a specific event type. If you want to listen to multiple event types, you will have to send multiple <code class="highlighter-rouge">subscribe_events</code> commands.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">18</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"subscribe_events"</span><span class="p">,</span><span class="w">
@ -218,9 +166,7 @@ b. Server can send results of previous commands.</li>
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The server will respond with a result message to indicate that the subscription is active.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">18</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
@ -229,9 +175,7 @@ b. Server can send results of previous commands.</li>
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>For each event that matches, the server will send a message of type <code class="highlighter-rouge">event</code>. The <code class="highlighter-rouge">id</code> in the message will point at the original <code class="highlighter-rouge">id</code> of the <code class="highlighter-rouge">listen_event</code> command.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">18</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="s2">"event"</span><span class="p">,</span><span class="w">
@ -278,11 +222,8 @@ b. Server can send results of previous commands.</li>
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h3><a class="title-link" name="unsubscribing-from-events" href="#unsubscribing-from-events"></a> Unsubscribing from events</h3>
<p>You can unsubscribe from previously created subscription events. Pass the id of the original subscription command as value to the subscription field.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"unsubscribe_events"</span><span class="p">,</span><span class="w">
@ -290,9 +231,7 @@ b. Server can send results of previous commands.</li>
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The server will respond with a result message to indicate that unsubscribing was successful.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
@ -301,12 +240,8 @@ b. Server can send results of previous commands.</li>
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h3><a class="title-link" name="calling-a-service" href="#calling-a-service"></a> Calling a service</h3>
<p>This will call a service in Home Assistant. Right now there is no return value. The client can listen to <code class="highlighter-rouge">state_changed</code> events if it is interested in changed entities as a result of a service call.</p>
<pre><code class="language-json5">{
<p>This will call a service in Home Assistant. Right now there is no return value. The client can listen to <code class="highlighter-rouge">state_changed</code> events if it is interested in changed entities as a result of a service call.</p><pre><code class="language-json5">{
"id": 24,
"type": "call_service",
"domain": "light",
@ -317,9 +252,7 @@ b. Server can send results of previous commands.</li>
}
}
</code></pre>
<p>The server will indicate with a message indicating that the service is done executing.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">24</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
@ -328,20 +261,15 @@ b. Server can send results of previous commands.</li>
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h3><a class="title-link" name="fetching-states" href="#fetching-states"></a> Fetching states</h3>
<p>This will get a dump of all the current states in Home Assistant.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"get_states"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The server will respond with a result message containing the states.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
@ -350,20 +278,15 @@ b. Server can send results of previous commands.</li>
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h3><a class="title-link" name="fetching-config" href="#fetching-config"></a> Fetching config</h3>
<p>This will get a dump of the current config in Home Assistant.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"get_config"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The server will respond with a result message containing the config.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
@ -372,20 +295,15 @@ b. Server can send results of previous commands.</li>
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h3><a class="title-link" name="fetching-services" href="#fetching-services"></a> Fetching services</h3>
<p>This will get a dump of the current services in Home Assistant.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"get_services"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The server will respond with a result message containing the services.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
@ -394,20 +312,15 @@ b. Server can send results of previous commands.</li>
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h3><a class="title-link" name="fetching-panels" href="#fetching-panels"></a> Fetching panels</h3>
<p>This will get a dump of the current registered panels in Home Assistant.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"get_panels"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>The server will respond with a result message containing the current registered panels.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">19</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"result"</span><span class="p">,</span><span class="w">
@ -416,11 +329,8 @@ b. Server can send results of previous commands.</li>
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h2><a class="title-link" name="error-handling" href="#error-handling"></a> Error handling</h2>
<p>If an error occurs, the <code class="highlighter-rouge">success</code> key in the <code class="highlighter-rouge">result</code> message will be set to <code class="highlighter-rouge">false</code>. It will contain an <code class="highlighter-rouge">error</code> key containing an object with two keys: <code class="highlighter-rouge">code</code> and <code class="highlighter-rouge">message</code>.</p>
<table>
<thead>
<tr>
@ -443,7 +353,6 @@ b. Server can send results of previous commands.</li>
</tr>
</tbody>
</table>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"id"</span><span class="p">:</span><span class="w"> </span><span class="mi">12</span><span class="p">,</span><span class="w">
</span><span class="nt">"type"</span><span class="p">:</span><span class="s2">"result"</span><span class="p">,</span><span class="w">
@ -455,18 +364,10 @@ b. Server can send results of previous commands.</li>
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/developers/websocket_api.markdown'>Edit this page on GitHub</a></div>
<div class='section'>
@ -555,13 +456,10 @@ b. Server can send results of previous commands.</li>
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
@ -571,7 +469,6 @@ b. Server can send results of previous commands.</li>
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
@ -583,7 +480,6 @@ b. Server can send results of previous commands.</li>
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
@ -591,4 +487,4 @@ b. Server can send results of previous commands.</li>
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
</html>